fuse

Overview ¶

Package fuse is the STATE half of the ingestion fuse: reading and writing the box, the JSON file the two emergency powers live in. cmd/nova-fuse is the thin command on top of it. The box's path always comes from the caller — there is no default location and no environment variable, per this repo's no-guessed-paths rule.

WHAT IS ACTUALLY DECIDED HERE, and why each one is not arbitrary:

1. THE READ HAS ONE YES AND TWO NOES. A readable box says what it says. "cannot read the box" is CANNOT TELL, and "no box at the path" is CANNOT TELL too: a fuse box that is not where the caller said can prove nothing is blown, and a reader that answered it with an empty box turned a mistyped --box, a box moved or deleted, or a second --box pointing somewhere empty into VERIFIED CLEAR -- a fail-open in a safety control. Both noes are errors, and every caller must treat an error as BLOWN; ErrNoBox tells them apart, so a refusal can name the right remedy (CreateBox for the first, a hand repair for the second). Lstat refuses a link or non-regular path before open; SameFile then proves the opened descriptor is the file that was inspected. The read is limited to 1 MiB and refuses a file that reaches the limit: a box is only a few lines, and an unbounded read lets a directory writer exhaust memory. errors.Is with fs.ErrNotExist distinguishes absent from unreadable; it does not say which part of the path is missing, and it does not need to, since both answers refuse. A box comes into being by CreateBox, which never replaces one, or by a write verb on a box that was read.

2. MALFORMED IS UNREADABLE. A JSON array, a bare string, a truncated file, a lockdown whose value is not an object -- every one fails the decode and comes back as CANNOT TELL, which every caller must treat as BLOWN. A bare JSON null fails no decode -- a struct ignores it with no error -- so the read requires a JSON OBJECT at the top level before it decodes anything, and names the kind it found instead: a null, an array, a string, a number or a boolean is refused, because a wrong-shaped value is CANNOT TELL, never the VERIFIED CLEAR a normalised empty map would make of it. Its remedy is a hand restoration, not init: init is the remedy for a path with no box and never replaces one. An UNKNOWN top-level member is refused too, which is the policy for a gate: a key the reader does not know is a key it cannot account for, and answering CLEAR over a box someone meant to block with it is the fail-open this package exists to prevent. `"quarantine": null` stays deliberately supported -- a box a person hand-edits into that shape is a readable empty box. Reaching the fail-closed answer by a crash deep inside a caller is not a design; this is.

3. THE WRITE IS TEMP-FILE + RENAME, PUBLISHED UNDER THE BOX'S LOCK. The file whose corruption means PERMANENT LOCKDOWN must never be left torn: a truncating write can leave half a file if the process dies, and a half file is an unreadable box that only a person can clear, by hand, live. Rename within one directory is atomic, so a reader sees the old box or the new one and never a fragment. A box mutation (MutateBox) holds the lock file beside the box -- <box>.lock, pkg/filelock -- across its read, its change and its publish, so two copies of the tool blowing fuses at once land BOTH writes, and neither can produce a corrupt box. The one deliberate exception is a lockdown whose lock cannot be taken: it blows unserialized rather than not at all -- a fuse you cannot blow is not a fuse -- and cmd/nova-fuse says so on a NOTE line (BoxLockUntaken tells that failure from a box that cannot be written at all).

4. SURFACE NAMES ARE MATCHED NORMALIZED, AND THAT CUTS BOTH WAYS. Raw string comparison lets `quarantine Discord` then `check discord` answer CLEAR -- a fail-OPEN in a safety control, reached by a capital letter. Normalizing collapses spellings into one surface, and the honest statement of what that does is not "it can only ever block more": it is that EQUIVALENT SPELLINGS ARE ONE SURFACE, IN BOTH DIRECTIONS. `check` refuses on any spelling, so the class blocks more. LiftQuarantine removes EVERY spelling in the class, so a lift lifts more too -- deliberately, because a lift that left one spelling behind would verify its own failure, and because an operator who lifts a surface means the surface. It is not silent either way: each removal is returned under its stored spelling so the caller can announce it on its own line. The consequence to know: a box holding two keys that fold together holds ONE surface, not two.

5. THE ESCAPE LIVES AT PRINT TIME, because the tool cannot trust what it did not write. The box is world-readable on purpose (a fuse nobody else can see is a fuse that stops nothing) and hand-editable on purpose (that is the only lockdown-replacement mechanism there is), so on a shared machine the reason, the `at` stamp and the stored surface names are authored by whoever can write the file. Echoed raw into a one-line output grammar, a newline forges a SECOND event line beneath a real one -- a `FUSE OK lockdown=clear` under a `FUSE FAIL`, which a caller scanning the grammar reads as permission -- and an ESC sequence does the same to an operator's terminal. cmd/nova-fuse prints every such string through pkg/oneline's Escape, which escapes every control character as the text is printed and so holds for a box this tool never wrote; Fold only tidies what this tool writes itself, and is never a refusal, because a fuse you cannot blow is not a fuse. Constraining writes alone would defend exactly the case that needs no defending. The escaped set is category Cc plus U+2028 and U+2029, which break a line for readers that follow Unicode rather than counting newlines. Folding also widens the surface classes of note 4, in both directions -- see there.