this repo has no description
1(** Atomic directory replacement.
2
3 Implements a staging/commit/rollback pattern for updating a
4 directory without partial visibility. On commit, the sequence is:
5
6 + Rename existing final dir to [.old] backup
7 + Rename staging dir to final location
8 + Remove [.old] backup
9
10 If the process crashes between steps, {!cleanup_stale} recovers on
11 the next startup by removing orphaned [.new] and [.old] directories.
12
13 This module has no domain knowledge — the caller provides the
14 target directory path directly.
15
16 Several functions require [env] because they may need to remove
17 root-owned directories via sudo. *)
18
19val cleanup_stale :
20 Eio_unix.Stdenv.base ->
21 Fpath.t ->
22 (unit, [> Rresult.R.msg ]) result
23(** [cleanup_stale env dir] recursively scans [dir] and removes any
24 directories whose names end in [.new] or [.old] (leftovers from
25 crashed swaps). Uses sudo for root-owned directories. *)
26
27val prepare :
28 Fpath.t -> (Fpath.t, [> Rresult.R.msg ]) result
29(** [prepare target] creates a staging directory at [target ^ ".new"]
30 and returns its path. Removes any existing staging dir from a
31 previous failed attempt. The caller writes content into the
32 returned path, then calls {!commit} or {!rollback}. *)
33
34val commit :
35 Eio_unix.Stdenv.base ->
36 Fpath.t ->
37 (bool, [> Rresult.R.msg ]) result
38(** [commit env target] atomically swaps the staging directory
39 ([target ^ ".new"]) into [target]. Returns [Ok true] if the swap
40 succeeded, [Ok false] if there was no staging directory. On
41 failure, attempts to restore the previous state. Uses sudo to
42 remove the old directory. *)
43
44val rollback :
45 Eio_unix.Stdenv.base ->
46 Fpath.t ->
47 (unit, [> Rresult.R.msg ]) result
48(** [rollback env target] removes the staging directory
49 ([target ^ ".new"]) without committing. Uses sudo if needed. *)