# xturn v2.0.0 - Table of Contents

> Elixir STUN/TURN relay server for WebRTC -- UDP, TCP, TLS, and DTLS listeners with long-term and shared-secret auth.

## Pages

- [XTurn](readme.md)
- [LICENSE](license.md)

- Guides
  - [XTurn architecture](architecture.md)
  - [xturn plugins](plugin.md)

- Release notes
  - [Changelog](changelog.md)

## Modules

- [Plug.Adapters.Cowboy2](Plug.Adapters.Cowboy2.md): Internal Plug adapter shim for Maru on plug_cowboy 2.x.
- [Xirsys.API.Router.Allocation](Xirsys.API.Router.Allocation.md): Operator REST routes under `/allocation` for allocation introspection.
- [Xirsys.API.Router.Auth](Xirsys.API.Router.Auth.md): Operator REST routes under `/auth` for credential management.
- [Xirsys.XTurn.Actions.Allocate](Xirsys.XTurn.Actions.Allocate.md): Pipeline action for TURN **Allocate** requests.
- [Xirsys.XTurn.Actions.Authenticates](Xirsys.XTurn.Actions.Authenticates.md): Shared pipeline gate for STUN/TURN methods that require credentials.
- [Xirsys.XTurn.Actions.ChannelBind](Xirsys.XTurn.Actions.ChannelBind.md): Pipeline action for TURN **ChannelBind** requests.
- [Xirsys.XTurn.Actions.ChannelData](Xirsys.XTurn.Actions.ChannelData.md): Pipeline action for TURN **ChannelData** messages.
- [Xirsys.XTurn.Actions.Connect](Xirsys.XTurn.Actions.Connect.md): Pipeline action for TURN **Connect** requests.
- [Xirsys.XTurn.Actions.ConnectionBind](Xirsys.XTurn.Actions.ConnectionBind.md): Pipeline action for TURN **ConnectionBind** requests.
- [Xirsys.XTurn.Actions.CreatePerm](Xirsys.XTurn.Actions.CreatePerm.md): Pipeline action for TURN **CreatePermission** requests.
- [Xirsys.XTurn.Actions.HasRequestedTransport](Xirsys.XTurn.Actions.HasRequestedTransport.md): Guard that validates REQUESTED-TRANSPORT on **Allocate**.
- [Xirsys.XTurn.Actions.NotAllocationExists](Xirsys.XTurn.Actions.NotAllocationExists.md): Guard that rejects duplicate **Allocate** on the same client 5-tuple.
- [Xirsys.XTurn.Actions.Refresh](Xirsys.XTurn.Actions.Refresh.md): Pipeline action for TURN **Refresh** requests.
- [Xirsys.XTurn.Actions.SendIndication](Xirsys.XTurn.Actions.SendIndication.md): Pipeline action for TURN **Send** indications.
- [Xirsys.XTurn.AddressFamily](Xirsys.XTurn.AddressFamily.md): IPv4/IPv6 address-family constants for TURN Allocate and Refresh.
- [Xirsys.XTurn.Allocate.Bytes](Xirsys.XTurn.Allocate.Bytes.md): Lock-free per-allocation relay byte counters.
- [Xirsys.XTurn.Allocate.Client.State](Xirsys.XTurn.Allocate.Client.State.md): In-process state for one `Allocate.Client` GenServer.
- [Xirsys.XTurn.Allocate.Quota](Xirsys.XTurn.Allocate.Quota.md): Per-username concurrent allocation limit.
- [Xirsys.XTurn.Allocate.TcpRegistry](Xirsys.XTurn.Allocate.TcpRegistry.md): ETS registries for RFC 6062 TCP relay connection ids and spliced sockets.
- [Xirsys.XTurn.Auth.Supervisor](Xirsys.XTurn.Auth.Supervisor.md): OTP supervisor for TURN authentication services.
- [Xirsys.XTurn.Auth.Table](Xirsys.XTurn.Auth.Table.md): ETS-backed store for ephemeral long-term TURN credentials.
- [Xirsys.XTurn.Auth.UUID](Xirsys.XTurn.Auth.UUID.md): Random identifiers and hex encoding for TURN credential challenges.
- [Xirsys.XTurn.Certs](Xirsys.XTurn.Certs.md): Certificate reload for TURNS and DTLS listeners.
- [Xirsys.XTurn.Certs.SignalHandler](Xirsys.XTurn.Certs.SignalHandler.md): `:gen_event` handler that reloads TLS certificates on SIGHUP.
- [Xirsys.XTurn.Certs.SignalHandler.Registrar](Xirsys.XTurn.Certs.SignalHandler.Registrar.md): Installs the SIGHUP certificate reload handler at boot.
- [Xirsys.XTurn.Certs.Watcher](Xirsys.XTurn.Certs.Watcher.md): Polls configured certificate files and reloads secure listeners on change.
- [Xirsys.XTurn.Channels.Channel](Xirsys.XTurn.Channels.Channel.md): In-memory TURN channel binding for one peer on an allocation.
- [Xirsys.XTurn.DualIp](Xirsys.XTurn.DualIp.md): Dual-homed listen helpers for NAT behavior discovery.
- [Xirsys.XTurn.PacketLog](Xirsys.XTurn.PacketLog.md): Structured logging of raw STUN/TURN datagrams exchanged with clients.
- [Xirsys.XTurn.PacketLog.Writer](Xirsys.XTurn.PacketLog.Writer.md): Serialises packet log lines to a dedicated file.
- [Xirsys.XTurn.PeerFilter](Xirsys.XTurn.PeerFilter.md): Validates XOR-PEER-ADDRESS for CreatePermission and ChannelBind.
- [Xirsys.XTurn.Plugin.InstanceSupervisor](Xirsys.XTurn.Plugin.InstanceSupervisor.md): DynamicSupervisor for passive plugin GenServer instances.
- [Xirsys.XTurn.Plugin.Supervisor](Xirsys.XTurn.Plugin.Supervisor.md): Supervisor for the relay plugin subsystem.
- [Xirsys.XTurn.RelayFamily](Xirsys.XTurn.RelayFamily.md): Gates peer and refresh operations by active relay address family.
- [Xirsys.XTurn.RelayPort](Xirsys.XTurn.RelayPort.md): Opens relay UDP ports according to server port policy.
- [Xirsys.XTurn.ReservationStore](Xirsys.XTurn.ReservationStore.md): Short-lived holds for RFC 8656 RESERVATION-TOKEN relay ports.
- [Xirsys.XTurn.RootSupervisor](Xirsys.XTurn.RootSupervisor.md): Root OTP supervisor for TURN listeners and the HTTP API.
- [Xirsys.XTurn.Server](Xirsys.XTurn.Server.md): Placeholder GenServer for OTP supervision compatibility.
- [Xirsys.XTurn.SocketPipeline](Xirsys.XTurn.SocketPipeline.md): Socket pipeline for stream transports (TCP, TLS-over-TCP).
- [Xirsys.XTurn.SocketPipeline.Datagram](Xirsys.XTurn.SocketPipeline.Datagram.md): Socket pipeline for datagram transports (UDP, DTLS).
- [Xirsys.XTurn.StunHelper](Xirsys.XTurn.StunHelper.md): Encodes STUN indications for peer-to-client relay traffic.
- [Xirsys.XTurn.Supervisor](Xirsys.XTurn.Supervisor.md): OTP supervisor for the TURN server worker tree.
- [Xirsys.XTurn.TimedEntry](Xirsys.XTurn.TimedEntry.md): Map of values with per-key expiry timers.
- [Xirsys.XTurn.Timing](Xirsys.XTurn.Timing.md): Allocation lifetime and refresh deadline helpers.
- [Xirsys.XTurn.Tuple5](Xirsys.XTurn.Tuple5.md): Five-tuple identity for a TURN allocation on this server.

