srt-runtime 0.4.0

SRT (Secure Reliable Transport, draft-sharabayko-srt-01) packet codecs + sans-IO HSv5 Caller-Listener and Rendezvous handshake state machines, an ARQ reliability engine, a TSBPD delivery scheduler, LiveCC packet pacing, FileCC window-based congestion control, optional (crypto feature) payload encryption, and an optional (tokio feature) async UDP socket adapter; no_std core.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167

//! `srt-runtime` — SRT (Secure Reliable Transport) packet codecs.
//!
//! Spec grounding: [`draft-sharabayko-srt-01`](https://datatracker.ietf.org/doc/html/draft-sharabayko-srt-01)
//! (free, redistributable IETF Internet-Draft), vendored at
//! `specs/ietf_draft_sharabayko_srt_01.txt`; the curated field tables this
//! crate implements against live in `specs/rules/srt-rules.md`.
//!
//! # Scope of this release
//!
//! This release adds a sans-IO **ARQ (Automatic Repeat reQuest) reliability
//! engine** (§4.8/§4.8.1/§4.8.2/§4.10), a **TSBPD delivery scheduler**
//! (§4.5/§4.6/§4.7, curated at `specs/rules/srt-tsbpd.md`), a **LiveCC packet
//! pacing controller** (§5.1, curated at `specs/rules/srt-livecc.md`), a
//! **Rendezvous handshake state machine** (§4.3.2, curated at
//! `specs/rules/srt-rendezvous.md`), and the **HSv5 Caller-Listener handshake
//! state machine** (§4.3.1) on top of the packet codecs (§3, Packet Structure
//! — the 16-byte SRT header, the data packet §3.1, and every control packet
//! type in §3.2, including Handshake with its extension messages: Handshake
//! Extension §3.2.1.1, Key Material §3.2.1.2/§3.2.2, Stream ID §3.2.1.3, Group
//! Membership §3.2.1.4).
//!
//! - [`arq::Sender`] / [`arq::Receiver`] drive the loss-detection, ACK/NAK/
//!   ACKACK exchange, and RTT/RTTVar estimation (§4.8, §4.10) over the
//!   existing [`packet`] codecs — see the `arq` module doc for the full rule
//!   mapping and its explicit non-goals (TLPKTDROP, RTO/congestion control,
//!   send-queue overflow sizing).
//! - [`tsbpd::TsbpdScheduler`] drives receiver-side delivery timing (§4.5,
//!   rule 9's `PktTsbpdTime` formula) and too-late packet drop (§4.6,
//!   `TLPKTDROP_THRESHOLD`) — see the `tsbpd` module doc for the full rule
//!   mapping and its explicit non-goals (drift estimation, sender-side
//!   TLPKTDROP, wrapping-period `TsbpdTimeBase` adjustment).
//! - [`livecc::LiveCC`] drives sender-side packet pacing (§5.1): the
//!   `PKT_SND_PERIOD` inter-packet send interval computed from a running EWMA
//!   of `AvgPayloadSize` and the configured `MAX_BW` (§5.1.1's `MAXBW_SET` /
//!   `INPUTBW_SET` / `INPUTBW_ESTIMATED` modes) — see the `livecc` module doc
//!   for the full formula mapping.
//! - [`filecc::FileCc`] drives sender-side **file/bulk-transfer** congestion
//!   control (§5.2): the two-phase Slow Start / Congestion Avoidance
//!   AIMD algorithm that grows/shrinks both `CWND_SIZE` and `PKT_SND_PERIOD`
//!   — the window-based sibling of [`livecc::LiveCC`]'s pacing-only model —
//!   see the `filecc` module doc for the full formula mapping and its two
//!   flagged spec gaps.
//! - [`caller::CallerHandshake`] / [`listener::ListenerHandshake`] drive the
//!   induction → conclusion exchange (§4.3.1.1/§4.3.1.2): building the wire
//!   packets via the existing [`packet`] codecs, validating the peer's
//!   replies, and exposing [`handshake_sm::NegotiatedParams`] on success.
//! - [`rendezvous::RendezvousHandshake`] drives the symmetric peer-to-peer
//!   exchange (§4.3.2): both sides run the same engine; the cookie contest
//!   (greater cookie wins) resolves which one plays
//!   [`rendezvous::RendezvousRole::Initiator`] vs
//!   [`rendezvous::RendezvousRole::Responder`] at runtime, through the
//!   `Waving -> Attention -> Initiated -> Connected` states.
//!
//! The optional `crypto` feature (off by default) adds the §6 payload
//! **encryption** path on top of that: AES-CTR encrypt/decrypt, RFC 3394 AES
//! key wrap/unwrap of the SEK, and PBKDF2 (HMAC-SHA1) KEK derivation — see
//! [`crypto`]. [`packet::KeyMaterial`] still only carries the wrapped-key
//! *bytes*; [`crypto`] is what actually wraps/unwraps and encrypts/decrypts
//! them. The same feature also wires that primitive into the handshake
//! exchange — [`handshake_sm::CryptoConfig`] (§6.1.5 Key Material Exchange,
//! piggybacked on [`caller::CallerHandshake`]/[`listener::ListenerHandshake`]'s
//! existing CONCLUSION extension flow, reusing [`packet::KeyMaterial`]
//! rather than inventing a new wire message) — and adds a sans-IO
//! SEK-rotation driver for §6.1.6 KM Refresh, [`km_refresh::KmRefreshDriver`].
//!
//! **Explicit follow-ups, not attempted here:**
//! - CUBIC/BBR or any other alternative file-transfer congestion-control
//!   algorithm (§5.2 names them as applicable alternatives to
//!   [`filecc::FileCc`]'s default algorithm but does not describe them).
//! - Wiring [`filecc::FileCc`] / [`livecc::LiveCC`] into a real send-queue
//!   scheduler ([`arq::Sender`] has no congestion-control hook today).
//! - Wiring the negotiated SEK from [`handshake_sm::NegotiatedParams`] (or
//!   [`km_refresh::KmRefreshDriver`]'s events) into [`io`]'s tokio adapter to
//!   actually encrypt/decrypt data-packet payloads end-to-end over a real
//!   socket — the handshake negotiation and the rotation state machine are
//!   both sans-IO and fully wired/tested; driving real payload
//!   encryption from them through `io.rs` (additive, `crypto`-feature-gated,
//!   without touching the existing ARQ/TSBPD paths) is a follow-up.
//!
//! **Permanently out of scope:** the Version-4 legacy Rendezvous path (§4.3.2).
//! Only the current HSv5 Rendezvous flow ([`rendezvous`]) is implemented; V4 is
//! a legacy interop path for pre-HSv5 peers and is not planned.
//!
//! # The sans-IO contract
//!
//! No sockets: [`packet::SrtPacket::parse`] takes the bytes of one UDP
//! datagram and returns a typed packet; the packet's `serialize_into` writes
//! it back out. [`caller::CallerHandshake`] / [`listener::ListenerHandshake`]
//! / [`rendezvous::RendezvousHandshake`] extend the same contract to the
//! handshake *exchange* — `start`/`feed` consume typed packets and return
//! bytes to send plus typed [`handshake_sm::HandshakeOutput`] events;
//! timeouts/retransmits are driven by caller-supplied `tick()` calls, never a
//! wall-clock read from inside the crate.
//!
//! # Reserved-bit policy
//!
//! Fields the spec documents as fixed-value or reserved-for-future-use
//! (`Subtype` on every Control Type except User-Defined; the header
//! `Type-specific Information` word where a packet type does not use it; the
//! Key Material message's `S`/`V`/`PT`/`Sign`/`Resv1`/`Resv2`/`Resv3` fields)
//! are validated against their spec-mandated value on parse and are not
//! stored in the typed structs — they are reconstructed on serialize. A
//! non-compliant value is a structured [`error::Error`], never a panic.
//!
//! # Module map
//! - [`packet`] — [`packet::SrtPacket`], the data/control packet types, and
//!   their sub-structures (handshake extensions, Key Material, ACK variants,
//!   NAK loss-list coding).
//! - [`arq`] — [`arq::Sender`] / [`arq::Receiver`] (§4.8 ARQ, §4.10 RTT),
//!   [`arq::seq`] (wrap-safe sequence arithmetic), [`arq::rtt::RttEstimator`].
//! - [`tsbpd`] — [`tsbpd::TsbpdScheduler`]: sans-IO TSBPD delivery timing and
//!   too-late packet drop (§4.5/§4.6).
//! - [`livecc`] — [`livecc::LiveCC`] / [`livecc::MaxBwConfig`]: sans-IO LiveCC
//!   packet pacing (§5.1).
//! - [`filecc`] — [`filecc::FileCc`] / [`filecc::Phase`]: sans-IO FileCC
//!   window + pacing congestion control (§5.2).
//! - [`handshake_sm`] — shared handshake types: [`handshake_sm::HandshakeConfig`],
//!   [`handshake_sm::NegotiatedParams`], [`handshake_sm::HandshakeOutput`],
//!   [`handshake_sm::RejectionReason`] (§4.3, Table 7).
//! - [`caller`] — [`caller::CallerHandshake`] (§4.3.1, Caller role).
//! - [`listener`] — [`listener::ListenerHandshake`] (§4.3.1, Listener role).
//! - [`rendezvous`] — [`rendezvous::RendezvousHandshake`] (§4.3.2).
//! - [`error`] — the [`Error`] enum and [`Result`] alias.
//! - [`crypto`] (feature `crypto`) — §6 payload encryption primitives.
//! - [`km_refresh`] (feature `crypto`) — [`km_refresh::KmRefreshDriver`]: the
//!   sans-IO §6.1.6 KM Refresh (SEK-rotation) state machine.
//! - [`io`] (feature `tokio`) — [`io::SrtSocket`] / [`io::SrtListener`]: an
//!   async UDP socket adapter driving the sans-IO handshake + ARQ + TSBPD
//!   engines end-to-end over real sockets.

#![cfg_attr(not(feature = "std"), no_std)]
#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]

extern crate alloc;

pub mod arq;
pub mod caller;
#[cfg(feature = "crypto")]
#[cfg_attr(docsrs, doc(cfg(feature = "crypto")))]
pub mod crypto;
pub mod error;
pub mod filecc;
pub mod handshake_sm;
#[cfg(feature = "crypto")]
#[cfg_attr(docsrs, doc(cfg(feature = "crypto")))]
pub mod km_refresh;
pub mod listener;
pub mod livecc;
pub mod packet;
pub mod rendezvous;
pub mod tsbpd;

#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub mod io;

pub use caller::{CallerHandshake, CallerHandshakeState};
pub use error::{Error, Result};
pub use handshake_sm::{HandshakeConfig, HandshakeOutput, NegotiatedParams, RejectionReason};
pub use listener::{ListenerHandshake, ListenerHandshakeState};
pub use packet::SrtPacket;
pub use rendezvous::{RendezvousHandshake, RendezvousHandshakeState, RendezvousRole};

/// The Internet-Draft this crate implements packet structure from.
pub const SPEC: &str = "draft-sharabayko-srt-01";