Xirsys.Sockets.Handler behaviour (xturn_sockets v2.2.1)

View Source

Business logic for one pipeline tier.

handle_packet/4 is required. handle_connect/1 and handle_disconnect/2 are optional.

Return values from handle_packet/4:

  • {:ok, state} - packet consumed, no reply
  • {:reply, iodata(), state} - send iodata on the same connection
  • {:descend, tier, payload, state} - push payload into another named tier
  • {:close, state} - stop the connection after this packet

What problem this solves

After an accumulator yields a whole packet, something must interpret it. XTurn and host applications implement this behaviour per tier so STUN binding, TURN allocation, and relay logic stay out of the generic drain engine.

RFCs

Handlers typically implement protocol logic from:

This behaviour only defines the callback contract; it does not parse messages.

Summary

Types

meta()

Packet metadata from the accumulator (:from, :received_at, ...).

state()

Opaque handler state, returned from handle_connect/1 or handle_packet/4.

Callbacks

handle_connect(t)

Called once when a stream connection is accepted (not used on stateless UDP).

handle_disconnect(term, state)

Called when the connection process exits.

handle_packet(binary, meta, t, state)

Handles one whole packet from this tier's accumulator.

Types

meta()

@type meta() :: map()

Packet metadata from the accumulator (:from, :received_at, ...).

state()

@type state() :: term()

Opaque handler state, returned from handle_connect/1 or handle_packet/4.

Callbacks

handle_connect(t)

(optional) 
@callback handle_connect(Xirsys.Sockets.Conn.t()) :: {:ok, state()}

Called once when a stream connection is accepted (not used on stateless UDP).

Parameters

handle_disconnect(term, state)

(optional) 
@callback handle_disconnect(term(), state()) :: :ok

Called when the connection process exits.

Parameters

  • reason - exit reason (:normal, :tcp_closed, ...)
  • state - last handler state

handle_packet(binary, meta, t, state)

@callback handle_packet(binary(), meta(), Xirsys.Sockets.Conn.t(), state()) ::
  {:ok, state()}
  | {:reply, iodata(), state()}
  | {:descend, atom(), binary(), state()}
  | {:close, state()}

Handles one whole packet from this tier's accumulator.

Parameters

  • packet - framed payload (header stripped for length-prefixed tiers)
  • meta - accumulator metadata for this packet
  • conn - connection context (addresses, socket, assigns)
  • state - previous handler state