- Entry
  - [Xirsys.API](Xirsys.API.md): Maru HTTP router for XTurn operator REST endpoints.
  - [Xirsys.XTurn](Xirsys.XTurn.md): XTurn is a STUN/TURN relay server for real-time media (WebRTC, VoIP, and similar).

- Listen
  - [Xirsys.XTurn.Accumulators.StunTurn](Xirsys.XTurn.Accumulators.StunTurn.md): STUN/TURN framing accumulator for one client connection.
  - [Xirsys.XTurn.DatagramListener](Xirsys.XTurn.DatagramListener.md): UDP listener that registers bound endpoints in `ListenRegistry`.
  - [Xirsys.XTurn.Handlers.StunTurn](Xirsys.XTurn.Handlers.StunTurn.md): Socket handler that multiplexes TURN control and media on one connection.
  - [Xirsys.XTurn.ListenConfig](Xirsys.XTurn.ListenConfig.md): Resolves STUN/TURN listen ports and default bind tuples.
  - [Xirsys.XTurn.ListenRegistry](Xirsys.XTurn.ListenRegistry.md): Stable `{transport, socket}` lookup per bound `{ip, port}` endpoint.

- Control
  - [Xirsys.XTurn.Binding](Xirsys.XTurn.Binding.md): Handles STUN Binding requests (client address discovery).
  - [Xirsys.XTurn.ClientWorker](Xirsys.XTurn.ClientWorker.md): GenServer shard that runs the STUN/TURN control pipeline.
  - [Xirsys.XTurn.ClientWorker.Pool](Xirsys.XTurn.ClientWorker.Pool.md): Supervisor and dispatcher for sharded STUN/TURN control workers.
  - [Xirsys.XTurn.Conn](Xirsys.XTurn.Conn.md): Mutable request context passed through STUN/TURN action pipelines.
  - [Xirsys.XTurn.Pipeline](Xirsys.XTurn.Pipeline.md): Decodes and dispatches STUN/TURN control requests.
  - [Xirsys.XTurn.Response](Xirsys.XTurn.Response.md): Pending STUN success or error attached to `%Conn{}` during pipeline processing.

