49 lines
1.5 KiB
Markdown
49 lines
1.5 KiB
Markdown
# Internal: Storage
|
|
|
|
## Purpose
|
|
|
|
Explain the object-store interface and S3 implementation used by Narratio.
|
|
Remote key layout and lifecycle belong in [Operations](../operations.md), while
|
|
operator-selected storage fields and credential mechanisms belong in
|
|
[Configuration](../config.md).
|
|
|
|
## 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`
|