# XTurn Plugin API

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

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

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

## What problem this solves

A TURN relay forwards media between clients and peers. Operators often need to
inspect or meter that traffic (abuse guards, QoS counters) without forking the
server. This package defines the behaviour and structs that [xturn](https://github.com/Lazarus404/xturn)
calls and that plugin packages implement.

## Installation

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

## Main modules

- `Xirsys.XTurn.Plugin` - behaviour (`mode/0`, `hooks/0`, `attach?/2`, `init/2`,
  `handle_frame/3`, optional `handle_close/2` and `handle_info/2`)
- `Xirsys.XTurn.Plugin.Allocation` - per-allocation context for attach/init
- `Xirsys.XTurn.Plugin.Frame` - per-frame metadata for `handle_frame/3`

Concrete plugins (for example
[xturn-plugins](https://github.com/Lazarus404/xturn-plugins)) depend on this
API only, not on the full xturn application, so they build and test standalone.

## RFCs

- [RFC 5766](https://www.rfc-editor.org/rfc/rfc5766) / [RFC 8656](https://www.rfc-editor.org/rfc/rfc8656) (TURN relay path)
- [RFC 3550](https://www.rfc-editor.org/rfc/rfc3550) (RTP payloads common on the relay)
- [RFC 7983](https://www.rfc-editor.org/rfc/rfc7983) (first-byte demultiplexing)

## Usage

Implement the behaviour:

```elixir
defmodule MyApp.Plugin do
  @behaviour Xirsys.XTurn.Plugin

  @impl true
  def mode, do: :active

  @impl true
  def hooks, do: [:egress]

  @impl true
  def attach?(%Xirsys.XTurn.Plugin.Allocation{}, _opts), do: true

  @impl true
  def init(_allocation, _opts), do: {:ok, nil}

  @impl true
  def handle_frame(payload, %Xirsys.XTurn.Plugin.Frame{}, _state), do: {:ok, payload}
end
```

## Changelog

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

## License

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