Group.Transport behaviour (Group v0.3.1)

Transport contract for Group replica data.

Implementations must return promptly and must never wait for socket or remote mailbox backpressure. This applies to outgoing/5 and the optional lifecycle callbacks. Returning :busy or :disconnected is safe: replica anti-entropy will retransmit the missing state.

Erlang distribution remains Group's control plane and supplies the stable node identity used here. A sideband adapter can use its descriptor/2 in the control hello to exchange endpoints and pass incoming messages to incoming/4 or incoming_batch/4. source_node is routing metadata supplied by the adapter; Group uses it to validate stream origins and member pids.

Adapters do not need to preserve ordering. Group serializes writes per shard and sequences each origin/generation/shard/cluster/epoch stream; receivers discard duplicates and request gaps. Per-shard ordered delivery avoids repair traffic and is therefore the preferred fast path.

A sideband implementation can delegate outgoing/5 to Group.Transport.Outbox.push/5. That adds one local send only for the configured sideband transport; the default distribution adapter retains its direct remote :erlang.send_nosuspend/3 path.

Summary

Types

message()

outgoing_result()

Callbacks

child_spec(keyword)

descriptor(group, opts)

id()

outgoing(group, target_node, shard, message, opts)

Called when Group has an outgoing replica message for another node.

peer_down(group, node, shard, opts)

Reports that one shard lane no longer has live peer authority.

peer_up(group, node, shard, descriptor, opts)

Reports that one shard lane can address a peer through this transport.

Functions

incoming(group, source_node, shard, message)

Passes an incoming replica message to the corresponding local shard.

incoming_batch(group, source_node, shard, messages)

Passes a complete incoming batch to the corresponding local shard.

normalize(module)

validate!(transport)

Types

message()

@type message() :: term()

outgoing_result()

@type outgoing_result() :: :ok | :busy | :disconnected

Callbacks

child_spec(keyword)

(optional)

@callback child_spec(keyword()) :: Supervisor.child_spec() | :ignore

descriptor(group, opts)

@callback descriptor(group :: atom(), opts :: keyword()) :: term()

id()

@callback id() :: term()

outgoing(group, target_node, shard, message, opts)

@callback outgoing(
  group :: atom(),
  target_node :: node(),
  shard :: non_neg_integer(),
  message(),
  opts :: keyword()
) :: outgoing_result()

Called when Group has an outgoing replica message for another node.

This callback must return promptly and must never wait for transport or remote backpressure. :ok means the transport took responsibility for the message, not that the remote shard received it.

peer_down(group, node, shard, opts)

(optional)

@callback peer_down(
  group :: atom(),
  node(),
  shard :: non_neg_integer(),
  opts :: keyword()
) :: :ok

Reports that one shard lane no longer has live peer authority.

peer_up(group, node, shard, descriptor, opts)

(optional)

@callback peer_up(
  group :: atom(),
  node(),
  shard :: non_neg_integer(),
  descriptor :: term(),
  opts :: keyword()
) :: :ok

Reports that one shard lane can address a peer through this transport.

A transport sharing one node-level connection across lanes should retain the route until peer_down/4 has retired every shard previously reported up.

Functions

incoming(group, source_node, shard, message)

Passes an incoming replica message to the corresponding local shard.

This is a local mailbox operation. source_node identifies the peer whose replica lane supplied the message. Stream generation, epoch, group, shard, origin, and member-pid ownership are validated by the replica.

Returns :disconnected and drops the message if that shard is not currently registered, for example while its supervisor is restarting.

incoming_batch(group, source_node, shard, messages)

Passes a complete incoming batch to the corresponding local shard.

A finite-message transport may segment the encoded batch on the wire, but it must reassemble every segment before calling this function. Group never observes or applies a partial batch. source_node has the same routing meaning as in incoming/4.

Like incoming/4, this returns :disconnected if the destination shard is unavailable.