38 lines
1.7 KiB
Markdown
38 lines
1.7 KiB
Markdown
# Storage
|
|
|
|
## Purpose
|
|
|
|
`internal/storage` defines backend-rooted logical file access for core packages. Callers use slash-separated paths relative to a configured backend root.
|
|
|
|
## Inputs and outputs
|
|
|
|
The storage interface supports byte reads, stream reads, byte writes, stream writes, exact metadata lookup, traversal, destination emptiness checks, and guarded managed deletion.
|
|
|
|
Entries report a logical path, type, and size when available. Entry types are `file`, `directory`, `symlink`, and `other`.
|
|
|
|
## Boundaries
|
|
|
|
Core packages should depend on `internal/storage`, not adapter packages. Adapter-specific path handling stays behind backend implementations.
|
|
|
|
The local adapter lives in `internal/adapters/local`. Runtime backend construction is wired through the app-level backend factory and storage registry. The fake backend lives in `internal/storage/fake` for tests and is not registered for runtime use.
|
|
|
|
## Paths
|
|
|
|
Logical file paths must be non-empty, relative, clean, slash-separated, and must not contain `.` or `..` segments or backslashes. Prefix paths follow the same rules, except an empty prefix means the backend root.
|
|
|
|
## Failure behavior
|
|
|
|
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.
|
|
|
|
## Deletion
|
|
|
|
Backends expose guarded managed deletion only. `DeleteManagedBundle` may delete listed managed outputs plus `.distributor.json`; it does not provide broad recursive deletion.
|
|
|
|
## Tests
|
|
|
|
Before changing storage behavior, inspect tests under:
|
|
|
|
- `internal/storage`
|
|
- `internal/storage/fake`
|
|
- `internal/adapters/local`
|