The blob-transport behaviour (implementation.md §7, Decision): how the
extracted per-key state travels between donor and recipient. v1 ships
in-band (Fief.Transfer.Channel.InBand) — the blob rides the :peer
payload on dist — behind a hard max_blob_size; an out-of-band TCP channel
is the planned fast-follow implementing this same behaviour.
ship/2 runs on the donor at freeze time (ledger assembly) and returns the
term that rides the wire in {:grant, key, wire_blob} / {:push, key, wire_blob}; fetch/2 runs on the recipient before the key's init/3
rehydrates it (and on the donor for a {:resume, key, blob} after regaining
ownership) and returns the original blob. In-band, both are (checked) identity; an
out-of-band channel would return a handle from ship/2 and dereference it
in fetch/2.
Enforcement point (Decision): the size cap is enforced at freeze — the
earliest donor-side ship gate — so the residual ledger only ever holds
shippable blobs and no new machine event is needed for the failure. A blob
the channel refuses is excluded from the ledger with a loud
Logger.error naming the :max_blob_size config (plus a
:blob_rejected checkpoint); the recipient's pull then converges through
the machine's own path — {:not_here, key} → escheat from durable truth.
Un-persisted state in an unshippable blob is lost; that is the stated
failure semantics, same class as node death.
ctx carries %{instance:, vnode_id:, key:, max_blob_size:}.
Summary
Types
What rides the :peer payload: the blob itself (in-band) or a handle.
Callbacks
Recipient side (and donor resume): recover the blob from its wire form.
Donor side, at freeze: admit (and possibly stage) a blob for transport.
Types
@type wire_blob() :: term()
What rides the :peer payload: the blob itself (in-band) or a handle.
Callbacks
@callback fetch(wire_blob(), ctx :: map()) :: {:ok, Fief.Transfer.blob()} | {:error, term()}
Recipient side (and donor resume): recover the blob from its wire form.
@callback ship(Fief.Transfer.blob(), ctx :: map()) :: {:ok, wire_blob()} | {:error, term()}
Donor side, at freeze: admit (and possibly stage) a blob for transport.