From d86ac87aeb7f848504fa430e636915313a63eafb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20=C5=9Aled=C5=BA?= Date: Mon, 6 Nov 2023 12:49:52 +0100 Subject: [PATCH] Document and refactor PeerConnection options (#11) --- lib/ex_webrtc/ice_candidate.ex | 4 +- lib/ex_webrtc/peer_connection.ex | 26 +++--- .../peer_connection/configuration.ex | 81 ++++++------------- lib/ex_webrtc/session_description.ex | 4 +- 4 files changed, 42 insertions(+), 73 deletions(-) diff --git a/lib/ex_webrtc/ice_candidate.ex b/lib/ex_webrtc/ice_candidate.ex index ae0a2a65..e597d912 100644 --- a/lib/ex_webrtc/ice_candidate.ex +++ b/lib/ex_webrtc/ice_candidate.ex @@ -1,5 +1,7 @@ defmodule ExWebRTC.IceCandidate do - @moduledoc false + @moduledoc """ + ICE candidate + """ # not exacly the same as W3 IceCandidate @type t() :: %__MODULE__{ diff --git a/lib/ex_webrtc/peer_connection.ex b/lib/ex_webrtc/peer_connection.ex index 60fb1d55..c9e1f69a 100644 --- a/lib/ex_webrtc/peer_connection.ex +++ b/lib/ex_webrtc/peer_connection.ex @@ -1,5 +1,7 @@ defmodule ExWebRTC.PeerConnection do - @moduledoc false + @moduledoc """ + PeerConnection + """ use GenServer @@ -46,12 +48,15 @@ defmodule ExWebRTC.PeerConnection do ] #### API #### - - def start_link(configuration \\ []) do + @spec start_link(Configuration.options()) :: GenServer.on_start() + def start_link(options \\ []) do + configuration = Configuration.from_options!(options) GenServer.start_link(__MODULE__, {self(), configuration}) end - def start(configuration \\ []) do + @spec start(Configuration.options()) :: GenServer.on_start() + def start(options \\ []) do + configuration = Configuration.from_options!(options) GenServer.start(__MODULE__, {self(), configuration}) end @@ -103,16 +108,7 @@ defmodule ExWebRTC.PeerConnection do @impl true def init({owner, config}) do - config = struct(Configuration, config) - :ok = Configuration.check_support(config) - - # ATM, ExICE does not support relay via TURN - stun_servers = - config.ice_servers - |> Enum.flat_map(&if(is_list(&1.urls), do: &1.urls, else: [&1.urls])) - |> Enum.filter(&String.starts_with?(&1, "stun:")) - - {:ok, ice_agent} = ICEAgent.start_link(:controlled, stun_servers: stun_servers) + {:ok, ice_agent} = ICEAgent.start_link(:controlled, stun_servers: config.ice_servers) dtls_transport = DTLSTransport.new(ice_agent) state = %__MODULE__{ @@ -425,8 +421,6 @@ defmodule ExWebRTC.PeerConnection do end {:ok, %{state | transceivers: new_transceivers, dtls_transport: dtls}} - else - error -> error end end diff --git a/lib/ex_webrtc/peer_connection/configuration.ex b/lib/ex_webrtc/peer_connection/configuration.ex index c197389e..865d8f73 100644 --- a/lib/ex_webrtc/peer_connection/configuration.ex +++ b/lib/ex_webrtc/peer_connection/configuration.ex @@ -1,10 +1,7 @@ defmodule ExWebRTC.PeerConnection.Configuration do - @moduledoc false - - @type bundle_policy() :: - :balanced - | :max_compat - | :max_bundle + @moduledoc """ + PeerConnection configuration + """ @type ice_server() :: %{ optional(:credential) => String.t(), @@ -12,61 +9,35 @@ defmodule ExWebRTC.PeerConnection.Configuration do :urls => [String.t()] | String.t() } - # TODO implement - @type certificate() :: :TODO - - @type ice_transport_policy() :: - :all - | :relay - - @type rtcp_mux_policy() :: - :negotiate - | :require - - @type t() :: %__MODULE__{ - bundle_policy: bundle_policy(), - certificates: [certificate()], - ice_candidate_pool_size: non_neg_integer(), - ice_servers: [ice_server()], - ice_transport_policy: ice_transport_policy(), - peer_identity: String.t(), - rtcp_mux_policy: rtcp_mux_policy() - } - - defstruct bundle_policy: :max_bundle, - certificates: nil, - ice_candidate_pool_size: 0, - ice_servers: [], - ice_transport_policy: :all, - peer_identity: nil, - rtcp_mux_policy: :require + @typedoc """ + Options that can be passed to `ExWebRTC.PeerConnection.start_link/1`. - @spec check_support(t()) :: :ok - def check_support(config) do - if config.ice_transport_policy != :all do - raise "#{inspect(config.ice_transport_policy)} ice transport policy is currently not supported" - end + Currently, ExWebRTC always uses the following config: + * bundle_policy - max_bundle + * ice_candidate_pool_size - 0 + * ice_transport_policy - all + * rtcp_mux_policy - require - if config.ice_candidate_pool_size != 0 do - raise "Ice candidate pool size different than 0 (pre-gathering) is currently not supported" - end + This config cannot be changed. + """ + @type options() :: [ice_servers: [ice_server()]] - if config.bundle_policy != :max_bundle do - raise "Bundle policy options different than :max_bundle are currently not supported" - end + @typedoc false + @type t() :: %__MODULE__{ice_servers: [ice_server()]} - if config.certificates != nil do - raise "Certificates configuration option is currently not supported" - end + defstruct ice_servers: [] - if config.peer_identity != nil do - raise "Identify option is currently not supported" - end + @doc false + @spec from_options!(options()) :: t() + def from_options!(options) do + config = struct!(__MODULE__, options) - if config.rtcp_mux_policy != :require do - raise "RTCP mux policy option :negotiate is currently not supported" - end + # ATM, ExICE does not support relay via TURN + stun_servers = + config.ice_servers + |> Enum.flat_map(&List.wrap(&1.urls)) + |> Enum.filter(&String.starts_with?(&1, "stun:")) - :ok + %__MODULE__{config | ice_servers: stun_servers} end end diff --git a/lib/ex_webrtc/session_description.ex b/lib/ex_webrtc/session_description.ex index 4c5f1297..9e67d90c 100644 --- a/lib/ex_webrtc/session_description.ex +++ b/lib/ex_webrtc/session_description.ex @@ -1,5 +1,7 @@ defmodule ExWebRTC.SessionDescription do - @moduledoc false + @moduledoc """ + SessionDescription + """ @type description_type() :: :answer