Skip to content

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.

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.

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.

EndpointSupported behavior
/files/writeStore UTF-8 content or binary contentBase64, with an optional contentType. Return path, byte size, ETag and version ID.
/files/readRead the current object or a supplied versionId. Return Base64 content and object metadata.
/files/listRecursively list current objects under an optional prefix, with sizes, ETags and modification dates.
/files/deleteRemove the current object through MinIO’s versioned deletion behavior.
/buckets/listList buckets in the configured namespace, including creation dates and current object counts.
/buckets/createCreate a named bucket with versioning enabled.
/buckets/deleteDelete 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.

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.

PrimitiveResult
blob.getCopy object bytes into the caller’s bounded output buffer.
blob.putWrite bytes through the declared storage binding.
blob.headRead the object’s size without fetching its body.
blob.deleteRequest 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.

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.

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.

SettingPurpose
FILE_BINDFile-service listener; defaults to 0.0.0.0:8091.
FILE_MAX_BODY_BYTESJSON request and decoded file limit; defaults to 16 MiB.
MINIO_ENDPOINTObject-store endpoint; HTTPS is used when configured in the URL.
MINIO_BUCKETDefault bucket and prefix for additional logical buckets.
MINIO_REGIONRegion used when creating buckets.
MINIO_ACCESS_KEY, MINIO_SECRET_KEYCredentials 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.

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.