xturn_plugins

# XTurn Plugins

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

Home: [https://github.com/Lazarus404/xturn-plugins](https://github.com/Lazarus404/xturn-plugins)

Hex: [https://hex.pm/packages/xturn_plugins](https://hex.pm/packages/xturn_plugins)

## What problem this solves

TURN relays forward media between WebRTC clients and peers. Operators often
need abuse filtering and usage metrics on that path. This package ships two
plugins that implement the
[xturn-plugin-api](https://github.com/Lazarus404/xturn-plugin-api) contract
without depending on the full xturn application (so they build and test
standalone).

## Installation

```elixir
def deps do
  [
    {:xturn_plugins, "~> 0.1"}
  ]
end
```

## Main modules

- `Xirsys.XTurn.Plugin.Guard` - active relay-abuse guard: RFC 7983 first-byte
  demux plus an RTP payload-type allowlist. Drop-only; never rewrites frames
  (SRTP auth tags would break).
- `Xirsys.XTurn.Plugin.Metrics` - passive per-allocation QoS/metering:
  packet/byte counters, per-SSRC loss/duplicate/reorder (RFC 3550 A.1/A.3),
  interarrival jitter, and TURN framing mix.

## RFCs

- [RFC 5766](https://www.rfc-editor.org/rfc/rfc5766) / [RFC 8656](https://www.rfc-editor.org/rfc/rfc8656) (TURN data path)
- [RFC 7983](https://www.rfc-editor.org/rfc/rfc7983) (multiplexing demux)
- [RFC 3550](https://www.rfc-editor.org/rfc/rfc3550) (RTP/RTCP metrics)
- [RFC 3711](https://www.rfc-editor.org/rfc/rfc3711) (SRTP; Guard does not rewrite)

## Usage

```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 is safe to
deploy before switching to `:enforce`. Default `payload_types: [0, 8]` covers
PCMU/PCMA; set it explicitly for WebRTC deployments using dynamic payload
types (Opus, VP8, and others).

## Tests

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

Tests drive each plugin's callbacks directly against
`xturn_plugin_api` `Allocation`/`Frame` structs.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

Apache-2.0. See [LICENSE.md](LICENSE.md).