Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion js/net/src/connection/stats.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ import { Milli } from "@moq/clock";
* Every field is optional. The qmux/WebSocket fallback implements no `getStats()` at
* all and reports nothing; see {@link Probe} for what the peer measures.
*
* The field names match Rust's `moq_net::session::Stats` but the counters keep each
* The field names match Rust's `moq_net::session::Stats`, except its native-only
* `streams`, which W3C stats cannot report. The counters keep each
* stack's own semantics rather than being normalized. Notably W3C excludes
* retransmissions and QUIC overhead from the byte counts where native QUIC includes
* them, and counts packets where native QUIC counts datagrams.
Expand Down
15 changes: 15 additions & 0 deletions rs/moq-net/src/client.rs
Original file line number Diff line number Diff line change
Expand Up @@ -556,6 +556,7 @@ mod tests {
control_writes: Arc<Mutex<Vec<u8>>>,
send_rate: Mutex<Option<u64>>,
bytes_sent: Mutex<Option<u64>>,
streams: Mutex<Option<crate::transport::Streams>>,
}

fn any_close(events: &kio::Ref<'_, Vec<(u32, String)>>) -> Poll<()> {
Expand All @@ -579,6 +580,7 @@ mod tests {
control_writes: writes,
send_rate: Mutex::new(None),
bytes_sent: Mutex::new(None),
streams: Mutex::new(None),
};
Self {
state: Arc::new(state),
Expand Down Expand Up @@ -676,16 +678,22 @@ mod tests {
FakeStats {
send_rate: *self.state.send_rate.lock().unwrap(),
bytes_sent: *self.state.bytes_sent.lock().unwrap(),
streams: *self.state.streams.lock().unwrap(),
}
}
}

struct FakeStats {
streams: Option<crate::transport::Streams>,
send_rate: Option<u64>,
bytes_sent: Option<u64>,
}

impl crate::transport::Stats for FakeStats {
fn streams(&self) -> Option<crate::transport::Streams> {
self.streams
}

fn estimated_send_rate(&self) -> Option<u64> {
self.send_rate
}
Expand Down Expand Up @@ -1224,6 +1232,10 @@ mod tests {
let fake = FakeSession::new(Some(ALPN_LITE_04), Vec::new());
fake.set_send_rate(None);
fake.set_bytes_sent(Some(0));
*fake.state.streams.lock().unwrap() = Some(crate::transport::Streams {
bidi: crate::transport::StreamState { open: 3, available: 5 },
uni: crate::transport::StreamState { open: 7, available: 11 },
});

let client = Client::new().with_versions(Version::Lite(lite::Version::Lite04).into());
let (session, driver) = client.connect(moq_clock::now(), fake.clone()).await.unwrap();
Expand All @@ -1234,6 +1246,8 @@ mod tests {
);

fake.set_bytes_sent(Some(4242));
assert_eq!(session.stats().streams.unwrap().bidi.open, 3);
*fake.state.streams.lock().unwrap() = Some(crate::transport::Streams::default());

session.abort(Error::Cancel);
session.closed().await;
Expand All @@ -1243,6 +1257,7 @@ mod tests {
Some(4242),
"the closing snapshot must carry the session's final counters"
);
assert_eq!(session.stats().streams, Some(crate::transport::Streams::default()));
}

// The send-bandwidth sampler lives inside the driver: it samples as soon as a
Expand Down
4 changes: 4 additions & 0 deletions rs/moq-net/src/session.rs
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,9 @@ struct StatsState {
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct Stats {
/// Locally initiated stream occupancy and remaining peer stream-ID credit.
pub streams: Option<crate::transport::Streams>,

Comment on lines +47 to +49

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Synchronize the new stats API across packages

This adds public moq-net stream statistics only on the Rust side, while a repo-wide search shows js/net/src/connection/stats.ts and doc/concept remain unchanged even though the JavaScript Stats interface says its fields match Rust's session::Stats. Update the JS surface and concept documentation, or explicitly document the native-only unsupported field so the cross-language APIs do not silently diverge.

AGENTS.md reference: AGENTS.md:L107-L110

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Partly fixed in 3e0353e: the JS Stats doc no longer claims a full match and names streams as Rust's native-only field, since W3C getStats() has no stream counts to report. Declining the rest: an always-absent JS field or a concept-doc section would publish surface no browser consumer needs, and doc/concept and the binding docs describe only what the stats tracks and moq-ffi carry, which this PR leaves unchanged.

(Written by Claude Opus 5.5)

/// Smoothed round-trip time estimate.
pub rtt: Option<Duration>,

Expand Down Expand Up @@ -641,6 +644,7 @@ impl<S: crate::transport::poll::Session> Supervisor<S> {
fn snapshot<S: crate::transport::poll::Session>(session: &S) -> Stats {
let stats = session.stats();
Stats {
streams: stats.streams(),
rtt: stats.rtt(),
estimated_send_rate: stats.estimated_send_rate().map(bandwidth::Rate::from_bps),
bytes_sent: stats.bytes_sent(),
Expand Down
29 changes: 29 additions & 0 deletions rs/moq-net/src/transport.rs
Original file line number Diff line number Diff line change
Expand Up @@ -88,11 +88,40 @@ impl Wire {
}
}

/// A snapshot of locally initiated transport streams.
///
/// Counts describe backend protocol state, not application stream handles.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Streams {
/// Bidirectional streams initiated by this endpoint.
pub bidi: StreamState,
/// Unidirectional streams initiated by this endpoint.
pub uni: StreamState,
}

/// Stream occupancy and remaining opening credit for one direction.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct StreamState {
/// Streams not yet fully closed by the transport. A bidirectional stream
/// remains open until both halves are closed, including transport retirement.
pub open: u64,
/// Additional stream IDs permitted by the peer's current cumulative limit.
///
/// Closing a stream does not directly restore this credit: it increases only
/// when the peer grants more. This is not a fixed concurrent capacity.
pub available: u64,
}

/// Connection-level statistics.
///
/// Methods return `Option`: `None` means the implementation doesn't track
/// this metric, while `Some(0)` means actually zero.
pub trait Stats {
/// Locally initiated stream occupancy and remaining peer stream-ID credit.
fn streams(&self) -> Option<Streams> {
None
}

/// Total bytes sent over the connection, including retransmissions and overhead.
fn bytes_sent(&self) -> Option<u64> {
None
Expand Down
1 change: 1 addition & 0 deletions rs/moq-quic/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ Changes on top of the upstream commit, besides the renames:
- **Late stream limits**: peer transport parameters that raise a stream limit after an open was refused emit `StreamEvent::Available`, as `MAX_STREAMS` does. A server accepted before the rest of a multi-packet ClientHello (a post-quantum key share is enough) otherwise leaves a 0.5-RTT `open_uni` parked until the idle timeout. Not offered upstream yet.
- **Stream credit on stop**: `RecvStream::stop` on a stream whose final size is already known (finished or reset) frees it and queues `MAX_STREAMS` at once, as reading the reset does, instead of leaving the credit until the next packet arrives. Not offered upstream yet; quinn `main` has the same gap.
- **Connection limits** (`Limits`, `Connection::set_limits`, and the drivers' `set_limits`): one validated call changes a live connection's stream limit and windows, refusing values a peer would reject and changing nothing then. moq-tokio and moq-uring re-export the type, so both runtimes check limits the same way. Not offered upstream: it only bundles quinn's existing setters.
- **Stream occupancy** (`ConnectionStats::streams`, `StreamStats`): per direction, `open` counts locally initiated streams until `StreamsState::stream_freed` fully retires them (both halves of a bidi stream; a FIN or reset only once acknowledged), and `available` is the peer's cumulative `MAX_STREAMS` minus the next stream ID. A rejected 0-RTT resets both, and a closed connection reports zeros. A cherry-pick touching `insert_local`, `stream_freed`, or `zero_rtt_rejected` has to keep the count. Not offered upstream: quinn exposes no stream counts.

Recheck the BBR3 changes when cherry-picking quinn#2481 updates, or if it merges.

Expand Down
9 changes: 8 additions & 1 deletion rs/moq-quic/src/connection/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,9 @@ impl ConnectionTag {
Self(NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed))
}
}
pub use stats::{ConnectionStats, CreditStats, FrameStats, PathStats, UdpStats};
pub use stats::{
ConnectionStats, CreditStats, FrameStats, PathStats, StreamState, StreamStats, UdpStats,
};

mod streams;
pub(crate) use streams::StreamsState;
Expand Down Expand Up @@ -1424,6 +1426,11 @@ impl Connection {
stats.path.bandwidth_estimate = self.path.congestion.metrics().bandwidth_estimate;
stats.path.current_mtu = self.path.mtud.current_mtu();
stats.credit = self.streams.credit_stats();
stats.streams = if self.state.is_closed() {
StreamStats::default()
} else {
self.streams.stream_stats()
};

stats
}
Expand Down
23 changes: 23 additions & 0 deletions rs/moq-quic/src/connection/stats.rs
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,8 @@ pub struct ConnectionStats {
pub path: PathStats,
/// Connection-level receive flow control
pub credit: CreditStats,
/// Locally initiated stream occupancy and remaining peer stream-ID credit.
pub streams: StreamStats,
}

/// Connection-level receive flow control, from the receiver's side
Expand All @@ -193,3 +195,24 @@ pub struct CreditStats {
/// advertised
pub available: u64,
}

/// Locally initiated transport stream statistics.
#[derive(Debug, Default, Copy, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct StreamStats {
/// Locally initiated bidirectional streams.
pub bidi: StreamState,
/// Locally initiated unidirectional streams.
pub uni: StreamState,
}

/// One direction's stream occupancy and remaining opening credit.
#[derive(Debug, Default, Copy, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct StreamState {
/// Streams not fully retired, including both halves of bidirectional streams.
pub open: u64,
/// Additional stream IDs allowed by the peer's cumulative MAX_STREAMS limit.
/// Closing a stream does not restore this credit until the peer grants more.
pub available: u64,
}
134 changes: 126 additions & 8 deletions rs/moq-quic/src/connection/streams/state.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ use crate::{
Dir, MAX_STREAM_COUNT, Side, StreamId, TransportError, VarInt,
coding::BufMutExt,
connection::ConnectionTag,
connection::stats::{CreditStats, FrameStats},
connection::stats::{CreditStats, FrameStats, StreamState, StreamStats},
frame::{self, FrameStruct, StreamMetaVec},
transport_parameters::TransportParameters,
};
Expand Down Expand Up @@ -83,6 +83,7 @@ pub(crate) struct StreamsState {
pub(super) recv: FxHashMap<StreamId, Option<StreamRecv>>,
pub(super) free_recv: Vec<StreamRecv>,
pub(super) next: [u64; 2],
local_open: [u64; 2],

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Add this fork change to the carried-change inventory

This adds custom stream-accounting behavior directly to the hard-forked moq-quic, but rs/moq-quic/README.md has no corresponding entry under “Carried changes.” CONTRIBUTING.md:78-79 requires every carried fork change to be recorded with its upstream PR or the reason it has none; without that entry, future Quinn cherry-pick audits can overlook this custom state-management behavior. Add the inventory entry in this change.

AGENTS.md reference: AGENTS.md:L8-L8

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 286c8fb: rs/moq-quic/README.md now lists the stream count under "Carried changes" (not offered upstream, since quinn exposes no stream counts), naming insert_local, stream_freed, and zero_rtt_rejected as the spots a cherry-pick must keep.

(Written by Claude Opus 5.5)

/// Maximum number of locally-initiated streams that may be opened over the lifetime of the
/// connection so far, per direction
pub(super) max: [u64; 2],
Expand Down Expand Up @@ -179,6 +180,7 @@ impl StreamsState {
recv: FxHashMap::default(),
free_recv: Vec::new(),
next: [0, 0],
local_open: [0, 0],
max: [0, 0],
max_remote: [max_remote_bi.into(), max_remote_uni.into()],
sent_max_remote: [max_remote_bi.into(), max_remote_uni.into()],
Expand Down Expand Up @@ -277,6 +279,7 @@ impl StreamsState {
}
}
self.next[dir as usize] = 0;
self.local_open[dir as usize] = 0;

// If 0-RTT was rejected, any flow control frames we sent were lost.
if self.flow_control_adjusted {
Expand Down Expand Up @@ -1035,6 +1038,7 @@ impl StreamsState {
pub(super) fn insert_local(&mut self, id: StreamId) {
debug_assert_eq!(id.initiator(), self.side);
assert!(self.send.insert(id, None).is_none());
self.local_open[id.dir() as usize] += 1;
if id.dir() == Dir::Bi {
let recv = self.free_recv.pop();
assert!(self.recv.insert(id, recv).is_none());
Expand Down Expand Up @@ -1127,15 +1131,28 @@ impl StreamsState {
}
}

pub(crate) fn stream_stats(&self) -> StreamStats {
let state = |dir: Dir| StreamState {
open: self.local_open[dir as usize],
available: self.max[dir as usize].saturating_sub(self.next[dir as usize]),
};
StreamStats {
bidi: state(Dir::Bi),
uni: state(Dir::Uni),
}
}

/// Update counters for removal of a stream
pub(super) fn stream_freed(&mut self, id: StreamId, half: StreamHalf) {
if id.initiator() != self.side {
let fully_free = id.dir() == Dir::Uni
|| match half {
StreamHalf::Send => !self.recv.contains_key(&id),
StreamHalf::Recv => !self.send.contains_key(&id),
};
if fully_free {
let fully_free = id.dir() == Dir::Uni
|| match half {
StreamHalf::Send => !self.recv.contains_key(&id),
StreamHalf::Recv => !self.send.contains_key(&id),
};
if fully_free {
if id.initiator() == self.side {
self.local_open[id.dir() as usize] -= 1;
} else {
self.allocated_remote_count[id.dir() as usize] -= 1;
self.ensure_remote_streams(id.dir());
}
Expand Down Expand Up @@ -1182,6 +1199,107 @@ mod tests {
};
use bytes::Bytes;

#[test]
fn stream_statistics_wait_for_both_halves_and_do_not_recycle_id_credit() {
for side in [Side::Client, Side::Server] {
let mut state = make(side);
state.set_params(&TransportParameters {
initial_max_streams_uni: 1u32.into(),
initial_max_streams_bidi: 1u32.into(),
..TransportParameters::default()
});
let conn_state = ConnState::Established;
let mut pending = Retransmits::default();
for dir in Dir::iter() {
let id = Streams {
state: &mut state,
conn_state: &conn_state,
}
.open(dir, Default::default())
.unwrap();
assert_eq!(state.local_open[dir as usize], 1);
let snapshot = state.stream_stats();
assert_eq!(
match dir {
Dir::Bi => snapshot.bidi,
Dir::Uni => snapshot.uni,
}
.available,
0
);
SendStream {
id,
state: &mut state,
pending: &mut pending,
conn_state: &conn_state,
}
.finish()
.unwrap();
// FIN is not closure until the peer acknowledges it.
assert_eq!(state.local_open[dir as usize], 1);
state.received_ack_of(frame::StreamMeta {
id,
offsets: 0..0,
fin: true,
});
if dir == Dir::Bi {
assert_eq!(state.stream_stats().bidi.open, 1);
let _ = state
.received(
frame::Stream {
id,
offset: 0,
fin: true,
data: Bytes::new(),
},
0,
)
.unwrap();
let mut recv = RecvStream {
id,
state: &mut state,
pending: &mut pending,
};
let mut chunks = recv.read(true).unwrap();
assert!(chunks.next(1).unwrap().is_none());
let _ = chunks.finalize();
}
assert_eq!(state.local_open[dir as usize], 0);
assert_eq!(state.max[dir as usize] - state.next[dir as usize], 0);
}
}
}

#[test]
fn rejected_early_streams_reset_occupancy_and_id_credit() {
let mut state = make(Side::Client);
state.max = [1, 1];
let conn_state = ConnState::Established;
for dir in Dir::iter() {
Streams {
state: &mut state,
conn_state: &conn_state,
}
.open(dir, Default::default())
.unwrap();
}
state.zero_rtt_rejected();
assert_eq!(
state.stream_stats().bidi,
StreamState {
open: 0,
available: 1
}
);
assert_eq!(
state.stream_stats().uni,
StreamState {
open: 0,
available: 1
}
);
}

fn make(side: Side) -> StreamsState {
StreamsState::new(
side,
Expand Down
2 changes: 1 addition & 1 deletion rs/moq-quic/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ pub use crate::connection::{
Chunk, Chunks, ClosedStream, Connection, ConnectionError, ConnectionStats, Credit, CreditStats,
Datagrams, Event, FinishError, FrameStats, PathStats, ReadError, ReadableError, RecvStream,
RttEstimator, SendDatagramError, SendGroup, SendGroups, SendOptions, SendStream,
ShouldTransmit, StreamEvent, Streams, UdpStats, WriteError, Written,
ShouldTransmit, StreamEvent, StreamState, StreamStats, Streams, UdpStats, WriteError, Written,
};
#[cfg(feature = "qlog")]
pub use connection::qlog::QlogStream;
Expand Down
Loading
Loading