View Source ExLibSRT.Server (ExLibSRT v0.2.0)

Implementation of the SRT server.

Glossary

Stream ID — An optional string identifier carried by each SRT connection. Clients can specify a stream ID when connecting, and the server can use it to identify and route connections.
Owner — The process that receives notifications about new connections (srt_server_conn/0), rejected connections ({:srt_server_rejected_client, stream_id}), and server errors (srt_server_error/0).
Receiver — The process that receives data messages (srt_data/0) and disconnection notifications (srt_server_conn_closed/0) for a specific connection. Can be bound via bind_with_process/3 or bind_with_handler/3.

Accepting connections

whitelist mode

Each SRT connection can carry a streamid string which can be used for identifying the stream. When accept_mode: :whitelist or accept_mode: {:whitelist, ids} the server operates in whitelist mode: only connections whose streamid is present in the whitelist are accepted.

The whitelist can be supplied up-front via the :accept_mode option of start/3 / start_link/3 (e.g., accept_mode: {:whitelist, stream_ids}), and modified at runtime with add_stream_id_to_whitelist/2 and remove_stream_id_from_whitelist/2.

When a client connects with a stream ID that is not on the whitelist, the server responds with rejection code 1403 (analogous to HTTP 403 Forbidden).

accept-all mode

When accept_mode: :accept_all the server operates in accept-all mode: every incoming connection is accepted at the SRT level regardless of its stream ID.

In both modes the owner process receives a srt_server_conn/0 message for each accepted connection. The owner then has 1 second to call bind_with_process/3 or bind_with_handler/3 to register a receiver for that connection. If no binding happens within 1 second the connection is dropped and the owner receives srt_server_conn_timeout/0.

The registered receiver will receive srt_data/0 and srt_server_conn_closed/0 messages.

Password Authentication

SRT supports password-based authentication. When using password authentication:

Password must be between 10 and 79 characters long (SRT specification requirement)
Empty string means no password authentication (default behavior)
All connecting clients must provide the same password

A process starting the server will also receive the following notifications:

srt_server_conn/0 - a new client connection has been established
srt_server_conn_closed/0 - a client connection has been closed
srt_server_error/0 - server has encountered an error
srt_data/0 - server has received new data on a client connection

Summary

Types

accept_mode()

connection_id()

srt_data()

srt_server_conn()

srt_server_conn_closed()

srt_server_conn_timeout()

srt_server_error()

t()

Functions

add_stream_id_to_whitelist(agent, stream_id)

Adds a stream ID to the server's whitelist at runtime.

bind_with_handler(agent, conn_id, handler)

Spawns an ExLibSRT.Connection process backed by handler and binds it to a pending connection.

bind_with_process(agent, conn_id, receiver \\ nil)

Registers the given process (defaults to self()) as the receiver for a pending connection.

child_spec(arg)

Returns a specification to start this module under a supervisor.

close_server_connection(connection_id, agent)

Closes the connection to the given client.

read_socket_stats(connection_id, agent)

Reads socket statistics.

remove_stream_id_from_whitelist(agent, stream_id)

Removes a stream ID from the server's whitelist at runtime.

start(address, port, opts \\ [])

Starts a new SRT server outside the supervision tree, binding to given address and port.

start_link(address, port, opts \\ [])

Starts a new SRT server binding to given address and port and links to current process.

stop(agent)

Stops the server.

Types

accept_mode()

@type accept_mode() :: :accept_all | :whitelist | {:whitelist, [String.t()]}

connection_id()

@type connection_id() :: non_neg_integer()

srt_data()

@type srt_data() :: {:srt_data, connection_id(), data :: binary()}

srt_server_conn()

@type srt_server_conn() ::
  {:srt_server_conn, connection_id(), stream_id :: String.t()}

srt_server_conn_closed()

@type srt_server_conn_closed() :: {:srt_server_conn_closed, connection_id()}

srt_server_conn_timeout()

@type srt_server_conn_timeout() ::
  {:srt_server_conn_timeout, connection_id(), stream_id :: String.t()}

srt_server_error()

@type srt_server_error() :: {:srt_server_error, connection_id(), error :: String.t()}

t()

@type t() :: pid()

Functions

add_stream_id_to_whitelist(agent, stream_id)

