dart_udx 4.3.0
dart_udx: ^4.3.0 copied to clipboard
A Dart implementation of UDX - reliable, multiplexed, and congestion-controlled streams over UDP
Changelog #
All notable changes to dart-udx will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
4.3.0 - 2026-10-23 #
Fixed #
- A sender lost part of its window with every retransmitted packet. The ACK path looked each acknowledged sequence up in a map keyed by the packet's original sequence; a retransmission is re-keyed under a fresh sequence, so the ACK of a resend found nothing and the packet's bytes stayed in flight and charged to the connection's send window for the rest of the connection. A dozen losses froze the sender, which then wrote only through a 30 s escape hatch that ignored both limits.
PacketManager.handleAckFramenow returns the acknowledged packets themselves (their size and last send time travel with them across a re-key), and the socket credits every one of them.test/retransmit_accounting_test.dartdrops packets on a relay and checks the accounting afterwards. - After the first loss a connection never sampled the RTT or grew its window again. The socket kept a TCP-style cumulative-ack point that a retransmission's never-acknowledged original sequence stuck forever; every later ACK counted as a duplicate. The controller now works from what each ACK frame newly acknowledges, as QUIC does (RFC 9002 sections 5.1 and 7.3): the RTT sample comes from the largest newly acknowledged packet's last send, the window grows by the bytes acknowledged, and recovery ends when a packet sent after it began is acknowledged. The duplicate-ACK counter and its fast retransmit are gone; loss detection from ACK ranges follows in a later release.
test/largest_newly_acked_test.dart. - A PTO probe could acknowledge data the peer never got. The probe was a PING under the last data packet's sequence number; both peers acknowledge a numbered PING, so when that data packet was lost and the PING arrived, its ACK marked the data acknowledged and the stream hung at that offset. The RTO and the PTO fire together, so one lost resend was enough. The probe is now the oldest unacknowledged packet re-sent under a fresh sequence (RFC 9002 section 6.2.4), and collapses into a resend made within the last RTO.
test/pto_probe_test.dart. UDPSocket.ping()never completed on a connection with nothing else in flight. Its PING was sent untracked, so the ACK matched nothing. The PING is tracked until acknowledged or the wait ends (never retransmitted), and its ACK also gives an RTT sample.- A go-udx sender got no loss signal from a dart-udx receiver. Every packet was acknowledged on arrival with only itself in the frame, so an ACK never showed a gap, a lost ACK lost that packet's acknowledgement for good, and the phone sent one datagram for every datagram it received. go-udx declares loss only from the gaps in an ACK, so server-to-phone traffic had no congestion response to loss at all and recovered by RTO timers alone. The receiver now keeps a 512-packet history (
RecvTracker, go-udx's recvTracker) and every ACK carries it as ranges, repeated until the sender has seen them (RFC 9000 section 13.2.4); it acknowledges at once when a packet is out of order, opens or closes a stream, or carries a PING or MTU probe, and otherwise after every second packet or when the ACK timer (a quarter of the smoothed RTT, 1 to 25 ms) fires, reporting the delay in the frame.test/recv_tracker_test.dart,test/delayed_ack_test.dart. The skippedack_handling_test.dart, which tested the stream-level ACK builder that no longer exists, is removed. - Timing no longer runs on the wall clock. RTT samples, send times, ACK delay, pacing, the idle check and every timer used
DateTime.now(), which a phone steps on carrier time sync and when it leaves doze: a forward step over 30 s idle-closed every connection on the next watchdog tick, a step of a few seconds inflated one RTT sample into a 5 s PTO, and a backward step gave negative samples. A monotonicClock(one process-wideStopwatch;SystemClock) now times everything, injectable throughUDXMultiplexer(clock:), andFakeClockdrives time by hand in tests.UDXPacket.sentTime,lastSentTimeandlastRetransmitandCongestionController.onPacketAcked's send time are instants on that clock (Duration), no longerDateTime.test/clock_test.dart. - Loss recovery is QUIC's: one PTO per connection with probes, loss declared from ACKs, persistent congestion. Recovery was one retransmission timer per packet, backing off to a 2 s cap, plus a PTO that only sent a PING. On a radio gap every timer fired together and the whole window went out again, past the congestion window and the pacer, and again every two seconds into a dead path; the resends never contracted the window. Now, as RFC 9002 and go-udx v0.2: loss is declared from acknowledgements over every outstanding packet below the largest acknowledged (three behind, or older than 9/8 RTT, with a loss timer for the rest); lost packets leave flight, contract the window once per epoch, and are re-sent under fresh sequences through the window and the pacer (
LostQueue, lost data before new data); one PTO per connection (srtt + max(4 rttvar, 1 ms) + max_ack_delay, doubling until the idle timeout) re-sends the two oldest outstanding packets as probes; a loss span of three PTOs with no ACK since is persistent congestion and collapses the window to the minimum.UDPSocket.ping()is unchanged.test/loss_detection_test.dart,test/pto_timer_test.dart,test/lost_queue_test.dart,test/persistent_congestion_test.dart, and a 3 s cut over real sockets intest/pto_probe_test.dart. - ACK delay handling follows RFC 9002 section 5.3. The first sample sets every estimate as measured; later samples subtract the reported delay (capped at 25 ms) only when that leaves them at or above
min_rtt. - Slow start ended at 64 KB. The slow-start threshold started at 65535 bytes, 44 packets, so after the first 64 KB the window grew at CUBIC's pace: on a lossless 40 ms path a sender was window-bound at 2 MB/s for the whole transfer. Slow start now runs until the first loss (RFC 9002 section 7.3.1); the same 2 MB over a 40 ms path takes half a second instead of two.
Changed #
- A writer blocked on the congestion window or the peer's limits now waits for the socket to wake it (
UDPSocket.sendCreditChanged, completed on every ACK, MAX_DATA, WINDOW_UPDATE and close) instead of polling every 50 ms, and never sends past a limit. While blocked on the peer's limit it sends STREAM_DATA_BLOCKED or DATA_BLOCKED every 500 ms, so a lost WINDOW_UPDATE or MAX_DATA is re-advertised (go-udx already answers both; a dart-udx receiver now re-advertises MAX_DATA on DATA_BLOCKED). CongestionController.onPacketAckedis called once per ACK frame with all the newly acknowledged bytes; its fourth argument now says whether the frame's largest acknowledged packet was newly acknowledged.processDuplicateAckandonFastRetransmitare removed.- The pacer follows the window. The pacing rate is gain × cwnd / smoothed RTT (gain 2 in slow start, 1.25 after, as QUIC stacks pace), recomputed on every change to the window or the RTT estimate; it used to be 2.88 × cwnd / min RTT, recomputed only when min RTT fell or the window contracted. Sends draw on a budget that holds a burst of ten datagrams (or two milliseconds of the rate, whichever is more), so a writer does not sleep between every two packets and Dart's whole-millisecond timers still reach the rate. PTO probes still go out unpaced but are drawn from the budget. Until the first RTT sample nothing is paced.
- The PTO has no 200 ms floor and no 5 s cap, and the first one is about a second. The probe timeout is smoothed RTT + max(4 × RTT variation, 1 ms) + max_ack_delay, as RFC 9002 section 6.2.1 has it: on a 30 ms path a loss costs about 60 ms, not the 200 ms floor that stood in for the missing max_ack_delay term, and a slow path's PTO is bounded by the backoff and the idle timeout. Before the first RTT sample the estimates are the RFC's initial 333 ms and 166 ms (they were 100 ms and 50 ms), so the first probe waits about a second for a slow path's handshake instead of 325 ms.
minRttis null until the first sample. - Streams send full-size datagrams on paths that carry them. Path-MTU discovery (RFC 8899) now runs: once the first RTT sample is in, the socket probes up from the 1200-byte base towards 1472 with padded, numbered packets, and streams chunk their data to the validated size (
UDPSocket.maxDatagram, read at each write). A probe size is ruled out after three losses; the search ends within 16 bytes of one that failed. A probe is never re-sent, is not booked in flight and its loss is no congestion signal. A path that shrinks under the validated size, as a carrier's tunnel does after a handover, is a black hole: three full-size data packets lost in a row with none acknowledged between, or three probe timeouts in a row, take the size back to 1200 at once, re-sends are re-chunked to fit, and the search starts over a minute later. The old controller was never driven, and a probe's padding was parsed as a thousand PADDING frames. Same model in go-udx.
4.2.1 - 2026-10-22 #
Fixed #
- A write of more than one packet never crossed a mobile carrier's path. Stream data went out in datagrams of up to 1454 bytes. A carrier's tunnel (464XLAT, GTP) carries less than 1500 and drops a larger datagram that may not be fragmented, so the write stalled until the connection was given up: a phone on Rogers 5G could not send a photo, a post with an image or its prekeys. Stream data now goes out in datagrams of at most 1200 bytes (
safeDatagramSize, QUIC's 1200), which fit the 1280-byte IPv6 minimum MTU with the longest connection IDs. go-udx v0.1.4 sends the same size.test/small_mtu_path_test.dartsends 8 KB across a 1350-byte path.
4.2.0 - 2026-10-18 #
Fixed #
- A multiplexer whose UDP socket stopped kept its connections on a dead socket (dartudx-5ry). Dart closes a socket on any error, for example when Android refuses the packets of an app whose network it cut while the screen was off. The multiplexer had no error or done handler and ignored
RawSocketEvent.closed, so it did not notice. Its connections stayed open, sends went nowhere, and every dial through it timed out. Now the multiplexer closes its connections and itsconnectionsstream when its socket stops, and sends nothing more.
Added #
UDXMultiplexer.donecompletes when the socket stops, with the error it stopped with, if any.UDXMultiplexer.lostis true when the socket stopped by itself, not byclose(). A listener can use it to bind a new socket.
4.1.0 - 2026-10-05 #
Added #
createSocket(..., shared: false)makes a dial that is its own connection. By default, a second dial to the samehost:portreturns the first dial's socket. Two callers that dialed one address at once then shared one connection and one close: when one caller gave up on its dial and closed its socket, the connection of the other caller also closed. Withshared: false, each call makes a new socket with its own connection ID, as in go-udx, and later calls do not get it back. The default does not change.
4.0.0 - 2026-10-04 #
One breaking change: crossing dials stay two connections, as with go-udx and js-udx, so a hole punch between dart-udx and go-libp2p peers completes.
Changed #
- Crossing dials are two connections, not one. When both ends dial each other at once (a hole punch), a SYN that arrived while this side's own dial to that address was still pending was folded into the dial, on the assumption that the peer would fold ours too. go-udx and js-udx never do: they keep both connections, so the folded socket answered whichever of the peer's two connections had last sent it a packet, and neither worked. Every new connection id is now its own connection, emitted on
connections, as with go-udx; a hole punch leaves one connection each way. Code that relied on twocreateSocketdials meeting as one connection must accept the peer's dial instead.
Fixed #
- A dial no longer reuses a connection the peer opened.
createSocketreturned any socket for the address, including one accepted from the peer, so a dial made after the peer's SYN arrived was sent over the peer's connection. Only dials are reused by address now. handleIncomingDatagramForTestroutes through the same code as received datagrams; it had its own, older copy.
Compatibility #
The wire version is still 3. A 3.x peer still folds a crossing dial into its own, so a simultaneous open between a 3.x peer and a 4.0.0 peer can fail as it did with go-udx; dial in one direction, or upgrade both ends.
3.1.0 - 2026-10-02 #
Interoperability fixes found while porting UDX to TypeScript (js-udx), checked against go-udx and js-udx over real UDP.
Fixed #
- Several streams on one connection no longer collapse into the first. A stream a peer opened was registered under the destination id the peer used. go-udx and js-udx never learn our id for a stream they open and address it to 0 throughout, as does dart-udx's own dialer, so every such stream became stream 0: a second one, concurrent or opened while the first was still closing, was routed into the first, its packets acknowledged and its bytes dropped, and it hung until the idle timeout. A stream a peer opens now gets the id the peer named if that is free (dart-libp2p names both ids of its first stream), or else the next free even id, as a go-udx acceptor would; its SYN-ACK carries that id.
- Frame types use go-udx's wire codes. They were written as the
FrameTypeenum's index, which has no gap at 0x0c, so every type from STOP_SENDING up was one below go-udx's and js-udx's. Those peers rejected our STOP_SENDING, and we misread their STREAM_DATA_BLOCKED (0x0f) as NEW_CONNECTION_ID and dropped the packet.FrameTypenow carries an explicitcode(FrameType.fromCode). - STREAM_DATA_BLOCKED is answered, as go-udx does, by re-advertising the stream's current limit. It is how go-udx and js-udx recover a stream whose WINDOW_UPDATE was lost. RESET_STREAM, STOP_SENDING, WINDOW_UPDATE and STREAM_DATA_BLOCKED are routed like STREAM frames, falling back to the sender's stream id.
- ACK frames never overflow their one-byte gap and range counts.
AckFrame.fromReceivedstops at a gap over 255 or at 255 ranges, andtoBytesthrows rather than silently truncating. - Connections from the same address stay apart. go-udx and js-udx dial every connection from one shared socket. An inbound SYN from an address with an existing connection joined that connection unless it was a genuine simultaneous open; it now gets its own socket, keyed by connection id.
Added #
UDPSocket.isServer,UDPSocket.isHandshakeCompleted,UDPSocket.allocateIncomingStreamId,UDXStream.deliverStreamDataBlocked,AckFrame.fromReceived,FrameType.codeandFrameType.fromCode.
Compatibility #
The wire version is still 3. Between 3.1.0 and 3.0.0 peers, STOP_SENDING (sent by UDXStream.stopReceiving) is lost in both directions, since the two number it differently; nothing else dart-udx sends changed. go-udx and js-udx interoperate fully only with 3.1.0.
3.0.0 - 2026-09-23 #
Breaking #
- Wire protocol v3: STREAM frames carry a byte offset and each stream reassembles its own bytes. Ordering used to happen at the socket, on the connection's packet sequence number, so a gap belonging to one stream stalled delivery on every other stream sharing the connection. That matters here more than in Go, because dart-libp2p uses UDX directly as its libp2p stream multiplexer, so concurrent streams are the normal case. v3 does not interoperate with v2 (2.0.x), and both ends must be upgraded together. The eight offset bytes sit where a v2 parser expects the data length, so a v2 peer does not fail on a v3 frame: it reads a plausible wrong length and hands nonsense to the application. The version is therefore checked on receive and packets of an unsupported version are dropped, which makes a mismatch look like an unreachable peer rather than corruption. go-udx carries the matching change; the two are a flag day.
- FIN carries the stream's final size. FIN is a flag on a frame that can overtake data still in flight, so closing on its arrival truncated the tail. A stream now ends when its delivered bytes reach that size.
UDXStream.datacounts consumption, and a slow reader now throttles the sender. The getter returns a cached mapped view of the underlying stream that counts each chunk as it is delivered. With no listener, or a paused subscription, events sit in the controller, nothing is counted, the advertised offset stops advancing and the sender stalls. That is the point: inbound transfers previously had no stream-level back-pressure at all.setWindowsets a window size rather than an absolute offset. It cannot revoke credit already granted: it advertisesbytesConsumed + newSize, and because the peer applies offsets monotonically, a smaller size takes effect only once the peer catches up to the offset it already holds.
Fixed #
- Stream flow control did not bind on upload. WINDOW_UPDATE carries an absolute offset, the highest cumulative byte position the peer will accept, but the sender compared it against
inflight, the bytes currently outstanding, which also happens to be the connection-level counter. Against an offset that grows for the life of the stream, that comparison stops binding almost immediately, leaving the congestion window as the only limit. Measured against a peer with a deliberately slow reader, the sender ran 3.9x past the offset it had been granted. It now gates on the per-streambytesWritten. - Offsets survive the 4GB wrap. The frame field is a uint32, so an offset is transmitted modulo 2^32. The receiver recovers the full value by choosing the candidate nearest the limit it already holds (RFC 1982 serial-number arithmetic), which is unambiguous because the true offset is always within one receive window of the current limit. Clamping instead would stall a stream permanently at 4GB. Updates are applied monotonically, so a stale or reordered frame can never revoke granted credit.
- The receive window tracked bytes received rather than bytes consumed, so a receiver kept granting credit whether or not the application was reading. A sender pushing 16MB at a reader sleeping 25ms between chunks had all 16,777,216 bytes accepted while the application had consumed 143,740. The window is now anchored to consumption, advertised as an absolute offset, and doubles per update up to 4MB. The same push now moves 361,980 bytes against 151,972 consumed. This supersedes the fixed-threshold workaround added in 2.0.3's line of development.
- Loss recovery follows QUIC. A retransmitted packet is re-keyed under a fresh sequence number and the give-up cap is removed, mirroring the go-udx fix.
sentTimeis deliberately not reset, since it is read only for persistent-congestion detection and RTT sampling uses a separate map, so retransmits correctly take no RTT sample. - Idle connections are now closed by a backstop timeout of
max(maxIdleTimeout, 3xPTO), self-rearming, which resets streams silently and logs the close reason. - A stream is opened by a data frame, not only by SYN. Opening on SYN alone was safe only while socket-level ordering guaranteed the SYN arrived first. A bare FIN deliberately still does not open one, since it carries nothing to deliver.
- Packets are routed by the sender's stream id when the destination id is unknown. A peer that has not yet learned our local id addresses its first packets to 0, so the same stream could arrive under two ids and open twice.
UDXPacket.currentVersionwas a second hardcoded copy of the version number that silently disagreed withUdxVersion.currentthe moment either was bumped. It now aliases it.- The out-of-order buffer's backstop sits above the largest receive window rather than at it, and overrunning it fails the stream rather than silently dropping bytes that were already acknowledged and so will never be re-sent.
- SocketException from the multiplexer is handled: the error is emitted as an event and the socket closes gracefully instead of throwing out of the send path.
Added #
- Diagnostic logging points for packet receive, ACK generation, send and small-payload delivery, gated behind
UdxLogging.infoand off by default.
2.0.3 - 2026-02-22 #
Fixed #
- Control-only stream packets (WindowUpdate) no longer consume sequence numbers, preventing permanent receiver stalls when the Go UDX peer buffers out-of-order packets waiting for a gap that can never be filled
- Fixes 64KB+ payload echo timeouts and yamux keepalive-triggered connection kills
2.0.2 - 2026-02-22 #
Fixed #
- Control-only packets (ACKs, window updates) now bypass connection-level receive ordering, preventing sequence gaps when reordered ACKs advance
_nextExpectedSeqpast data packets - Fixes handshake failures over networks with packet reordering (mobile, satellite, congested links)
2.0.1 - 2026-02-17 #
Fixed #
- Stream-level flow control: send window updates when 25% of receive window consumed, preventing yamux mux stalls on long-lived streams
- Connection window exhaustion due to uninitialized CUBIC epoch
- Always use bidirectional stream type for incoming connections
Changed #
- Per-connection packet sequencing for QUIC RFC 9000 compliance
2.0.0 - 2026-01-03 #
Breaking Changes #
- Variable-Length Connection IDs: Connection IDs can now be 0-20 bytes (previously fixed at 8 bytes)
- Updated Packet Format: New packet header format includes version field and variable-length CID encoding
- Protocol Version: Bumped to v2 (0x00000002) to reflect breaking changes
Added - Phase 1: Packet Format Foundation #
-
Variable-Length Connection IDs: Support for 0-20 byte CIDs per QUIC spec
ConnectionId.minCidLengthandConnectionId.maxCidLengthconstantsConnectionId.random(length)factory with configurable length- Updated
UDXPacketserialization to handle variable-length CIDs
-
Version Negotiation: Full version negotiation support
UdxVersionclass with v1/v2 supportVersionNegotiationPacketfor incompatible version handling- Automatic VERSION_NEGOTIATION response for unsupported versions
-
CONNECTION_CLOSE Frame: Graceful connection termination
ConnectionCloseFramewith error code, frame type, and reason phraseUdxErrorCodeconstants for standard error codesUDPSocket.closeWithError()method for sending CONNECTION_CLOSE- Automatic handling of incoming CONNECTION_CLOSE frames
-
STATELESS_RESET Mechanism: Connection state recovery
StatelessResetTokenclass with HMAC-SHA256 generationStatelessResetPacketfor stateless connection terminationUDXMultiplexer.sendStatelessReset()method- Automatic detection and handling of stateless reset packets
Added - Phase 2: Stream Management #
-
Unidirectional Streams: Half-duplex stream support
StreamTypeenum: bidirectional, unidirectionalLocal, unidirectionalRemoteStreamIdHelperfor QUIC-style stream ID encoding- Automatic stream type detection from stream ID
- Write operation validation based on stream directionality
-
STOP_SENDING Frame: Receiver-initiated stream termination
StopSendingFramefor signaling unwanted dataUDXStream.stopReceiving()method- Automatic handling of incoming STOP_SENDING frames
-
BLOCKED Frames: Flow control signaling
DataBlockedFramefor connection-level blockingStreamDataBlockedFramefor stream-level blocking- Automatic BLOCKED frame transmission when flow control limits are hit
- Events for applications to respond to blocking
-
Stream Priorities: Priority-based stream scheduling
UDXStream.priorityproperty (0-255, lower = higher priority)UDXStream.setPriority()method- Infrastructure for future priority-based packet scheduling
Added - Phase 3: Security Enhancements #
-
Anti-Amplification Limits: DDoS protection per RFC 9000
- 3x amplification factor enforcement
- Packet queueing when amplification limit is reached
- Address validation after receiving sufficient data
UDPSocket._onAddressValidated()for flushing queued packets
-
CID Rotation Frames: Connection ID management
NewConnectionIdFramefor providing new CIDsRetireConnectionIdFramefor CID retirement- Infrastructure for future active CID rotation
Added - Phase 4: Performance Enhancements #
-
ECN Support: Explicit Congestion Notification infrastructure
- Optional ECN count fields in
AckFrame(ect0Count, ect1Count, ceCount) CongestionController.processEcnFeedback()placeholder- Ready for future OS-level ECN integration
- Optional ECN count fields in
-
RTT Estimation Improvements: RFC 9002 compliance
maxAckDelayconstant (25ms per RFC 9002)- ACK delay capping in
_updateRtt()method - More accurate RTT measurements
Added - Phase 5: Code Quality #
-
Configurable Logging: Structured logging system
UdxLoggingclass with debug, info, warn, error levelsUdxLoggertypedef for custom logger functions- Verbose and info flags for log level control
- Replacement of direct print statements
-
Constants Extraction: Centralized configuration
constants.dartwith all transport parameters- Error codes, timeouts, and limits
- Improved code maintainability
Changed #
UDXPacketnow includesversionfield (default:UDXPacket.currentVersion)UDXStreamconstructor now accepts optionalstreamTypeparameterUDPSocket.handleIncomingDatagram()is now async to support CONNECTION_CLOSE handling- Sequence number handling for non-reliable frames (ACKs, STOP_SENDING, etc.) reuses last sent sequence
Fixed #
- Sequence number desynchronization bug (documented in SEQUENCE_NUMBER_DESYNC_FIX.md)
- Linter warnings for unused variables and redundant null checks
Migration Guide #
For v1 → v2 Migration:
-
Packet Format: No action required if using default 8-byte CIDs. Variable-length CIDs are opt-in.
-
Version Negotiation: Clients will automatically handle VERSION_NEGOTIATION. Listen for
versionNegotiationevents if needed:socket.on('versionNegotiation', (event) { print('Server doesn\'t support our version: ${event['clientVersion']}'); }); -
Graceful Shutdown: Replace
socket.close()withsocket.closeWithError()for explicit error codes:await socket.closeWithError(UdxErrorCode.noError, 'Normal close'); -
Unidirectional Streams: Specify stream type when creating:
final stream = await UDXStream.createOutgoing( udx, socket, localId, remoteId, host, port, streamType: StreamType.unidirectionalLocal, ); -
Logging: Enable logging for debugging:
UdxLogging.setDefaultLogger(); UdxLogging.verbose = true;
Notes #
- Full CID rotation implementation requires additional state management (future enhancement)
- ECN processing awaits OS-level integration (infrastructure in place)
- Stream priority scheduling is partially implemented (priorities settable, scheduling to be enhanced)
0.3.1 Previous Version #
Previous changes not documented in this changelog.