Files and Object Storage
Files and Object Storage
Section titled “Files and Object Storage”sigMAX provides object storage for application files and a versioned history for project artifacts. The inspected runtime includes a Node.js file service backed by MinIO, host-mediated WASM blob operations, and Studio tools for browsing and restoring generated files.
These capabilities complement PostgreSQL storage. Their availability depends on configured services and declared bindings; the Core and Pro distinction concerns deployment and the WASM execution boundary.
Three Ways To Work With Files
Section titled “Three Ways To Work With Files”Application file service
JSON operations to write, read, list and delete objects in logical buckets.
WASM host primitives
Bounded blob.get, blob.put, blob.head and blob.delete calls through a declared Dapr binding.
Studio project storage
Versioned contracts, code, WASM binaries, reports and other generated artifacts, with file restoration and project snapshots.
The file service and the blob.* primitives use different interfaces. A running file service does not automatically configure a dapr_blob binding. The selected adapter must implement the operations expected by its caller.
Application Files And Buckets
Section titled “Application Files And Buckets”The file service creates its default MinIO bucket at startup and enables versioning. Additional logical buckets are placed inside the configured namespace and also have versioning enabled. The default bucket is protected from bucket deletion.
All operations below use HTTP POST with a JSON body on the private file-service interface.
| Endpoint | Supported behavior |
|---|---|
/files/write | Store UTF-8 content or binary contentBase64, with an optional contentType. Return path, byte size, ETag and version ID. |
/files/read | Read the current object or a supplied versionId. Return Base64 content and object metadata. |
/files/list | Recursively list current objects under an optional prefix, with sizes, ETags and modification dates. |
/files/delete | Remove the current object through MinIO’s versioned deletion behavior. |
/buckets/list | List buckets in the configured namespace, including creation dates and current object counts. |
/buckets/create | Create a named bucket with versioning enabled. |
/buckets/delete | Delete a named bucket; force: true first removes its retained object versions. |
Object requests accept an optional logical bucket; omission selects default. Object names and list prefixes reject parent traversal. They identify storage objects, not host filesystem paths.
For example, the JSON body of a text write can be:
{ "bucket": "default", "path": "reports/summary.txt", "content": "Report ready", "contentType": "text/plain; charset=utf-8"}The returned versionId can be supplied to a later read. The application file service does not expose a version-history listing or a restore endpoint; Studio’s artifact history is a separate surface.
Files From Business WASM
Section titled “Files From Business WASM”Business modules refer to a logical binding and object key. The host checks the operation’s capability and resolves a binding of kind dapr_blob before invoking the configured Dapr component. Storage credentials and physical locations stay outside the module.
| Primitive | Result |
|---|---|
blob.get | Copy object bytes into the caller’s bounded output buffer. |
blob.put | Write bytes through the declared storage binding. |
blob.head | Read the object’s size without fetching its body. |
blob.delete | Request object deletion through the binding. |
The current Rust host limits object keys to 512 bytes, each get or put value to 1 MiB, and the combined blob operations to 64 calls per request. Keys cannot be absolute paths, contain backslashes, empty path segments or .. segments. A capability alone is insufficient: the logical binding and its Dapr component must also exist.
These are verified Rust-host primitives. The COS2000 executor has its own implementation status and host interface; equivalent behavior must be established by the Pro integration.
Artifact History And Project Snapshots
Section titled “Artifact History And Project Snapshots”Studio stores project artifacts in a dedicated versioned MinIO bucket. The generated directory on disk is a materialized working copy. File views expose current content, retained versions, ETags, timestamps and sizes.
Studio can:
- read a specific retained version of a generated file;
- restore an older file by writing it as a new current version;
- create, list, restore and delete project snapshots;
- retain a snapshot manifest and archived copies of selected project objects;
- create an automatic backup snapshot before restoration and record a restoration audit.
Snapshot restoration checks project identity and the signed-contract digest. Individual governed contract artifacts cannot be restored over an active signature through the ordinary file restore route; an addendum is required. Restore routes also reject conflicting active generation work.
Project snapshots capture project objects and artifacts. They do not constitute a backup of the running PostgreSQL database or of every application bucket.
Studio Management
Section titled “Studio Management”When the MinIO extent is installed, Studio exposes bucket listing, creation, deletion, content browsing and object reads through its topology API. The topology service starts MinIO with a project-scoped persistent volume and starts the file adapter with a Dapr sidecar on the private runtime network.
The generation pipeline also produces generated/file-storage.yaml, recording the MinIO provider configuration references and which components require file storage. This declaration is useful when checking a component’s service dependencies.
Configuration And Effective Limits
Section titled “Configuration And Effective Limits”| Setting | Purpose |
|---|---|
FILE_BIND | File-service listener; defaults to 0.0.0.0:8091. |
FILE_MAX_BODY_BYTES | JSON request and decoded file limit; defaults to 16 MiB. |
MINIO_ENDPOINT | Object-store endpoint; HTTPS is used when configured in the URL. |
MINIO_BUCKET | Default bucket and prefix for additional logical buckets. |
MINIO_REGION | Region used when creating buckets. |
MINIO_ACCESS_KEY, MINIO_SECRET_KEY | Credentials held by the service. |
The file adapter buffers requests and downloaded objects in memory. Base64 expands binary data, so a write’s JSON body can hit the 16 MiB request limit before the decoded object reaches 16 MiB. A WASM or public HTTP route may impose a smaller limit.
The inspected file API has no presigned upload/download URL, multipart upload or streaming endpoint. Listing is recursive and has no exposed pagination parameter. These are the current adapter limits, independent of MinIO’s wider capabilities.
The file adapter itself has no per-user authentication layer. Its private network placement and the authorized calling surface determine access. MinIO versioning preserves object history; retention policies and external backups require separate configuration.
Implementation References
Section titled “Implementation References”The behavior described here is implemented in file-service/src/index.js and file-service/src/paths.js, with WASM primitives in runtime/src/primitives.rs. Studio’s artifact history and snapshots are in studio/apps/api/src/services/projects.ts; service provisioning is in studio/apps/topology/src/docker.ts in the inspected sigMAX_runtime repository.
Continue with the runtime capability catalogue or database operations.