ekklesiaandClaude Opus 5
b9ca0d560d
`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]>
52 lines
2.4 KiB
TypeScript
52 lines
2.4 KiB
TypeScript
import type {
|
|
ModuleStorageBody,
|
|
ModuleStorageListOptions,
|
|
ModuleStorageListing,
|
|
ModuleStorageObject,
|
|
ModuleStorageObjectMetadata,
|
|
ModuleStoragePutOptions,
|
|
} from "@ekklesia/contracts";
|
|
|
|
/**
|
|
* The seam between Core's module-facing storage facade and whatever actually stores bytes.
|
|
*
|
|
* This is the **portability boundary made executable**. Everything above it — the scoped facade,
|
|
* binding resolution, lifecycle eligibility, diagnostics — is provider-agnostic and would be
|
|
* identical in a standalone host. Everything below it is one implementation
|
|
* (`createS3StorageProvider`) that could be replaced without any module changing a line.
|
|
*
|
|
* It deliberately speaks in **physical buckets**: resolving a module's logical bucket to a physical
|
|
* one has already happened by the time anything reaches here (`./binding.js`), so a provider never
|
|
* has to know what a module is. That split is what keeps scoping enforcement in exactly one place
|
|
* rather than duplicated into every provider.
|
|
*
|
|
* Also deliberately absent: any operation that *destroys* a bucket. Core never deletes a bucket, so
|
|
* there is no method to call by mistake, and disabling or removing a module cannot take data with it
|
|
* (ADR 0030).
|
|
*/
|
|
export interface StorageProvider {
|
|
/**
|
|
* Makes sure a physical bucket exists, idempotently.
|
|
*
|
|
* Called lazily on first use of a binding rather than at startup, so a storage outage can never
|
|
* prevent the platform from booting.
|
|
*/
|
|
ensureBucket(physicalBucket: string): Promise<void>;
|
|
list(physicalBucket: string, options: ModuleStorageListOptions): Promise<ModuleStorageListing>;
|
|
head(physicalBucket: string, key: string): Promise<ModuleStorageObjectMetadata>;
|
|
get(physicalBucket: string, key: string): Promise<ModuleStorageObject>;
|
|
put(
|
|
physicalBucket: string,
|
|
key: string,
|
|
body: ModuleStorageBody,
|
|
options: ModuleStoragePutOptions,
|
|
): Promise<ModuleStorageObjectMetadata>;
|
|
delete(physicalBucket: string, key: string): Promise<void>;
|
|
/** A cheap reachability probe for diagnostics only. Its result is **never** persisted and never
|
|
* influences a module's lifecycle state — a provider being briefly unreachable is an operational
|
|
* condition, not an administrative decision (ADR 0030). */
|
|
probe(): Promise<void>;
|
|
/** Releases provider connections. Called once, during API shutdown. */
|
|
close(): Promise<void>;
|
|
}
|