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
1 change: 1 addition & 0 deletions doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ moq-transport at setup and presents one API either way. Media is a layer above
What you use it for, beyond what the concept page already describes:

- **An origin outlives the session.** `origin.route(path, options)` returns a `Route` that owns the broadcast to fill (`route.broadcast()`) and controls its announcement: `announce()`, `withdraw()`, `set_cost()`, and dropping the last clone retracts it. `origin.route_prefix(prefix, options)` serves requests beneath a prefix instead, each answered with `request.serve(held)`, `request.route(options)` (the path's own exact route) or `reject`. A standalone broadcast cannot announce; publish one only through a prefix route's `serve`. A reconnect announces existing routes again, and closing the session does not delete them.
- **Routes report what the mesh filled in.** An announcement's `route` gives its `instance()`, `cost()`, the hop ids it crossed (`hops()`, oldest first, 0 for an anonymous hop) and `is_anonymous()`; an application sets only `RouteOptions`. An origin's own hop id is `origin::Config::hop`, random unless a relay names one.
- **Requests can pin an instance.** `consumer.request(path, Some(instance))` resolves only through a route announcing that [publisher instance](/concept/moq-lite#publisher-instances); `None` takes whichever route wins. The resolved consumer names its instance in `info().instance`, pinned or not. A route serves a random instance minted when it is created and kept across `withdraw()` and `announce()`; set one with `RouteOptions::with_instance(instance, epoch)` only for a publisher that continues its group sequences across restarts and raises the epoch each time. `route.instance()` names it.
- **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, `None` once the path goes offline, and whatever serves it next, like JS `follow(path)`. `consumer.announced()` lists paths only as present or absent. 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.
Expand Down
11 changes: 2 additions & 9 deletions js/net/api/index.api.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,8 @@
# `@moq/net`

```ts
import { $ZodBranded } from "zod/v4/core";
import { Instant } from "@moq/clock";
import { Milli } from "@moq/clock";
import { ZodMiniBigInt } from "zod/mini";
import { infer } from "zod/mini";

export namespace Announce {
export interface Announce {
Expand Down Expand Up @@ -465,8 +462,6 @@ export namespace Origin {
readonly closed: Signals.GetPromise<Error | null>;
readonly path: Path.Valid;
}
export type Hop = infer<typeof Origin.HopSchema>;
export const HopSchema: $ZodBranded<ZodMiniBigInt<bigint>, "Hop", "out">;
export class Producer implements Origin.Table {
constructor();
announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer;
Expand Down Expand Up @@ -515,10 +510,9 @@ export namespace Origin {
withdraw(): void;
}
export interface RouteInfo {
readonly auth?: Auth.Credential;
readonly anonymous: boolean;
readonly cost: Origin.Cost;
readonly epoch?: bigint;
readonly hops: readonly Origin.Hop[];
readonly hops: readonly bigint[];
readonly instance?: Instance.Valid;
}
export interface RouteOptions {
Expand All @@ -532,7 +526,6 @@ export namespace Origin {
route(path: Path.Valid, options?: Origin.RouteOptions): Origin.Route;
routePrefix(prefix: Path.Valid, options?: Origin.RouteOptions): Origin.Route;
}
export function isAnonymous(route: Origin.RouteInfo): boolean;
}

export namespace Path {
Expand Down
16 changes: 8 additions & 8 deletions js/net/bench/broadcasts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,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, RouteInfo } from "../src/hop.ts";
import { HopSchema, 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 @@ -268,7 +268,7 @@ for (const routeCount of routeCounts) {
for (const consumerCount of [8, 32, 128]) {
const cache = new BroadcastCache();
const owners = Array.from({ length: routeCount }, () => ({}));
for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`pool/${i}`), owners[i], RouteInfo.default);
for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`pool/${i}`), owners[i], WireRoute.default);
const sources = Array.from({ length: consumerCount }, () => new BroadcastProducer());
const held = sources.map((source, i) => {
const path = Path.from(`pool/${i % routeCount}/job/${i}`);
Expand All @@ -277,7 +277,7 @@ for (const routeCount of routeCounts) {
const touched = Path.from("pool/0/job/0");
const start = performance.now();
for (let i = 0; i < 4096; i++) {
cache.announce(Path.from("pool/0"), owners[0], { ...RouteInfo.default, cost: BigInt(i) });
cache.announce(Path.from("pool/0"), owners[0], { ...WireRoute.default, cost: BigInt(i) });
const shared = cache.get(touched, cache.instance(touched));
if (!shared || shared.closed !== held[0].closed) throw new Error("update replaced the source");
shared.close();
Expand All @@ -294,7 +294,7 @@ for (const routeCount of routeCounts) {
for (const consumerCount of [1, 8, 32]) {
const cache = new BroadcastCache();
const owners = Array.from({ length: routeCount }, () => ({}));
for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`pool/${i}`), owners[i], RouteInfo.default);
for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`pool/${i}`), owners[i], WireRoute.default);
const sources = Array.from({ length: consumerCount }, () => new BroadcastProducer());
const paths = sources.map((_, i) => Path.from(`pool/0/job/${i}`));
const held = sources.map((source, i) => cache.insert(paths[i], cache.instance(paths[i]), source.consume()));
Expand All @@ -304,7 +304,7 @@ for (const routeCount of routeCounts) {
let duplicates = 0;
const start = performance.now();
for (let round = 0; round < 256; round++) {
if (round % 2 === 0) cache.announce(prefix, specific, { ...RouteInfo.default, instance });
if (round % 2 === 0) cache.announce(prefix, specific, { ...WireRoute.default, instance });
else cache.withdraw(prefix, specific);
for (let i = 0; i < consumerCount; i++) {
const instance = cache.instance(paths[i]);
Expand All @@ -329,7 +329,7 @@ console.log("blind,announcements,consumers,invalidate_us,stale");
for (const routeCount of routeCounts) {
for (const consumerCount of [1, 8, 32]) {
const cache = new BroadcastCache();
for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`other/${i}`), {}, RouteInfo.default);
for (let i = 0; i < routeCount; i++) cache.announce(Path.from(`other/${i}`), {}, WireRoute.default);
const source = new BroadcastProducer();
const keeper = source.consume();
const paths = Array.from({ length: consumerCount }, (_, i) => Path.from(`pool/job/${i}`));
Expand All @@ -340,7 +340,7 @@ for (const routeCount of routeCounts) {
for (let round = 0; round < 256; round++) {
const held = paths.map((path) => cache.insert(path, cache.instance(path), source.consume()));
const start = performance.now();
cache.announce(prefix, owner, RouteInfo.default);
cache.announce(prefix, owner, WireRoute.default);
cache.withdraw(prefix, owner);
elapsed += performance.now() - start;
for (const path of paths) {
Expand Down Expand Up @@ -371,7 +371,7 @@ for (const routeCount of routeCounts) {
const held = [];
for (let route = 0; route < routeCount; route++) {
const prefix = Path.from(`route/${route}`);
cache.announce(prefix, owners[route], RouteInfo.default);
cache.announce(prefix, owners[route], WireRoute.default);
for (let consumer = 0; consumer < (route === 0 ? consumerCount : 1); consumer++) {
const path = Path.from(`${prefix}/job/${consumer}`);
const instance = cache.instance(path);
Expand Down
4 changes: 2 additions & 2 deletions js/net/bench/forward.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import { AuthSession } from "../src/auth_session.ts";
import { Producer as BroadcastProducer } from "../src/broadcast.ts";
import type { Established } from "../src/connection/established.ts";
import { forwardAnnounced } from "../src/connection/forward.ts";
import { RouteInfo } from "../src/hop.ts";
import { WireRoute } from "../src/hop.ts";
import { Producer } from "../src/origin.ts";
import * as Path from "../src/path.ts";
import { registerWire } from "../src/wire.ts";
Expand Down Expand Up @@ -52,7 +52,7 @@ class FakeSession {
}

const announce = (stream: Announce.Producer, prefix: Path.Valid, cost: bigint, kind: "start" | "update") =>
stream.append({ prefix, captures: undefined, kind, route: RouteInfo.normalize({ cost }) });
stream.append({ prefix, captures: undefined, kind, route: WireRoute.normalize({ cost }) });

console.log("touched,heads,routes,update_us");
for (const touched of ["covering", "single"] as const) {
Expand Down
4 changes: 2 additions & 2 deletions js/net/src/announced.test-util.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { Signal } from "@moq/signals";
import type { Options, Routes } from "./announced";
import type { RouteInfo } from "./hop";
import type { WireRoute } from "./hop";
import type * as Path from "./path";

/** A closeable announcement snapshot for tests and benchmarks. @internal */
Expand All @@ -10,7 +10,7 @@ export async function announcedView(
options?: Options,
) {
const stream = origin.routes(scope, options);
const value = new Signal<ReadonlyMap<Path.Valid, RouteInfo>>(new Map());
const value = new Signal<ReadonlyMap<Path.Valid, WireRoute>>(new Map());
const done = (async () => {
for await (const event of stream)
value.update((previous) => {
Expand Down
40 changes: 33 additions & 7 deletions js/net/src/announced.test.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
import { expect, test } from "bun:test";
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 { RouteInfo } from "./hop.ts";
import { HopSchema, 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";
import { wireOf } from "./wire.ts";
Expand All @@ -19,7 +21,7 @@ test("next streams every appended event in order", async () => {
const producer = new Announce.Producer();
const consumer = producer.consume();

const route = RouteInfo.default;
const route = WireRoute.default;
producer.append({ prefix: p("a"), captures: undefined, kind: "start", route });
producer.append({ prefix: p("a"), captures: undefined, kind: "end", route });

Expand All @@ -31,7 +33,7 @@ test("a listing reports only a path becoming present or absent", async () => {
const producer = new Announce.Producer();
const listing = Announce.list(producer.consume());

const route = RouteInfo.default;
const route = WireRoute.default;
producer.append({ prefix: p("a"), captures: undefined, kind: "start", route });
producer.append({ prefix: p("a"), captures: undefined, kind: "update", route });
producer.append({ prefix: p("a"), captures: undefined, kind: "restart", route });
Expand All @@ -41,11 +43,35 @@ test("a listing reports only a path becoming present or absent", async () => {
expect((await listing.next())?.kind).toBe("absent");
});

test("a listing shows a route's facts, never its epoch or credential", async () => {
const producer = new Announce.Producer();
const listing = Announce.list(producer.consume());

const instance = Instance.random();
const route = WireRoute.normalize({
instance,
epoch: 3n,
hops: [HopSchema.parse(7n), UNKNOWN_HOP],
cost: 5n,
auth: {} as Credential,
});
producer.append({ prefix: p("a"), captures: undefined, kind: "start", route });

const event = await listing.next();
expect(event).toEqual({
kind: "present",
prefix: p("a"),
captures: undefined,
route: { instance, hops: [7n, 0n], cost: 5n, anonymous: true },
});
expect(Object.keys(event?.route ?? {}).sort()).toEqual(["anonymous", "cost", "hops", "instance"]);
});

test("the consumer is an async iterable of the same events", async () => {
const producer = new Announce.Producer();
const consumer = producer.consume();

const route = RouteInfo.default;
const route = WireRoute.default;
producer.append({ prefix: p("a"), captures: undefined, kind: "start", route });
producer.append({ prefix: p("a"), captures: undefined, kind: "end", route });

Expand All @@ -64,7 +90,7 @@ test("a same-name re-announce is a distinct update", async () => {
// The stream is a log, not a set: it carries a redundant announce as its own update rather
// than collapsing it. Deciding what a repeat means belongs to the session layer, which resolves
// a restart into either nothing (an identical route) or an in-place update.
const route = RouteInfo.default;
const route = WireRoute.default;
producer.append({ prefix: p("a"), captures: undefined, kind: "start", route });
producer.append({ prefix: p("a"), captures: undefined, kind: "start", route });

Expand Down Expand Up @@ -97,7 +123,7 @@ test("closing a consumer releases only that handle", async () => {
expect(producer.closed.peek()).toBeUndefined();

// The other reader keeps the stream: an event still reaches it.
const route = RouteInfo.default;
const route = WireRoute.default;
producer.append({ prefix: p("a"), captures: undefined, kind: "start", route });
expect((await second.next())?.prefix).toBe(p("a"));

Expand Down Expand Up @@ -178,7 +204,7 @@ const start = (prefix: string): Announce.RouteEvent => ({
prefix: p(prefix),
captures: undefined,
kind: "start",
route: RouteInfo.default,
route: WireRoute.default,
});

test("a stream syncs once the reader is past what was queued at the boundary", async () => {
Expand Down
17 changes: 12 additions & 5 deletions js/net/src/announced.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
* @module
*/
import { type GetPromise, type Getter, Once, Signal } from "@moq/signals";
import type { RouteInfo } from "./hop.js";
import { type RouteInfo, routeInfo, type WireRoute } from "./hop.ts";
import type * as Path from "./path.js";

/**
Expand All @@ -29,6 +29,13 @@ export interface Announce {
route: RouteInfo;
}

/**
* An {@link Announce} as the origin and sessions carry it, with the route's internal metadata.
*
* @internal
*/
export type Routed = Omit<Announce, "route"> & { route: WireRoute };

/**
* What an announcement listing yields: a path becoming present or absent.
*
Expand All @@ -49,7 +56,7 @@ export type Event = { kind: "present" | "absent" } & Announce;
*
* @internal
*/
export type RouteEvent = { kind: "start" | "update" | "restart" | "end" } & Announce;
export type RouteEvent = { kind: "start" | "update" | "restart" | "end" } & Routed;

/**
* Options for an announcement stream.
Expand Down Expand Up @@ -316,9 +323,9 @@ export class Consumer {
for (;;) {
const event = await this.#routes.next();
if (!event) return undefined;
const { kind, ...announce } = event;
if (kind === "start") return { kind: "present", ...announce };
if (kind === "end") return { kind: "absent", ...announce };
const { kind, prefix, captures, route } = event;
if (kind === "start") return { kind: "present", prefix, captures, route: routeInfo(route) };
if (kind === "end") return { kind: "absent", prefix, captures, route: routeInfo(route) };
}
}

Expand Down
8 changes: 4 additions & 4 deletions js/net/src/connection/forward.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { type Installed, Manual, Milli, Nano } from "@moq/clock";
import * as Announce from "../announced.ts";
import { AuthSession } from "../auth_session.ts";
import { type Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "../broadcast.ts";
import { RouteInfo } from "../hop.ts";
import { 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 @@ -132,7 +132,7 @@ class FakeSession {
}
}

function start(stream: Announce.Producer, prefix: string, route: RouteInfo = RouteInfo.default) {
function start(stream: Announce.Producer, prefix: string, route: WireRoute = WireRoute.default) {
stream.append({ prefix: Path.from(prefix), captures: undefined, kind: "start", route });
}

Expand Down Expand Up @@ -411,12 +411,12 @@ for (const [name, instances] of [

const narrow = origin.routes(Path.Pattern.subtree(Path.from("a/b")));
await settle();
start(session.stream("a/b/**"), "a/b/x", { ...RouteInfo.default, instance: instances[0] });
start(session.stream("a/b/**"), "a/b/x", { ...WireRoute.default, instance: instances[0] });
await settle();
const broad = origin.routes(Path.Pattern.subtree(Path.from("a")));
const events = record(broad);
await settle();
start(session.stream("a/**"), "a/b/x", { ...RouteInfo.default, instance: instances[1] });
start(session.stream("a/**"), "a/b/x", { ...WireRoute.default, instance: instances[1] });
await settle();
expect(events).toEqual(["start a/b/x"]);

Expand Down
6 changes: 3 additions & 3 deletions js/net/src/connection/forward.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
import { Milli, Nano } from "@moq/clock";
import { type Dispose, race } from "@moq/signals";
import type * as Announce from "../announced.ts";
import { type RouteInfo, routesEqual } from "../hop.ts";
import { routesEqual, type WireRoute } from "../hop.ts";
import { coveringPrefixes } from "../internal.ts";
import type { Producer as OriginProducer, Route } from "../origin.ts";
import * as Path from "../path.ts";
Expand Down Expand Up @@ -41,7 +41,7 @@ interface Interest {
interface Reported {
handle: Route;
/** Each request's latest route for the prefix. */
readonly reporters: Map<Interest, RouteInfo>;
readonly reporters: Map<Interest, WireRoute>;
}

/**
Expand Down Expand Up @@ -118,7 +118,7 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi
* instance, so nothing resolved through the old one is joined again, and an in-place
* update otherwise.
*/
const updateReported = (existing: Reported, prefix: Path.Valid, route: RouteInfo, restart: boolean) => {
const updateReported = (existing: Reported, prefix: Path.Valid, route: WireRoute, restart: boolean) => {
const current = wireOf(existing.handle).info;
if (restart || route.epoch !== current?.epoch) {
// Inserted before the old one leaves, so local readers see one restart rather than
Expand Down
6 changes: 3 additions & 3 deletions js/net/src/connection/reload.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import * as Announce from "../announced.ts";
import { Viewers } from "../bandwidth.ts";
import type { Producer as BroadcastProducer } from "../broadcast.ts";
import { ConnectTimeout, SessionCode, SessionError, StreamCode, toTransport } from "../error.ts";
import { RouteInfo } from "../hop.ts";
import { WireRoute } from "../hop.ts";
import { ALPN as IetfALPN } from "../ietf/version.ts";
import * as Lite from "../lite/index.ts";
import { createMockTransportPair, type MockTransport, textFrame } from "../mock.ts";
Expand Down Expand Up @@ -1030,7 +1030,7 @@ test("closing an announce consumer during upstream teardown does not append retr
prefix: Path.from("alice/camera.hang"),
captures: undefined,
kind: "start",
route: RouteInfo.default,
route: WireRoute.default,
});
await consumer.next();
upstream.close();
Expand Down Expand Up @@ -1136,7 +1136,7 @@ test("a pump owes the retractions of the upstream it replaces", async () => {
const consumer = producer.consume();

const first = new Announce.Producer();
first.append({ prefix: Path.from("a"), captures: undefined, kind: "start", route: RouteInfo.default });
first.append({ prefix: Path.from("a"), captures: undefined, kind: "start", route: WireRoute.default });
first.synced();
const upstream = new Signal(first);
const pump = new Effect((effect) => pumpAnnounced(effect, effect.get(upstream).consume(), producer));
Expand Down
2 changes: 1 addition & 1 deletion js/net/src/connection/reload.ts
Original file line number Diff line number Diff line change
Expand Up @@ -876,7 +876,7 @@ export class Reload {
*/
export function pumpAnnounced(effect: Effect, upstream: Announce.Routes, producer: Announce.Producer) {
// The last event per active route rides along for its retraction.
const active = new Map<Path.Valid, Announce.Announce>();
const active = new Map<Path.Valid, Announce.Routed>();
let live = true;
const retract = () => {
live = false;
Expand Down
Loading
Loading