xturn_plugins

# XTurn Plugins

Example plugins for [xturn](https://github.com/Lazarus404/xturn):

- `Xirsys.XTurn.Plugin.Guard` — active relay-abuse guard: RFC 7983 first-byte demux plus
  an RTP payload-type allowlist. Drop-only; never rewrites frames, since any header
  rewrite would invalidate an SRTP auth tag.
- `Xirsys.XTurn.Plugin.Metrics` — passive per-allocation QoS and metering exporter:
  packet/byte counters, per-SSRC loss/duplicate/reorder counts via extended RTP sequence
  numbers (RFC 3550 A.1/A.3), RFC 3550 §6.4.1 interarrival jitter, and framing mix
  (ChannelData vs. Send/Data Indication).

Each plugin implements the [`Xirsys.XTurn.Plugin`](https://github.com/xirsys/xturn-plugin-api)
behaviour from `xturn_plugin_api` — this package depends only on that contract, not on
`xturn` itself, so it builds and tests standalone. `xturn` can depend on it directly (as
a normal, non-circular dependency) to make these plugins available.

## Usage

Add as a dependency, then configure in your xturn config:

```elixir
defp deps do
  [
    {:xturn_plugins, "~> 0.1.0"}
  ]
end
```

```elixir
config :xturn,
  plugins: [
    {Xirsys.XTurn.Plugin.Guard, mode: :monitor, payload_types: [0, 8]},
    {Xirsys.XTurn.Plugin.Metrics, flush_ms: 5_000}
  ]
```

`Guard` defaults to `:monitor` (telemetry only, never drops) so it's safe to deploy
before switching to `:enforce`. Its default `payload_types: [0, 8]` covers PCMU/PCMA;
set it explicitly for WebRTC deployments using dynamic payload types (Opus, VP8, etc.).

## Tests

```bash
cd xturn-plugins
mix test
```

Tests drive each plugin's callbacks directly (`init/2`, `handle_frame/3`,
`handle_close/2`, ...) against `xturn_plugin_api`'s `Allocation`/`Frame` structs, the
same way xturn's plugin runtime would. No dependency on `xturn` itself is needed to
build or test this package.