Prepare for release

Author: mickel8

README.md

@@ -1,8 +1,26 @@
 # ExICE
 
+[![Package](https://img.shields.io/badge/-Package-important)](https://hex.pm/packages/ex_ice) 
+[![Documentation](https://img.shields.io/badge/-Documentation-blueviolet)](https://hexdocs.pm/ex_ice)
 [![codecov](https://codecov.io/gh/elixir-webrtc/ex_ice/branch/master/graph/badge.svg?token=83POQD1KST)](https://codecov.io/gh/elixir-webrtc/ex_ice)
 
-Implementation of Trickle ICE protocol - [RFC 8445](https://datatracker.ietf.org/doc/html/rfc8445) and [RFC 8838](https://datatracker.ietf.org/doc/html/rfc8838)
+Trickle ICE implementation.
+
+RFC implemented:
+* [RFC 8445](https://datatracker.ietf.org/doc/html/rfc8445)
+* [RFC 8838](https://datatracker.ietf.org/doc/html/rfc8838)
+
+## Features
+* compatible both with aggressive and regular nomination
+* role conflict resolution
+* supports host, prflx, srflx and remote relay candidates (support for local relay candidates is planned)
+* transaction pacing
+* keepalives on valid and selected pairs
+
+## Limitations
+* there is always only one stream and one component -
+we don't plan to add support for multiple streams and components
+as WebRTC multiplexes traffic on a single socket but PRs are welcomed
 
 ## Installation
 
@@ -14,4 +32,13 @@ def deps do
 end
 ```
 
+## Usage
+
+See our [example](https://github.com/elixir-webrtc/ex_ice/tree/master/example), 
+[integration tests](https://github.com/elixir-webrtc/ex_ice/blob/master/test/integration/p2p_test.exs),
+and [documentation](https://hexdocs.pm/ex_ice/readme.html) for usage examples.
+
+We also provide a very simple [signalling server](https://github.com/elixir-webrtc/ex_ice/tree/master/signalling_server), which can be used
+to connect two ICE agents.
+
 

lib/candidate.ex

@@ -34,9 +34,9 @@ defmodule ExICE.Candidate do
           type(),
           :inet.ip_address(),
           :inet.port_number(),
-          :inet.ip_address(),
-          :inet.port_number(),
-          :inet.socket(),
+          :inet.ip_address() | nil,
+          :inet.port_number() | nil,
+          :inet.socket() | nil,
           priority: integer()
         ) :: t()
   def new(type, address, port, base_address, base_port, socket, opts \\ [])

lib/candidate_pair.ex

@@ -55,7 +55,7 @@ defmodule ExICE.CandidatePair do
     }
   end
 
-  @spec schedule_keepalive(t(), Process.dest()) :: :ok
+  @spec schedule_keepalive(t(), Process.dest()) :: t()
   def schedule_keepalive(pair, dest \\ self())
 
   def schedule_keepalive(%{keepalive_timer: timer} = pair, dest) when is_reference(timer) do

lib/checklist.ex

@@ -7,7 +7,7 @@ defmodule ExICE.Checklist do
 
   @type t() :: map()
 
-  @spec get_next_pair(t()) :: CandidatePair.t()
+  @spec get_next_pair(t()) :: CandidatePair.t() | nil
   def get_next_pair(checklist) do
     # FIXME correctly handle frozen pairs, according to sec 6.1.4.2
     checklist
@@ -16,27 +16,27 @@ defmodule ExICE.Checklist do
     |> elem(1)
   end
 
-  @spec get_pair_for_nomination(t()) :: CandidatePair.t()
+  @spec get_pair_for_nomination(t()) :: CandidatePair.t() | nil
   def get_pair_for_nomination(checklist) do
     checklist
     |> Enum.filter(fn {_id, pair} -> pair.valid? end)
     |> Enum.max_by(fn {_id, pair} -> pair.priority end, fn -> {nil, nil} end)
     |> elem(1)
   end
 
-  @spec get_valid_pair(t()) :: CandidatePair.t()
+  @spec get_valid_pair(t()) :: CandidatePair.t() | nil
   def get_valid_pair(checklist) do
     checklist
     |> Enum.find({nil, nil}, fn {_id, pair} -> pair.valid? end)
     |> elem(1)
   end
 
-  @spec find_pair(t(), CandidatePair.t()) :: CandidatePair.t()
+  @spec find_pair(t(), CandidatePair.t()) :: CandidatePair.t() | nil
   def find_pair(checklist, pair) do
     find_pair(checklist, pair.local_cand, pair.remote_cand)
   end
 
-  @spec find_pair(t(), Candidate.t(), Candidate.t()) :: CandidatePair.t()
+  @spec find_pair(t(), Candidate.t(), Candidate.t()) :: CandidatePair.t() | nil
   def find_pair(checklist, local_cand, remote_cand) do
     # TODO which pairs are actually the same?
     checklist
@@ -75,7 +75,7 @@ defmodule ExICE.Checklist do
 
   @spec prune(t()) :: t()
   def prune(checklist) do
-    # This is done according to RFC 8838 sec. 10 
+    # This is done according to RFC 8838 sec. 10
     {waiting, in_flight_or_done} =
       Enum.split_with(checklist, fn {_id, p} -> p.state in [:waiting, :frozen] end)
 

lib/ice_agent.ex

@@ -32,6 +32,11 @@ defmodule ExICE.ICEAgent do
 
   @conn_check_handler %{controlling: ControllingHandler, controlled: ControlledHandler}
 
+  @typedoc """
+  ICE agent role.
+
+  `:controlling` agent is responsible for nominating a pair.
+  """
   @type role() :: :controlling | :controlled
 
   @typedoc """
@@ -72,52 +77,98 @@ defmodule ExICE.ICEAgent do
           stun_servers: [String.t()]
         ]
 
-  defguard are_pairs_equal(p1, p2)
-           when p1.local_cand.base_address == p2.local_cand.base_address and
-                  p1.local_cand.base_port == p2.local_cand.base_port and
-                  p1.local_cand.address == p2.local_cand.address and
-                  p1.local_cand.port == p2.local_cand.port and
-                  p1.remote_cand.address == p2.remote_cand.address and
-                  p1.remote_cand.port == p2.remote_cand.port
+  defguardp are_pairs_equal(p1, p2)
+            when p1.local_cand.base_address == p2.local_cand.base_address and
+                   p1.local_cand.base_port == p2.local_cand.base_port and
+                   p1.local_cand.address == p2.local_cand.address and
+                   p1.local_cand.port == p2.local_cand.port and
+                   p1.remote_cand.address == p2.remote_cand.address and
+                   p1.remote_cand.port == p2.remote_cand.port
 
-  defguard is_response(class) when class in [:success_response, :error_response]
+  defguardp is_response(class) when class in [:success_response, :error_response]
 
+  @doc """
+  Starts and links a new ICE agent.
+
+  Process calling this function is called a `controlling process` and
+  has to be prepared for receiving ExICE messages described by `t:signal/0`.
+  """
   @spec start_link(role(), opts()) :: GenServer.on_start()
   def start_link(role, opts \\ []) do
     GenServer.start_link(__MODULE__, opts ++ [role: role, controlling_process: self()])
   end
 
+  @doc """
+  Gets local credentials.
+
+  They remain unchanged until ICE restart.
+  """
   @spec get_local_credentials(pid()) :: {:ok, ufrag :: binary(), pwd :: binary()}
   def get_local_credentials(ice_agent) do
     GenServer.call(ice_agent, :get_local_credentials)
   end
 
+  @doc """
+  Sets remote credentials.
+
+  Call to this function is mandatory to start connectivity checks.
+  """
   @spec set_remote_credentials(pid(), binary(), binary()) :: :ok
   def set_remote_credentials(ice_agent, ufrag, passwd)
       when is_binary(ufrag) and is_binary(passwd) do
     GenServer.cast(ice_agent, {:set_remote_credentials, ufrag, passwd})
   end
 
+  @doc """
+  Starts ICE gathering process.
+
+  Once a new candidate is discovered, it is sent as a message to the controlling process.
+  See `t:signal/0` for a message structure.
+  """
   @spec gather_candidates(pid()) :: :ok
   def gather_candidates(ice_agent) do
     GenServer.cast(ice_agent, :gather_candidates)
   end
 
+  @doc """
+  Adds a remote candidate.
+
+  If an ICE agent has already gathered any local candidates and
+  have remote credentials set, adding a remote candidate will start
+  connectivity checks.
+  """
   @spec add_remote_candidate(pid(), String.t()) :: :ok
   def add_remote_candidate(ice_agent, candidate) when is_binary(candidate) do
     GenServer.cast(ice_agent, {:add_remote_candidate, candidate})
   end
 
+  @doc """
+  Informs ICE agent that a remote side finished its gathering process.
+
+  Call to this function is mandatory to nominate a pair (when an agent is the `controlling` one)
+  and in turn move to the `completed` state.
+  """
   @spec end_of_candidates(pid()) :: :ok
   def end_of_candidates(ice_agent) do
     GenServer.cast(ice_agent, :end_of_candidates)
   end
 
+  @doc """
+  Sends data.
+
+  Can only be called after moving to the `connected` state.
+  """
   @spec send_data(pid(), binary()) :: :ok
   def send_data(ice_agent, data) when is_binary(data) do
     GenServer.cast(ice_agent, {:send_data, data})
   end
 
+  @doc """
+  Restarts ICE.
+
+  If there were any valid pairs in the previous ICE session,
+  data can still be sent.
+  """
   @spec restart(pid()) :: :ok
   def restart(ice_agent) do
     GenServer.cast(ice_agent, :restart)
@@ -998,7 +1049,7 @@ defmodule ExICE.ICEAgent do
     Checklist pair: #{checklist_pair.id}.
     """)
 
-    # if we get here, don't update discovered_pair_id and succeeded_pair_id of 
+    # if we get here, don't update discovered_pair_id and succeeded_pair_id of
     # the checklist pair as they are already set
     conn_check_pair = %CandidatePair{
       conn_check_pair

mix.exs

@@ -1,14 +1,23 @@
 defmodule ExICE.MixProject do
   use Mix.Project
 
+  @version "0.1.0"
+  @source_url "https://github.com/elixir-webrtc/ex_ice"
+
   def project do
     [
       app: :ex_ice,
-      version: "0.0.1",
+      version: "0.1.0",
       elixir: "~> 1.13",
       start_permanent: Mix.env() == :prod,
+      description: "Implementation of trickle ICE protocol",
+      package: package(),
       deps: deps(),
 
+      # docs
+      docs: docs(),
+      source_url: @source_url,
+
       # code coverage
       test_coverage: [tool: ExCoveralls],
       preferred_cli_env: [
@@ -27,6 +36,13 @@ defmodule ExICE.MixProject do
     ]
   end
 
+  def package do
+    [
+      licenses: ["Apache-2.0"],
+      links: %{"GitHub" => "https://github.com/elixir-webrtc/ex_ice"}
+    ]
+  end
+
   defp deps do
     [
       {:ex_stun, "~> 0.1.0"},
@@ -35,4 +51,14 @@ defmodule ExICE.MixProject do
       {:credo, "~> 1.6", only: [:dev, :test], runtime: false}
     ]
   end
+
+  defp docs do
+    [
+      main: "readme",
+      extras: ["README.md"],
+      source_ref: "v#{@version}",
+      formatters: ["html"],
+      nest_modules_by_prefix: [ExICE]
+    ]
+  end
 end