feat: add host-provided module object storage
CI / verify (pull_request) Successful in 36s
CI / infrastructure-smoke (pull_request) Successful in 13s
CI / migration-smoke (pull_request) Failing after 2m20s

`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:
ekklesia
2026-08-23 08:45:53 -05:00
co-authored by Claude Opus 5
parent 527239f6de
commit b9ca0d560d
55 changed files with 4420 additions and 74 deletions
-8
View File
@@ -30,14 +30,6 @@
"description": "Prefix this module puts in front of a record value."
}
],
"storage": {
"buckets": [
{
"id": "records",
"description": "Private objects owned by this example module."
}
]
},
"entrypoints": {
"server": "./dist/server/index.js",
"schema": "./dist/schema/index.js",
+10 -1
View File
@@ -4,6 +4,7 @@ import {
ANONYMOUS_PRINCIPAL,
type CapabilityId,
EMPTY_MODULE_CONFIGURATION,
EMPTY_MODULE_STORAGE,
type ModuleConfiguration,
type ModuleDatabase,
type ModuleRouteDefinitionInput,
@@ -69,7 +70,11 @@ describe("module template", () => {
description: "Read example records.",
},
]);
expect(manifest.storage.buckets.map((bucket) => bucket.id)).toEqual(["records"]);
// The template declares **no** logical storage bucket, deliberately. Since ADR 0030 a declared
// bucket is a real requirement: a module that declares one is blocked on an installation with no
// object-storage provider. A starting point that could not run without S3 configured would be a
// poor starting point, so storage is something a module author opts into.
expect(manifest.storage.buckets).toEqual([]);
expect(manifest.entrypoints.schema).toBe("./dist/schema/index.js");
expect(manifest.entrypoints.migrations).toBe("./drizzle");
});
@@ -134,6 +139,9 @@ describe("module template", () => {
params: Object.freeze({}),
principal: ANONYMOUS_PRINCIPAL,
services,
// The template declares no logical bucket, so it receives storage that refuses every one —
// present rather than `undefined`, so module code never branches on whether the host has it.
storage: EMPTY_MODULE_STORAGE,
});
const response = await route.handler(new Request("http://localhost/records"), context);
@@ -175,6 +183,7 @@ describe("module template", () => {
params: Object.freeze({}),
principal: ANONYMOUS_PRINCIPAL,
services: Object.freeze({ database: fakeModuleDatabase(fakeRows) }),
storage: EMPTY_MODULE_STORAGE,
});
const response = await route.handler(new Request("http://localhost/records"), context);