Skip to content

Commit 25a1ad6

Browse files
docs Zoo-Code-Org#2357: say what the backup option and a DACL refusal actually promise
- the backup option docstring still described the old rename-away-and-rollback flow; it now describes the copy flow, including that the copy is never a rollback source and what happens to it when removal fails - DaclInspectionError's docstring now says causeError carries the platform failure behind the refusal rather than null Comment text only - no executable line changed. parse, prettier, eslint and the safeWriteText spec (77 passed) re-run green on this head.
1 parent 87d4aff commit 25a1ad6

1 file changed

Lines changed: 14 additions & 4 deletions

File tree

‎src/services/file-safety/safeWriteText.ts‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,16 @@ import { getErrorCode } from "../../utils/errorCode"
77

88
export interface SafeWriteTextOptions {
99
/**
10-
* When true, preserve the old-file semantics: rename target -> backup first,
11-
* after commit rename delete the backup; on failure roll the backup back to
12-
* the target path. When false (default) the atomic rename simply replaces
13-
* the target -- crash-safe window is zero.
10+
*
11+
* When true, keep a durable copy of the previous content at a sibling
12+
* safeWriteText.bak_* file for the duration of the write: the target is copied
13+
* before the commit rename and the copy is removed after it. The copy is never
14+
* a rollback source - nothing is restored on failure, because the copy never
15+
* displaced the target: before the commit the target still holds its previous
16+
* content, and after it the target holds the new content and this call removes
17+
* the copy, reporting it as OrphanedBackupAfterFailedWriteError if the removal
18+
* itself fails. When false (default) the atomic rename simply replaces the
19+
* target -- crash-safe window is zero.
1420
*/
1521
backup?: boolean
1622

@@ -216,6 +222,10 @@ export class PostCommitDurabilityError extends Error {
216222
* replace it with a file that inherits different rights. On Windows the publish is refused before
217223
* anything is committed: a save that silently widened who can read the file is not a save the
218224
* caller can trust, and nothing has been published yet, so the target still holds its content.
225+
* causeError carries the platform failure behind the refusal - the access check
226+
* error or the icacls error - so a caller can tell a command that ran and refused
227+
* from one that could not be started at all; it is the runner's own error, not a
228+
* summary of it.
219229
*/
220230
export class DaclInspectionError extends Error {
221231
constructor(

0 commit comments

Comments
 (0)