webrtc_turn_client (webrtc v0.1.0)

View Source

Sans-IO TURN client for UDP (RFC 8656), one allocation per client state.

The client talks to a single TURN server over the owner's UDP socket. It never touches the socket: it returns {send, Bin} actions (the destination is always the server) and {event, Event} actions.

  C0 = webrtc_turn_client:new(#{server => {IP, 3478},
                               username => <<"u">>, password => <<"p">>}),
  {C1, Acts} = webrtc_turn_client:allocate(Now, C0),
  %% for every datagram from the server:
  {C2, Acts2} = webrtc_turn_client:handle_packet(Bin, Now, C1),
  %% at next_timeout/1:
  {C3, Acts3} = webrtc_turn_client:handle_timeout(Now, C2),
  %% relay data to a peer (a permission is created on demand):
  {C4, Acts4} = webrtc_turn_client:send(PeerAddr, Data, Now, C3),
  %% release the allocation:
  {C5, Acts5} = webrtc_turn_client:close(Now, C4).

Behavior:

  • Allocate is sent first without credentials (RFC 8489 §9.2.3.1). A 401 with REALM and NONCE is retried with the long-term credential (USERNAME, REALM, NONCE, MESSAGE-INTEGRITY). When the 401 carries PASSWORD-ALGORITHMS the first supported algorithm is used, PASSWORD-ALGORITHMS and PASSWORD-ALGORITHM are echoed and all later requests use MESSAGE-INTEGRITY-SHA256 (§9.2.5). A 438 is retried with the new nonce.
  • REQUESTED-TRANSPORT is always UDP. REQUESTED-ADDRESS-FAMILY is sent when the family option is given.
  • The allocation is refreshed one minute before it expires (or at half its lifetime when shorter than two minutes).
  • Permissions are refreshed every 240 s (lifetime 300 s), channel bindings every 540 s (lifetime 600 s).
  • send/4 uses ChannelData when a channel is bound to the peer, otherwise a Send indication. Data for a peer without an installed permission is queued (bounded) until CreatePermission succeeds.
  • Responses to authenticated requests must carry valid integrity, otherwise they are discarded and retransmissions continue.

Events:

  • {allocated, #{relayed := Addr, mapped := Addr | undefined, lifetime := Seconds}}
  • {allocate_failed, Reason} with timeout, {error, Code} or {unsupported, What}
  • {allocation_lost, Reason} (437, refresh failure, expiry)
  • {permission, IP, ok | {error, Reason}}
  • {channel, Peer, {ok, Number} | {error, Reason}}
  • {data, Peer, Data}: data relayed from Peer
  • closed: the allocation was deleted

Summary

Functions

Bind a channel to Peer (RFC 8656 §12.1). Data keeps flowing through Send indications until the binding is confirmed.

Delete the allocation (Refresh with LIFETIME 0, RFC 8656 §8).

Install (or keep refreshing) a permission for IP.

Options: server (required), username, password, software (default <<"erlang-webrtc">>, undefined to omit), family (ipv4 | ipv6, REQUESTED-ADDRESS-FAMILY), lifetime (requested seconds), rto, rc, rm (transactions), queue_limit.

Relay Data to Peer. Dropped (as UDP would) when there is no allocation.

Types

action/0

-type action() :: {send, binary()} | {event, event()}.

address/0

-type address() :: webrtc_stun:address().

client/0

-opaque client()

event/0

-type event() ::
          {allocated,
           #{relayed := address(), mapped := address() | undefined, lifetime := non_neg_integer()}} |
          {allocate_failed, term()} |
          {allocation_lost, term()} |
          {permission, inet:ip_address(), ok | {error, term()}} |
          {channel, address(), {ok, 16384..20479} | {error, term()}} |
          {data, address(), binary()} |
          closed.

state_name/0

-type state_name() :: idle | allocating | allocated | failed | closing | closed.

Functions

allocate(Now, Turn)

-spec allocate(integer(), client()) -> {client(), [action()]}.

bind_channel(Peer, Now, Turn)

-spec bind_channel(address(), integer(), client()) -> {client(), [action()]}.

Bind a channel to Peer (RFC 8656 §12.1). Data keeps flowing through Send indications until the binding is confirmed.

channel(Peer, Turn)

-spec channel(address(), client()) -> {ok, 16384..20479} | error.

close(Now, Turn)

-spec close(integer(), client()) -> {client(), [action()]}.

Delete the allocation (Refresh with LIFETIME 0, RFC 8656 §8).

create_permission(IP, Now, Turn)

-spec create_permission(inet:ip_address(), integer(), client()) -> {client(), [action()]}.

Install (or keep refreshing) a permission for IP.

handle_packet(Bin, Now, C)

-spec handle_packet(binary(), integer(), client()) -> {client(), [action()]}.

handle_timeout(Now, C)

-spec handle_timeout(integer(), client()) -> {client(), [action()]}.

has_permission(IP, Turn)

-spec has_permission(inet:ip_address(), client()) -> boolean().

mapped_address(Turn)

-spec mapped_address(client()) -> address() | undefined.

new(Opts)

-spec new(map()) -> client().

Options: server (required), username, password, software (default <<"erlang-webrtc">>, undefined to omit), family (ipv4 | ipv6, REQUESTED-ADDRESS-FAMILY), lifetime (requested seconds), rto, rc, rm (transactions), queue_limit.

next_timeout(Turn)

-spec next_timeout(client()) -> integer() | infinity.

relayed_address(Turn)

-spec relayed_address(client()) -> address() | undefined.

send(Peer, Data, Now, Turn)

-spec send(address(), binary(), integer(), client()) -> {client(), [action()]}.

Relay Data to Peer. Dropped (as UDP would) when there is no allocation.

server(Turn)

-spec server(client()) -> address().

state(Turn)

-spec state(client()) -> state_name().