webrtc_sctp_assoc (webrtc v0.1.0)

View Source

Sans-IO SCTP association (RFC 9260) for SCTP over DTLS (RFC 8261), with partial reliability (RFC 3758, RFC 7496), stream reconfiguration (RFC 6525), message interleaving (RFC 8260) and zero checksum (RFC 9653).

The engine follows the contract of docs/ARCHITECTURE.md: it never does IO, reads the clock or starts timers. The owner feeds it the decrypted DTLS application data with handle_packet/3, calls handle_timeout/2 at the time returned by next_timeout/1 and executes the returned actions:

- {send, Bin}: send Bin as one DTLS application data record. - {event, Event}: report to the upper layer.

Events:

- {connected, Info} and {restarted, Info} (peer restart, §5.2.4 case A, all state was reset). Info holds the negotiated features: message_interleaving, partial_reliability, stream_reconfig, zero_checksum, outbound_streams, inbound_streams, peer_rwnd. - {message, StreamId, Ppid, Data}: a complete user message. - {message_too_large, StreamId}: a message over max_message_size was dropped; later data on the stream is dropped until it is reset. - {stream_reset, [StreamId]}: the peer reset these incoming streams ([] means all). The next message starts at sequence number 0. - {outgoing_stream_reset, [StreamId]}: a reset requested with reset_streams/3 completed. - {stream_reset_failed, [StreamId], Result}: the peer refused it. - {buffered_amount_low, StreamId}: the bytes queued on the stream fell to the threshold set with set_buffered_amount_low_threshold/3. - {peer_error, [Cause]}: the peer sent an ERROR chunk. - {closed, Reason}: the association is over. Reasons: shutdown, aborted (local abort), {peer_abort, [Cause]}, max_retransmissions, handshake_timeout, stale_cookie, shutdown_timeout (T5-shutdown-guard, 5 times rto_max), {protocol_violation, Info}.

Options of new/1 (all optional): local_port, remote_port (default 5000), mtu (largest SCTP packet, default 1200; the base size of path MTU discovery), max_mtu (largest packet PLPMTUD probes for, default mtu: no discovery), outbound_streams, inbound_streams (default 65535), receive_buffer (advertised window, default 1 MiB), send_buffer (bytes queued and not yet sent, default 8 MiB), max_message_size (largest incoming message, default 256 KiB), rto_initial, rto_min, rto_max (ms, defaults 1000, 1000, 60000), max_backoff (ms or infinity, the default: the ceiling of the doubling after a timer expires, see webrtc_sctp_ack:backoff/3), max_burst (4), max_retransmissions (Association.Max.Retrans, 10, or infinity: never give up on the peer, the owner ends the association), max_init_retransmissions (8), cookie_lifetime (ms, 60000), heartbeat_interval (ms or infinity, 30000), sack_delay (ms, at most 500, default 200), sack_frequency (2), interleaving (offer I-DATA, default false), zero_checksum (accept and send zero checksums when the peer agrees, only valid over DTLS, default false), cookie_secret (binary, default random) and random_seed (deterministic tags and TSNs for tests).

Summary

Functions

Abort the association (§9.1); Reason goes into a User-Initiated Abort cause when not empty.

Start the association: send INIT (no-op unless closed).

Negotiated parameters (empty before establishment).

The lower layer moved to another path (RFC 8261 §6.1, ICE selected a new pair): path MTU back to the base and searched again, congestion state and RTO back to their initial values (RFC 9260 §7.2.1, §6.3).

Restart congestion control, keeping the path's RTT and MTU: the DSCP of the association changed (RFC 8837 §5).

Reset outgoing streams (RFC 6525), used to close data channels. The request is sent once every message queued on these streams has been handed to SCTP.

Queue a user message. Messages sent before the association is established wait in the queue. Options: ordered (default true) and one partial reliability policy, max_retransmits or max_lifetime (milliseconds, counted from this call).

Scheduling weight of an outgoing stream (RFC 8260 §3.6).

Graceful shutdown (§9.2): queued data is sent and acknowledged before SHUTDOWN.

Counters and current congestion control state.

Types

action/0

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

assoc/0

-opaque assoc()

event/0

-type event() ::
          {connected, map()} |
          {restarted, map()} |
          {message, 0..65535, 0..4294967295, binary()} |
          {message_too_large, 0..65535} |
          {stream_reset, [0..65535]} |
          {outgoing_stream_reset, [0..65535]} |
          {stream_reset_failed, [0..65535], term()} |
          {buffered_amount_low, 0..65535} |
          {peer_error, [term()]} |
          {closed, term()}.

send_opts/0

-type send_opts() ::
          #{ordered => boolean(),
            max_retransmits => non_neg_integer() | infinity,
            max_lifetime => non_neg_integer() | infinity}.

Functions

abort(Now, A)

-spec abort(integer(), assoc()) -> {assoc(), [action()]}.

abort(Reason, Now, Assoc)

-spec abort(binary(), integer(), assoc()) -> {assoc(), [action()]}.

Abort the association (§9.1); Reason goes into a User-Initiated Abort cause when not empty.

buffered_amount(Sid, Assoc)

-spec buffered_amount(0..65535, assoc()) -> non_neg_integer().

connect(Now, A)

-spec connect(integer(), assoc()) -> {assoc(), [action()]}.

Start the association: send INIT (no-op unless closed).

handle_packet(Bin, Now, Assoc)

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

handle_timeout(Now, A0)

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

info(Assoc)

-spec info(assoc()) -> map().

Negotiated parameters (empty before establishment).

new(Opts)

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

next_timeout(Assoc)

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

path_changed(Now, Assoc)

-spec path_changed(integer(), assoc()) -> {assoc(), [action()]}.

The lower layer moved to another path (RFC 8261 §6.1, ICE selected a new pair): path MTU back to the base and searched again, congestion state and RTO back to their initial values (RFC 9260 §7.2.1, §6.3).

reset_congestion(Assoc)

-spec reset_congestion(assoc()) -> assoc().

Restart congestion control, keeping the path's RTT and MTU: the DSCP of the association changed (RFC 8837 §5).

reset_streams(Sids, Now, Assoc)

-spec reset_streams([0..65535], integer(), assoc()) -> {ok, assoc(), [action()]} | {error, atom()}.

Reset outgoing streams (RFC 6525), used to close data channels. The request is sent once every message queued on these streams has been handed to SCTP.

send(Sid, Ppid, Data, Opts, Now, Assoc)

-spec send(0..65535, 0..4294967295, binary(), send_opts(), integer(), assoc()) ->
              {ok, assoc(), [action()]} | {error, atom()}.

Queue a user message. Messages sent before the association is established wait in the queue. Options: ordered (default true) and one partial reliability policy, max_retransmits or max_lifetime (milliseconds, counted from this call).

set_buffered_amount_low_threshold(Sid, Low, Assoc)

-spec set_buffered_amount_low_threshold(0..65535, non_neg_integer(), assoc()) -> assoc().

set_stream_priority(Sid, W, Assoc)

-spec set_stream_priority(0..65535, 0..65535, assoc()) -> assoc().

Scheduling weight of an outgoing stream (RFC 8260 §3.6).

shutdown(Now, Assoc)

-spec shutdown(integer(), assoc()) -> {assoc(), [action()]}.

Graceful shutdown (§9.2): queued data is sent and acknowledged before SHUTDOWN.

state(Assoc)

-spec state(assoc()) -> atom().

stats(Assoc)

-spec stats(assoc()) -> map().

Counters and current congestion control state.