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

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

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