1.7 KiB
Internal: File Operations
internal/fileops owns the narrow mechanics for durable replacement of one
byte file. Callers keep ownership of serialization, validation, cancellation,
and destination-directory policy.
Replacement Contract
ReplaceFileAtomic requires an existing destination directory. It creates a
sibling temporary file, writes the complete byte sequence, applies the
caller-supplied mode, syncs and closes the file, runs an optional pre-rename
check, replaces the destination with a rename, then syncs the containing
directory.
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; any cleanup failure is returned alongside the primary failure. A failure after the rename may leave the new file visible, but it is not reported as crash-durable.
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.
Directory-Sync Support
Linux and macOS attempt to sync the destination directory. Windows opens the
directory with backup semantics and flushes its buffers. If either operation
is unavailable for the platform, directory handle, or filesystem,
ErrDirectorySyncUnsupported is returned. Narratio does not treat that result
as successful crash-durable replacement.
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.