Documentation
¶
Overview ¶
Package jsonedit edits one top-level key of a JSON config file that another program (Claude Code) also rewrites: atomically, verified by reading back, every other key byte-identical, and backs such files up with rotation. It imports only the standard library. Unix only (flock, stat owner and link count); aimux ships for darwin and linux.
Index ¶
- Variables
- func Backup(path, dir string, keep int) (string, error)
- func EditKey(path, key string, fn func(old json.RawMessage) (json.RawMessage, error)) error
- func EditKeyVerbatim(path, key string, fn func(old json.RawMessage) (json.RawMessage, error)) error
- func ReplaceMemberVerbatim(obj json.RawMessage, key string, value json.RawMessage) (json.RawMessage, error)
- func SetMember(obj json.RawMessage, key string, value json.RawMessage) (json.RawMessage, error)
Constants ¶
This section is empty.
Variables ¶
var ErrConcurrentWrite = errors.New("config kept changing while editing; it holds the other writer's last version, without this edit")
ErrConcurrentWrite means another writer kept changing the file while EditKey worked on it. The file holds that writer's last version: either none of our writes landed, or the last one was replaced.
Functions ¶
func Backup ¶
Backup copies path to dir/<base>.<UTC 20060102T150405Z>, 0600, keeping the newest keep copies; returns the copy's path.
The stamp is the later of now and the newest existing backup's, so a clock that went back cannot make the new copy sort oldest. A second backup with the same stamp gets "-1", "-2", ... appended (one past the highest already there, so a name freed by rotation is never reused and order stays newest last). dir is created 0700 if missing. Rotation only removes files named like this file's backups; anything else in dir stays.
func EditKey ¶
func EditKey(path, key string, fn func(old json.RawMessage) (json.RawMessage, error)) error
EditKey rewrites one top-level key of the JSON object at path with fn(old) (old is nil when absent), keeping every other key byte-identical, writing atomically (temp in same dir, original mode, rename), re-reading to verify, and retrying from a fresh read up to 5 times if the file changed in between.
fn returning nil removes the key. fn may run once per attempt, each time on the value just read, and only the last call's result is written: it must be a pure function of old (it may record what it decided, last call wins), must do no I/O and must not call EditKey (the directory lock is not reentrant, so a nested call waits out the lock timeout and fails).
The new value is reformatted to the file's top-level style (indented like the first entry, or compact). Everything outside the key's value is copied from the original bytes, so the other keys, their order and the whitespace between them are unchanged. Nothing is written when the value does not change. If path is a symlink its target is edited.
Concurrency: aimux editors serialize on an advisory flock of the file's directory (waiting up to 10 s). Around the write window (the pre-rename check through the rename) EditKey also holds <file>.lock, a directory in proper-lockfile's format, in case the other writer (Claude Code bundles proper-lockfile) honours it; harmless if it does not. A change made by a writer that ignores both, between the read and the rename, is detected by re-reading just before the rename and starts the edit over. One window remains: a write landing between that re-read and the rename (one syscall) is replaced by ours. After the rename the file is read back; if our value is not in it the edit starts over. A read that does not parse (a torn read of a file being rewritten in place) waits 50 ms and starts over; the file is reported invalid only when two reads in a row return the same invalid bytes.
func EditKeyVerbatim ¶
func EditKeyVerbatim(path, key string, fn func(old json.RawMessage) (json.RawMessage, error)) error
EditKeyVerbatim is like EditKey but does not reformat fn's returned value. Use when fn has already formatted the value to preserve internal structure (e.g., SetMember preserving sibling members' formatting). The value must still be valid JSON.
func ReplaceMemberVerbatim ¶
func ReplaceMemberVerbatim(obj json.RawMessage, key string, value json.RawMessage) (json.RawMessage, error)
ReplaceMemberVerbatim returns obj with the existing member key's value replaced by value's exact bytes (not reformatted), so a value saved earlier can be put back byte for byte. An absent member is an error.
func SetMember ¶
func SetMember(obj json.RawMessage, key string, value json.RawMessage) (json.RawMessage, error)
SetMember returns obj with one member set to value (nil value removes the member). Every other member's bytes, order and whitespace are preserved. The new value is formatted to match obj's style (indented if obj is multi-line, compact if inline). obj must be a JSON object; arrays and other types are refused. Duplicate members are refused.
Types ¶
This section is empty.