distribute - v2.1.0

distribute/handshake/actor

Types

HandshakeMessage

</> 
pub type HandshakeMessage {
  NetworkMessage(BitArray)
  TimeoutMessage(String)
  Init(process.Subject(HandshakeMessage), Int)
}

Constructors

Values

start_initiator_handshake

</> 
pub fn start_initiator_handshake(
  local: handshake.Hello,
  timeout_ms: Int,
  send_fn: fn(BitArray) -> Nil,
  on_success: fn(String, handshake.MemberMetadata) -> Nil,
  on_failure: fn(String, String) -> Nil,
  registry: option.Option(process.Subject(actor.RegistryCommand)),
) -> Result(process.Subject(HandshakeMessage), actor.StartError)

Start an initiator handshake actor.

Uses the stub crypto provider by default. For production use, use start_initiator_handshake_with_crypto with a real provider.

start_initiator_handshake_with_crypto

</> 
pub fn start_initiator_handshake_with_crypto(
  local: handshake.Hello,
  timeout_ms: Int,
  send_fn: fn(BitArray) -> Nil,
  on_success: fn(String, handshake.MemberMetadata) -> Nil,
  on_failure: fn(String, String) -> Nil,
  registry: option.Option(process.Subject(actor.RegistryCommand)),
  crypto: state.CryptoProvider,
) -> Result(process.Subject(HandshakeMessage), actor.StartError)

Start an initiator handshake actor with a specific crypto provider.

Arguments

  • crypto - Crypto provider to use for key exchange

start_responder_handshake

</> 
pub fn start_responder_handshake(
  timeout_ms: Int,
  send_fn: fn(BitArray) -> Nil,
  on_success: fn(String, handshake.MemberMetadata) -> Nil,
  on_failure: fn(String, String) -> Nil,
  registry: option.Option(process.Subject(actor.RegistryCommand)),
) -> Result(process.Subject(HandshakeMessage), actor.StartError)

Start a responder handshake actor.

The responder waits for incoming handshake messages from an initiator, performs capability negotiation and key exchange, and upon successful completion registers the negotiated node in the optional registry.

Parameters

  • timeout_ms: Timeout in milliseconds for each handshake step. If a response is not received within this time, the handshake will retry or fail.

  • send_fn: Callback invoked with raw bytes to send to the remote peer. The caller is responsible for transmitting these bytes over the network.

  • on_success: Callback invoked when the handshake completes successfully. Receives the remote node ID and negotiated metadata (including secure context).

  • on_failure: Callback invoked when the handshake fails. Receives the remote node ID (or empty string if unknown) and a failure reason string.

  • registry: Optional registry actor subject. When provided (Some(reg)), the responder will:

    • Look up the initiator’s node ID when receiving the Hello message to validate known nodes and retrieve cached metadata
    • Register the successfully negotiated node metadata upon completion

    When None, registry operations are skipped and the handshake proceeds without persistence.

Returns

Ok(Subject(HandshakeMessage)) - A subject for sending network messages and timeouts to the handshake actor. Use NetworkMessage(bytes) to forward incoming protocol bytes from the remote peer.

Error(actor.StartError) - If the actor fails to start.

Registry Integration

When a registry is provided, the responder performs these operations:

  1. On Hello received: Attempts lookup_sync to check if the initiator’s node is already known. If found, the cached metadata can be used for validation (e.g., verify capabilities haven’t changed unexpectedly). Currently logged but not enforced; future versions may add strict validation.

  2. On Established: Calls register_sync to persist the negotiated protocol version and secure context. If registration fails, the handshake is aborted and on_failure is called with a registry error reason.

start_responder_handshake_with_crypto

</> 
pub fn start_responder_handshake_with_crypto(
  timeout_ms: Int,
  send_fn: fn(BitArray) -> Nil,
  on_success: fn(String, handshake.MemberMetadata) -> Nil,
  on_failure: fn(String, String) -> Nil,
  registry: option.Option(process.Subject(actor.RegistryCommand)),
  crypto: state.CryptoProvider,
) -> Result(process.Subject(HandshakeMessage), actor.StartError)

Start a responder handshake actor with a specific crypto provider.

Arguments

  • crypto - Crypto provider to use for key exchange
✨ Search Document