Xirsys.XTurn.Pipeline (xturn v2.0.0)

Decodes and dispatches STUN/TURN control requests.

What problem this solves

TURN servers handle many message types: Binding, Allocate, Refresh, permission and channel management, TCP relay setup, and more. Each type has prerequisite checks (authentication, existing allocation, transport). The pipeline decodes wire bytes via xmedialib, picks the handler from method and class, and runs an ordered action list on %Conn{}.

Relayed media (ChannelData and Send indications) normally bypasses this module on the listener fast path; workers invoke it only for control-plane frames.

Internal note

Called from ClientWorker; operators do not call process_message/1 directly.

RFCs

RFC 8489 / RFC 5389 (STUN decode and Binding)
RFC 5766 (Allocate, Refresh, ChannelBind, permissions, ChannelData)
RFC 8656 (address family and extension attributes)
RFC 6062 (Connect, ConnectionBind)
RFC 7635 (ACCESS-TOKEN when enabled)
RFC 3489 (classic decode fallback on UDP when configured)

Summary

Functions

do_request(input)

Routes a decoded STUN/TURN message to the appropriate handler.

process_message(conn)

Entry point for a single client message.

Functions

do_request(input)

@spec do_request(
  %Xirsys.XTurn.Conn{
    client_ip: term(),
    client_port: term(),
    client_socket: term(),
    decoded_message: term(),
    force_auth: term(),
    halt: term(),
    is_control: term(),
    message: term(),
    reply_from: term(),
    reply_to: term(),
    response: term(),
    server_ip: term(),
    server_port: term(),
    splice_peer: term()
  }
  | false
) ::
  %Xirsys.XTurn.Conn{
    client_ip: term(),
    client_port: term(),
    client_socket: term(),
    decoded_message: term(),
    force_auth: term(),
    halt: term(),
    is_control: term(),
    message: term(),
    reply_from: term(),
    reply_to: term(),
    response: term(),
    server_ip: term(),
    server_port: term(),
    splice_peer: term()
  }
  | false

Routes a decoded STUN/TURN message to the appropriate handler.

Dispatches by decoded_message.method and class:

:binding - Binding.process/1
:allocate, :refresh, :channelbind, :createperm, :connect, :connection_bind - action chains
:send indication - SendIndication (blocked on TCP control allocations)
:channel data - ChannelData action chain

Returns the updated %Conn{} or false.

process_message(conn)

@spec process_message(%Xirsys.XTurn.Conn{
  client_ip: term(),
  client_port: term(),
  client_socket: term(),
  decoded_message: term(),
  force_auth: term(),
  halt: term(),
  is_control: term(),
  message: term(),
  reply_from: term(),
  reply_to: term(),
  response: term(),
  server_ip: term(),
  server_port: term(),
  splice_peer: term()
}) ::
  %Xirsys.XTurn.Conn{
    client_ip: term(),
    client_port: term(),
    client_socket: term(),
    decoded_message: term(),
    force_auth: term(),
    halt: term(),
    is_control: term(),
    message: term(),
    reply_from: term(),
    reply_to: term(),
    response: term(),
    server_ip: term(),
    server_port: term(),
    splice_peer: term()
  }
  | false

Entry point for a single client message.

Decodes STUN/TURN (with optional RFC 3489 fallback on UDP when configured), handles RFC 5766 ChannelData, rejects malformed non-STUN frames, and delegates to do_request/1. Returns an updated %Conn{} or false on decode failure.