Xirsys.XTurn.Conn (xturn v2.0.0)

Copy Markdown View Source

Mutable request context passed through STUN/TURN action pipelines.

What problem this solves

Each incoming STUN or TURN message needs shared state: the raw bytes, decoded attributes, who sent it, which server socket received it, and any response built so far. Action modules (authenticate, allocate, channel bind, and so on) read and update one %Conn{} instead of threading many arguments.

Internal note

Library and server internals only; operators configure XTurn via application env and REST API, not by building %Conn{} structs directly.

RFCs

Summary

Types

t()

STUN/TURN request context.

Functions

halt(conn)

Stops further actions from running on this connection.

response(conn, class, attrs \\ nil)

Attaches a success or error response to the connection.

response(conn, err, msg, nonce)

Builds an error response with an explicit nonce (401/438).

to_reply(conn)

Encodes conn.response into STUN wire format.

Types

t()

@type t() :: %Xirsys.XTurn.Conn{
  client_ip: :inet.ip_address() | nil,
  client_port: pos_integer() | nil,
  client_socket: Xirsys.XTurn.ClientSocket.t() | nil,
  decoded_message: term(),
  force_auth: boolean(),
  halt: boolean() | nil,
  is_control: boolean(),
  message: binary() | nil,
  reply_from: {module(), term()} | nil,
  reply_to: {:inet.ip_address(), :inet.port_number()} | nil,
  response: Xirsys.XTurn.Response.t() | nil,
  server_ip: :inet.ip_address() | nil,
  server_port: pos_integer() | nil,
  splice_peer: port() | nil
}

STUN/TURN request context.

Fields

  • :message - raw inbound bytes, or nil
  • :decoded_message - decoded %XMediaLib.Stun{} (or map-like attrs), or unset
  • :client_socket - %ClientSocket{} used to reply, or nil
  • :client_ip / :client_port - peer that sent the request
  • :server_ip / :server_port - local listen endpoint that received it
  • :is_control - when true, data-plane Send/ChannelData paths are blocked
  • :force_auth - require MESSAGE-INTEGRITY even when auth is optional
  • :response - %Response{} being built, or nil
  • :halt - when true, later pipeline actions are skipped
  • :splice_peer - optional TCP splice peer port
  • :reply_from - optional {transport_mod, socket} override for the reply
  • :reply_to - optional {ip, port} override for where to send the reply

Functions

halt(conn)

Stops further actions from running on this connection.

response(conn, class, attrs \\ nil)

@spec response(t(), atom() | integer(), map() | binary() | any()) :: t()

Attaches a success or error response to the connection.

  • response(conn, class, attrs) - success response (class is an atom, e.g. :success)
  • response(conn, err, msg) - error response (integer code + reason phrase)
  • response(conn, err, msg, nonce) - error with explicit nonce (401/438)

response(conn, err, msg, nonce)

@spec response(t(), integer(), binary(), String.t()) :: t()

Builds an error response with an explicit nonce (401/438).

to_reply(conn)

@spec to_reply(t()) :: {:ok, iodata()} | :noreply

Encodes conn.response into STUN wire format.

Returns {:ok, iodata()} when a reply should be sent, or :noreply when the pipeline produced no response (e.g. indications, halts without response).