diff --git a/demo/web/src/stats.ts b/demo/web/src/stats.ts index 814a3446b92..40a89063812 100644 --- a/demo/web/src/stats.ts +++ b/demo/web/src/stats.ts @@ -185,7 +185,7 @@ discovery.run((effect) => { }); }); -function subscribeNode(effect: Signals.Effect, origin: Net.Origin.Table, path: Net.Path.Valid, node: string) { +function subscribeNode(effect: Signals.Effect, origin: Net.Origin.Reader, path: Net.Path.Valid, node: string) { nodeStats.mutate((s) => { s[node] = { egress: {}, diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 5794f3acbe0..13237c38196 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -378,7 +378,7 @@ export namespace Group { export const IMPLEMENTATION: string; export namespace Origin { - export class Consumer { + export class Consumer implements Origin.Reader { announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; get closed(): Signals.GetPromise; get discovery(): Signals.Getter; @@ -418,6 +418,13 @@ export namespace Origin { get route(): Origin.Route | undefined; unannounce(): void; } + export interface Reader { + announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; + readonly closed: Signals.GetPromise; + readonly discovery: Signals.Getter; + follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; + request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; + } export class Request { readonly path: Path.Valid; prepare(epoch: Epoch.Valid): Origin.Prepared; @@ -444,13 +451,8 @@ export namespace Origin { epoch?: Epoch.Valid; hops: Origin.Hop[]; } - export interface Table { - announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; - readonly closed: Signals.GetPromise; + export interface Table extends Origin.Reader { createBroadcast(path: Path.Valid): Origin.Publication; - readonly discovery: Signals.Getter; - follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; - request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; requests(prefix: Path.Valid): Origin.Requests; } export function isAnonymous(route: Origin.Route): boolean; diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 8af6989d3a0..4040546a1de 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -1101,25 +1101,22 @@ class OriginState { } /** - * A non-owning handle on an origin: publish into it and read it, without its lifecycle. + * The read side of an origin, borrowed: resolve broadcasts by path and watch what is + * available, without publishing into it or owning its lifecycle. * - * What a shared connection lends out. {@link Producer} implements it, so code that is - * handed an origin rather than owning one should accept this type: closing the origin - * stays the owner's alone, and a borrower cannot express it. A borrower that only reads - * should accept just the {@link Consumer} members it needs, so `producer.consume()` fits too. + * Code that only reads an origin should accept this type. {@link Consumer} implements it + * and {@link Table} extends it, so `producer.consume()`, a borrowed table, and a structural + * equivalent all fit. * * @public */ -export interface Table { - /** Settles once the origin closes; see {@link Producer.closed}. */ +export interface Reader { + /** Settles once the origin closes; see {@link Consumer.closed}. */ readonly closed: GetPromise; /** Whether every attached session announces into the table; see {@link Consumer.discovery}. */ readonly discovery: Getter; - /** Create an unannounced broadcast at `path`; see {@link Producer.createBroadcast}. */ - createBroadcast(path: Path.Valid): Publication; - /** Resolve one publisher instance at `path`; see {@link Consumer.request}. */ request(path: Path.Valid, options?: RequestOptions): Requesting; @@ -1128,6 +1125,21 @@ export interface Table { /** The available broadcasts under `scope`, as a live stream; see {@link Consumer.announced}. */ announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; +} + +/** + * A non-owning handle on an origin: publish into it and read it, without its lifecycle. + * + * What a shared connection lends out. {@link Producer} implements it, so code that is + * handed an origin rather than owning one should accept this type: closing the origin + * stays the owner's alone, and a borrower cannot express it. A borrower that only reads + * should accept {@link Reader} instead, so `producer.consume()` fits too. + * + * @public + */ +export interface Table extends Reader { + /** Create an unannounced broadcast at `path`; see {@link Producer.createBroadcast}. */ + createBroadcast(path: Path.Valid): Publication; /** Advertise a prefix and serve requests under it; see {@link Producer.requests}. */ requests(prefix: Path.Valid): Requests; @@ -1679,7 +1691,7 @@ export class Requesting { * * @public */ -export class Consumer { +export class Consumer implements Reader { #state: OriginState; #scope: Scope; diff --git a/js/watch/api/element.api.md b/js/watch/api/element.api.md index 3c3ed50a4ec..e3ea8a99964 100644 --- a/js/watch/api/element.api.md +++ b/js/watch/api/element.api.md @@ -16,7 +16,7 @@ import { Video } from "@moq/watch"; export default class extends HTMLElement { constructor(); - attributeChangedCallback(name: "delay" | "buffer" | "follow" | "announced" | "url" | "name" | "volume" | "muted" | "paused" | "visible" | "backend" | "versions" | "catalog-format" | "captions", oldValue: string | null, newValue: string | null): void; + attributeChangedCallback(name: "delay" | "buffer" | "url" | "name" | "follow" | "volume" | "muted" | "paused" | "visible" | "backend" | "versions" | "announced" | "catalog-format" | "captions", oldValue: string | null, newValue: string | null): void; readonly audio: Audio.Decoder; get backend(): Video.Backend; set backend(value: Video.Backend); diff --git a/js/watch/api/index.api.md b/js/watch/api/index.api.md index 16172b792d3..a0f85527470 100644 --- a/js/watch/api/index.api.md +++ b/js/watch/api/index.api.md @@ -107,7 +107,7 @@ export type BroadcastInput = { enabled: Signals.Getter; follow: Signals.Getter; name: Signals.Getter; - origin: Signals.Getter | undefined>; + origin: Signals.Getter; }; export type BroadcastOutput = { @@ -161,7 +161,7 @@ export type PlayerInput = { enabled: Signals.Getter; follow: Signals.Getter; name: Signals.Getter; - origin: BroadcastInput["origin"]; + origin: Signals.Getter; paused: Signals.Getter; probe: Signals.Getter; text: { diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index eba038b74d0..01e64924aae 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -46,7 +46,10 @@ function provesOther(active: Moq.Broadcast.Consumer | undefined, epoch: Moq.Epoc // Whether an announced route covers `path`, until closed. Hidden routes count: a service claim // under a `.`-named prefix is kept out of listings, but it still covers the renditions it would // produce, and this is never shown to anyone. -function watchCovered(origin: Origin, path: Moq.Path.Valid): { covered: Getter; close: () => void } { +function watchCovered( + origin: Moq.Origin.Reader, + path: Moq.Path.Valid, +): { covered: Getter; close: () => void } { const announced = origin.announced(Path.Pattern.literal(path), { hidden: true, covering: true }); const covered = new Signal(false); const active = new Set(); @@ -103,7 +106,7 @@ export type CatalogFormat = (typeof CATALOG_FORMATS)[number]; export type BroadcastInput = { // The read-side origin to borrow. Independent of any connection: whichever sessions feed // the origin resolve the broadcast, and the handle spans their reconnects. - origin: Getter | undefined>; + origin: Getter; // Whether to start downloading the broadcast. Defaults to true. enabled: Getter; @@ -127,8 +130,6 @@ export type BroadcastInput = { catalog: Getter; }; -type Origin = NonNullable>; - /** Signals the component derives. */ export type BroadcastOutput = { // "error" means the origin refused the broadcast; `error` says why. @@ -166,13 +167,13 @@ export class Broadcast { // its relay about the broadcasts a catalog actually references. readonly #watches = new Map< Moq.Path.Valid, - { origin: Origin; covered: Getter; close: () => void; users: number } + { origin: Moq.Origin.Reader; covered: Getter; close: () => void; users: number } >(); // Requests are shared by callers; each owns its restart watch in the origin. readonly #references = new Map< Moq.Path.Valid, - { origin: Origin; follow: boolean; request: Moq.Origin.Requesting; users: number } + { origin: Moq.Origin.Reader; follow: boolean; request: Moq.Origin.Requesting; users: number } >(); // The catalog as published, before renditions this consumer cannot use are dropped. Kept @@ -228,7 +229,7 @@ export class Broadcast { // gets selected: its service claims a covering prefix, and nothing announces the exact path // until this subscribes. Watches exactly `path`, shared by every caller asking about it. // The blind cases (announcement gate off, no discovery) never reach here; see `#relativeTarget`. - #isPathAnnounced(effect: Effect, origin: Origin, path: Moq.Path.Valid): boolean { + #isPathAnnounced(effect: Effect, origin: Moq.Origin.Reader, path: Moq.Path.Valid): boolean { let entry = this.#watches.get(path); if (!entry || entry.origin !== origin) { entry?.close(); @@ -251,7 +252,11 @@ export class Broadcast { } // Share one origin request across callers reading the same referenced broadcast. - #requestBroadcast(effect: Effect, origin: Origin, path: Moq.Path.Valid): Moq.Broadcast.Consumer | undefined { + #requestBroadcast( + effect: Effect, + origin: Moq.Origin.Reader, + path: Moq.Path.Valid, + ): Moq.Broadcast.Consumer | undefined { const follow = effect.get(this.in.follow); let entry = this.#references.get(path); if (!entry || entry.origin !== origin || entry.follow !== follow) { diff --git a/js/watch/src/player.ts b/js/watch/src/player.ts index 245837bba15..ad585ac2edb 100644 --- a/js/watch/src/player.ts +++ b/js/watch/src/player.ts @@ -4,7 +4,7 @@ import type * as Moq from "@moq/net"; import { Path } from "@moq/net"; import { Effect, type Getter, getter, type Inputs, type Readonlys, Signal } from "@moq/signals"; import * as Audio from "./audio"; -import { Broadcast, type BroadcastInput, type CatalogFormat } from "./broadcast"; +import { Broadcast, type CatalogFormat } from "./broadcast"; import { type Delay, Sync } from "./sync"; import * as Text from "./text"; import * as Video from "./video"; @@ -12,7 +12,7 @@ import * as Video from "./video"; /** Inputs for a complete broadcast playback pipeline. */ export type PlayerInput = { /** Read-side origin that supplies the broadcast, borrowed without its lifecycle. */ - origin: BroadcastInput["origin"]; + origin: Getter; /** Broadcast path relative to the origin. */ name: Getter; /** Whether the pipeline may subscribe. */ diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index 69dac2c2d8f..afdec386649 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -75,7 +75,6 @@ Rejected in planning: - [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) - Rust, JS, and the bindings resolve a broadcast with `request(path, epoch)` or `follow(path, epoch)`, and every racy two-step caller is gone - [Routes are the origin API](/quest/m1/api-audit/route/README.md) - apps announce exact or prefix routes through one `Route` handle that owns its broadcast and carries an `identity`, prefix routes can serve a held broadcast, and readers get a listing plus `follow` -- [@moq/net names the origin read side](/quest/m1/api-audit/origin-reader.md) - `Origin.Reader`, which `Origin.Table` extends, replaces `Pick` lists ## Related diff --git a/quest/m1/api-audit/origin-reader.md b/quest/m1/api-audit/origin-reader.md deleted file mode 100644 index bab430313fd..00000000000 --- a/quest/m1/api-audit/origin-reader.md +++ /dev/null @@ -1,20 +0,0 @@ -# [S] @moq/net names the origin read side - -## Goal - -@moq/net exports a named read-side origin interface, `Origin.Reader`, that -`Origin.Table` extends, so readers such as @moq/watch accept that one name -instead of repeating a `Pick` list. - -## Plan - -[moq-dev/moq#7251](https://github.com/moq-dev/moq/pull/7251) makes @moq/watch -accept a structural read-side origin and leaves the named interface as a -follow-up. Name it before the API cut, and move existing `Pick` lists to it. -If #7251 has not merged, `Player` and `Broadcast` still take `Origin.Table`: -widen their origin inputs to `Origin.Reader` here. - -Decided 2026-10-30 (maintainer, /quest-plan of the 2026-10-30 /quest-complete follow-ups): ✅ new m1 api-audit quest / drop. - -Public API: @moq/net adds `Origin.Reader`; @moq/watch's origin inputs accept -it. Both are additive, so nothing migrates. Wire: none.