eric/distributor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Document internal component contracts

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-31 04:06:48 +00:00
parent eac73a79a1
commit 93c22884b0
8 changed files with 225 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/internal/storage.md
View File

@@ -24,10 +24,18 @@ Logical file paths must be non-empty, relative, clean, slash-separated, and must
Storage errors use typed categories such as not found, already exists, invalid path, conflict, permission, temporary, unsupported, and unknown. Callers should use helper predicates rather than matching error strings.
Backends may wrap implementation-specific errors, but callers should receive storage errors where practical. Traversal can stop cleanly with `ErrStopWalk`.
## Deletion
Backends expose guarded managed deletion only. `DeleteManagedBundle` may delete listed managed outputs plus `.distributor.json`; it does not provide broad recursive deletion.
## Local and fake backends
The local adapter maps logical paths to a configured filesystem root and keeps adapter-specific path handling behind the storage interface.
The fake backend is an in-memory implementation for package tests. It is not registered for runtime use.
## Tests
Before changing storage behavior, inspect tests under:
@@ -35,3 +43,11 @@ Before changing storage behavior, inspect tests under:
- `internal/storage`
- `internal/storage/fake`
- `internal/adapters/local`
## Invariants
- Core packages depend on `internal/storage`, not concrete adapters.
- Logical paths are slash-separated and confined to the backend root.
- `storage.List` uses backend traversal and returns deterministic entries.
- Managed deletion is limited to recorded outputs plus `.distributor.json`.
- Runtime backend registration is owned by `internal/app`.