This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
enroll/diff.py
BundleRef (dataclass)
Purpose: represents a prepared harvest bundle that diff can read from.
Fields:
dir: Path: directory containing at least state.json and (optionally) artifacts/
tempdir: Optional[tempfile.TemporaryDirectory]: Set only when the bundle had to be extracted/decrypted into a temporary directory. Lets the caller clean up later
Property:
state_path -> Path: dir / "state.json"
Lifecycle / where it's used:
Constructed by _bundle_from_input(path, sops_mode=...) which accepts:
- bundle directory
- direct state.json path
- .tar.gz/.tgz
- .sops encrypted tarball (or when --sops is enabled)
compare_harvests() uses ExitStack to ensure any tempdir.cleanup() happens.
Key design detail:
This class is the bridge between "user supplied something" and “we have a real directory with files”.
FileRec (frozen dataclass)
Purpose: a normalized record for one harvested file entry, used for diff indexing.
Fields:
- path: absolute destination path on the target system (e.g. /etc/nginx/nginx.conf)
- role: which role captured it (e.g. nginx, etc_custom, users)
- src_rel: relative path inside that role’s artifact tree (usually path.lstrip("/"))
- owner, group, mode: file metadata captured during harvest (strings)
- reason: why the file was captured (modified_conffile, systemd_dropin, etc.)
Lifecycle / where it's used:
Built by _file_index(bundle_dir, state) which walks all managed_files across:
- services, package roles, users, apt_config, etc_custom, usr_local_custom, extra_paths
- compare_harvests() compares:
- existence (added/removed)
- metadata differences
- content hash differences by hashing the corresponding artifact file at:
artifacts/<role>/<src_rel>
Important semantic choice:
The file index key is the absolute path. If duplicates appear, the first wins.