ecc6767541
A task ended from outside (JoinHandle::abort, as a server's shutdown ends a task past its
bound) drops the RIST listener it holds unclosed. That drop only tells the receiver's task,
which holds the sockets, to go: the port stays bound until a worker has run it to its end.
`RistListener::closer` now gives a `RistCloser`. It closes the listener the way `close` does
(the receiver's task ended and awaited), from outside the task that holds it, after that task
has been ended. Two closes of one listener at once both return once it is closed, and a close
cut short leaves the task to the next. `close` and the drop behave as before.
tests/listener_close.rs holds it for each profile, from a task on a runtime of one worker, 40
rounds, with a flow connected every other round. The listener's task is ended, the closer
closes the listener, and both ports bind at once.
The file's tests now take fixed ports below the range a system hands out for port 0. On a
shared Linux host, 5 of 1000 runs of the binary failed with the earlier ports, the unchanged
SRT check among them: a port first handed out for port 0 went to another socket between a close
and the check. With the low ports: 1000 of 1000 pass on Linux and 300 of 300 on macOS.
Fail-first: the new test was run on unfixed origin/main (b56b175e9, Linux) with the closer
left out, the drop alone being all that tree offers. Both profiles failed at round 1:
"127.0.0.1:21232 is still bound when the close returns: Address already in use (os error 98)".
Co-Authored-By: Claude Opus 5.5 <[email protected]>
5.9 KiB
joule-contrib
Contribution over UDP with retransmission, for WAI's ingest gateway: SRT
(draft-sharabayko-srt-01) and RIST (VSF TR-06-1:2020 Simple Profile, VSF TR-06-2:2024 Main
Profile), the MPEG transport stream both carry, and an account of what became of every
sequence number. WAI's extensions/live-contribution.md profiles them; joule-moq-ingest
uses this crate to bring a contribution link into a room's tracks.
SRT
srt::Listener serves many callers on one UDP port, each connection found by the socket ID
its packets name; srt::call calls a listener. Both run the caller-listener handshake of the
draft's §4.3.1 (the SYN cookie, the HSv5 extensions, the stream ID, the key material), and
live mode (§7.1): every message one packet, TSBPD over the negotiated latency, too-late drop,
ACK/ACKACK with the RTT estimate, immediate and periodic NAKs, retransmission, AES-CTR with
the key wrapped (RFC 3394) under PBKDF2-HMAC-SHA1. A listener decides each caller through an
Admission, which sees the stream ID and gives the passphrase, the role (receive or send) and
the latency, or a rejection code. Listener::close returns once the port is closed: the
listener's task and every connection's (each holds the socket) ended and awaited, each
connection's SHUTDOWN sent. Dropping a listener only tells its task to go.
RIST (feature rist)
rist::RistListener receives one flow: the Simple Profile's RTP on an even port P and RTCP on
P + 1, or the Main Profile's GRE-over-UDP tunnel on one port, in reduced overhead mode with
the VSF EtherType or the legacy one, keep-alives, and PSK (PBKDF2-HMAC-SHA256 over the GRE
nonce, AES-CTR on the GRE sequence number). It takes the first flow whose CNAME is the one it
expects, and, under PSK, whose packets decrypt. It requests what is missing with range or
bitmask requests, measures the RTT with the RTT echo, and delivers each packet a buffer after
it was expected. RistListener::close returns once its port (the Simple Profile's two) is
closed; dropping it only tells its task to go. RistListener::closer gives a RistCloser,
which closes it the same way from outside the task that holds it, after that task has been
ended and dropped the listener unclosed. rist::send is the sender of either profile.
The account
stats::Account records what a receiver did with every sequence number, in order: delivered
at the first try, recovered within the window, dropped when its time passed, or outstanding
when the link ended; the loss runs, the requests sent and the numbers they named, the
retransmissions, duplicates and late arrivals received, the round trips, how long each
recovery took and its least margin. It is cut into parts, which the gateway signs as the link
record.
The transport stream
ts::Demux reads the PAT and PMT (each section's CRC checked) and reassembles each stream's
PES packets, with the PTS extended past 33 bits; a PES missing a packet is dropped whole and
counted. ts::Mux writes a program of one video and one audio stream, and ts::Pacer times
a stream's chunks by its PCR.
Tools
| binary | what |
|---|---|
joule-contrib-send |
sends a transport stream file (paced by its PCR) or a synthetic program over SRT (calling or listening) or RIST |
joule-contrib-recv |
receives over SRT or RIST into a file, and prints the link's account |
joule-contrib-bench |
one link on loopback, both ends in the process: the payload rate, CPU time and energy, with a lossy path if asked |
URLs: srt://HOST:PORT?streamid=…&passphrase=…&pbkeylen=16&latency=MS (calls; srt://:PORT
listens), rist://HOST:PORT?profile=simple|main&cname=…&secret=…&aes-type=128|256&buffer=MS.
Tests
| test | what |
|---|---|
| unit tests | RFC 3394, RFC 6070 and TR-06-2 Annex B vectors, SP 800-38A's CTR vector; the packet formats; the TR-06-1 Appendix A requests; the TS multiplexer against the demultiplexer, a lost packet, the PTS wrap; the account |
srt_link |
SRT on loopback through a proxy that drops datagrams each way, every payload in order, the account of every sequence number; each key length, a wrong and a missing passphrase, the rejection codes; a packet held for the latency window; a listener that sends to a caller that receives |
rist_link |
the Simple Profile with range and bitmask requests through lossy proxies; the Main Profile in the clear, under PSK of each length and in the legacy format; another CNAME and another passphrase refused |
listener_close |
from a task on a runtime of one worker, an SRT listener and a RIST listener of each profile closed many times, with a peer connected and without: each port binds at once when the close returns, and an SRT connection's link reads listener_stopped; a RIST listener held by a task that is ended, closed through its RistCloser, binds at once too |
interop (ignored) |
against each transport's reference tools run locally, named by WAI_SRT_LIVE_TRANSMIT, WAI_RISTSENDER and WAI_RISTRECEIVER: their caller and senders into this crate and this crate into their listener and receivers, byte for byte, encrypted and through lossy paths. With --ignored, a tool not named fails the test |
The lossy module's proxy drops, delays and reorders datagrams from a fixed seed.
Patents
VSF TR-06-1:2020 and TR-06-2:2024 each carry an intellectual property notice: a patent is
claimed to read on their protocol sections, and its holder has assured the forum that it will
license the claims to implementers. The RIST code is therefore built only with the feature
rist, which no default build turns on; whether a distributed build carries it is a licensing
decision for the distributor (extensions/live-contribution.md §10).
Dependencies
AES, CTR, HMAC, SHA-1 and SHA-256 from RustCrypto (MIT OR Apache-2.0); PBKDF2 (RFC 8018) and AES key wrap (RFC 3394) are written here over them. tokio, serde, serde_json, hex, tracing and rand_core: MIT or Apache-2.0. No C library is linked.
Licence
Apache-2.0.