defmodule Specter do
@moduledoc """
Specter is a method for managing data structures and entities provided by
`webrtc.rs`. It is intended as a low-level library with some small set of
opinions, which can composed into more complex behaviors by higher-level
libraries and applications.
## Key points
Specter wraps `webrtc.rs`, which heavily utilizes async Rust. For this reason,
many functions cannot be automatically awaited by the caller—the NIF functions
send messages across channels to separate threads managed by Rust, which send
messages back to Elixir that can be caught by `receive` or `handle_info`.
## Usage
A process initializes Specter via the `init/1` function, which registers the
current process for callbacks that may be triggered via webrtc entities.
iex> ## Initialize the library. Register messages to the current pid.
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.l.google.com:19302"])
...>
iex> ## Create a peer connection's dependencies
iex> {:ok, media_engine} = Specter.new_media_engine(specter)
iex> {:ok, registry} = Specter.new_registry(specter, media_engine)
...>
iex> Specter.media_engine_exists?(specter, media_engine)
true
iex> Specter.registry_exists?(specter, registry)
true
...>
iex> {:ok, api} = Specter.new_api(specter, media_engine, registry)
...>
iex> Specter.media_engine_exists?(specter, media_engine)
false
iex> Specter.registry_exists?(specter, registry)
false
...>
iex> ## Create a peer connection
iex> {:ok, pc_1} = Specter.PeerConnection.new(specter, api)
iex> assert_receive {:peer_connection_ready, ^pc_1}
iex> Specter.PeerConnection.exists?(specter, pc_1)
true
iex> ## Add a thing to be negotiated
iex> :ok = Specter.PeerConnection.create_data_channel(specter, pc_1, "data")
iex> assert_receive {:data_channel_created, ^pc_1}
...>
iex> ## Create an offer
iex> :ok = Specter.PeerConnection.create_offer(specter, pc_1)
iex> assert_receive {:offer, ^pc_1, offer}
iex> :ok = Specter.PeerConnection.set_local_description(specter, pc_1, offer)
iex> assert_receive {:ok, ^pc_1, :set_local_description}
...>
iex> ## Create a second peer connection, to answer back
iex> {:ok, media_engine} = Specter.new_media_engine(specter)
iex> {:ok, registry} = Specter.new_registry(specter, media_engine)
iex> {:ok, api} = Specter.new_api(specter, media_engine, registry)
iex> {:ok, pc_2} = Specter.PeerConnection.new(specter, api)
iex> assert_receive {:peer_connection_ready, ^pc_2}
...>
iex> ## Begin negotiating offer/answer
iex> :ok = Specter.PeerConnection.set_remote_description(specter, pc_2, offer)
iex> assert_receive {:ok, ^pc_2, :set_remote_description}
iex> :ok = Specter.PeerConnection.create_answer(specter, pc_2)
iex> assert_receive {:answer, ^pc_2, answer}
iex> :ok = Specter.PeerConnection.set_local_description(specter, pc_2, answer)
iex> assert_receive {:ok, ^pc_2, :set_local_description}
...>
iex> ## Receive ice candidates
iex> assert_receive {:ice_candidate, ^pc_1, _candidate}
iex> assert_receive {:ice_candidate, ^pc_2, _candidate}
...>
iex> ## Shut everything down
iex> Specter.PeerConnection.close(specter, pc_1)
:ok
iex> assert_receive {:peer_connection_closed, ^pc_1}
...>
iex> :ok = Specter.PeerConnection.close(specter, pc_2)
iex> assert_receive {:peer_connection_closed, ^pc_2}
## Thoughts
During development of the library, it can be assumed that callers will
implement `handle_info/2` function heads appropriate to the underlying
implementation. Once these are more solid, it would be nice to `use Specter`,
which will inject a `handle_info/2` callback, and send the messages to
other callback functions defined by a behaviour. `handle_ice_candidate`,
and so on.
Some things are returned from the NIF as UUIDs. These are declared as `@opaque`,
to indicate that users of the library should not rely of them being in a
particular format. They could change later to be references, for instance.
"""
alias Specter.Native
@enforce_keys [:native]
defstruct [:native]
@typedoc """
`t:native_t/0` references are returned from the NIF, and represent state held
in Rust code.
"""
@opaque native_t() :: Specter.Native.t()
@typedoc """
`t:Specter.t/0` wraps the reference returned from `init/1`. All functions interacting with
NIF state take a `t:Specter.t/0` as their first argument.
"""
@type t() :: %Specter{native: native_t()}
@typedoc """
`t:Specter.api_t/0` represent an instantiated API managed in the NIF.
"""
@opaque api_t() :: String.t()
@typedoc """
`t:Specter.media_engine_t/0` represents an instantiated MediaEngine managed in the NIF.
"""
@opaque media_engine_t() :: String.t()
@typedoc """
`t:Specter.registry_t/0` represent an instantiated intercepter Registry managed in the NIF.
"""
@opaque registry_t() :: String.t()
@typedoc """
A uri in the form `protocol:host:port`, where protocol is either
`stun` or `turn`.
Defaults to `stun:stun.l.google.com:19302`.
"""
@type ice_server() :: String.t()
@typedoc """
Options for initializing RTCPeerConnections. This is set during initialization
of the library, and later used when creating new connections.
"""
@type init_options() :: [] | [ice_servers: [ice_server()]]
@doc """
Initialize the library. This registers the calling process to receive
callback messages to `handle_info/2`.
| param | type | default |
| ------------- | ------------------ | ------- |
| `ice_servers` | `list(String.t())` | `["stun:stun.l.google.com:19302"]` |
## Usage
iex> {:ok, _specter} = Specter.init(ice_servers: ["stun:stun.example.com:3478"])
"""
@spec init() :: {:ok, t()}
@spec init(init_options()) :: {:ok, t()} | {:error, term()}
def init(args \\ []) do
with {:ok, native} <- Native.init(args) do
{:ok, %Specter{native: native}}
end
end
@doc """
Returns the current configuration for the initialized NIF.
## Usage
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.example.com:3478"])
iex> Specter.config(specter)
{:ok, %Specter.Config{ice_servers: ["stun:stun.example.com:3478"]}}
"""
@spec config(t()) :: {:ok, Specter.Config.t()} | {:error, term()}
def config(%Specter{native: ref}), do: Native.config(ref)
@doc """
Returns true or false, depending on whether the media engine is available for
consumption, i.e. is initialized and has not been used by a function that takes
ownership of it.
## Usage
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.l.google.com:19302"])
iex> {:ok, media_engine} = Specter.new_media_engine(specter)
iex> Specter.media_engine_exists?(specter, media_engine)
true
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.l.google.com:19302"])
iex> Specter.media_engine_exists?(specter, UUID.uuid4())
false
"""
@spec media_engine_exists?(t(), media_engine_t()) :: boolean() | no_return()
def media_engine_exists?(%Specter{native: ref}, media_engine) do
case Native.media_engine_exists(ref, media_engine) do
{:ok, value} ->
value
{:error, error} ->
raise "Unable to determine whether media engine exists:\n#{inspect(error)}"
end
end
@doc """
An APIBuilder is used to create RTCPeerConnections. This accepts as parameters
the output of `init/1`, `new_media_enine/1`, and `new_registry/2`.
Note that this takes ownership of both the media engine and the registry,
effectively consuming them.
| param | type | default |
| -------------- | -------- | ------- |
| `specter` | `t()` | |
| `media_engine` | `opaque` | |
| `registry` | `opaque` | |
## Usage
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.l.google.com:19302"])
iex> {:ok, media_engine} = Specter.new_media_engine(specter)
iex> {:ok, registry} = Specter.new_registry(specter, media_engine)
iex> {:ok, _api} = Specter.new_api(specter, media_engine, registry)
"""
@spec new_api(t(), media_engine_t(), registry_t()) :: {:ok, api_t()} | {:error, term()}
def new_api(%Specter{native: ref}, media_engine, registry),
do: Native.new_api(ref, media_engine, registry)
@doc """
Creates a MediaEngine to be configured and used by later function calls.
Codecs and other high level configuration are done on instances of MediaEngines.
A MediaEngine is combined with a Registry in an entity called an APIBuilder,
which is then used to create RTCPeerConnections.
## Usage
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.l.google.com:19302"])
iex> {:ok, _media_engine} = Specter.new_media_engine(specter)
"""
@spec new_media_engine(t()) :: {:ok, media_engine_t()} | {:error, term()}
def new_media_engine(%Specter{native: ref}), do: Native.new_media_engine(ref)
@doc """
Creates an intercepter registry. This is a user configurable RTP/RTCP pipeline,
and provides features such as NACKs and RTCP Reports. A registry must be created for
each peer connection.
The registry may be combined with a MediaEngine in an API (consuming both). The API
instance is then used to create RTCPeerConnections.
Note that creating a registry does **not** take ownership of the media engine.
## Usage
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.l.google.com:19302"])
iex> {:ok, media_engine} = Specter.new_media_engine(specter)
iex> {:ok, _registry} = Specter.new_registry(specter, media_engine)
...>
iex> Specter.media_engine_exists?(specter, media_engine)
true
"""
@spec new_registry(t(), media_engine_t()) :: {:ok, registry_t()} | {:error, term()}
def new_registry(%Specter{native: ref}, media_engine),
do: Native.new_registry(ref, media_engine)
@doc """
Returns true or false, depending on whether the registry is available for
consumption, i.e. is initialized and has not been used by a function that takes
ownership of it.
## Usage
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.l.google.com:19302"])
iex> {:ok, media_engine} = Specter.new_media_engine(specter)
iex> {:ok, registry} = Specter.new_registry(specter, media_engine)
iex> Specter.registry_exists?(specter, registry)
true
iex> {:ok, specter} = Specter.init(ice_servers: ["stun:stun.l.google.com:19302"])
iex> Specter.registry_exists?(specter, UUID.uuid4())
false
"""
@spec registry_exists?(t(), registry_t()) :: boolean() | no_return()
def registry_exists?(%Specter{native: ref}, registry) do
case Native.registry_exists(ref, registry) do
{:ok, value} ->
value
{:error, error} ->
raise "Unable to determine whether registry exists:\n#{inspect(error)}"
end
end
end
