webrtc_turn_client (webrtc v0.1.0)
View SourceSans-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
familyoption 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/4uses 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}withtimeout,{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 fromPeerclosed: 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
-type address() :: webrtc_stun:address().
-opaque client()
-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.
-type state_name() :: idle | allocating | allocated | failed | closing | closed.
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).
-spec create_permission(inet:ip_address(), integer(), client()) -> {client(), [action()]}.
Install (or keep refreshing) a permission for IP.
-spec has_permission(inet:ip_address(), client()) -> boolean().
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.
-spec state(client()) -> state_name().