Documentation
¶
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:
THE READ HAS THREE ANSWERS, NEVER TWO. "no box" is a VERIFIED FACT -- a fuse box that was never created holds no blown fuses. "cannot read the box" is a THIRD answer and it is never the reassuring one. A reader that collapses them (an exists-style probe answers false both when the file is absent AND when the directory above it cannot be stat'd) turns a permissions change into "nothing blown" -- a fail-open in a safety control. os.ReadFile + errors.Is(err, fs.ErrNotExist) tells UNREADABLE apart from NONEXISTENT, which is why the read is written with the stdlib primitive that distinguishes those two rather than the one that does not. What that primitive does NOT distinguish: a missing box file from a missing parent directory -- both come back fs.ErrNotExist, so `--box /no/such/dir/fuses.json` also answers VERIFIED CLEAR. Accepted, deliberately, not overlooked: --box is a locator, the caller's statement of where the box lives, and a caller that names the wrong box gets that box's truth -- here, an empty one. The case is pinned by test (TestCheckIntoANonexistentDirectoryIsAlsoClear in cmd/nova-fuse), so changing this answer is a decision, never a drive-by.
MALFORMED IS UNREADABLE. A JSON array, a bare string, a truncated file, a lockdown whose value is not an object -- every one fails the unmarshal and comes back as CANNOT TELL, which every caller must treat as BLOWN. Reaching the fail-closed answer by a crash deep inside a caller is not a design; this is.
THE WRITE IS TEMP-FILE + RENAME. 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 your 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. Two copies of the tool blowing fuses at once lose one WRITE, but neither can produce a corrupt box.
SURFACE NAMES ARE MATCHED NORMALIZED. Raw string comparison lets `quarantine Discord` then `check discord` answer CLEAR -- a fail-OPEN in a safety control, reached by a capital letter. Normalizing can only ever collapse two names into one, which blocks more and never less.
Index ¶
Constants ¶
const UnreadableSuffix = ".unreadable"
UnreadableSuffix names where the bytes of an unreadable box are kept when a lockdown has to clobber it. Back up before mutating what cannot be reconstructed: a corrupt fuse box is evidence -- of a torn write, a bad hand-edit, or something worse -- and blowing an emergency power must not be the thing that destroys it.
Variables ¶
This section is empty.
Functions ¶
func PreserveUnreadable ¶
PreserveUnreadable copies an unreadable box aside before it is replaced. It returns the destination it TRIED, so the caller can name it either way -- reporting where the bytes went and reporting that they could not be saved are both better than silence.
Types ¶
type Box ¶
Box is the whole fuse box. Lockdown is a pointer so that absent, null and present are three distinguishable states rather than one zero value.
func ReadBox ¶
ReadBox returns the fuse box, or the reason it could not be read. See note 1.
A nil error with an empty Box means VERIFIED CLEAR. A non-nil error means CANNOT TELL, and the only correct treatment of that is BLOWN.
func (Box) LiftQuarantine ¶
LiftQuarantine removes EVERY quarantine entry matching surface (normalized, see note 4) and returns the removed entries under their stored keys, so the caller can announce exactly what was lifted and why it had been blown. An empty surface matches NOTHING, mirroring Quarantined: a missing argument must never empty the box.
Every match is removed, not just the first: the box is hand-editable, so two spellings of one surface can coexist, and a lift that removed only one would leave the surface still answering as quarantined -- a lift that verifies its own failure.
THE SOFT HALF ONLY. The fuse design separates the powers: quarantine is your own decision in both directions, so this function exists; lockdown is hard -- a blown fuse is not reset, it is REPLACED, and only in a live conversation with your person -- so no LiftLockdown exists here, and none may be added.
func (Box) Quarantined ¶
Quarantined answers whether this surface is blocked, returning the key AS STORED so a refusal can quote the file rather than the caller's spelling of it.
An empty surface matches NOTHING, and the caller must say so out loud: a check with no surface has verified only that there is no lockdown, and a printed claim must never outrun what was measured.
Source Files