XTurn Plugin API

Shared plugin contract for xturn data-plane plugins.

Home: https://github.com/Lazarus404/xturn-plugin-api

Hex: 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 calls and that plugin packages implement.

Installation

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) depend on this API only, not on the full xturn application, so they build and test standalone.

RFCs

• RFC 5766 / RFC 8656 (TURN relay path)
• RFC 3550 (RTP payloads common on the relay)
• RFC 7983 (first-byte demultiplexing)

Usage

Implement the behaviour:

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.

License

Apache-2.0. See LICENSE.md.