feat: add host-provided module object storage
`manifest.storage.buckets` has existed since manifest version 1 and meant nothing — discovery validated it and no code read it. This turns it into a real capability, which is what stands between Announcements and the module system: that product currently fetches a hardcoded LAN S3 endpoint, parses ListObjectsV2 XML by hand, and hands the browser direct object URLs. - A module declares a logical bucket and receives a scoped facade at `context.storage` — list, head, get, put, delete. The contract names no provider: no endpoint, region, credential, or physical bucket is reachable from it, which is what lets the same module run under a future standalone host over its own or a shared S3-compatible service. - Core's first provider speaks S3 through the AWS SDK. SeaweedFS is the deployment target (ADR 0004), never an API name. Probing the pinned image found `CreateBucket` reporting `BucketAlreadyExists` rather than AWS's `BucketAlreadyOwnedByYou`; treating only the AWS spelling as success would have failed every second boot. A live test pins it. - Logical → physical mapping is deterministic and collision-safe: an installation prefix, the module and bucket ids joined by `--` (which cannot occur inside either identifier, so `a-b`+`c` and `a`+`b-c` cannot collide), and a digest over the full untruncated identity. Two modules declaring `assets` always get separate namespaces; neither can see the physical name. - Declaring a bucket is now a requirement: with no provider configured the module is `blocked · storage_unavailable` through ADR 0028's existing resolver, propagating to required dependents. An installation with no object storage stays a complete deployment. - Binding availability is not provider health. Eligibility asks whether storage is configured, never whether it answered; bucket creation is lazy on first use so a storage outage cannot stop the platform booting; a running module whose store blinks stays running and retries. Nothing deletes a bucket. - Credentials are deployment-supplied, never persisted, never routed through module configuration, and never visible to modules, module UI, diagnostics, or API responses. Provider errors translate to a closed code set carrying no endpoint, bucket, request id, or XML. - Retires ADR 0029's transitional `bucket` configuration key. No manifest version change. The template declares no bucket, so it still runs without S3. See ADR 0030. Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
co-authored by
Claude Opus 5
parent
527239f6de
commit
b9ca0d560d
@@ -356,3 +356,29 @@ is hot-reloaded. Migration discovery remains independent of configuration validi
|
||||
independent of enabled state. Endpoints and credentials for shared infrastructure stay platform
|
||||
concerns — a module declares which bucket it needs, not an S3 endpoint — leaving room for the object
|
||||
storage service Core still does not have. There is no settings UI.
|
||||
|
||||
Phase 7A pass 3 turns `manifest.storage.buckets` — inert since manifest version 1 — into a real
|
||||
host-provided capability ([ADR 0030](decisions/0030-host-provided-module-object-storage.md)). A module
|
||||
declares a **logical** bucket and receives a scoped facade at `context.storage` offering list, head,
|
||||
get, put, and delete, with `get` returning a Web stream so an object never has to be buffered. The
|
||||
contract names no provider: there is no endpoint, region, credential, or physical bucket reachable
|
||||
from it, which is what lets the same module run under a future standalone host backed by its own or a
|
||||
shared S3-compatible service.
|
||||
|
||||
The host owns everything else. Core's first provider speaks the S3-compatible protocol through the
|
||||
AWS SDK against a configured endpoint, with SeaweedFS as the intended deployment target (ADR 0004) but
|
||||
never as an API name. A logical bucket maps to a physical one deterministically — a configurable
|
||||
installation prefix, the module and bucket ids joined by a separator that cannot occur inside either,
|
||||
and a digest over the full identity — so two modules declaring `assets` are always isolated and one
|
||||
storage service can host several installations. Bucket creation is idempotent and lazy on first use;
|
||||
nothing ever deletes a bucket.
|
||||
|
||||
Storage is optional: an installation without a provider is complete, and only a module that *declares*
|
||||
a bucket is affected — it is reported `blocked · storage_unavailable` through ADR 0028's existing
|
||||
resolver, propagating to required dependents. Crucially, eligibility asks whether storage is
|
||||
**configured**, never whether it answered: a configured provider that is briefly unreachable stays an
|
||||
operational error a module retries through, never a lifecycle state, so the platform is no less
|
||||
resilient than the products it will absorb. Startup performs no storage I/O at all. Credentials are
|
||||
deployment-supplied, never persisted, never routed through module configuration, and never visible to
|
||||
modules, module UI, diagnostics, or API responses. Browsers reach objects through a module's own
|
||||
routes; signed URLs and public object delivery are deferred.
|
||||
|
||||
Reference in New Issue
Block a user