Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
9b26727
chore(quest): claim quest/m1/socket/js.md
kixelated Nov 4, 2026
626dfc3
feat(net): add JavaScript socket endpoints
kixelated Nov 4, 2026
5dd754c
test(net): link wider fill quarantine to its investigation
kixelated Nov 4, 2026
a3d4dc3
test(net): identify socket interop failure phases
kixelated Nov 4, 2026
0971df4
test(net): cover routed socket refusals
kixelated Nov 4, 2026
0c4415b
style(net): format socket interop cleanup
kixelated Nov 4, 2026
b2d3ec9
Merge origin/main into quest/m1/socket/js
kixelated Nov 4, 2026
2850771
docs(quest): record socket adapter decision and relay evidence
kixelated Nov 4, 2026
83f39ab
fix(net): bind socket lifetime to the original peer
kixelated Nov 4, 2026
ec4fa34
test(net): annotate the incoming protocol union
kixelated Nov 4, 2026
d284534
test(net): verify late socket requests before publishing
kixelated Nov 4, 2026
e749d22
fix(net): leave socket acceptance bounded by its lifetime
kixelated Nov 4, 2026
419d63c
docs(quest): leave request budget scope for maintainer decision
kixelated Nov 4, 2026
5e19a57
Merge remote-tracking branch 'origin/main' into js-socket-iterate
kixelated Nov 4, 2026
dec9635
fix(net)!: bound JS track requests by their lifetime, not a fixed budget
kixelated Nov 4, 2026
e5f8e8d
docs(net): record the info signal in the API report
kixelated Nov 4, 2026
994d14f
Merge remote-tracking branch 'origin/main' into js-socket-iterate
kixelated Nov 4, 2026
b4ace92
Merge main and preserve lifecycle-bound socket requests with queued c…
kixelated Nov 5, 2026
d495371
Merge remote-tracking branch 'origin/main' into takeover/js-sockets
kixelated Nov 5, 2026
99b7f08
fix(net): format lifecycle checks and narrow the optional answer budget
kixelated Nov 5, 2026
2147d14
test(net): preserve the unfinished-tail case through the merge
kixelated Nov 5, 2026
a58fc99
test(net): quarantine the known reload drain race
kixelated Nov 5, 2026
216d399
refactor(net): reuse request lifetime and session encoding helpers
kixelated Nov 5, 2026
df8eea7
Merge origin/main and align JavaScript sockets with settled session s…
kixelated Nov 6, 2026
698e89c
test(socket): quarantine the draft-18 burst scheduling race
kixelated Nov 6, 2026
ddd1721
style(socket): apply repository shell formatting
kixelated Nov 6, 2026
68bd23a
fix(socket): fail TCP sessions missing their only group
kixelated Nov 6, 2026
c732c1b
Merge remote-tracking branch 'origin/main' into iterate/js-socket-end…
kixelated Nov 6, 2026
5dea81f
test(socket): restrict early bursts to lite
kixelated Nov 6, 2026
2471c51
Merge remote-tracking branch 'origin/main' into iterate/js-socket-end…
kixelated Nov 6, 2026
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
45 changes: 45 additions & 0 deletions doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,3 +89,48 @@ frame.finish();
const reader = await consumer.nextFrame();
for (let chunk = await reader?.readChunk(); chunk; chunk = await reader?.readChunk()) save(chunk);
```

## Sockets

Use `Moq.socket.Endpoint` for [point-to-point sessions](/concept/socket), with the same
origin publishing and consuming through the relay. Each endpoint announces one hidden
broadcast; accepting verifies that the named peer actually dialed this session.
Every hop needs moq-lite-07 or moq-transport. Lite-07 currently requires explicitly
offering `moq-lite-07-wip`; older moq-lite hops do not carry these hidden endpoints. While
the endpoint's own client connection is moq-lite before 07, its dials and accepts fail as
unsupported instead of waiting. 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.

```ts
const connection = await Moq.Connection.connect({
url, versions: ["moq-lite-07-wip"],
publish: origin.consume(), consume: origin,
});
const endpoint = new Moq.socket.Endpoint(origin, Moq.Path.from("game"), "viewer");
const session = await endpoint.dialTcp("server", { signal: abort.signal });
session.producer.writeFrame({ payload: new TextEncoder().encode("hello") });
session.producer.finish(); // FIN in this direction; the peer may still reply.
for (let frame = await session.consumer.readFrame(); frame; frame = await session.consumer.readFrame()) {
receive(frame.payload);
}
endpoint.close();
connection.close();
```

A server takes `await endpoint.acceptTcp()`, then accepts or rejects that incoming dial.
The incoming peer and session are unverified claims; `accept()` can fail if the original
dial has closed. A pending dial waits for acceptance until it is cancelled or the endpoint
or session closes, with no acceptance timeout.
TCP and track dials have independent accept queues. For independent messages, use
`dialTrack` / `acceptTrack`: the stream exposes a track producer and an already subscribed
consumer in ascending order until updated. It skips groups that never arrive whole,
including refused, dropped, or evicted groups; a cut group is never a complete message.
TCP joins its one group live, recovering the head with a joining FETCH or fill over
moq-transport. Both stream types expose `peer` and
`session`; read and write through their producer and consumer handles.

JS TCP currently reads without fastest-reader pacing. A reader that falls behind the
group's bounded tail fails with an eviction error, so keeping up is required for lossless
delivery. Finishing a producer is FIN; aborting, closing the endpoint, or releasing a TCP
reader early resets the session. Close endpoints explicitly, and use `AbortSignal` to
cancel pending dials and accepts. Keep session ids secret.
24 changes: 23 additions & 1 deletion js/net/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,28 @@ How to update your code for each breaking change, newest first.

## Unreleased

### Track requests wait for their answer instead of timing out

A subscription, `info()`, or `fetchGroup()` the publisher hasn't answered no longer fails
with `StreamCode.ControlTimeout` after ten seconds, since the publisher's application may
hold its answer, as Rust allows. It waits until the last subscriber closes, the fetch's
`signal` aborts, the broadcast or session closes, or the publisher refuses it.
Waiting for stream credit also lasts until cancellation. To give up sooner, close
the subscriber or abort the fetch on a timer of your own. `info({ signal })` accepts
the same cancellation signal. Announcement discovery keeps waiting while it is wanted;
IETF advertisements retain their answer budget.

### Socket endpoints are available

The additive `socket` namespace exports `Endpoint`, `TcpStream`, and `TrackStream`.
Use `dialTcp` / `acceptTcp` or `dialTrack` / `acceptTrack` on endpoints sharing a prefix;
cancel pending operations with an `AbortSignal`, and explicitly close endpoints when done.
Track readers skip groups that are refused, dropped, or evicted instead of waiting forever.
TCP readers join their one group live, recovering its head with a joining FETCH or fill
over moq-transport. The existing wire is unchanged. Every hop must support moq-lite-07 (currently an
explicit `moq-lite-07-wip` offer) or moq-transport; while the endpoint's own client
connection is moq-lite before 07, its dials and accepts fail as unsupported.

### Absolute IETF subscriptions keep their prefix

Explicit group ranges now keep their requested start when the subscription answer
Expand Down Expand Up @@ -94,7 +116,7 @@ The route metadata interface `Origin.Route` is now the read-only `Origin.RouteIn

