fs

Overview ¶

Package fs is Harbor's filesystem ArtifactStore driver. It is the single-binary production target — durable across process restart, no external dependency, suitable for embedded deployments.

Storage layout:

<root>/<tenant>/<user>/<session>/<task>/<namespace>/<id>
<root>/<tenant>/<user>/<session>/<task>/<namespace>/<id>.meta.json

Empty `TaskID` becomes the literal directory `_` so the scope hierarchy stays five levels deep (the consumer pattern is "session-scoped artifacts have empty task," and we want their directories distinguishable from a task literally named ""). The other identity components are mandatory and validated upstream.

Atomicity. Each Put writes blob + meta as a pair of `tmp.<id>` / `tmp.<id>.meta.json` files, then `os.Rename`s each in turn. On crash mid-write only fully-renamed pairs are visible; stray `tmp.*` files from a crash are best-effort cleaned by `New` at startup (any remaining ones are harmless — `Get` ignores them).

Path safety. Per AGENTS.md §7 #5: every constructed path is run through `filepath.Clean` and then prefix-checked with the canonicalized root. The `Filename` field in `PutOpts` is metadata only — never used in path construction (the `id` is). The path-safety test exists as defense in depth.

Concurrency. A single `sync.RWMutex` guards the in-memory ref index that mirrors disk; the index is rebuilt at `New` time by scanning `<root>` and re-reading `.meta.json` files. The lock scope spans both the index update and the disk operations to keep them atomic from the caller's POV. Cross-process concurrent access to the same root is OUT OF SCOPE for V1 (one binary, one root); a locking strategy for that lands when a phase needs it.