What it is
A composable module for storing, serving, and managing user files (such as avatars and message attachments) directly inside a SpacetimeDB application. It sits in the server-side layer of a SpacetimeDB module, handling file metadata and binary content in the database while exposing upload, rename, delete, list, and HTTP download capabilities to the rest of the app.
Where it fits
- User avatars and profile images: An app where each user uploads a profile picture that other users can view publicly via a cached HTTP route.
- Chat attachments: A messaging app where users attach files to conversations, with per-owner storage quotas and private-by-default visibility.
- Content management: A small CMS or dashboard where authenticated users manage a folder-like hierarchy of assets and need paginated directory listings.
- Secure file downloads: An app that needs to gate file access behind application-level auth, serving private files only to verified callers while caching public ones efficiently.
- Multi-tenant storage: A platform where many users share the same path namespace without collision, each subject to their own storage quota.
How it works
Files are stored in two parts: a metadata record and a separate binary record. Keeping them separate means that listing files, checking whether a file exists, or responding to a cache-validation request never requires loading the raw bytes. Each file belongs to an owner (identified by any opaque string the host application chooses, such as a user ID) and is addressed by a path within that owner's namespace. Two different owners can use the same path without conflict.
Visibility controls whether a file is accessible to anyone or only to its owner. The module enforces size limits per file and a total quota per owner at write time, and it computes a content fingerprint server-side so that HTTP clients can cache responses and skip re-downloading unchanged files. The HTTP serving layer handles cache headers, conditional responses, and content-type safety automatically, including forcing non-image types to download rather than render in the browser.
The host application wires the module into its own reducers and procedures, deciding how to derive the owner identity from the authenticated caller. Access control for private files over HTTP is left to the host, which can integrate with a separate auth module to verify the request before passing it through. This design keeps the file module focused on storage mechanics while letting the application own its own identity and permission model.
