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
5 changes: 4 additions & 1 deletion doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,10 @@ route.announce();
Examples:
[`js/net/examples/`](https://github.com/moq-dev/moq/tree/main/js/net/examples).
Runs in the browser and, over WebSocket, in Node, Bun, and Deno; see
[server-side](/lib/js/#server-side). Path patterns are on the
[server-side](/lib/js/#server-side). The WebSocket fallback and the moq-transport stack load
on demand as separate chunks, so a moq-lite session WebTransport wins within its head start
never downloads them.
Path patterns are on the
[concept page](/concept/moq-lite#path-patterns).

Groups retain a 32 MiB live tail without limiting their lifetime or frame count.
Expand Down
14 changes: 3 additions & 11 deletions js/net/bench/broadcasts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import { Signal } from "@moq/signals";
import type { Grant } from "../src/auth.ts";
import { Producer as BroadcastProducer } from "../src/broadcast.ts";
import { BroadcastCache } from "../src/consume.ts";
import { HopSchema, WireRoute } from "../src/hop.ts";
import { toHop, WireRoute } from "../src/hop.ts";
import * as Instance from "../src/instance.ts";
import { AnnounceRequest } from "../src/lite/announce.ts";
import { Publisher } from "../src/lite/publisher.ts";
Expand Down Expand Up @@ -202,15 +202,7 @@ for (const patternCount of [8, 32, 128]) {
...Array.from({ length: patternCount - 1 }, (_, i) => Path.Pattern.literal(`other/${i}`)),
]);
const grant = new Signal<Grant | undefined>({ publish: new Path.Patterns(), subscribe });
const subscriber = new Subscriber(
quic,
Version.DRAFT_05,
HopSchema.parse(1n),
undefined,
undefined,
undefined,
grant,
);
const subscriber = new Subscriber(quic, Version.DRAFT_05, toHop(1n), undefined, undefined, undefined, grant);
const groups = await Promise.all(
Array.from({ length: fetchCount }, (_, i) => subscriber.fetchGroup(Path.from(`room/${i}`), "video", 0n)),
);
Expand Down Expand Up @@ -409,7 +401,7 @@ for (const routeCount of routeCounts) {
});
const senders = Array.from({ length: observerCount }, () => {
const pair = createMockTransportPair(ALPN_07_WIP);
const publisher = new Publisher(pair.server, Version.DRAFT_07, HopSchema.parse(1n), origin.consume());
const publisher = new Publisher(pair.server, Version.DRAFT_07, toHop(1n), origin.consume());
const entered = Promise.withResolvers<void>();
const release = Promise.withResolvers<void>();
const stream = new Stream({
Expand Down
4 changes: 2 additions & 2 deletions js/net/src/announced.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { yieldNow } from "@moq/clock";
import * as Announce from "./announced.ts";
import type { Credential } from "./auth.ts";
import type { Producer as BroadcastProducer } from "./broadcast.ts";
import { HopSchema, UNKNOWN_HOP, WireRoute } from "./hop.ts";
import { toHop, UNKNOWN_HOP, WireRoute } from "./hop.ts";
import * as Instance from "./instance.ts";
import { Producer as OriginProducer } from "./origin.ts";
import * as Path from "./path.ts";
Expand Down Expand Up @@ -51,7 +51,7 @@ test("a listing shows a route's facts, never its epoch, hops, credential, or dra
const route = WireRoute.normalize({
instance,
epoch: 3n,
hops: [HopSchema.parse(7n), UNKNOWN_HOP],
hops: [toHop(7n), UNKNOWN_HOP],
cost: 5n,
auth: {} as Credential,
draining: true,
Expand Down
22 changes: 14 additions & 8 deletions js/net/src/connection/connect.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { Duration, Elapsed, sleep, timeout } from "@moq/clock";
import { Session as Qmux, type SessionOptions as QmuxOptions, type Version as QmuxVersion } from "@moq/qmux";
import type { Session as Qmux, SessionOptions as QmuxOptions, Version as QmuxVersion } from "@moq/qmux";
import { type Getter, race } from "@moq/signals";
import type * as Auth from "../auth.ts";
import { vacant } from "../auth_session.ts";
Expand All @@ -20,6 +20,7 @@ import { DEFAULT_TIMEOUT, exchangeSetup, handsOff } from "./handshake.ts";
import type { Session } from "./session.ts";
import { inspect } from "./stats.ts";
import { credential, fallback, hold, type Presentation } from "./tokens.ts";
import { transportOf } from "./transport.ts";

// Default head start for WebTransport before attempting the WebSocket fallback.
const DEFAULT_WEBSOCKET_DELAY = Duration.millis(500);
Expand Down Expand Up @@ -496,7 +497,8 @@ async function connectInner(
void abort.then(() => session.close());

// Record who won the race to this server, so QUIC's next head start follows the last result.
if (session instanceof Qmux) {
const websocket = transportOf(session) === "websocket";
if (websocket) {
console.debug(show(parse(url)), "connected via WebSocket");
websocketWon.add(server);
} else {
Expand All @@ -514,9 +516,9 @@ async function connectInner(
session.close();
throw new Error("server negotiated no protocol, and no offered version negotiates in SETUP");
}
const won = session instanceof Qmux && fallbackDial ? fallbackDial : dial;
const won = websocket && fallbackDial ? fallbackDial : dial;
const connection = await connectTransport(url, session as WebTransport, wiring(won), offered.setup);
if (session instanceof Qmux) {
if (websocket) {
const forget = () => websocketWon.delete(server);
void connection.closed.then(forget, forget);
}
Expand Down Expand Up @@ -952,13 +954,17 @@ async function connectWebSocket(
cancel: Promise<void>,
options: QmuxOptions,
): Promise<Qmux | undefined> {
const timer = sleep(delay);

const active = await Promise.race([cancel, timer.then(() => true)]);
const active = await race([cancel, sleep(delay).then(() => true)]);
if (!active) return undefined;

// qmux loads only once the fallback dials, so a session WebTransport wins within its head
// start never downloads it.
const qmux = await race([cancel, import("@moq/qmux")]);
if (!qmux) return undefined;
const { Session } = qmux;

for (let wait = WEBSOCKET_REDIAL; ; wait = wait.mul(2)) {
const quic = new Qmux(url, options);
const quic = new Session(url, options);

// Wait for the WebSocket to connect, for the cancel promise to resolve, or for the
// redial. `ready` rejects on a refused/failed connection, so a throw here is the
Expand Down
9 changes: 3 additions & 6 deletions js/net/src/connection/stats.test.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
import { expect, spyOn, test } from "bun:test";
import { Duration, yieldNow } from "@moq/clock";
import { Manual } from "@moq/clock/test";
import { Session as QmuxSession } from "@moq/qmux";
import { Effect } from "@moq/signals";
import * as Ietf from "../ietf/index.ts";
import * as Lite from "../lite/index.ts";
import { createMockTransportPair, MockTransport } from "../mock.ts";
import { createMockTransportPair, type MockTransport } from "../mock.ts";
import { type AcceptProps, accept as acceptSession, type ConnectProps, connect as connectSession } from "./index.ts";
import { Reload } from "./reload.ts";
import { canEstimate, estimates, type TransportStats, transportStats } from "./stats.ts";
Expand Down Expand Up @@ -120,11 +119,9 @@ const kinds: { name: string; estimates: boolean; shape: (quic: MockTransport) =>
{
name: "the WebSocket fallback",
estimates: false,
// A qmux session is what marks the fallback; the mock keeps its own behavior.
// A qmux session labels itself as the fallback; the mock keeps its own behavior.
shape: (quic) => {
const proto = Object.create(QmuxSession.prototype);
Object.defineProperties(proto, Object.getOwnPropertyDescriptors(MockTransport.prototype));
Object.setPrototypeOf(quic, proto);
Object.assign(quic, { transport: "websocket" });
},
},
{
Expand Down
8 changes: 3 additions & 5 deletions js/net/src/connection/transport.ts
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
import { Session } from "@moq/qmux";

/** The wire transport a session runs over. */
export type Transport = "webtransport" | "websocket" | "webrtc";

/**
* The transport a live session is actually running over. WebSocket and WebRTC adapters
* share the WebTransport shape; WebRTC carries its label to avoid a dependency cycle.
* share the WebTransport shape and carry their label, so `@moq/qmux` stays a lazy chunk.
*
* @internal Not re-exported from the package entrypoint.
*/
export function transportOf(quic: WebTransport): Transport {
if ("transport" in quic && quic.transport === "webrtc") return "webrtc";
return quic instanceof Session ? "websocket" : "webtransport";
const label = "transport" in quic ? quic.transport : undefined;
return label === "webrtc" || label === "websocket" ? label : "webtransport";
}
23 changes: 12 additions & 11 deletions js/net/src/hop.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@
* @module
*/
import type { Duration } from "@moq/clock";
import * as z from "zod/mini";
import type { Credential } from "./auth.ts";
import type * as Instance from "./instance.ts";
import { isLeadingOnes, type StreamVersion } from "./stream.ts";
Expand All @@ -20,17 +19,19 @@ import { isLeadingOnes, type StreamVersion } from "./stream.ts";
* stamps into a chain as an announcement passes through, so a receiver can spot its own
* id and reject a loop. The SETUP parameter that carries it session-wide is `Hop` too.
*
* The {@link HopSchema} validates any incoming value and brands it so the type system
* {@link toHop} validates any incoming value and brands it so the type system
* enforces "only validated ids flow into hop chains." Internal code that synthesizes one
* (e.g. `randomHop`) uses `HopSchema.parse(...)` to brand a raw bigint.
* (e.g. `randomHop`) brands a raw bigint the same way.
*/
export const HopSchema = z
.bigint()
.check(z.refine((value) => value >= 0n && value < 1n << 64n, "Hop must be a non-negative 64-bit integer"))
.brand("Hop");
export type Hop = bigint & { readonly [hopBrand]: true };

/** A relay's hop id, validated by {@link HopSchema}. */
export type Hop = z.infer<typeof HopSchema>;
declare const hopBrand: unique symbol;

/** Brand `value` as a {@link Hop}, refusing anything outside the unsigned 64-bit range. */
export function toHop(value: bigint): Hop {
if (value < 0n || value >= 1n << 64n) throw new RangeError("Hop must be a non-negative 64-bit integer");
return value as Hop;
}

/**
* The reserved id 0, meaning "no identity".
Expand All @@ -40,7 +41,7 @@ export type Hop = z.infer<typeof HopSchema>;
* in common, and never excluded from an advertisement. A chain that holds a 0 anywhere
* is anonymous for route selection.
*/
export const UNKNOWN_HOP: Hop = HopSchema.parse(0n);
export const UNKNOWN_HOP: Hop = toHop(0n);

/**
* The id `hop` carries on a wire in `version`'s varint form.
Expand Down Expand Up @@ -77,7 +78,7 @@ export function randomHop(): Hop {
// Mask to 53 bits.
const raw = buf[0] & 0x1f_ffff_ffff_ffffn;
// Guard against the (astronomically unlikely) zero draw.
return HopSchema.parse(raw === 0n ? 1n : raw);
return toHop(raw === 0n ? 1n : raw);
}

/** The static cost of pulling content through a route; lower wins. */
Expand Down
4 changes: 2 additions & 2 deletions js/net/src/ietf/cluster.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { expect, test } from "bun:test";
import { ProtocolViolation, StreamCode, StreamError } from "../error.ts";
import { type Hop, HopSchema, UNKNOWN_HOP } from "../hop.ts";
import { type Hop, toHop, UNKNOWN_HOP } from "../hop.ts";
import * as Path from "../path.ts";
import { Reader, Writer } from "../stream.ts";
import * as Cluster from "./cluster.ts";
Expand All @@ -19,7 +19,7 @@ const VERSION = Version.DRAFT_18;
const CLUSTER = { cluster: true };

function origin(id: bigint): Hop {
return HopSchema.parse(id);
return toHop(id);
}

function hops(...ids: bigint[]): Hop[] {
Expand Down
6 changes: 3 additions & 3 deletions js/net/src/ietf/cluster.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
*/

import { ProtocolViolation, reason } from "../error.ts";
import { type Hop, HopSchema, MAX_HOPS, UNKNOWN_HOP } from "../hop.ts";
import { type Hop, MAX_HOPS, toHop, UNKNOWN_HOP } from "../hop.ts";
import * as Varint from "../varint.ts";
// Type-only: SETUP loads eagerly and must not pull in the message parameter codec.
import type { Parameters } from "./parameters.ts";
Expand Down Expand Up @@ -93,7 +93,7 @@ export function fromSetup(params: SetupOptions): Hop | undefined {
// 0 is legal: the peer speaks the extension but withholds its identity.
const value = params.getVarint(SetupOption.HopId);
if (value === undefined) return undefined;
return HopSchema.parse(value);
return toHop(value);
}

/**
Expand Down Expand Up @@ -233,7 +233,7 @@ function decodeHops(value: Uint8Array): Hop[] {
while (rest.length > 0) {
// A short read here means the entries did not exactly fill the length.
const [hop, remain] = Varint.decodeLeadingOnes(rest);
hops.push(HopSchema.parse(hop));
hops.push(toHop(hop));
rest = remain;

// Bail before the buffer does: a hostile length would otherwise cost us one
Expand Down
10 changes: 5 additions & 5 deletions js/net/src/ietf/peer-violations.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { expect, spyOn, test } from "bun:test";
import { SessionCode, StreamCode, StreamError } from "../error.ts";
import { HopSchema } from "../hop.ts";
import { toHop } from "../hop.ts";
import { createMockTransportPair } from "../mock.ts";
import * as Path from "../path.ts";
import { Stream, Writer } from "../stream.ts";
Expand Down Expand Up @@ -111,8 +111,8 @@ for (const [version, alpn] of versions) {
);
await writer.u53(RequestOk.id);
await new RequestOk({}).encode(writer, version);
const self = HopSchema.parse(5n),
peer = HopSchema.parse(9n);
const self = toHop(5n),
peer = toHop(9n);
const entry = async (name: string) => {
await writer.u53(SubscribeNamespaceEntry.id);
await new SubscribeNamespaceEntry({
Expand Down Expand Up @@ -161,8 +161,8 @@ for (const [version, alpn] of versions) {
`${alpn}: %s releases a slot after route reflection and reattachment`,
async (ending) => {
const pair = createMockTransportPair(alpn);
const self = HopSchema.parse(5n),
peer = HopSchema.parse(9n);
const self = toHop(5n),
peer = toHop(9n);
const subscriber = new Subscriber({
session: new NativeSession(pair.server, version, true),
quic: pair.server,
Expand Down
20 changes: 10 additions & 10 deletions js/net/src/ietf/publisher.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import {
Stream as StreamError,
unauthorized,
} from "../error.ts";
import { type Hop, HopSchema } from "../hop.ts";
import { type Hop, toHop } from "../hop.ts";
import * as Instance from "../instance.ts";
import { hooks } from "../internal.ts";
import { createMockTransportPair, manual, SessionBroadcast, settlesWithin } from "../mock.ts";
Expand Down Expand Up @@ -1537,9 +1537,9 @@ test("closing the session ends the unsolicited announce loop", async () => {
* not read ours either, so sending it the parameters would be a protocol violation.
*/
test("an advertisement carries our hop id once the peer declared one", async () => {
const self: Hop = HopSchema.parse(7n);
const self: Hop = toHop(7n);

for (const peer of [HopSchema.parse(9n), undefined]) {
for (const peer of [toHop(9n), undefined]) {
const pair = createMockTransportPair(ALPN.DRAFT_18);
const { pub, origin } = publisher(pair.server, { cluster: { self, peer } });
publish(origin, Path.from("mine"));
Expand Down Expand Up @@ -1631,8 +1631,8 @@ async function readUpdate(stream: Stream): Promise<Cluster.Update> {
function clustered(requiresSolicitation = false, auth?: Tokens) {
const clock = new Manual();
const installed = clock.install();
const self: Hop = HopSchema.parse(7n);
const peer: Hop = HopSchema.parse(9n);
const self: Hop = toHop(7n);
const peer: Hop = toHop(9n);
const pair = createMockTransportPair(ALPN.DRAFT_18);
const { pub, origin } = publisher(pair.server, { cluster: { self, peer }, requiresSolicitation, auth });
const streams = accepted(pair.client);
Expand All @@ -1643,9 +1643,9 @@ function clustered(requiresSolicitation = false, auth?: Tokens) {
return { clock, self, pair, pub, origin, streams, close };
}

const VIA: Hop = HopSchema.parse(3n);
const MID: Hop = HopSchema.parse(4n);
const OTHER: Hop = HopSchema.parse(5n);
const VIA: Hop = toHop(3n);
const MID: Hop = toHop(4n);
const OTHER: Hop = toHop(5n);

/**
* A reprice is a REQUEST_UPDATE on the request that already carries the namespace, with
Expand Down Expand Up @@ -2165,11 +2165,11 @@ test("an unanswered update drops the request and re-offers the namespace fresh",
* the peer cannot see must not withdraw and advertise the namespace again.
*/
test.each([
["an unchanged price with Cluster", HopSchema.parse(9n)],
["an unchanged price with Cluster", toHop(9n)],
["any re-price without Cluster", undefined],
])("%s sends nothing", async (_, peer) => {
using clock = manual();
const self: Hop = HopSchema.parse(7n);
const self: Hop = toHop(7n);
const pair = createMockTransportPair(ALPN.DRAFT_18);
const { pub, origin } = publisher(pair.server, { cluster: { self, peer } });
const broadcast = origin.route(Path.from("mine"), { cost: 4n });
Expand Down
Loading