Skip to content

Documentation · IGNIS

Getting Started ​

Pick the setup closest to yours, copy the declaration, then change the names. Each one is a complete TStaticAssetComponentOptions you register in preConfigure().

SetupFiles arrive byStorageWho reads
A. Public product imagesserverUploadS3anyone
B. An Excel importdirectUpload + validationS3signed-in users
C. Private reportsserverUploaddisksigned-in users

Not sure which way files should arrive? Read Two ways a file arrives first.

Register the options ​

All three share this wiring. The key you give each entry (productImages below) names its controller and its service keys.

ts
import { BaseApplication } from '@venizia/ignis';
import { StaticAssetComponent } from '@venizia/ignis/static-asset';
import type { TStaticAssetComponentOptions } from '@venizia/ignis/static-asset';

export abstract class Application extends BaseApplication {
  override preConfigure(): void {
    const options: TStaticAssetComponentOptions = {
      // one entry per bucket - see the three setups below
    };

    this.component(StaticAssetComponent, { options });
  }
}

An application that registers components through configs.artifacts binds the same object at StaticAssetBindingKeys.STATIC_ASSET_OPTIONS instead.

Create the bucket ​

The component never creates the bucket, and no route does. Create it once, before the first request. On S3 that is your cloud console or your infrastructure code. On disk, a bucket is a folder under the helper's basePath.

ts
import type { IStorageHelper } from '@venizia/ignis-helpers';

export const ensureBucket = async (opts: {
  helper: IStorageHelper;
  name: string;
}): Promise<void> => {
  const bucket = { name: opts.name };
  const isExisting = await opts.helper.hasBucket({ bucket });

  if (!isExisting) {
    await opts.helper.createBucket({ bucket });
  }
};

An upload to a bucket that does not exist answers 400 with [upload] Bucket does not exist.

A. Public product images ​

Anyone may view an image. Only signed-in users change them. Every upload also writes a MetaLink row, so a product can point at its pictures.

ts
import { Authentication } from '@venizia/ignis';
import type { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';
import type { BaseMetaLinkRepository, TStaticAssetComponentOptions } from '@venizia/ignis/static-asset';

export const buildProductImages = (opts: {
  storage: BunS3Helper;
  metaLinkRepository: BaseMetaLinkRepository;
}): TStaticAssetComponentOptions => ({
  productImages: {
    basePath: '/product-images',
    bucket: 'product-images',
    helper: opts.storage,
    auth: {
      authenticate: { strategies: [Authentication.STRATEGY_JWT] },
      publicRead: { use: true },
    },
    serverUpload: { use: true, maxBytes: 5 * 1024 * 1024 },
    directUpload: { use: false },
    metaLink: { use: true, repository: opts.metaLinkRepository },
  },
});
RoutePathWho may call it
getObjectByNameGET /product-images/objects/{objectName}anyone (publicRead)
downloadObjectByNameGET /product-images/download/{objectName}anyone (publicRead)
uploadPOST /product-images/objectsJWT
listObjectsGET /product-images/objectsJWT - listing is never public
deleteObjectDELETE /product-images/objects/{objectName}JWT
recreateMetaLinkPUT /product-images/meta-links/{objectName}JWT

Continue with Server upload.

B. An Excel import with validation ​

A user uploads a workbook straight to S3. Your code reads it once, returns cell errors, and a valid file gets a commitToken. The server commits with that token; the browser never confirms.

ts
import { Authentication } from '@venizia/ignis';
import { z } from '@hono/zod-openapi';
import { applicationEnvironment } from '@venizia/ignis-helpers';
import type { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';
import { StaticAssetValidation } from '@venizia/ignis/static-asset';
import type { TStaticAssetComponentOptions } from '@venizia/ignis/static-asset';

const CellIssueSchema = z.object({
  sheet: z.string(),
  row: z.number().int(),
  column: z.string(),
  code: z.string(),
  message: z.string(),
});

export const buildOrderImport = (opts: {
  storage: BunS3Helper;
  checkWorkbook: (opts: {
    key: string;
    size: number;
    stream: ReadableStream<Uint8Array>;
  }) => Promise<z.infer<typeof CellIssueSchema>[]>;
}): TStaticAssetComponentOptions => ({
  orderImport: {
    basePath: '/order-import',
    bucket: 'imports',
    keyPrefix: 'orders/',
    helper: opts.storage,
    auth: { authenticate: { strategies: [Authentication.STRATEGY_JWT] } },
    serverUpload: { use: false },
    metaLink: { use: false },
    routes: { uploadCommit: { use: false } },
    directUpload: {
      use: true,
      secretKey: applicationEnvironment.getRequired('APP_ENV_UPLOAD_SECRET'),
      maxBytes: 20 * 1024 * 1024,
      resolvers: {
        owner: ({ context }) => String(context.get(Authentication.CURRENT_USER).userId),
      },
      validation: StaticAssetValidation.define({
        issueSchema: CellIssueSchema,
        handler: async ({ file }) => {
          const stream = await file.stream();
          const issues = await opts.checkWorkbook({ key: file.key, size: file.size, stream });

          return { isValid: issues.length === 0, issues };
        },
      }),
    },
  },
});
RoutePathWho may call it
uploadPolicyPOST /order-import/upload-policyJWT
uploadValidatePOST /order-import/upload-validateJWT
getObjectByName, downloadObjectByName, listObjects, deleteObjectunder /order-import/objects and /order-import/downloadJWT
  • There is no POST /objects (serverUpload: { use: false }) and no upload-commit (routes.uploadCommit: { use: false }). Your service commits with commitService.commit once it accepts the file. Pass it the commitToken that upload-validate returned, not the one the policy issued. The other combinations are in Who commits, and with which token.
  • directUpload.authorize is left out because auth already requires a signed-in user.
  • keyPrefix is required with directUpload. It keeps committed files in orders/, and keeps the pending files (under pending/) out of everything the routes serve. See The pending prefix.

Continue with Direct upload.

C. Private reports on disk ​

Reports are generated and stored for signed-in users only. Nothing is public, and a report is always a download.

ts
import { Authentication } from '@venizia/ignis';
import { DiskHelper } from '@venizia/ignis-helpers';
import type { TStaticAssetComponentOptions } from '@venizia/ignis/static-asset';

export const buildReports = (): TStaticAssetComponentOptions => ({
  reports: {
    basePath: '/reports',
    bucket: 'reports',
    keyPrefix: 'monthly/',
    helper: new DiskHelper({ basePath: './app_data' }),
    auth: { authenticate: { strategies: [Authentication.STRATEGY_JWT] } },
    serverUpload: { use: true, maxBytes: 50 * 1024 * 1024 },
    directUpload: { use: false },
    metaLink: { use: false },
    routes: { getObjectByName: { use: false } },
  },
});
RoutePathWho may call it
downloadObjectByNameGET /reports/download/{objectName}JWT
uploadPOST /reports/objectsJWT
listObjectsGET /reports/objectsJWT
deleteObjectDELETE /reports/objects/{objectName}JWT
  • routes.getObjectByName: { use: false } removes inline viewing, so every read is an attachment.
  • keyPrefix keeps the entry inside monthly/ of the reports bucket.
  • The whole upload body is held in memory while it is parsed, so keep maxBytes to what your process can hold.
  • A DiskHelper cannot take directUpload: a signed POST policy is an S3 feature, and the types refuse it.

Next ​