Migration
An entry is now one flat object, and every switch is a toggle: { use: false } or { use: true, ...options }. Nothing is aliased. An old option fails type-checking until you move it. This page maps every one.
Four changes need more than a rename:
- One bucket per entry.
bucketis required and leaves the URL. The four bucket routes are gone. Stored links that contain/buckets/<name>/stop working. See Links already stored. - Direct upload needs a
keyPrefix. Committed keys move under it. See Direct upload entries. - No more
onCommit, no more spool. Check the file invalidation, and do work after a commit in the code that callscommit. - A validation handler gets a pinned file, and validate returns the token commit needs. See The validation handler.
Old to new
| Old | New |
|---|---|
controller.name | name, optional: derived from the entry key (staticAsset becomes StaticAssetController) |
controller.basePath | basePath |
controller.isStrict | removed: routes are always strict (/path and /path/ differ) |
controller.rawObjectPath | rawObjectPath |
controller.bucket | bucket, required |
no controller.bucket (bucket in the URL) | removed: declare one entry per bucket |
getBuckets, getBucketByName, createBucket, deleteBucket routes | removed. Create the bucket in your storage or with helper.createBucket |
controller.keyPrefix | keyPrefix, required with directUpload |
controller.routes.X: { enabled: false } | routes.X: { use: false } |
controller.routes.X: { enabled: true } or overrides | routes.X: { use: true, ...overrides } |
controller.directUpload | directUpload: { use: true, ... }, or directUpload: { use: false } |
directUpload.validation | directUpload.validation: { use: false }, or StaticAssetValidation.define(...), which returns it switched on |
directUpload.onCommit | removed: check the file in validation, and do work after a commit in the code that calls commit |
storage: 'bun-s3' or 'disk' | removed: the helper declares it (helper.storageType) |
StaticAssetStorageTypes | StorageTypes from @venizia/ignis-helpers |
useMetaLink: true and metaLink | metaLink: { use: true, repository, createMetaLink? }, or metaLink: { use: false } |
metaLink.model | removed |
createMetaLink({ ..., query }) | createMetaLink({ ..., labels }) |
TStaticAssetUploadQuery | TStaticAssetUploadLabels (folderPath is no longer a label) |
extra.maxBytes | serverUpload.maxBytes |
extra.maxFolderDepth | maxFolderDepth (on the entry, not in serverUpload) |
extra.parseMultipartBody.maxFiles | serverUpload.maxFiles, and directUpload.maxFiles for a policy request |
extra.parseMultipartBody.storage and uploadDir | removed: the whole body is parsed into memory before the first file is written, so spooling to disk saved nothing |
extra.normalizeNameFn and resolveObjectName | serverUpload.objectKey: one hook that gets { bucket, file, defaultKey } |
TStaticAssetObjectNameResolver | TStaticAssetObjectKeyResolver |
extra.normalizeLinkFn | link |
extra | removed: every option is typed |
defineRoutesBefore | extend.before |
defineExtraRoutes | extend.after |
auth.publicRead: true | auth.publicRead: { use: true } |
TStaticAssetExtraOptions, TStaticAssetBucketParams, TStaticAssetListQuery | removed |
Behaviour that changed
| Old | New |
|---|---|
A label in the query string answered 400 (labels_in_query) | Labels are read from the body only. A label in the URL is ignored. |
| Labels were checked by hand, in two places | One schema parses the labels on both paths |
listObjects parsed maxKeys by hand (max_keys_invalid) | The route's schema parses it |
The upload handler checked the folder path (core.static_asset.folder_*) | The storage helper checks it |
| The server upload's default key was the lowercased name | The default key is <keyPrefix><folderPath>/<uuid>/<name> |
serverUpload.maxBytes also refused a whole body over maxBytes | It bounds each file |
Serve routes copied Content-Encoding, Cache-Control, ETag and Last-Modified from storage metadata | They send ETag and Last-Modified from the stat |
StaticAssetControllerFactory.resolveServedContentType decided the served type | StaticAssetServe.resolveServedContentType, same options and answer |
directUpload.authorize was required | Optional when the entry's auth authenticates or authorizes. |
Details for the rows above:
- Labels. The schema parses
principalType,principalId,variantandsequence. Asequencethat is not an integer is the standard validation error (422) on both paths. maxKeys. A bad value is the standard validation error.- Folder path. The storage helper answers
core.storage.folder_path_invalidandcore.storage.folder_depth_exceeded. The segment check is part of the path check. - Default key. A second upload of
report.pdfused to overwrite the first. Now uploads never overwrite each other, and a client that built the URL from the file name must readobject.keyorlinkfrom the response. The uuid folder does not count againstmaxFolderDepth. maxBytes. The body limit ismaxFilesxmaxBytesplus framing, so two 3 MB files pass under 5 MB.resolveServedContentType.StaticAssetServeis exported, withapplyValidatorsfor a route of your own.- Serve routes. The old copy of those headers never worked in practice, because the stat holds them outside the metadata. The routes now answer
304toIf-None-MatchandIf-Modified-Since. NoCache-Controlis set.
The folder, labels and maxKeys changes also change codes. See the error reference.
Unchanged, on purpose
StaticAssetIngestUtility.fromUrl, rawObjectPath, extend.before and extend.after, and the recreateMetaLink route stay. commit, verify and validate keep their parameters, and owner is now required: see Resolvers replace resolveOwner. validate now also answers a commitToken: see The validation handler.
New and not breaking
- The download route honours a
Rangeheader, likegetObjectByName. BunS3HelperandDiskHelperdeclarestorageType. OnIStorageHelperit is optional, so a custom helper compiles, but an entry refuses a helper that declares neitherdisknorbun-s3.
One declaration, before and after
// Before
{
assets: {
auth: { authenticate: { strategies: ['jwt'] }, publicRead: true },
controller: {
name: 'AssetController',
basePath: '/assets',
isStrict: true,
bucket: 'uploads',
keyPrefix: 'tenant-a',
routes: { getBuckets: { enabled: true }, deleteObject: { enabled: false } },
directUpload: {
authorize: ({ context }) => Boolean(context.get('currentUser')),
secretKey,
maxBytes: 100 * 1024 * 1024,
expires: { upload: { unit: 'minute', value: 10 } },
onCommit: scanForViruses,
},
},
storage: StaticAssetStorageTypes.BUN_S3,
helper: storageHelper,
useMetaLink: true,
metaLink: { model: BaseMetaLinkModel, repository: metaLinkRepository },
extra: {
maxBytes: 10 * 1024 * 1024,
maxFolderDepth: 3,
parseMultipartBody: { storage: 'disk', uploadDir: './spool', maxFiles: 5 },
normalizeLinkFn: ({ object }) => `https://cdn.example.com/${object.key}`,
},
resolveObjectName: ({ defaultKey }) => defaultKey,
defineExtraRoutes: addHealthRoute,
},
}// After
import { Authentication } from '@venizia/ignis';
import { z } from '@hono/zod-openapi';
import { DurationUnits } from '@venizia/ignis-helpers';
import type { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';
import { StaticAssetValidation } from '@venizia/ignis/static-asset';
import type {
BaseMetaLinkRepository,
TStaticAssetComponentOptions,
TStaticAssetDefineExtraRoutes,
} from '@venizia/ignis/static-asset';
export const migrated = (opts: {
storageHelper: BunS3Helper;
metaLinkRepository: BaseMetaLinkRepository;
secretKey: string;
addHealthRoute: TStaticAssetDefineExtraRoutes;
scanForViruses: (opts: { bucketName: string; key: string }) => Promise<string[]>;
}): TStaticAssetComponentOptions => ({
assets: {
name: 'AssetController',
basePath: '/assets',
bucket: 'uploads',
keyPrefix: 'tenant-a/',
helper: opts.storageHelper,
link: ({ object }) => `https://cdn.example.com/${object.key}`,
auth: {
authenticate: { strategies: [Authentication.STRATEGY_JWT] },
publicRead: { use: true },
},
routes: { deleteObject: { use: false } },
maxFolderDepth: 3,
serverUpload: { use: true, maxBytes: 10 * 1024 * 1024, maxFiles: 5 },
directUpload: {
use: true,
secretKey: opts.secretKey,
maxBytes: 100 * 1024 * 1024,
resolvers: {
owner: ({ context }) => String(context.get(Authentication.CURRENT_USER).userId),
},
expires: { upload: { unit: DurationUnits.MINUTE, value: 10 } },
// onCommit is gone: the check that ran there is the validation.
validation: StaticAssetValidation.define({
issueSchema: z.object({ message: z.string() }),
handler: async ({ file }) => {
const problems = await opts.scanForViruses({ bucketName: 'uploads', key: file.key });
return { isValid: problems.length === 0, issues: problems.map((message) => ({ message })) };
},
}),
},
metaLink: { use: true, repository: opts.metaLinkRepository },
extend: { after: opts.addHealthRoute },
},
});What changed besides names:
getBucketsis gone with every bucket route. There is nothing to turn on.directUpload.authorizeis left out becauseauthalready authenticates every route.resolveObjectName: ({ defaultKey }) => defaultKeydid nothing, soobjectKeyis left out.storageis gone: the helper is an S3 helper, so MetaLink rows recordbun-s3.parseMultipartBodyis gone: the body is held in memory, somaxBytesis the guard.keyPrefixgained a trailing slash. Both spellings work, because the component normalizes it.
Direct upload entries
keyPrefix is now required with directUpload. It keeps the pending files out of everything the routes serve. An entry that had no keyPrefix must add one, and that has two effects:
- Committed keys move under the prefix. An object already committed at the bucket root (
<generated>/<name>) is outside the new scope, so the entry answers404for it. Move the object under the prefix, and update its MetaLink row, or keep the old objects reachable through another entry on the same bucket without a prefix. - Tokens issued before the upgrade fail. A commit token names the old pending key, which is outside the new scope. The commit refuses it. Users upload again.
An entry that already had a keyPrefix keeps its keys. Check that pendingPrefix (default pending/) and keyPrefix do not contain one another, or the entry refuses to start. See The pending prefix.
Resolvers replace resolveOwner
directUpload.resolveOwner is now directUpload.resolvers.owner, and it is required: a token is always signed for an owner.
// Before
directUpload: {
use: true,
resolveOwner: ({ context }) => userIdOf(context),
// ...
},import type { TStaticAssetDirectUploadOptions } from '@venizia/ignis/static-asset';
declare const userIdOf: (context: unknown) => string;
export const directUpload: { use: true } & TStaticAssetDirectUploadOptions = {
use: true,
secretKey: 'replace-with-a-real-secret',
maxBytes: 100 * 1024 * 1024,
validation: { use: false },
resolvers: { owner: ({ context }) => userIdOf(context) },
};Also changed with it:
- The services take a required
owner.verifyis async and answers{ bucket, object, owner, metadata }.commitanswersownerandmetadatatoo. - The validation handler takes
{ file, owner, metadata }. - A commit refuses a destination that already holds an object (
409upload_already_committed), and a policy refuses afileNamethat is not one valid key segment (400object_name_invalid). - Tokens issued before the upgrade fail with
400invalid_commit_token. Users upload again.
The validation handler
The handler takes { file, owner, metadata } and reads through file. It no longer receives helper, bucket or object. file is a StaticAssetPinnedFile: key, size and stream({ range? }). See Validation.
// Before
handler: async ({ bucket, object, owner, helper }) => {
const fileStream = await helper.getObject({ bucket, object });
const issues = await checkWorkbook({ fileStream, owner });
return { isValid: issues.length === 0, issues };
},import { z } from '@hono/zod-openapi';
import { StaticAssetValidation } from '@venizia/ignis/static-asset';
export const workbookValidation = (opts: {
checkWorkbook: (opts: {
stream: ReadableStream<Uint8Array>;
owner: string;
}) => Promise<string[]>;
}) =>
StaticAssetValidation.define({
issueSchema: z.string(),
// After
handler: async ({ file, owner }) => {
const stream = await file.stream();
const issues = await opts.checkWorkbook({ stream, owner });
return { isValid: issues.length === 0, issues };
},
});file.stream() returns a web ReadableStream, where helper.getObject returned a Node Readable. Convert with Readable.fromWeb if your parser needs a Node stream.
upload-validate now answers { isValid, issues, commitToken? }, and upload-commit takes only that token when validation is on:
| Step | Before | Now |
|---|---|---|
upload-validate answer | { isValid, issues } | { isValid, issues, commitToken? }, the new validated token present only when isValid is true |
upload-commit body | the policy's commitToken | the commitToken validate returned |
commit with the policy's token | ran the handler again | 422 core.static_asset.upload_not_validated |
| A file that changed after validate | copied | 409 core.static_asset.upload_changed, nothing copied |
Update every client that posts to upload-commit: send the token from the validate answer. With validation off nothing changes. A token issued before the upgrade does not carry the new fields, so it answers 400 invalid_commit_token and the user uploads again.
Links already stored
With the bucket in the URL gone, the object route is /objects/{objectName} and the download route is /download/{objectName}. A MetaLink row written before the upgrade holds the old link (/assets/buckets/uploads/objects/...) in its link column.
- Without a
createMetaLinkhook,PUT /meta-links/{objectName}rewriteslinkfor every row of that object. - With a hook, the hook owns
link: update the column with a migration of your own. - A client that built URLs by hand drops
/buckets/{bucketName}from them.
Services built by hand
Most apps never construct the two services: the component builds and binds them. If yours does, the options changed.
StaticAssetUploadPolicyService
| Option | Shape |
|---|---|
| Options now | { scope, helper, bucket, keyPrefix, directUpload } |
directUpload | { maxBytes, expires?, secretKey, pendingPrefix? } |
issuePolicies takes owner, required.
StaticAssetUploadCommitService
| Option | Shape |
|---|---|
| Options now | { scope, helper, bucket, keyPrefix, objectKeyMaxDepth, directUpload, storage, metaLink?, link } |
directUpload | { secretKey, pendingPrefix?, resolvers, validation? } |
keyPrefix is a string on both. StaticAssetControllerFactory.build({ key, entry, policyService?, commitService? }) resolves the entry itself, so a hand-built controller takes the entry as you wrote it.
Find and replace
Search a file at a time and read each hit: these move options between objects, so a blind replace misses the nesting.
| Search | Replace with |
|---|---|
controller: { | lift its keys onto the entry |
{ enabled: false } | { use: false } |
{ enabled: true } | { use: true } |
useMetaLink: true, | delete the line, and add use: true to metaLink |
storage: StaticAssetStorageTypes. | delete the line |
extra: { | split into serverUpload and link |
resolveObjectName / normalizeNameFn | serverUpload.objectKey |
normalizeLinkFn (in an entry) | link |
defineRoutesBefore | extend.before |
defineExtraRoutes | extend.after |
publicRead: true | publicRead: { use: true } |
onCommit | delete, and move the check into validation.handler |
handler: async ({ bucket, object, helper }) | handler: async ({ file, owner }), and read through await file.stream() |
model: BaseMetaLinkModel (in a metaLink) | delete the line |
query (in a createMetaLink hook) | labels |
StaticAssetStorageTypes | StorageTypes |
A toggle you did not have before is required. Add serverUpload, directUpload and metaLink to every entry, as { use: false } where the feature was off.
Earlier renames
The names of the component's exports changed in an earlier release - StaticAssetComponentBindingKeys to StaticAssetBindingKeys, AssetControllerFactory.defineAssetController to StaticAssetControllerFactory.build, the @app/static-asset-component/... key strings to @app/static-asset/..., and the rest. The changelog lists each one with its replacement.
Files:
packages/core-server/src/components/static-asset/common/types.ts-TStaticAssetEntrypackages/core-server/src/components/static-asset/utilities/entry.utility.ts- the start-up rules