Architecture Overview
Multistore is an S3-compliant gateway that sits between clients and backend object stores. It provides authentication, authorization, and transparent proxying with zero-copy streaming.
High-Level Architecture
Design Principles
Runtime-agnostic core — The core proxy logic (multistore) has zero runtime dependencies. No Tokio, no worker-rs. It compiles to both native and WASM targets.
Path-based router — A Router maps URL paths to RouteHandler implementations using matchit for efficient matching. Extension crates provide Router extension traits (e.g., OidcRouterExt, StsRouterExt) for one-call registration, keeping protocol-specific logic out of runtimes.
Two-phase dispatch — The ProxyGateway separates request resolution from execution. resolve_request() determines what to do; the runtime executes it. This keeps streaming logic in runtime-specific code where it belongs.
Presigned URLs for streaming — GET, HEAD, PUT, and DELETE operations use presigned URLs. The runtime forwards the request directly to the backend — no buffering, no double-handling of bodies.
Pluggable traits — Four trait boundaries enable customization:
Router/RouteHandler— Path-based pre-dispatch request interception (STS, OIDC discovery, custom endpoints)BucketRegistry— Bucket lookup, authorization, and listingCredentialRegistry— Credential and role storageProxyBackend— How the runtime interacts with backends
Key Components
| Component | Crate | Responsibility |
|---|---|---|
| ProxyGateway | multistore | Router-based dispatch + S3 parsing + identity resolution + two-phase dispatch |
| BucketRegistry | multistore | Bucket lookup, authorization, listing |
| CredentialRegistry | multistore | Load credentials and roles |
| STS Route Handler | multistore-sts | OIDC token exchange, credential minting |
| OIDC Provider | multistore-oidc-provider | Self-signed JWT minting, OIDC discovery, backend credential exchange |
| Server Runtime | multistore-server | Tokio/Hyper HTTP server |
| Workers Runtime | multistore-cf-workers | WASM-based Cloudflare Workers |
Further Reading
- Crate Layout — How the workspace is organized
- Request Lifecycle — How a request flows through the proxy
- Multi-Runtime Design — How the same core runs on native and WASM