skarbiec fence

Invocation#

skarbiec fence arm --transaction <T> [--reason <text>]
skarbiec fence lift --transaction <T>
skarbiec fence show

Purpose#

Hold every write to the vault while it is moved to another host, so nothing is written to the copy being moved, while reads go on; or, with a reason, hold the copy a move left behind for good.

Required inputs and options#

• --transaction names the move's own id. --reason, on arm only, is one line saying why writes are held (such as `the vault moved to <host>`); it is kept in the fence and said by every refusal and read. Every other command takes --fence <T>, which lets its writes through a fence armed for T: the move's own steps (owner rotate, recipient add, grant issue, set and so on).

Output and state effects#

• arm takes the vault's write lock, so a write already under way finishes first, then writes {transaction, since} — and reason, when given — to <vault without .json>.fence.json beside the vault, which moves with it, and journals fence-arm; while it stands every vault write is refused — set and every other save, and pull, mirror pull and backup restore, which check it under the same lock — and every POST /v1/items/read and /v1/items/revision answer carries fence {transaction, since, reason}. A fence file that cannot be read stops every write, and reads still answer, carrying fence {unreadable: <why>}. A second arm for the same transaction answers already true. lift removes the file and journals fence-lift; lift with no fence standing answers lifted false. show prints the vault and the fence, or null.

Refusals#

• A write while fenced is refused with `the vault is moving (transaction <T>, since <S>); retry after it`, or, when the fence has a reason, `writes to this vault are held: <reason> (transaction <T>, since <S>)`, naming --fence <T> for the move's own steps and `skarbiec fence lift --transaction <T>`; one passing another transaction is refused the same way, and nothing is written. arm while a write holds the vault's lock is refused with `fence arm: a write to the vault is in progress; run fence arm again once it ends`, writing no fence. arm of another transaction is refused naming the one standing; lift of another transaction is refused naming it; arm with no vault is refused naming SKARBIEC_VAULT_FILE; a fence file that does not parse or names no transaction or time is refused naming fence lift. arm or lift without --transaction, a --reason that is empty or holds a line break, and any other flag, exit 2 naming it.

Examples#

Real test: SKARBIEC=<binary> tests/vault/fence.sh arms, writes refused and passed, reads the fence through serve, lifts, and checks each refusal; report.txt under target/real-tests/fence.