56 lines
2.6 KiB
Markdown
56 lines
2.6 KiB
Markdown
# Internal: File Operations
|
|
|
|
`internal/fileops` owns the narrow mechanics for atomically visible replacement of one
|
|
byte file. Callers keep ownership of serialization, validation, cancellation,
|
|
and destination-directory policy.
|
|
|
|
## Destination Paths
|
|
|
|
Ordinary workspace replacement uses standard operating-system path semantics.
|
|
Callers with a root-scoped safety contract own that validation at their boundary.
|
|
|
|
Remote object acquisition uses a writer supplied by the storage owner. The
|
|
writer receives a `fileops`-owned, already-open sibling temporary file rather
|
|
than a mutable destination path. Callers still own remote object selection,
|
|
validation, conflict handling, and final mode.
|
|
|
|
Directory promotion keeps the verified destination parent open while it creates
|
|
the temporary tree, copies regular source entries, and performs the platform
|
|
no-replace rename. Platforms without a verified handle-relative atomic
|
|
no-replace primitive reject promotion before writing a temporary tree.
|
|
|
|
## Cleanup Contract
|
|
|
|
`RemoveAllUnderRoot` accepts an explicit root and a proper descendant, opens
|
|
that root with `os.OpenRoot`, and removes the normalized root-relative target
|
|
with `Root.RemoveAll`. It rejects root, traversal, and out-of-root targets; a
|
|
missing target is successful. `RemoveFileUnderRoot` additionally requires an
|
|
existing leaf to be regular. Command and post-publish policy remains owned by
|
|
`internal/app`.
|
|
|
|
## Bounded Reads
|
|
|
|
`ReadFileBounded` opens a normal path and reads at most its caller-supplied
|
|
limit. Credential mode policy and environment precedence remain owned by
|
|
`internal/app`.
|
|
|
|
## Replacement Contract
|
|
|
|
`ReplaceFileAtomic` requires an existing destination directory. It creates a
|
|
sibling temporary file, writes the complete byte sequence, applies the
|
|
caller-supplied mode, closes the file, runs an optional pre-rename check, and
|
|
replaces the destination with a rename.
|
|
|
|
The pre-rename check is the last point at which a caller can cancel without
|
|
installing a new destination. A failure before the rename leaves the old
|
|
destination unchanged and removes the temporary file. Successful replacement
|
|
provides atomic visibility; it makes no crash- or power-loss durability claim.
|
|
|
|
Replacement follows the operating system's same-filesystem rename semantics.
|
|
If a platform cannot replace an existing destination, the operation returns an
|
|
error and never removes the old file as an emulation step.
|
|
|
|
`WriteFileAtomic`, copy helpers, and downloaded temporary-file installation
|
|
retain their compatibility behavior of creating the destination parent with
|
|
the repository's workspace permissions before using this contract.
|