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
20 changes: 4 additions & 16 deletions dart/moq/lib/src/aliases.dart
Original file line number Diff line number Diff line change
Expand Up @@ -89,9 +89,8 @@ typedef Instance = MoqInstance;
/// A route over a prefix: its origin-relative path, required wildcard captures (empty without wildcards), and route metadata.
typedef Announce = MoqAnnounce;

/// What an [AnnounceConsumer] yields: [AnnounceEventPresent],
/// [AnnounceEventUnavailable], [AnnounceEventAvailable], [AnnounceEventAbsent],
/// or [AnnounceEventOffline].
/// What an [AnnounceConsumer] yields: [AnnounceEventPresent] or
/// [AnnounceEventAbsent].
///
/// Another publisher instance taking a path over keeps it present: hold a
/// [Following] to see the broadcast change.
Expand All @@ -100,21 +99,10 @@ typedef AnnounceEvent = MoqAnnounceEvent;
/// A route now covers the path, which was absent; it may arrive unavailable.
typedef AnnounceEventPresent = PresentMoqAnnounceEvent;

/// The present path lost every usable path to its origin but may recover one:
/// it stays present while requests for it may fail.
typedef AnnounceEventUnavailable = UnavailableMoqAnnounceEvent;

/// The present path recovered a usable path: request it again.
typedef AnnounceEventAvailable = AvailableMoqAnnounceEvent;

/// The origin withdrew the path; carries its last route.
/// No route covers the path any more, whether its origin withdrew it or this
/// side let go of it; carries its last route.
typedef AnnounceEventAbsent = AbsentMoqAnnounceEvent;

/// This side let go of the path, which its origin may still serve: the session
/// it arrived on closed, or the network lost every path to it. Carries its last
/// route.
typedef AnnounceEventOffline = OfflineMoqAnnounceEvent;

/// The write side of a broadcast: publish tracks into it.
typedef BroadcastProducer = MoqBroadcastProducer;

