Fief.Transfer.Channel behaviour (Fief v0.1.0)

Copy Markdown View Source

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

wire_blob()

@type wire_blob() :: term()

What rides the :peer payload: the blob itself (in-band) or a handle.

Callbacks

fetch(wire_blob, ctx)

@callback fetch(wire_blob(), ctx :: map()) ::
  {:ok, Fief.Transfer.blob()} | {:error, term()}

Recipient side (and donor resume): recover the blob from its wire form.

ship(blob, ctx)

@callback ship(Fief.Transfer.blob(), ctx :: map()) ::
  {:ok, wire_blob()} | {:error, term()}

Donor side, at freeze: admit (and possibly stage) a blob for transport.