Skip to main content

Crate srt_runtime

Crate srt_runtime 

Source
Expand description

srt-runtime — SRT (Secure Reliable Transport) packet codecs.

Spec grounding: 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

Re-exports§

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

Modules§

arq
SRT ARQ (Automatic Repeat reQuest) reliability engine — draft-sharabayko-srt-01 §4.8 (Acknowledgement and Lost Packet Handling), §4.8.1 (Packet Acknowledgement — ACKs, ACKACKs), §4.8.2 (Packet Retransmission — NAKs), §4.10 (Round-Trip Time Estimation). Curated behavioural rules: specs/rules/srt-arq.md. The wire field layouts this module drives (ACK/NAK/ACKACK) are the existing crate::packet codecs — this module never re-encodes them, it only decides when to build one and what to do with one received.
caller
Caller-side handshake engine — draft-sharabayko-srt-01 §4.3.1 (Caller-Listener Handshake), Caller role.
cryptocrypto
SRT payload encryption — draft-sharabayko-srt-01 §6 (“Encryption”).
error
Error type for SRT packet parsing and serialization.
filecc
SRT File Transfer Congestion Control (FileCC) — window-based congestion control, draft-sharabayko-srt-01 §5.2 (curated at specs/rules/srt-congestion.md).
handshake_sm
Shared types for the sans-IO HSv5 handshake state machine — draft-sharabayko-srt-01 §4.3 (Handshake Messages) / §4.3.1 (Caller-Listener Handshake).
iotokio
Async real-socket UDP adapter over the sans-IO SRT engine.
km_refreshcrypto
SEK-rotation (“KM Refresh”) driver — draft-sharabayko-srt-01 §6.1.6 (KM Refresh), curated at specs/rules/srt-crypto.md (“KM Refresh — §6.1.6”).
listener
Listener-side handshake engine — draft-sharabayko-srt-01 §4.3.1 (Caller-Listener Handshake), Listener role.
livecc
SRT Live Congestion Control — packet pacing (draft-sharabayko-srt-01 §5.1, curated at specs/rules/srt-livecc.md).
packet
SRT packet structure — draft-sharabayko-srt-01 §3 (Packet Structure).
rendezvous
Rendezvous handshake engine — draft-sharabayko-srt-01 §4.3.2 (Rendezvous Handshake), curated at specs/rules/srt-rendezvous.md. Line cites below (LNNNN) are the source draft’s line numbers, exactly as recorded in that curation.
tsbpd
Timestamp-Based Packet Delivery (TSBPD) + Too-Late Packet Drop — SRT receiver-side delivery scheduling.

Constants§

SPEC
The Internet-Draft this crate implements packet structure from.