Fief.Wire (Fief v0.1.0)

Framework envelope shapes (implementation.md §8). Three shapes, built and parsed only here, versioned by a protocol integer:

{:fief, 1, :msg,   epoch, vnode, payload, from | nil}
{:fief, 1, :moved, epoch, delta}
{:fief, 1, :peer,  session, payload}

Payloads are opaque to the framework. The epoch in :msg is the sender's cached epoch — a fencing token for diagnostics, not an equality check.

Summary

Types

decoded()

delta()

envelope()

epoch()

session()

vnode_id()

Functions

decode(term)

Decode an inbound term. Non-fief terms and unsupported protocol versions are distinguished so receivers can drop vs. log-and-drop.

moved(epoch, delta)

Build a :moved envelope carrying a routing delta.

msg(epoch, vnode, payload, from \\ nil)

Build a :msg envelope.

peer(session, payload)

Build a :peer envelope; delivered only on session match (framework-enforced).

protocol_version()

The wire protocol version this build speaks.

Types

decoded()

@type decoded() ::
  {:msg, epoch(), vnode_id(), payload :: term(), from :: term() | nil}
  | {:moved, epoch(), delta()}
  | {:peer, session(), payload :: term()}

delta()

@type delta() :: [{vnode_id(), owner :: term()}]

envelope()

@type envelope() :: tuple()

epoch()

@type epoch() :: non_neg_integer()

session()

@type session() :: {vnode_id(), donor :: node(), recipient :: node(), epoch()}

vnode_id()

@type vnode_id() :: non_neg_integer()

Functions

decode(term)

@spec decode(term()) ::
  {:ok, decoded()} | {:error, {:unsupported_protocol, term()} | :not_fief}

Decode an inbound term. Non-fief terms and unsupported protocol versions are distinguished so receivers can drop vs. log-and-drop.

iex> Fief.Wire.msg(7, 3, :ping) |> Fief.Wire.decode()
{:ok, {:msg, 7, 3, :ping, nil}}

iex> Fief.Wire.decode({:fief, 99, :msg, 7, 3, :ping, nil})
{:error, {:unsupported_protocol, 99}}

iex> Fief.Wire.decode(:other)
{:error, :not_fief}

moved(epoch, delta)

@spec moved(epoch(), delta()) :: envelope()

Build a :moved envelope carrying a routing delta.

iex> Fief.Wire.moved(8, [{3, :"b@host"}])
{:fief, 1, :moved, 8, [{3, :"b@host"}]}

msg(epoch, vnode, payload, from \\ nil)

@spec msg(epoch(), vnode_id(), term(), term() | nil) :: envelope()

Build a :msg envelope.

iex> Fief.Wire.msg(7, 3, {:key, :get}, nil)
{:fief, 1, :msg, 7, 3, {:key, :get}, nil}

peer(session, payload)

@spec peer(session(), term()) :: envelope()

Build a :peer envelope; delivered only on session match (framework-enforced).

iex> session = {3, :"a@host", :"b@host", 8}
iex> Fief.Wire.peer(session, {:pull, "k"})
{:fief, 1, :peer, {3, :"a@host", :"b@host", 8}, {:pull, "k"}}

protocol_version()

@spec protocol_version() :: pos_integer()

The wire protocol version this build speaks.