### Opens wait their turn for stream credit ([#7894](https://github.com/moq-dev/moq/pull/7894))

`NoStreamCredit` is removed: a request no longer fails when the peer grants no more streams. Every open waits for credit, and returning credit goes to the open with the highest `sendOrder`. A request's 10s deadline runs only while none of its streams waits to open.
`NoStreamCredit` is removed: a request no longer fails when the peer grants no more streams. Every open waits for credit, and returning credit goes to the open with the highest `sendOrder`. Request opens leave the queue when their caller cancels.
`OpenOptions.timeout` and `OpenOptions.waitUntilAvailable` are removed; drop them. `Writer.tryOpen` still gives up on `cancel`, and its `sendOrder` may be a function, read again while the open waits.

### Relative group anchors are `bigint`
Expand Down
40 changes: 39 additions & 1 deletion js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -665,7 +665,7 @@ export namespace Track {
};
export class Consumer {
fetchGroup(sequence: bigint, options?: Track.FetchGroupOptions): Promise<Group.Consumer>;
info(): Promise<Track.Info>;
info(options?: Track.InfoOptions): Promise<Track.Info>;
readonly name: string;
subscribe(options?: Track.Subscription): Track.Subscriber;
}
Expand Down Expand Up @@ -713,6 +713,9 @@ export namespace Track {
export interface InfoInit extends Partial<Omit<Track.Info, "maxAge">> {
maxAge?: Milli | null;
}
export interface InfoOptions {
signal?: AbortSignal;
}
export type Order = "ascending" | "descending";
export class Ordered {
close(abort?: Error): void;
Expand Down Expand Up @@ -817,4 +820,39 @@ export namespace Varint {
export function encodeTo(dst: ArrayBuffer, v: number | bigint): Uint8Array;
export function size(v: number): number;
}

export namespace socket {
export class Endpoint {
constructor(origin: Origin.Producer, prefix: Path.Valid, id: string);
acceptTcp(options?: socket.Options): Promise<socket.Incoming<socket.TcpStream>>;
acceptTrack(options?: socket.Options): Promise<socket.Incoming<socket.TrackStream>>;
close(): void;
get closed(): Signals.GetPromise<Error | null>;
dialTcp(peer: string, options?: socket.Options): Promise<socket.TcpStream>;
dialTrack(peer: string, info?: Track.InfoInit, options?: socket.Options): Promise<socket.TrackStream>;
readonly id: string;
readonly prefix: Path.Valid;
}
export class Incoming<S extends socket.TcpStream | socket.TrackStream> {
accept(...args: S extends socket.TcpStream ? [options?: socket.Options] : [info?: Track.InfoInit, options?: socket.Options]): Promise<S>;
readonly peer: string;
reject(): void;
readonly session: string;
}
export interface Options {
signal?: AbortSignal;
}
export class TcpStream {
readonly consumer: Group.Consumer;
readonly peer: string;
readonly producer: Group.Producer;
readonly session: string;
}
export class TrackStream {
readonly consumer: Track.Subscriber;
readonly peer: string;
readonly producer: Track.Producer;
readonly session: string;
}
}
```
85 changes: 85 additions & 0 deletions js/net/bench/socket.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
/** Per-session socket handshake, frame delivery and teardown swept over endpoints x sessions per endpoint. */
import { yieldNow } from "@moq/clock";
import { accept } from "../src/connection/accept.ts";
import { connect } from "../src/connection/connect.ts";
import { Origin, Path, socket } from "../src/index.ts";
import * as Lite from "../src/lite/index.ts";
import { createMockTransportPair } from "../src/mock.ts";

console.debug = () => {};
console.log("mode,protocol,endpoints,sessions_per_endpoint,open_us,frame_us,close_us");
for (const mode of ["local", "lite07"] as const)
for (const protocol of ["tcp", "track"] as const)
for (const endpoints of [1, 8, 32])
for (const sessions of [1, 8, 32]) {
const samples: number[][] = [];
for (let round = 0; round < 4; round++) {
const origin = new Origin.Producer();
const remote = mode === "local" ? origin : new Origin.Producer();
const pair = mode === "lite07" ? createMockTransportPair(Lite.ALPN_07_WIP) : undefined;
const connections = pair
? await Promise.all([
connect({
url: new URL("https://localhost/bench"),
transport: pair.client,
publish: origin.consume(),
consume: origin,
}),
accept({
url: new URL("https://localhost/bench"),
transport: pair.server,
publish: remote.consume(),
consume: remote,
}),
])
: [];
const dialer = new socket.Endpoint(origin, Path.from("bench"), "dialer");
const peers = Array.from(
{ length: endpoints },
(_, i) => new socket.Endpoint(remote, Path.from("bench"), `peer-${i}`),
);
const start = performance.now();
const pairs = await Promise.all(
peers.flatMap((peer) =>
Array.from({ length: sessions }, async () => {
const incoming = protocol === "tcp" ? peer.acceptTcp() : peer.acceptTrack();
const dialing =
protocol === "tcp" ? dialer.dialTcp(peer.id) : dialer.dialTrack(peer.id);
return Promise.all([dialing, (await incoming).accept()]);
}),
),
);
const opened = performance.now();
await Promise.all(
pairs.map(async ([local, remote]) => {
local.producer.writeFrame({ payload: new Uint8Array(1024) });
const frame =
remote instanceof socket.TcpStream
? await remote.consumer.readFrame()
: await remote.consumer.ordered().readFrame();
if (frame?.payload.length !== 1024) throw new Error("missing socket payload");
}),
);
const received = performance.now();
dialer.close();
for (const peer of peers) peer.close();
origin.close();
remote.close();
for (const connection of connections) connection.abort();
await yieldNow();
const closed = performance.now();
if (round)
samples.push(
[opened - start, received - opened, closed - received].map(
(ms) => (ms * 1000) / pairs.length,
),
);
}
const median = [0, 1, 2].map((i) =>
samples
.map((sample) => sample[i])
.sort((a, b) => a - b)[1]
.toFixed(2),
);
console.log(`${mode},${protocol},${endpoints},${sessions},${median.join(",")}`);
}
2 changes: 2 additions & 0 deletions js/net/src/broadcast.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,7 @@ test("held info lookups keep a request until the last one lets go", async () =>
const opened = wireOf(broadcast).resolveTrackInfo("media", first.signal);
const request = await pulled;
if (!request) throw new Error("expected request");
expect(hooks.requestWanted(request).peek()).toBe(true);
const producer = request.accept();
const second = new AbortController();
await wireOf(broadcast).resolveTrackInfo("media", second.signal);
Expand All @@ -246,6 +247,7 @@ test("held info lookups keep a request until the last one lets go", async () =>
expect(producer.closed.peek()).toBeUndefined();

second.abort();
expect(hooks.requestWanted(request).peek()).toBe(false);
expect(producer.closed.peek()).toBeDefined();
broadcast.close();
});
Expand Down
32 changes: 22 additions & 10 deletions js/net/src/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ let stampProducer: (producer: Producer, path: Path.Valid) => void;

// Info lookups pending or held on a track.
class Lookups {
pending = 0;
pending = new Signal(0);
// Whether a lookup opened the request, so the last lookup to end closes it unless subscribed.
opened = false;
}
Expand Down Expand Up @@ -220,7 +220,7 @@ function logical(state: BroadcastState, name: string): { producer: track.Produce
});

state.requested.mutate((requested) => {
requested.push(hooks.makeRequest({ name, producer, pending: state.pending }));
requested.push(hooks.makeRequest({ name, producer, pending: state.pending, lookups }));
});

return { producer, requested: true };
Expand All @@ -230,21 +230,21 @@ function subscribe(state: BroadcastState, name: string, options?: track.Subscrip
return logical(state, name).producer.subscribe(options);
}

// A lookup is held until `hold` aborts, which also abandons it before the answer. A request a lookup opened is let go once it is answered and nobody holds or subscribes
// to it; closing it sooner would hand its handler a closed producer.
// A lookup holds a request until `hold` aborts, even before the answer. An unanswered
// request stays open for its handler; after acceptance nobody holding it releases it.
async function resolveTrackInfo(state: BroadcastState, name: string, hold?: AbortSignal): Promise<track.Info> {
hold?.throwIfAborted();
const { producer, requested } = logical(state, name);
const lookups = state.lookups.get(producer);
if (!lookups) return producer.info();
if (requested) lookups.opened = true;
lookups.pending++;
lookups.pending.update((pending) => pending + 1);

const info = producer.info();
let answered = false;
let ended = false;
const release = () => {
if (lookups.opened && lookups.pending === 0 && producer.demand().wanted.peek() === undefined)
if (lookups.opened && lookups.pending.peek() === 0 && producer.demand().wanted.peek() === undefined)
hooks.releaseTrack(producer);
};
info.then(
Expand All @@ -256,7 +256,7 @@ async function resolveTrackInfo(state: BroadcastState, name: string, hold?: Abor
);
const end = () => {
ended = true;
lookups.pending--;
lookups.pending.update((pending) => pending - 1);
if (answered) release();
};

Expand Down Expand Up @@ -393,6 +393,20 @@ export class Producer {
}

static {
hooks.reserveUnlistedTrack = (broadcast, name) => {
const state = broadcast.#state;
if (state.closed.peek() !== undefined) throw new Error("broadcast is closed");
if (lookup(state, name)) throw new Error("duplicate reserved track");
const producer = new track.Producer(name);
const lookups = new Lookups();
state.lookups.set(producer, lookups);
state.requests.set(name, producer);
void hooks.trackReleased(producer).then(() => {
if (state.requests.get(name) === producer) state.requests.delete(name);
});
return hooks.makeRequest({ name, producer, pending: state.pending, lookups });
};

hooks.onClosed = (producer, fn) => {
const closers = producer.#state.closers;
closers.add(fn);
Expand Down Expand Up @@ -434,9 +448,7 @@ export class Producer {
const request = takeQueued(this.#state, name);
if (request) {
const producer = request.accept(info);
// The application owns it now: a lookup that opened the request must not close it.
const lookups = this.#state.lookups.get(producer);
if (lookups) lookups.opened = false;
hooks.keepRequest(request);
this.#state.requests.delete(name);
adopt(this.#state, producer, track.authoredInfo(info));
return producer;
Expand Down
3 changes: 2 additions & 1 deletion js/net/src/connection/reload.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -941,7 +941,8 @@ test("a retired GOAWAY predecessor still closes by its handover cap", async () =

// A publication only a token's grant covers keeps that grant while the session drains, so
// closing the loop ends the tokens after the drain rather than cutting the final group.
test("closing the loop keeps the tokens until the session drains", async () => {
// Quarantined pending quest/m0/test-flakes-2/reload-close-drain.md.
test.skip("closing the loop keeps the tokens until the session drains", async () => {
const original = globalThis.WebTransport;
const clock = new Manual();
const installed = clock.install();
Expand Down
19 changes: 19 additions & 0 deletions js/net/src/ietf/join.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,25 @@ test("a reader in sequence order with no delay budget skips headless groups", as
expect(group?.sequence).toBe(GROUP + 2n);
});

for (const version of VERSIONS) {
for (const objectId of [0n, 2n]) {
test(`draft ${version}: a group-0 reader skips the Largest group's cut tail after object ${objectId}`, async () => {
const { subscriber, consumer, answer } = await subscribed(version, {
order: "ascending",
delay: { max: null },
ranges: [{ start: { absolute: 0n } }],
});
await answer({ groupId: 0n, objectId });
// Largest is inclusive, including object 0: its following tail is no whole message.
await subscriber.handleGroup(...liveStream(0n, Number(objectId) + 1, ["cut"], version));
await subscriber.handleGroup(...liveStream(1n, 0, ["whole"], version));
const group = await consumer.ordered().nextGroup();
expect(group?.sequence).toBe(1n);
expect(await frames(group)).toEqual(["whole"]);
});
}
}

