Storage
1. Overview
| Property | Value |
|---|---|
| Status | Stable |
| Owner | platform |
| Depends on | BunS3Helper (@venizia/ignis-helpers/bun-s3), APP_ENV_S3_* |
| Controllers | AssetController (/assets), BanksVNController (/assets/banks-vn) |
Object storage is S3/Minio-only via a single
BunS3Helperbound at component init. There is no local-disk backend (ADR-0001).
2. Entity Model
Storage operations produce a MetaLink row per uploaded object (see Domain Model). Objects themselves live in S3, keyed by bucketName + objectName.
3. Lifecycle
| From | Event | To | Guards |
|---|---|---|---|
* | upload | Stored | folderPath ≤2 segments, each isValidName |
Stored | get/download | streamed | isValidPath(name, maxDepth:2) |
Stored | delete | Removed | isValidPath; MetaLink rows deleteAll'd (async) |
Object names are a fresh
crypto.randomUUID().slice(0,8)per upload — the literali18n.jsonis the only preserved name. Uploads are not idempotent.
4. Operations
| Handler | Purpose | Inputs | Output |
|---|---|---|---|
AssetController UPLOAD | Store files in S3 + create MetaLinks | multipart body, query principalType/principalId/variant/folderPath | [{ objectName, link, metaLink }] |
AssetController GET_OBJECT_BY_NAME | Stream object inline | path objectName | binary stream |
AssetController DOWNLOAD_OBJECT_BY_NAME | Stream as attachment | path objectName | binary + Content-Disposition |
AssetController GET_I18N / DOWNLOAD_I18N | Stream i18n.json from APP_ENV_S3_BUCKET | — | binary stream |
AssetController DELETE_OBJECT | Remove S3 object + MetaLinks | path objectName | { success: true } |
AssetController LIST_OBJECTS | List bucket objects | query prefix/recursive/maxKeys | [{ name, size, lastModified, etag, prefix }] |
BanksVNController GET_BANKS_VN_REGISTRY | VN bank registry JSON (absolutized logo URLs) | — | JSON map (cache 1h) |
BanksVNController GET_BANK_VN_LOGO | Stream a bank PNG from disk | path filename (^[A-Za-z0-9]+\.png$) | image/png (cache 7d immutable) |
5. REST Endpoints
Full schemas render live from the host's
/doc/openapi.json. Source:controllers/asset/definition.ts,controllers/banks-vn/definition.ts.
| Verb | Path | Auth | Handler |
|---|---|---|---|
POST | /assets/upload | BASIC / JWT | AssetController UPLOAD |
GET | /assets/objects | BASIC / JWT | LIST_OBJECTS |
GET | /assets/objects/i18n | public | GET_I18N |
GET | /assets/download/i18n | public | DOWNLOAD_I18N |
GET | /assets/objects/{objectName} | public | GET_OBJECT_BY_NAME |
GET | /assets/download/{objectName} | public | DOWNLOAD_OBJECT_BY_NAME |
DELETE | /assets/objects/{objectName} | BASIC / JWT | DELETE_OBJECT |
GET | /assets/banks-vn | public | GET_BANKS_VN_REGISTRY |
GET | /assets/banks-vn/{filename} | public | GET_BANK_VN_LOGO |
Paths shown relative to the asset controllers; the actual prefix is the host base path (e.g.
/v1/api/commerce/assets/upload).
6. Events
Inbound / Outbound: none. Storage is synchronous REST + S3 only (see API Events).