Skip to content
Merged
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
11 changes: 9 additions & 2 deletions doc/concept/socket.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,15 @@ subscriptions, not a wire extension. It uses no instances and no track
listings, and relays carry it unchanged. It needs moq-lite-07 or
moq-transport on every hop: an endpoint's broadcast is
[hidden](/concept/moq-lite#hidden-broadcasts), and an older moq-lite hop
never carries hidden broadcasts, so a dial across one never finds its peer. This page is the convention, enough to implement it in any
language.
never carries hidden broadcasts, so a dial across one would never find its
peer. Clustered relays carry hidden broadcasts to each other on every version,
so the hop that decides is each endpoint's own session: while an endpoint's
client session is moq-lite before 07, its dials and accepts fail with
`Unsupported` instead of waiting, unless that session's publish half opts into
hidden broadcasts. A dialer can't tell a peer behind such a hop from one not
online yet, so its dial waits as for any absent peer, while the peer's own
accepts fail. This page is the convention, enough to
implement it in any language.
[`moq_net::socket`](https://docs.rs/moq-net/latest/moq_net/socket/) implements
it in Rust.

Expand Down
2 changes: 1 addition & 1 deletion doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ What you use it for, beyond what the concept page already describes:
- **Rank several CDNs.** Dial each with its own subscribe handle, `origin.clone().with_preference(origin::Preference::new(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. Requests use the preferred link that has a route and fail over to the next; see [multiple CDNs](/concept/moq-lite#multiple-cdns).
- **Request one instance, or follow them all.** `consumer.request(path, None)` resolves the instance serving a path now, and fails `Unroutable` only once discovery has synced with no route for it. `consumer.follow(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over or returns after an end, like JS `follow(path)`. A broadcast already resolved stays on the old instance until dropped or its route goes. See [identity and recovery](/concept/identity) to choose between following and holding one instance.
- **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `request`, or `follow`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request` owns discovery of its path, so no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-rtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything.
- **Dial and accept sockets.** `socket::Endpoint::new(&origin, prefix, id)` announces a hidden endpoint at `<prefix>/.socket/<id>`, used only to route dials. A session speaks one of two protocols, each with its own dial and accept. `accept_tcp()` and `accept_track()` yield an `Incoming` dial to `accept` or `reject` (dropping it rejects). `dial_tcp(peer)` and an accepted `tcp` dial yield a `socket::TcpStream`, a `group::Producer` and `group::Consumer` pair carrying one reliable, ordered byte pipe each way (finish is FIN, abort is RST, and `ready` paces the writer to the reader); `dial_track(peer, info)` and an accepted `track` dial yield a `socket::TrackStream`, this side's `track::Producer` and a `track::Subscriber` of the peer's half, subscribed reliably and in order until the application updates it, one message per group. A dial resolves once the peer accepts, and an accept checks that the claimed dialer really dialed this endpoint, waiting for its endpoint while the dial stays open. Session tracks are never announced or listed. See [Sockets](/concept/socket).
- **Dial and accept sockets.** `socket::Endpoint::new(&origin, prefix, id)` announces a hidden endpoint at `<prefix>/.socket/<id>`, used only to route dials. A session speaks one of two protocols, each with its own dial and accept. `accept_tcp()` and `accept_track()` yield an `Incoming` dial to `accept` or `reject` (dropping it rejects). `dial_tcp(peer)` and an accepted `tcp` dial yield a `socket::TcpStream`, a `group::Producer` and `group::Consumer` pair carrying one reliable, ordered byte pipe each way (finish is FIN, abort is RST, and `ready` paces the writer to the reader); `dial_track(peer, info)` and an accepted `track` dial yield a `socket::TrackStream`, this side's `track::Producer` and a `track::Subscriber` of the peer's half, subscribed reliably and in order until the application updates it, one message per group. A dial resolves once the peer accepts, and an accept checks that the claimed dialer really dialed this endpoint, waiting for its endpoint while the dial stays open. Every hop needs moq-lite-07 or moq-transport: while the origin has an older moq-lite client session whose publish half doesn't opt into hidden broadcasts (`with_hidden(true)`), dials and accepts fail with `Unsupported`. A dial to a peer behind such a hop waits, as for a peer not online yet. Session tracks are never announced or listed. See [Sockets](/concept/socket).
- **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a producer that replaces it starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups with `create_group` at an explicit sequence. Readers of an aborted track resume onto the replacement when they read through an origin request, whose route always names an instance; otherwise their subscription ends with the error.
- **Authored tracks default to a zero `max_age`.** `track::Info::default()` sets `max_age` to `Some(Duration::ZERO)`, the live edge only; a publisher that wants readers to reach history sets a longer bound, or `with_max_age(None)` for no publisher limit. Media tracks from `hang::container::track_info` declare `hang::container::MAX_AGE` (30 seconds). `max_age` is how long a superseded group stays fresh, never the newest group; it frees no bytes, which the cache pool's expiry reclaims. Received metadata keeps absence as no limit, and an origin's `cache_duration` can only cap it lower.
- **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track; the broadcast stays announced and keeps serving them until you close it or drop its last producer. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window.
Expand Down
7 changes: 4 additions & 3 deletions quest/m1/socket/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,8 +147,10 @@ standing where the 2026-11-04 decisions above don't replace it:
[moq-dev/moq#7677](https://github.com/moq-dev/moq/pull/7677): it needs
moq-lite-07 or moq-transport on every hop, since a moq-lite hop before 07
has no hidden opt-in and never carries an endpoint's `.socket/<id>`
broadcast; [older hops](/quest/m1/socket/old-hop-dial.md) make such a dial
fail instead of waiting.
broadcast. Relays' cluster links carry hidden broadcasts on every version,
so an endpoint's own client session is the hop that decides: while one is
moq-lite before 07, its dials and accepts fail `Unsupported` instead of
waiting ([moq-dev/moq#7888](https://github.com/moq-dev/moq/pull/7888)).
- Fixed channels become sessions or messages on one: boy's `command` and
per-viewer latency, CARLA's `control`, ack, and e-stop. Shared state such as
boy's `status` stays an ordinary broadcast.
Expand Down Expand Up @@ -187,7 +189,6 @@ announce-watch-request pairing remains in `rs/moq-boy`, `js/moq-boy`, or
## Required

- [JS sockets](/quest/m1/socket/js.md) - the same surface in `@moq/net`, interoperating with Rust
- [A socket dial over an older hop fails instead of waiting](/quest/m1/socket/old-hop-dial.md) - a dial through a pre-lite-07 hop fails `Unsupported`
- [Python sockets](/quest/m1/socket/py.md) - moq-ffi and `py/moq-rs` bindings, interoperating with Rust
- [moq-boy on sockets](/quest/m1/socket/boy.md) - viewers dial the emulator's endpoint and send commands and receive latency on their session
- [CARLA on sockets](/quest/m1/socket/carla.md) - drivers dial the truck's endpoint and send control and receive acks on their session
Expand Down
7 changes: 5 additions & 2 deletions quest/m1/socket/js.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,5 +23,8 @@ request so no listing names them; an unknown or unaccepted protocol is reset
as unsupported. JS reads without fastest-reader pacing until
[JS fastest-reader pacing](/quest/m2/js-fastest-reader.md), so a JS `tcp`
reader that falls a group tail behind fails with an eviction error; say so in
the docs. Add the Rust/JS pairs to `just test interop`, and document the
export in `doc/lib/js/net.md`.
the docs. As in Rust, dials and accepts fail as unsupported while the
endpoint's connection is moq-lite before 07, which never carries its hidden
broadcast, instead of waiting forever; test it against a lite-06 connection.
Add the Rust/JS pairs to `just test interop`, and document the export in
`doc/lib/js/net.md`.
43 changes: 0 additions & 43 deletions quest/m1/socket/old-hop-dial.md

This file was deleted.

2 changes: 1 addition & 1 deletion rs/moq-net/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- `socket`: `Endpoint`, which announces a hidden `<prefix>/.socket/<id>` broadcast, dials other endpoints, and accepts their dials in two protocols: `tcp` sessions (`dial_tcp`, `accept_tcp`, `TcpStream`), one group each way as a reliable, ordered byte pipe, and `track` sessions (`dial_track`, `accept_track`, `TrackStream`), a track each way with one message per group; see `doc/concept/socket.md`.
- `socket`: `Endpoint`, which announces a hidden `<prefix>/.socket/<id>` broadcast, dials other endpoints, and accepts their dials in two protocols: `tcp` sessions (`dial_tcp`, `accept_tcp`, `TcpStream`), one group each way as a reliable, ordered byte pipe, and `track` sessions (`dial_track`, `accept_track`, `TrackStream`), a track each way with one message per group. Dials and accepts fail `Unsupported` while the origin has a moq-lite client session before 07 whose publish half doesn't opt into hidden broadcasts, since its peer never hears the endpoint; see `doc/concept/socket.md`.
- `transport::SETUP_RECEIVE_WINDOW`, the connection credit a server offers before it admits a session: enough for the SETUP and one in-band AUTH.

## [0.3.10](https://github.com/moq-dev/moq/compare/moq-net-v0.3.9...moq-net-v0.3.10) - 2026-10-05
Expand Down
10 changes: 10 additions & 0 deletions rs/moq-net/src/lite/session.rs
Original file line number Diff line number Diff line change
Expand Up @@ -275,6 +275,11 @@ pub fn start(config: Config) -> Result<SessionStart, Error> {
.with_stats(stats.clone())
});
let subscribe = subscribe.unwrap_or_else(|| origin::Producer::empty(Hop::random()).with_stats(stats.clone()));
// Before lite-07 the peer can't ask for hidden routes, so a client publishes none of
// them unless its publish half opted in, and a socket endpoint behind it is
// unreachable. A server leaves it to the client, whose origin holds that endpoint.
let withholding =
(client && !version.has_hidden() && !publish.includes_hidden()).then(|| publish.hidden_withheld().hold());
let subscriptions = crate::session::Slots::default().with_stats(publish.stats(), crate::stats::Cap::Subscriptions);
let announces =
crate::session::Slots::new(limits.announces).with_stats(subscribe.stats(), crate::stats::Cap::Announces);
Expand Down Expand Up @@ -389,6 +394,7 @@ pub fn start(config: Config) -> Result<SessionStart, Error> {
publisher,
subscriber: SubscriberDriver::new(subscriber, early, client),
session,
withholding,
};

Ok(SessionStart {
Expand Down Expand Up @@ -423,6 +429,9 @@ pub(crate) struct Driver {
/// For the terminal close: the machine's last act reports the outcome to
/// the peer through the transport.
session: Transport,
/// Counts this session against the publish origin while it withholds that origin's
/// hidden routes from the peer.
withholding: Option<origin::HiddenWithholding>,
}

impl Driver {
Expand Down Expand Up @@ -452,6 +461,7 @@ impl Driver {
}
}
self.ending = Some(res);
self.withholding = None;
}
// Closing the transport first bounds every read, including when a control
// stream ended the protocol while the connection itself was still live.
Expand Down
3 changes: 3 additions & 0 deletions rs/moq-net/src/model/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,9 @@ pub use timed::Timed;
/// Publishing broadcasts, announcing routes, and consuming both through an origin.
pub mod origin {
pub use super::follow::Following;
pub(crate) use super::origin_impl::HiddenWithheld;
#[cfg(feature = "async")]
pub(crate) use super::origin_impl::HiddenWithholding;
#[cfg(feature = "async")]
// private: capability gap
pub(crate) use super::origin_impl::Lookup;
Expand Down
43 changes: 43 additions & 0 deletions rs/moq-net/src/model/origin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1984,6 +1984,40 @@ fn hides(heads: &[Path], prefix: &Path) -> bool {
.any(|head| prefix.strip_prefix(head).is_some_and(|below| below.is_hidden()))
}

/// How many sessions withhold an origin's hidden routes from their peer, such as a
/// moq-lite client before 07, whose peer can't ask for them.
#[derive(Clone, Debug, Default)]
pub(crate) struct HiddenWithheld(kio::Shared<usize>);

impl HiddenWithheld {
/// Count a session that withholds them, until the returned guard drops.
#[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))]
pub fn hold(&self) -> HiddenWithholding {
*self.0.lock() += 1;
HiddenWithholding(self.clone())
}

/// Ready while a session withholds them.
pub fn poll(&self, waiter: &kio::Waiter) -> Poll<()> {
self.0
.poll(waiter, |count| match **count {
0 => Poll::Pending,
_ => Poll::Ready(()),
})
.map(drop)
}
}

/// A session counted by [`HiddenWithheld::hold`], until dropped.
#[derive(Debug)]
pub(crate) struct HiddenWithholding(HiddenWithheld);

impl Drop for HiddenWithholding {
fn drop(&mut self) {
*self.0.0.lock() -= 1;
}
}

/// What an [`AnnounceConsumer`] yields.
#[derive(Clone, Debug)]
pub enum AnnounceEvent {
Expand Down Expand Up @@ -5163,6 +5197,9 @@ struct OriginState {
// discovered; see [`Interests`].
listeners: Vec<Listener>,
next_listener: u64,

// The sessions withholding this origin's hidden routes from their peer.
hidden_withheld: HiddenWithheld,
}

impl OriginState {
Expand All @@ -5179,6 +5216,7 @@ impl OriginState {
closed: false,
listeners: Vec::new(),
next_listener: 0,
hidden_withheld: HiddenWithheld::default(),
}
}

Expand Down Expand Up @@ -6590,6 +6628,11 @@ impl Consumer {
self.hidden.include
}

/// The sessions withholding this origin's hidden routes from their peer.
pub(crate) fn hidden_withheld(&self) -> HiddenWithheld {
self.shared.read().hidden_withheld.clone()
}

/// The egress stats context this handle was tagged with.
#[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))]
pub(crate) fn stats(&self) -> &stats::Session {
Expand Down
Loading
Loading