S3

Manages private file uploads and downloads between browsers and Amazon S3, tracking ownership and file state in SpacetimeDB with automatic retry on failure.

  • TypeScript
npm i @spacetimedb/s3

A SpacetimeDB module that manages private file storage backed by Amazon S3, handling the coordination layer between your app's users and the bucket. It lives server-side in your SpacetimeDB module and tracks file ownership, upload state, and deletion, while the actual file bytes travel directly between the browser and S3.

  • User-generated content: A social or productivity app where each user uploads their own documents, images, or attachments that only they can access.
  • Resumable workflows: Any app where uploads or deletes must survive server restarts or intermittent S3 failures without manual intervention.
  • Per-user quotas: A SaaS product that needs to enforce per-account file count and storage limits enforced on the server, not the client.
  • Secure file delivery: Apps that need time-limited download links generated server-side so files are never publicly accessible.
  • Existing SpacetimeDB apps adding file storage: A game or collaborative tool already on SpacetimeDB that needs to attach binary assets to its existing identity and permission model.

When a user wants to upload a file, the module reserves a slot in the database, signs a short-lived upload form, and hands it back to the browser. The browser posts the file directly to S3 using that form, so the file bytes never pass through SpacetimeDB. Once the browser signals that the upload is done, the module copies the file into its permanent location inside the bucket and verifies the checksum. Until that verification succeeds, the file is not considered ready.

All ongoing work, finishing a copy, retrying after a failure, removing deleted files from S3, is driven by a scheduled background task that runs every few seconds. This means the module can pick up where it left off after a restart or a transient S3 error, and it will keep retrying for up to an hour before giving up and cleaning up the failed upload.

Ownership and access control are enforced entirely on the server. The module ties each file to a SpacetimeDB identity, and your app decides who may upload, download, or delete by checking that identity in the relevant procedures. AWS credentials are stored privately in the database and are never exposed to clients. Download links are signed on demand and expire after a configurable window.

Related modules

Files

Module for storing and serving files (avatars, attachments) in SpacetimeDB apps. Supports upload, rename, delete, listing, visibility controls, and HTTP serving with caching.

SpacetimeDB0/wk

Agents

Stores conversations and runs AI assistants inside your SpacetimeDB module, with tools that can read and update your application's data.

SpacetimeDB0/wk

Auth

Adds user accounts, password and OAuth sign-in, email verification, and session management to a SpacetimeDB module. Exposes helpers to identify the caller in reducers and HTTP routes.

SpacetimeDB0/wk
Submodule

Edit details

One short paragraph describing the module.

A few bullets for scenarios where this is a good fit.

A few short paragraphs at the conceptual level.