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
12 changes: 9 additions & 3 deletions js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -388,10 +388,16 @@ export namespace Origin {
announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer;
get closed(): Signals.GetPromise<Error | null>;
get discovery(): Signals.Getter<boolean | undefined>;
follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Following;
request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
}
export type Cost = bigint;
export class Following {
readonly active: Signals.Getter<Broadcast.Consumer | undefined>;
close(): void;
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 Prepared {
Expand All @@ -408,7 +414,7 @@ export namespace Origin {
consume(): Origin.Consumer;
createBroadcast(path: Path.Valid): Origin.Publication;
get discovery(): Signals.Getter<boolean | undefined>;
follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Following;
request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
requests(prefix: Path.Valid): Origin.Requests;
scope(root: Path.Valid, patterns: Path.Patterns): Origin.Producer;
Expand All @@ -429,7 +435,7 @@ export namespace Origin {
announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer;
readonly closed: Signals.GetPromise<Error | null>;
readonly discovery: Signals.Getter<boolean | undefined>;
follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Following;
request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting;
}
export class Request {
Expand Down
2 changes: 1 addition & 1 deletion js/net/examples/discovery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ async function main() {

// Own and close the origin announcement watch.
const announced = origin.announced();
const requests = new Map<Moq.Path.Valid, Moq.Origin.Requesting>();
const requests = new Map<Moq.Path.Valid, Moq.Origin.Following>();

// Discover broadcasts announced by the server
for await (const announcement of announced) {
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 @@ -109,7 +109,7 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi
existing.reporters.set(interest, route);
// Another request covering the prefix only holds it; the first reporter drives it.
if (joined && existing.reporters.keys().next().value === interest) {
follow(existing, prefix, route, event.kind === "restart");
updateReported(existing, prefix, route, event.kind === "restart");
}
};

Expand All @@ -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 follow = (existing: Reported, prefix: Path.Valid, route: Route, restart: boolean) => {
const updateReported = (existing: Reported, prefix: Path.Valid, route: Route, restart: boolean) => {
if (restart || route.epoch !== existing.handle.route.epoch) {
// Inserted before the old one leaves, so local readers see one restart rather than
// an end and a start.
Expand All @@ -145,7 +145,7 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi
} else if (driving) {
// The next request takes over driving. Without an instance nothing proves it reports
// the stream the handle serves, so the route restarts rather than stitch two together.
follow(existing, prefix, next.value, next.value.instance === undefined);
updateReported(existing, prefix, next.value, next.value.instance === undefined);
}
};

Expand Down
6 changes: 3 additions & 3 deletions js/net/src/origin-request.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { StreamCode, StreamError } from "./error";
import { Route } from "./hop";
import * as Instance from "./instance.ts";
import { hooks } from "./internal.ts";
import { Producer, type Publication, type Request } from "./origin";
import { type Following, Producer, type Publication, type Request, type Requesting } from "./origin";
import * as Path from "./path";
import { wireOf } from "./wire";

Expand All @@ -16,7 +16,7 @@ test("a follower moves through restart, end and a later start", async () => {
const firstPublication = origin.createBroadcast(path);
const first = firstPublication.broadcast;
firstPublication.announce();
const request = origin.follow(path);
const request: Following = origin.follow(path);
expect(request.active.peek()?.instance).toBe(firstPublication.route?.instance);
const secondPublication = origin.createBroadcast(path);
const second = secondPublication.broadcast;
Expand Down Expand Up @@ -142,7 +142,7 @@ test("only a request can use a session without discovery", async () => {
const slot = wire.requests.peek()?.get(path);
if (!slot) throw new Error("request did not register");
expect(wire.blind(slot)).toBe(false);
const requested = origin.request(path);
const requested: Requesting = origin.request(path);
expect(wire.blind(slot)).toBe(true);
// The blind answer lands in the shared slot, but only the plain handle takes it.
const source = new BroadcastProducer();
Expand Down
80 changes: 67 additions & 13 deletions js/net/src/origin.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1220,7 +1220,7 @@ export interface Reader {
request(path: Path.Valid, options?: RequestOptions): Requesting;

/** Follow `path` across publisher instances; see {@link Consumer.follow}. */
follow(path: Path.Valid, options?: RequestOptions): Requesting;
follow(path: Path.Valid, options?: RequestOptions): Following;

/** The available broadcasts under `scope`, as a live stream; see {@link Consumer.announced}. */
announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer;
Expand Down Expand Up @@ -1662,7 +1662,7 @@ export class Producer implements Table {
}

/** Follow `path` across publisher instances; see {@link Consumer.follow}. */
follow(path: Path.Valid, options?: RequestOptions): Requesting {
follow(path: Path.Valid, options?: RequestOptions): Following {
return this.#reader.follow(path, options);
}

Expand Down Expand Up @@ -1727,7 +1727,7 @@ export class Producer implements Table {
// that would leak the unexported OriginState. Assigned in the class's static block.
let makeConsumer: (state: OriginState, scope: Scope) => Consumer;

// Same for Requesting: a public constructor would let a caller forge a handle that no origin
// Same for Requesting and Following: a public constructor would let a caller forge a handle that no origin
// ever registered, whose lifecycle guarantees are then false. `@internal` alone would not
// stop it, since the declaration emit keeps the constructor.
let makeRequesting: (
Expand All @@ -1737,6 +1737,13 @@ let makeRequesting: (
dispose: Dispose,
) => Requesting;

let makeFollowing: (
path: Path.Valid,
active: Getter<broadcast.Consumer | undefined>,
closed: Once<Error | null>,
dispose: Dispose,
) => Following;

let makeDynamic: (
prefix: Path.Valid,
entry: RouteEntry,
Expand All @@ -1753,7 +1760,7 @@ let publishPrepared: (request: Request, publication: Publication) => Publication
let rejectPrepared: (request: Request, err: Error) => void;

/**
* An owned request for a broadcast path; see {@link Consumer.request} and {@link Consumer.follow}.
* An owned request for one publisher instance at a broadcast path; see {@link Consumer.request}.
*
* @public
*/
Expand All @@ -1762,19 +1769,16 @@ export class Requesting {
readonly path: Path.Valid;

/**
* The current broadcast, or undefined while nothing provides the path.
* A followed path moves to each publisher instance, pinned to one when requested.
* A request retains its accepted instance. Another route of the same instance taking over keeps
* The accepted broadcast, or undefined while the request is pending.
* Another route of the same instance taking over keeps
* this handle: its tracks resume on that route from the first group each reader lacks.
* Closing this handle affects only this request.
*/
readonly active: Getter<broadcast.Consumer | undefined>;

/**
* Settles on refusal, origin shutdown, or explicit close.
* A request also ends when its accepted instance stops serving, and fails
* `Unroutable` while pending once discovery syncs without a route for it;
* a followed path waits for a later start, even when pinned.
* Settles on refusal, origin shutdown, explicit close, or the accepted instance ending.
* Fails `Unroutable` while pending once discovery syncs without a route for it.
*/
readonly closed: GetPromise<Error | null>;

Expand Down Expand Up @@ -1805,6 +1809,56 @@ export class Requesting {
}
}

/**
* An owned follower of the publisher instances announced at a broadcast path; see {@link Consumer.follow}.
*
* @public
*/
export class Following {
/** The followed path. */
readonly path: Path.Valid;

/**
* The current announced broadcast, or undefined between publisher instances.
* Moves to each new instance, or waits for the pinned instance when one was requested.
* Another route of the same instance keeps this handle and resumes its tracks.
* Closing this handle affects only this follower.
*/
readonly active: Getter<broadcast.Consumer | undefined>;

/**
* Settles on refusal, origin shutdown, or explicit close.
* Waits through gaps in announcements for a later start, even when pinned to an instance.
*/
readonly closed: GetPromise<Error | null>;

#dispose: Dispose;
#disposed = false;

private constructor(
path: Path.Valid,
active: Getter<broadcast.Consumer | undefined>,
closed: GetPromise<Error | null>,
dispose: Dispose,
) {
this.path = path;
this.active = active;
this.closed = closed;
this.#dispose = dispose;
}

static {
makeFollowing = (path, active, closed, dispose) => new Following(path, active, closed, dispose);
}

/** Withdraw the follower. The path stays routed for any other open request. Idempotent. */
close(): void {
if (this.#disposed) return;
this.#disposed = true;
this.#dispose();
}
}

/**
* The read side of an origin: resolve broadcasts by path and watch what is available.
*
Expand Down Expand Up @@ -1900,7 +1954,7 @@ export class Consumer implements Reader {
* its path until closed. Requires discovery: a session without it never serves a follower.
* A selected handler's refusal or the origin closing ends it.
*/
follow(path: Path.Valid, options: RequestOptions = {}): Requesting {
follow(path: Path.Valid, options: RequestOptions = {}): Following {
const instance = options.instance;
const absolute = this.#scope.path(path);
Path.Pattern.literal(path);
Expand Down Expand Up @@ -2004,7 +2058,7 @@ export class Consumer implements Reader {
changed();
}

return makeRequesting(path, active, closed, () => finish(null));
return makeFollowing(path, active, closed, () => finish(null));
}

// One resolution of `path`. A follower's (`announced`) takes only an announced front and
Expand Down
2 changes: 1 addition & 1 deletion js/publish/src/audio/encoder.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -804,7 +804,7 @@ test("audio failure stays local through demand changes and capture format re-arm
}
await feed.drain();
};
let announced: Moq.Origin.Requesting | undefined;
let announced: Moq.Origin.Following | undefined;
try {
await configuring;
await settle();
Expand Down
2 changes: 1 addition & 1 deletion js/publish/src/video/encoder.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1312,7 +1312,7 @@ test("a failed video encoder disables only its rendition and recovers on a fresh
let siblingSubscriber: Moq.Track.Subscriber | undefined;
let catalogSubscriber: Moq.Track.Subscriber | undefined;
let recovered: Moq.Track.Subscriber | undefined;
let announced: Moq.Origin.Requesting | undefined;
let announced: Moq.Origin.Following | undefined;
try {
await encoder.out.catalog.changed();
const net = broadcast.net.peek();
Expand Down
9 changes: 7 additions & 2 deletions js/watch/src/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,12 @@ export class Broadcast {
// Requests are shared by callers; each owns its restart watch in the origin.
readonly #references = new Map<
Moq.Path.Valid,
{ origin: Moq.Origin.Reader; follow: boolean; request: Moq.Origin.Requesting; users: number }
{
origin: Moq.Origin.Reader;
follow: boolean;
request: Moq.Origin.Requesting | Moq.Origin.Following;
users: number;
}
>();

// The catalog as published, before renditions this consumer cannot use are dropped. Kept
Expand Down Expand Up @@ -306,7 +311,7 @@ export class Broadcast {
const name = effect.get(this.in.name);
const follow = effect.get(this.in.follow);

let request: Moq.Origin.Requesting;
let request: Moq.Origin.Requesting | Moq.Origin.Following;
try {
request = follow ? origin.follow(name) : origin.request(name);
} catch (err) {
Expand Down
1 change: 0 additions & 1 deletion quest/m1/api-audit/resolve/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,6 @@ Wire: none.

## Required

- [JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md) - `follow` and `request` get their own JS types, matching Rust and the bindings
- [JS follow takes FollowOptions](/quest/m1/api-audit/resolve/follow-options.md) - `follow` and `request` get their own JS options types

## Related
Expand Down
6 changes: 1 addition & 5 deletions quest/m1/api-audit/resolve/follow-options.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ regenerated.
## Plan

Planned 2026-10-31 (`/quest-plan`, maintainer), a follow-up from
[JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md),
[JS follow returns a Following](https://github.com/moq-dev/moq/pull/7476),
which split the return types but kept one `RequestOptions` for both
methods. Keep the shared fields' names. Drop a field from `FollowOptions`
only if `follow` ignores it today, and say which in the PR. If the two
Expand All @@ -20,7 +20,3 @@ point is that each method's docs describe one behavior.

Public API: breaking for TypeScript type annotations that name
`RequestOptions` for a `follow` call. Wire: none.

## Required

- [JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md) - the `Following` return type this finishes
23 changes: 0 additions & 23 deletions quest/m1/api-audit/resolve/js-following.md

This file was deleted.

2 changes: 1 addition & 1 deletion test/interop/clients/js-native/subscribe.ts
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ async function run(): Promise<void> {
};
printGrant(connection.auth.grant.peek());
const unwatch = connection.auth.grant.subscribe(printGrant);
let requested: Moq.Origin.Requesting | undefined;
let requested: Moq.Origin.Following | undefined;
try {
if (values.finish) {
console.error("finish reader ready");
Expand Down
Loading