test("a tail parked on a refused joining FETCH is dropped", async () => {
const { subscriber, consumer, fetching } = await join();

Expand Down
2 changes: 1 addition & 1 deletion js/net/src/ietf/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1840,7 +1840,7 @@ export class Publisher {
// leaving this one namespace unadvertised.
let request: RequestStream | undefined;
try {
const deadline = new Deadline();
const deadline = new Deadline(Milli(ADVERTISE_TIMEOUT_MS));
const answer = await deadline.wait(
(async (): Promise<Answer> => {
const opened = await RequestStream.open(this.#session, deadline, { quic: this.#quic });
Expand Down
4 changes: 2 additions & 2 deletions js/net/src/ietf/request_stream.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@ test("a request's deadline ends it through the request, so later ends do nothing
});
const aborts = spyOn(stream, "abort");
const session = { version: Version.DRAFT_18, client: true, openBi: () => stream } as unknown as Session;
const deadline = new Deadline();
const deadline = new Deadline(Milli(REQUEST_TIMEOUT_MS));
const request = await RequestStream.open(session, deadline);
const answer = deadline.wait(new Promise<never>(() => {})).catch((e: unknown) => e);
await clock.advance(Nano.fromMilli(Milli(REQUEST_TIMEOUT_MS)));
Expand Down Expand Up @@ -213,7 +213,7 @@ test("a request waiting for stream credit outlasts its deadline, which runs from
client: true,
openBi: () => opening.promise,
} as unknown as Session;
const deadline = new Deadline();
const deadline = new Deadline(Milli(REQUEST_TIMEOUT_MS));
const send = mock((request: RequestStream) => request.writer.u8(1));
const sending = RequestStream.open(session, deadline).then(send);
let failure: unknown;
Expand Down
Loading
Loading