- Allocate
  - [Xirsys.XTurn.Allocate.Client](Xirsys.XTurn.Allocate.Client.md): GenServer owning one TURN allocation (relay, permissions, channels, TCP relay).
  - [Xirsys.XTurn.Allocate.Store](Xirsys.XTurn.Allocate.Store.md): ETS index of active TURN allocations and relay ingress rows.
  - [Xirsys.XTurn.Allocate.Supervisor](Xirsys.XTurn.Allocate.Supervisor.md): Dynamic supervisor for per-client TURN allocation GenServers.
  - [Xirsys.XTurn.Channels.Store](Xirsys.XTurn.Channels.Store.md): ETS-backed store of TURN channel bindings (client -> peer direction).
  - [Xirsys.XTurn.ClientSocket](Xirsys.XTurn.ClientSocket.md): Outbound send handle for data and STUN replies to the TURN client.
  - [Xirsys.XTurn.Permissions.Store](Xirsys.XTurn.Permissions.Store.md): ETS-backed CREATE PERMISSION allowlist keyed by allocation 5-tuple and peer IP.

- Data plane
  - [Xirsys.XTurn.DataPlane](Xirsys.XTurn.DataPlane.md): Hot path for relayed TURN media (client to peer and hairpin).
  - [Xirsys.XTurn.RelayIngress](Xirsys.XTurn.RelayIngress.md): Sharded supervisor for peer -> client relay ingress.
  - [Xirsys.XTurn.RelayIngress.Worker](Xirsys.XTurn.RelayIngress.Worker.md): GenServer shard that owns relay UDP sockets and delivers peer packets to clients.

- Auth
  - [Xirsys.XTurn.Auth.AccessToken](Xirsys.XTurn.Auth.AccessToken.md): RFC 7635 third-party authorization access tokens.
  - [Xirsys.XTurn.Auth.Client](Xirsys.XTurn.Auth.Client.md): GenServer-backed ephemeral long-term TURN credential store.
  - [Xirsys.XTurn.Auth.NonceStore](Xirsys.XTurn.Auth.NonceStore.md): Tracks STUN/TURN nonces per client endpoint before an allocation exists.
  - [Xirsys.XTurn.Auth.SharedSecret](Xirsys.XTurn.Auth.SharedSecret.md): Stateless TURN REST API credentials (coturn-compatible shared secret).

- Plugins
  - [Xirsys.XTurn.Plugin.Chain](Xirsys.XTurn.Plugin.Chain.md): Resolved plugin chain for one TURN allocation.
  - [Xirsys.XTurn.Plugin.Dispatch](Xirsys.XTurn.Plugin.Dispatch.md): Runs the per-allocation plugin chain on relay ingress and egress.
  - [Xirsys.XTurn.Plugin.Instance](Xirsys.XTurn.Plugin.Instance.md): GenServer wrapper for a passive (out-of-band) relay plugin.
  - [Xirsys.XTurn.Plugin.Lifecycle](Xirsys.XTurn.Plugin.Lifecycle.md): Attaches and detaches relay plugins when allocations start and end.
  - [Xirsys.XTurn.Plugin.Manager](Xirsys.XTurn.Plugin.Manager.md): Loads relay plugins and monitors allocation lifetimes.
  - [Xirsys.XTurn.Plugin.Table](Xirsys.XTurn.Plugin.Table.md): ETS-backed table mapping normalised allocation keys to plugin chains.