Expand Down
2 changes: 1 addition & 1 deletion dart/moq/lib/src/client.dart
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ final class Moq {
MoqRoute route(String path, {RouteOptions? options}) =>
session.publish().route(path: path, options: options ?? RouteOptions());

/// List the paths matching [options] as each becomes present, absent, or offline, or changes availability;
/// List the paths matching [options] as each becomes present or absent;
/// prefixes stay relative to the origin.
///
/// Listen to `announced(...).updates()` for a [Stream] of [AnnounceEvent]
Expand Down
3 changes: 1 addition & 2 deletions demo/boy/src/element.ts
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,6 @@ export default class MoqBoy extends HTMLElement {
if (!capture?.isLiteral) continue;

const id = capture.text;
const gone = entry.kind === "absent" || entry.kind === "offline";
if (entry.kind === "present" && !this.#sessions.has(id)) {
const config: GameConfig = {
sessionId: id,
Expand All @@ -235,7 +234,7 @@ export default class MoqBoy extends HTMLElement {
const game = new Game(config);
this.#sessions.set(id, game);
this.games.set(new Map(this.#sessions));
} else if (gone) {
} else if (entry.kind === "absent") {
const game = this.#sessions.get(id);
if (game) {
game.close();
Expand Down
3 changes: 1 addition & 2 deletions demo/carla/sim/moq_carla_sim/publish.py
Original file line number Diff line number Diff line change
Expand Up @@ -364,11 +364,10 @@ async def run(self, client: moq.Client, prefix: str) -> None:
async for event in announced:
# Every variant carries `announce`; uniffi's stubs type only the enum.
driver = event.announce.captures[0] # pyright: ignore[reportAttributeAccessIssue]
if isinstance(event, (moq.AnnounceEventAbsent, moq.AnnounceEventOffline)):
if isinstance(event, moq.AnnounceEventAbsent):
task = drivers.pop(driver, None)
if task is not None:
task.cancel()
# Availability changes reach the follow, which waits them out.
elif isinstance(event, moq.AnnounceEventPresent) and driver not in drivers:
drivers[driver] = asyncio.create_task(
self._follow(client, driver, f"{prefix}/{driver}"), name=f"driver:{driver}"
Expand Down
5 changes: 0 additions & 5 deletions demo/carla/sim/tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,6 @@ class AnnounceEventAbsent(AnnounceEvent):
pass


class AnnounceEventOffline(AnnounceEvent):
pass


class SnapshotProducer:
"""Records every published value; demand comes from the wrapped track."""

Expand All @@ -53,7 +49,6 @@ def update(self, value: object, timestamp: object) -> None:
moq.is_shutdown = lambda err: False
moq.AnnounceEventPresent = AnnounceEventPresent
moq.AnnounceEventAbsent = AnnounceEventAbsent
moq.AnnounceEventOffline = AnnounceEventOffline
moq.Timestamp = lambda value, scale: SimpleNamespace(value=value, scale=scale)
moq.TrackInfo = lambda **kwargs: SimpleNamespace(**kwargs)

Expand Down
7 changes: 2 additions & 5 deletions demo/carla/sim/tests/test_publish.py
Original file line number Diff line number Diff line change
Expand Up @@ -228,9 +228,6 @@ async def present(self, driver: str) -> None:
async def absent(self, driver: str) -> None:
await self.send(moq.AnnounceEventAbsent(SimpleNamespace(captures=[driver])))

async def offline(self, driver: str) -> None:
await self.send(moq.AnnounceEventOffline(SimpleNamespace(captures=[driver])))


class Run:
"""One driver run's broadcast: its `control` track hands out what `send` queues."""
Expand Down Expand Up @@ -359,13 +356,13 @@ async def scenario(relay: Relay, drivers, commands: asyncio.Queue, gate: Drive)
asyncio.run(watching(scenario))


def test_a_driver_this_side_lets_go_of_loses_the_lease() -> None:
def test_a_driver_that_returns_is_followed_afresh() -> None:
async def scenario(relay: Relay, drivers, commands: asyncio.Queue, gate: Drive) -> None:
await relay.announcements.present("abc")
await relay.following("abc").run(DRIVE)
await next_command(commands, gate)

await relay.announcements.offline("abc")
await relay.announcements.absent("abc")
assert (await next_command(commands, gate)).kind == "driver_left"
assert gate.driver is None

Expand Down
9 changes: 3 additions & 6 deletions doc/concept/identity.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,12 +139,9 @@ goes offline; JavaScript `origin.follow(path)`, whose `active` is undefined
between instances; the moq-ffi bindings `follow(path)`, whose `available()`
returns null once the path goes offline; and C `moq_origin_follow`, whose
callback reports `MOQ_FOLLOW_EVENT_OFFLINE`.
An announcement listing (`announced()`) reports a path becoming present,
unavailable while the network holds its route without a path to it, available
again once it recovers one, and finally absent once the origin withdraws it or
offline once this side lets go of it, which says nothing of whether the origin
still serves it. An instance change keeps it present, so a reader that needs
one holds a follower. `@moq/watch`, `moq play`, and `moqsrc` follow this way, and
An announcement listing (`announced()`) only reports a path becoming present or
absent, whether the origin withdrew it or this side let go of it: an instance
change keeps it present, so a reader that needs one holds a follower. `@moq/watch`, `moq play`, and `moqsrc` follow this way, and
`moq export ts --stitch` can splice a replacement as a marked program switch. A
request failing is never the signal to restart; the follower handing out a new
broadcast is. Nor is a track's error kind: a track withdrawn
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/go/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ for event, err := range announced.All(ctx) {
// handed each new run, with Available returning nil while the path is offline.
present, ok := event.(moq.AnnounceEventPresent)
if !ok {
continue // absent, offline, or a change in availability
continue // AnnounceEventAbsent
}
ann := present.Announce
// Prefix stays origin-relative; Captures is a list, empty without wildcards.
Expand Down
3 changes: 1 addition & 2 deletions doc/lib/kt/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,7 @@ Moq.connect("https://relay.example.com", ClientConfig(tls = ClientTls(roots = li
// each new run, or null once it goes offline.
val announce = when (event) {
is AnnounceEventPresent -> event.announce
// Absent, offline, or a change in availability.
else -> return@collect
is AnnounceEventAbsent -> return@collect
}
// Prefixes stay origin-relative; captures is a list of wildcard matches, empty without wildcards.
println(announce.captures)
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/py/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ async def main():
# A path stays present across publisher restarts: hold client.follow(path) to
# be handed each new run, or None once it goes offline.
if not isinstance(event, moq.AnnounceEventPresent):
continue # absent, offline, or a change in availability
continue # AnnounceEventAbsent
announcement = event.announce
print(announcement.captures) # list of wildcard matches, empty without wildcards
broadcast = await client.request(announcement.prefix)
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ What you use it for, beyond what the concept page already describes:
- **Routes report what the mesh filled in.** An announcement's `route` gives its `instance()` and `cost()`; an application sets only `RouteOptions`. The hop chain a relay uses for loop detection stays internal. An origin's own Node ID is `origin::Config::node`, 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. `origin.route(path, options)` serves a random instance minted when it is created and kept across `withdraw()` and `announce()`. Unless one is named, a claim moves to a fresh instance each time a job holding its current one ends, and a job takes the claim's. Set one with `RouteOptions::with_instance(instance, epoch)` only for a publisher that continues its timeline across restarts, so its group starts keep rising, and raises the epoch each time. `route.instance()` names it.
- **Rank several CDNs.** Dial each with its own subscribe handle, `origin.clone().with_priority(origin::Priority::new(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. After the earlier route keys, requests use the route with the highest priority, on moq-lite 07 the lowest of any link along its path, 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 as present, then unavailable or available as a held route loses and recovers its path, and finally absent once the origin withdraws one or offline once this side lets go of it, which says nothing of whether the origin still serves it. 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.
- **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 as present, then absent once no route covers one, whether the origin withdrew it or this side let go of it. A path whose captures change is reported absent and then present again while a route still covers it. Read a held route's availability from `announce.route.available()` or a `follow`. 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.
- **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `request`, or `follow`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request` owns discovery of its path, so no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-webrtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything.
- **Relay by opting into proxying.** On moq-lite-07 (`moq-lite-07-wip`, opt-in) a session sends its peer only the routes to its origin's own claims, so an application never becomes transit for anyone else. A relay built on the library marks the handle it publishes with `origin.clone().with_proxy(true)` to carry what it learned from other peers too; `moq-relay` does so for every session. Older versions advertise everything either way.
- **One track per name.** Concurrent subscriptions share one request and producer. A group is keyed by its start, its first frame's timestamp in the track's timescale, and starts only rise. An untimed track has no timescale, so its frames carry `Timestamp::unscaled(key)`, the group's key, and a timestamp's `scale()` is `None`: conversions such as `as_millis()` fail on it, and it compares with no scaled timestamp. Every frame write takes a `Timestamp`, and one that doesn't match its track is refused with `TimestampMismatch`. `append_group(start)` opens the next one at a `Timestamp`, converted into the track's timescale as a frame's is (`Timestamp::unscaled(key)` on an untimed track), declaring the range below it skipped; `create_group` places one without declaring anything. The broadcast keeps nothing of an ended track, and a name always means the same content, so a producer that replaces it starts its groups past its predecessor's. Readers of an aborted track resume onto the replacement when they read through an origin request, whose route always names an instance; otherwise their subscription ends with the error.
Expand Down
2 changes: 0 additions & 2 deletions go/wrapper/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,6 @@ for event, err := range announced.All(ctx) {
fmt.Println("broadcast online", event.Announce.Prefix)
case moq.AnnounceEventAbsent:
fmt.Println("broadcast ended", event.Announce.Prefix)
case moq.AnnounceEventOffline:
fmt.Println("broadcast offline", event.Announce.Prefix)
}
}
```
Expand Down
4 changes: 2 additions & 2 deletions go/wrapper/origin.go
Original file line number Diff line number Diff line change
Expand Up @@ -283,7 +283,7 @@ type AnnounceOptions struct {
}

// Announced lists the paths under a literal prefix matching an optional pattern filter, as each
// becomes present, absent, or offline, or changes availability. To see another publisher instance take a path over, use Follow.
// becomes present or absent. To see another publisher instance take a path over, use Follow.
func (o *OriginConsumer) Announced(options AnnounceOptions) (*AnnounceConsumer, error) {
inner, err := o.inner.Announced(ffi.MoqAnnounceConfig{
Prefix: options.Prefix,
Expand Down Expand Up @@ -322,7 +322,7 @@ func (o *OriginConsumer) Request(ctx context.Context, path string, instance *Ins
return &BroadcastConsumer{inner: inner}, nil
}

// AnnounceConsumer is a listing of paths, each present, absent, or offline.
// AnnounceConsumer is a listing of paths, each present or absent.
type AnnounceConsumer struct {
inner *ffi.MoqAnnounceConsumer
}
Expand Down
14 changes: 3 additions & 11 deletions go/wrapper/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -41,22 +41,14 @@ type (
// resolve a path with [OriginConsumer.Request]. Captures is a required slice,
// empty when the filter has no wildcards.
Announce = ffi.MoqAnnounce
// AnnounceEvent is what an AnnounceConsumer yields: AnnounceEventPresent, AnnounceEventUnavailable,
// AnnounceEventAvailable, AnnounceEventAbsent, or AnnounceEventOffline.
// AnnounceEvent is what an AnnounceConsumer yields: AnnounceEventPresent or AnnounceEventAbsent.
// Another publisher instance taking a path over keeps it present; see it with [OriginConsumer.Follow].
AnnounceEvent = ffi.MoqAnnounceEvent
// AnnounceEventPresent reports a route now covering a path that was absent; it may arrive unavailable.
AnnounceEventPresent = ffi.MoqAnnounceEventPresent
// AnnounceEventUnavailable reports that a present path lost every usable path to its origin but may
// recover one: it stays present while requests for it may fail.
AnnounceEventUnavailable = ffi.MoqAnnounceEventUnavailable
// AnnounceEventAvailable reports that a present path recovered a usable path: request it again.
AnnounceEventAvailable = ffi.MoqAnnounceEventAvailable
// AnnounceEventAbsent reports that the origin withdrew a path, carrying its last route.
// AnnounceEventAbsent reports that no route covers a path any more, whether its origin withdrew it
// or this side let go of it, carrying its last route.
AnnounceEventAbsent = ffi.MoqAnnounceEventAbsent
// AnnounceEventOffline reports that this side let go of a path, carrying its last route: the session
// it arrived on closed, or the network lost every path to it, so its origin may still serve it.
AnnounceEventOffline = ffi.MoqAnnounceEventOffline
// Range is a span of a track to deliver: from Start up to End, or onward when End is nil.
// A relative start is the first frame of its group, a relative end includes its whole
// group, and an absolute end is exclusive.
Expand Down
2 changes: 1 addition & 1 deletion js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ export namespace Announce {
get synced(): Signals.Getter<boolean>;
}
export type Event = {
kind: "present" | "unavailable" | "available" | "absent" | "offline";
kind: "present" | "absent";
} & Announce.Announce;
export interface Options {
covering?: boolean;
Expand Down
15 changes: 4 additions & 11 deletions js/net/src/announced.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -68,14 +68,14 @@ test("a listing shows a route's facts, never its epoch, hops, credential, or dra
expect(Object.keys(event?.route ?? {}).sort()).toEqual(["available", "cost", "instance"]);
});

test("a listing reports availability flips and tells an offline path from an absent one", async () => {
test("a listing stays quiet as availability flips and reports a let-go path absent", async () => {
const producer = new Announce.Producer();
const listing = Announce.list(producer.consume());
const route = WireRoute.normalize({ instance: Instance.random() });
const held = { ...route, available: false };

producer.append({ prefix: p("a"), captures: undefined, kind: "start", route: held });
// A re-price that leaves availability as it was is not reported.
// Neither a re-price nor an availability flip is reported.
producer.append({ prefix: p("a"), captures: undefined, kind: "update", route: { ...held, cost: 3n } });
producer.append({ prefix: p("a"), captures: undefined, kind: "update", route });
producer.append({ prefix: p("a"), captures: undefined, kind: "restart", route: held });
Expand All @@ -84,18 +84,11 @@ test("a listing reports availability flips and tells an offline path from an abs
producer.append({ prefix: p("b"), captures: undefined, kind: "end", route });

const seen = [];
for (let i = 0; i < 6; i++) {
for (let i = 0; i < 4; i++) {
const event = await listing.next();
seen.push(`${event?.kind} ${event?.prefix} ${event?.route.available}`);
}
expect(seen).toEqual([
"present a false",
"available a true",
"unavailable a false",
"offline a false",
"present b true",
"absent b true",
]);
expect(seen).toEqual(["present a false", "absent a false", "present b true", "absent b true"]);
});

test("the consumer is an async iterable of the same events", async () => {
Expand Down
Loading