@spec add_stream_id_to_whitelist(t(), String.t()) ::
  :ok | {:error, reason :: String.t()}

Adds a stream ID to the server's whitelist at runtime.

Once added, connections carrying this stream ID will be accepted and the owner will receive srt_server_conn/0. Call bind_with_process/3 or bind_with_handler/3 to register a receiver.

bind_with_handler(agent, conn_id, handler)

@spec bind_with_handler(t(), connection_id(), ExLibSRT.Connection.Handler.t()) ::
  {:ok, ExLibSRT.Connection.t()} | {:error, reason :: any()}

Spawns an ExLibSRT.Connection process backed by handler and binds it to a pending connection.

Must be called within 1 second of receiving srt_server_conn/0.

bind_with_process(agent, conn_id, receiver \\ nil)

@spec bind_with_process(t(), connection_id(), pid() | nil) ::
  :ok | {:error, reason :: String.t()}

Registers the given process (defaults to self()) as the receiver for a pending connection.

Must be called within 1 second of receiving srt_server_conn/0, otherwise the connection will have been dropped. Returns {:error, reason} if the connection ID is not found.

After a successful bind the receiver will receive srt_data/0 and srt_server_conn_closed/0 messages for the connection.

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

close_server_connection(connection_id, agent)

@spec close_server_connection(connection_id(), t()) ::
  :ok | {:error, reason :: String.t()}

Closes the connection to the given client.

read_socket_stats(connection_id, agent)

@spec read_socket_stats(connection_id(), t()) ::
  {:ok, ExLibSRT.SocketStats.t()} | {:error, reason :: String.t()}

Reads socket statistics.

remove_stream_id_from_whitelist(agent, stream_id)

@spec remove_stream_id_from_whitelist(t(), String.t()) ::
  :ok | {:error, reason :: String.t()}

Removes a stream ID from the server's whitelist at runtime.

After removal, new connections carrying that stream ID will be rejected.

start(address, port, opts \\ [])

@spec start(
  address :: String.t(),
  port :: non_neg_integer(),
  opts :: keyword()
) :: {:ok, t()} | {:error, reason :: String.t(), error_code :: integer()}

Starts a new SRT server outside the supervision tree, binding to given address and port.

One may usually want to bind to 0.0.0.0 address.

Options

:password - SRT passphrase for authentication. Must be between 10 and 79 characters long according to SRT specification. Empty string (default) means no password authentication.
:latency_ms - SRT latency in milliseconds. Defaults to -1.
:accept_mode - Controls how the server accepts connections. See whitelist mode and accept-all mode for details. Valid values are:
- :accept_all - Accept all connections regardless of stream ID.
- :whitelist - Whitelist mode with an empty initial whitelist.
- {:whitelist, stream_ids} - Whitelist mode with pre-populated stream IDs. Defaults to :whitelist.
:owner - The process that receives srt_server_conn/0 notifications for every accepted connection, as well as {:srt_server_rejected_client, stream_id} when a connection is rejected. Defaults to self().

start_link(address, port, opts \\ [])

@spec start_link(
  address :: String.t(),
  port :: non_neg_integer(),
  opts :: keyword()
) :: {:ok, t()} | {:error, reason :: String.t(), error_code :: integer()}

Starts a new SRT server binding to given address and port and links to current process.

One may usually want to bind to 0.0.0.0 address.

Options

:password - SRT passphrase for authentication. Must be between 10 and 79 characters long according to SRT specification. Empty string (default) means no password authentication.
:latency_ms - SRT latency in milliseconds, used to set SRTO_LATENCY flag. Defaults to -1 (meaning that SRTO_LATENCY flag is not set).
:accept_mode - Controls how the server accepts connections. See whitelist mode for details. Valid values are:
- :accept_all - Accept all connections regardless of stream ID.
- :whitelist - Whitelist mode with an empty initial whitelist.
- {:whitelist, stream_ids} - Whitelist mode with pre-populated stream IDs. Defaults to :whitelist.
:owner - The process that receives srt_server_conn/0 notifications for every accepted connection, as well as {:srt_server_rejected_client, stream_id} when a connection is rejected. Defaults to self().

stop(agent)

@spec stop(t()) :: :ok | {:error, reason :: String.t()}

Stops the server.

Stopping a server closes all active connections.