Internal: Storage

Purpose

Explain the object-store interface and S3 implementation used by Narratio. Remote key layout and lifecycle belong in Operations, while operator-selected storage fields and credential mechanisms belong in Configuration.

Primary Contract

storage.ObjectStore interface:

List(ctx, prefix)
Download(ctx, key, localPath)
Upload(ctx, localPath, key, opts)
Exists(ctx, key)

Key invariant:

callers pass full bucket-relative keys;
storage implementations do not infer campaign/session/run prefixes.

Composition

NewObjectStoreFromConfig constructs the S3-backed implementation from resolved configuration. The application loads configured filesystem secrets before calling it. The storage adapter consumes already-resolved values; it does not own discovery, defaults, or configuration validation.

S3 Backend Behavior

normalizes object keys.
List paginates and returns normalized ObjectInfo.
Download writes local files with parent directory creation.
Upload streams local file and returns remote metadata.
Exists maps not-found responses to false.

Invariants

storage layer is stateless regarding manifest/stage progression.
publish ordering semantics are owned by stage/app code, not storage adapters.

Implementation And Tests

Contract and S3 adapter: internal/adapters/storage
Composition: internal/app/object_store.go
Tests: internal/adapters/storage/*_test.go, internal/app/object_store_test.go

1.5 KiB Raw Blame History