Skip to main content

Module files

Module files 

Source
Expand description

The file operations of task programs, behind the fs functions and the dotenv reads of env.load_file and env.read.

Every operation resolves its path against the task directory, where an absolute path stands for itself and paths outside the tree are allowed, and it records each access it makes in the task’s Accesses:

  • a read of a file’s content is a read, and a path found missing is a probe;
  • an existence check is a probe;
  • reading a directory’s entries is a list, and a missing directory is a probe;
  • a write is a write of the file and of every parent directory it created.

Writes happen only when the content differs, so an unchanged file keeps its timestamps; a write is recorded either way. A write that changes the file is also a change, which FileChanges keeps with when it happened, so a pass in which a task program changed a file does work and the task is the file’s last writer. Text is UTF-8: bytes that are not valid UTF-8 are replaced with U+FFFD, as with command output. JSON is written in a stable form: object keys sorted by their UTF-8 bytes, indent spaces per level, and a trailing newline.

For the observation report of kizz run --output, the operations can also note how each access ended (Files::noting): into AccessOutcomes, ok for an access whose operation succeeded, and otherwise the number of the system’s error, which AccessOutcomes::observations names through the tracer’s error-name query, such as ENOENT for a missing file’s probe. Without it, as in every build, nothing more than the accesses is kept.

No operation can panic (“Kizz never panics”): a glob pattern is split at its first glob component with slice::get, never split_at, and the indentation of JSON is built in space reserved with String::try_reserve_exact, never with str::repeat, which panics when the length overflows, so an indent too large for memory is an error of the write.

Structs§

AccessOutcomes
How the file accesses of a task program ended, for the observation report of kizz run --output: each path with its access kinds, and each kind with how the operations that made it ended, before the errors are named.
ChangedFile
A file that a task program changed, and when.
FileChanges
The files that a task program changed through fs.write and fs.write_json, in the order it first changed each one, without repeats.
Files
The file operations of one task: paths resolve against the task directory, and every access is recorded, with every file a write changed.

Enums§

FileError
A file operation that failed.

Functions§

stable_json
value as stable JSON: object keys sorted by their UTF-8 bytes, each element and member on its own line indented by indent spaces per level, ": " between a key and its value, empty arrays and objects as [] and {}, and a trailing newline.