ExMoQ.Relay (ExMoQ.Relay v0.1.0)

Copy Markdown View Source

Runs a moq-relay binary as a supervised OS process.

{:ok, relay} = ExMoQ.Relay.start_link(quic: 4443)
ExMoQ.Relay.info(relay).quic  #=> "https://127.0.0.1:4443"

Summary

Types

How sessions are admitted.

The logging behaviour for the relay process.

The options of a relay to start.

Path patterns: one, or a list.

The certificate of the QUIC listener.

Functions

The arguments the relay binary is run with. Raises ArgumentError when options fail validation.

Returns a specification to start this module under a supervisor.

Finds the relay binary

Endpoints through which the relay can be reached, see %ExMoQ.Relay.Info{}.

Starts a relay not linked to the caller and blocks until moq-relay is ready to accept connections.

Starts a relay linked to the caller and blocks until moq-relay is ready to accept connections.

Types

auth()

@type auth() ::
  patterns()
  | [{:subscribe, patterns()} | {:publish, patterns()}, ...]
  | {:url, String.t()}

How sessions are admitted.

  • Path patterns for anonymous access ("**" is everything)
  • [subscribe: patterns, publish: patterns] to grant the two apart ([subscribe: "**"] lets anyone subscribe and no one publish)
  • {:url, url} for an auth server the relay POSTs to, see https://doc.moq.dev/bin/relay/auth

listener()

@type listener() :: :inet.port_number() | {:inet.port_number(), listener_opts()}

listener_opts()

@type listener_opts() :: [{:ip, :inet.ip_address()}]

log()

@type log() :: Logger.level() | {Logger.level(), (String.t() -> any())} | :none

The logging behaviour for the relay process.

  • A Logger level.
  • {level, fun}, where fun is called on each line.
  • :none to discard.

option()

@type option() ::
  {:binary, Path.t()}
  | {:quic, quic_listener() | nil}
  | {:tcp, listener()}
  | {:web, listener()}
  | {:internal, listener()}
  | {:auth, auth() | nil}
  | {:log, log()}
  | {:args, [String.t()]}
  | {:ready_timeout, non_neg_integer()}
  | {:name, GenServer.name()}

options()

@type options() :: [option()]

The options of a relay to start.

  • :binary - path to the relay, otherwise resolved with find_binary/1.
  • :quic - the QUIC listener (default 4443), or nil for none. {port, tls: tls} sets its certificate, see tls/0 (default {:generate, ["localhost"]}).
  • :tcp - a plaintext TCP listener (none by default).
  • :web - the HTTP listener serving moq-relay endpoints (none by default). It may share its port number with :quic.
  • :internal - the HTTP listener for operators (none by default).
  • :auth - see auth/0 (default "**"), or nil for none.
  • :log - logging behaviour, see log/0 (default :warning).
  • :args - list of extra command-line arguments (none by default).
  • :ready_timeout - milliseconds to wait for readiness (default 15_000).
  • :name - a name to register the relay's process under (none by default).

A listener given as a port binds to 127.0.0.1; {port, ip: ip} binds it to ip, like quic: {4443, ip: {0, 0, 0, 0}}.

patterns()

@type patterns() :: String.t() | [String.t(), ...]

Path patterns: one, or a list.

quic_listener()

@type quic_listener() ::
  :inet.port_number() | {:inet.port_number(), quic_listener_opts()}

quic_listener_opts()

@type quic_listener_opts() :: [ip: :inet.ip_address(), tls: tls()]

start_error()

@type start_error() ::
  {:validation_failed, String.t()}
  | {:binary_not_found, name :: Path.t()}
  | {:exit_status, non_neg_integer()}
  | {:not_ready, timeout_ms :: non_neg_integer()}

tls()

@type tls() ::
  {:generate, [String.t(), ...]} | {:files, cert :: Path.t(), key :: Path.t()}

The certificate of the QUIC listener.

  • {:generate, hosts} - self-signed by the relay at startup for hosts. Clients pin it by its hash, served by the web listener at /certificate.sha256.
  • {:files, cert, key} - paths to a PEM certificate chain and its private key.

Functions

args(opts)

@spec args(options()) :: [String.t()]

The arguments the relay binary is run with. Raises ArgumentError when options fail validation.

child_spec(init_arg)

@spec child_spec(options()) :: Supervisor.child_spec()

Returns a specification to start this module under a supervisor.

See Supervisor.

find_binary(binary \\ nil)

@spec find_binary(Path.t() | nil) :: Path.t() | nil

Finds the relay binary:

  • binary if given,
  • else $MOQ_RELAY,
  • else looks it up on $PATH.

A path is expanded relative to the current directory. Returns nil if not found.

info(relay)

Endpoints through which the relay can be reached, see %ExMoQ.Relay.Info{}.

start(opts \\ [])

@spec start(options()) ::
  {:ok, pid()} | {:error, start_error() | {:already_started, pid()}}

Starts a relay not linked to the caller and blocks until moq-relay is ready to accept connections.

start_link(opts \\ [])

@spec start_link(options()) ::
  {:ok, pid()} | {:error, start_error() | {:already_started, pid()}}

Starts a relay linked to the caller and blocks until moq-relay is ready to accept connections.

stop(relay, timeout \\ 5000)

@spec stop(GenServer.server(), timeout()) :: :ok