moqtail 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/client.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { $ as GoAway, En as Datagram, Fn as Tuple, G as SubscribeTracks, H as RequestError, J as RequestUpdate, K as SubscribeNamespace, Ln as Location, Q as Subscribe, St as MessageParameter, Tn as FetchHeader, U as RequestOk, V as ControlMessage, X as Publish, Y as SubscribeOk, Z as PublishDone, _n as ControlMessageType, _t as Fetch, bn as GroupOrder, cn as SubgroupHeader, dn as FullTrackName, hn as FetchObject, ln as MoqtObject, lt as TrackProperty, n as SetupOptions, nn as PublishBlocked, on as Header, q as TrackStatus, sn as RequestIdMap, tt as FetchOk, un as SubgroupObject, vn as FetchType, vt as Setup, x as StreamResetCode, xn as PublishDoneStatusCode, xt as PublishNamespace, yn as FilterType } from "./index-C8pNnaj0.mjs";
1
+ import { A as ControlMessage, An as GroupOrder, B as Subscribe, Cn as FullTrackName, Dn as FetchObject, En as EndOfRangeKind, F as TrackStatus, Fn as SwitchMode, I as RequestUpdate, L as SubscribeOk, Ln as FetchHeader, M as RequestOk, Mn as PublishDoneStatusCode, N as SubscribeTracks, P as SubscribeNamespace, R as Publish, Rn as Datagram, Rt as LocationFilter, Sn as SubgroupObject, U as FetchOk, Un as ObjectStatus, V as GoAway, Yn as Location, Z as TrackProperty, at as Fetch, bn as SubgroupHeader, j as RequestError, k as StreamResetCode, kn as ControlMessageType, lt as PublishNamespace, mn as PublishSkipped, ot as Setup, qn as Tuple, r as SetupOptions, ut as MessageParameter, vn as Header, xn as MoqtObject, yn as RequestIdMap, z as PublishDone } from "./index-BY6e1obL.mjs";
2
2
  import { t as LogLevel } from "./logger-dEoueCj7.mjs";
3
3
 
4
4
  //#region src/client/control_stream.d.ts
@@ -36,6 +36,74 @@ declare class ControlStream {
36
36
  close(): Promise<void>;
37
37
  }
38
38
  //#endregion
39
+ //#region src/client/data_event.d.ts
40
+ /** `in` for a stream the peer opened, `out` for one this client opened. */
41
+ type DataDirection = 'in' | 'out';
42
+ /** What every data event carries. */
43
+ type DataEventBase = {
44
+ direction: DataDirection; /** Local to this client, unique per data stream; every later event on the stream carries it. */
45
+ streamId: number;
46
+ /**
47
+ * When the client wrote or read it, as `performance.now()` in ms: high resolution and
48
+ * monotonic, so differences between events are exact. Add `performance.timeOrigin` for
49
+ * wall-clock time.
50
+ */
51
+ at: number;
52
+ };
53
+ /** A data stream opened: what its header says. */
54
+ type DataHeaderEvent = DataEventBase & {
55
+ kind: 'header';
56
+ stream: 'subgroup' | 'fetch'; /** Subgroup streams only. */
57
+ trackAlias?: bigint; /** Subgroup streams only. */
58
+ groupId?: bigint; /** Subgroup streams only; unknown here when the header defers it to the first Object ID. */
59
+ subgroupId?: bigint; /** Fetch streams only. */
60
+ requestId?: bigint; /** The track the stream belongs to, when the client knows it at header time. */
61
+ fullTrackName?: FullTrackName;
62
+ };
63
+ /** One object written or read. Only its identity and size are reported, never its payload. */
64
+ type DataObjectEvent = DataEventBase & {
65
+ kind: 'object';
66
+ groupId: bigint;
67
+ subgroupId?: bigint;
68
+ objectId: bigint;
69
+ payloadLength: number; /** Set for an object that carries a status instead of a payload. */
70
+ objectStatus?: ObjectStatus;
71
+ /**
72
+ * The object's LOC Timestamp property, when it carries one: the sender's media time,
73
+ * in whatever unit and clock the sender chose.
74
+ */
75
+ locTimestamp?: bigint;
76
+ };
77
+ /** A data stream ended: `fin` when it closed cleanly, `reset` when either side reset it. */
78
+ type DataStreamEndEvent = DataEventBase & {
79
+ kind: 'end';
80
+ reason: 'fin' | 'reset' | 'error';
81
+ resetCode?: StreamResetCode;
82
+ };
83
+ type DataEvent = DataHeaderEvent | DataObjectEvent | DataStreamEndEvent;
84
+ type DataEventObserver = (event: DataEvent) => void;
85
+ /** What a data stream is handed so it can report itself. */
86
+ type DataStreamObserver = {
87
+ onDataEvent: DataEventObserver; /** Names the track a header belongs to, if known. */
88
+ fullTrackNameOf?: (header: Header) => FullTrackName | undefined;
89
+ };
90
+ /**
91
+ * Turns one data stream's activity into {@link DataEvent}s. A throwing observer is
92
+ * logged and otherwise ignored, so it can never break the stream it watches.
93
+ */
94
+ declare class DataStreamReporter {
95
+ #private;
96
+ private readonly direction;
97
+ private readonly observer?;
98
+ readonly streamId: number;
99
+ constructor(direction: DataDirection, observer?: DataStreamObserver | undefined);
100
+ header(header: Header): void;
101
+ /** `header` is the stream's own: a subgroup object takes its group and subgroup from it. */
102
+ object(header: Header, object: SubgroupObject | FetchObject): void;
103
+ /** Reports how the stream ended. Only the first call counts. */
104
+ end(reason: DataStreamEndEvent['reason'], resetCode?: StreamResetCode): void;
105
+ }
106
+ //#endregion
39
107
  //#region src/client/track/object_cache.d.ts
40
108
  /**
41
109
  * In‑memory index of {@link MoqtObject} instances keyed by their {@link Location} (group/subgroup/object),
@@ -225,175 +293,6 @@ type Track = {
225
293
  trackProperties?: TrackProperty[];
226
294
  };
227
295
  //#endregion
228
- //#region src/client/request_stream.d.ts
229
- /**
230
- * Wraps a WebTransport bidirectional stream carrying one MOQT request.
231
- * Because a response is correlated by the stream it arrives on, nothing here needs a
232
- * request id.
233
- */
234
- declare class RequestStream {
235
- #private;
236
- readonly stream: ReadableStream<ControlMessage>;
237
- /**
238
- * The message this side opened the stream with, kept so the request can be re-issued
239
- * on a fresh stream when the peer migrates it with a GOAWAY (§10.4). Undefined on a
240
- * peer-opened stream, which is the peer's request to re-issue, not ours.
241
- */
242
- first?: ControlMessage;
243
- /**
244
- * The type of the message that opened this stream, whichever side opened it. It is
245
- * what the request on this stream *is*, which decides what may follow — a
246
- * REQUEST_UPDATE is only valid for the types §10.9 lists.
247
- */
248
- openingType?: ControlMessageType;
249
- /** Set when the request this stream carried has been re-issued on a new stream. */
250
- migrated: boolean;
251
- constructor(biStream: WebTransportBidirectionalStream);
252
- /**
253
- * Opens a new bidi stream and writes `first` on it.
254
- *
255
- * @throws :{@link ProtocolViolationError} If `first` is not one of the seven types
256
- * Table 5 marks `First`; those are the only ones allowed to open a request stream.
257
- */
258
- static open(webTransport: WebTransport, first: ControlMessage): Promise<RequestStream>;
259
- /**
260
- * Reads the next control message off this stream, or `undefined` once the peer has
261
- * closed or reset it.
262
- *
263
- * Takes ownership of {@link RequestStream.stream}'s reader on first use, so callers
264
- * must not mix `next()` with `stream.getReader()`.
265
- */
266
- next(): Promise<ControlMessage | undefined>;
267
- send(message: ControlMessage): Promise<void>;
268
- close(): Promise<void>;
269
- /**
270
- * Cancels the request by resetting its stream with `code` (§3.3.2), which is how
271
- * draft-18 cancels a request now that the dedicated cancel messages are gone.
272
- */
273
- reset(code: StreamResetCode): Promise<void>;
274
- }
275
- //#endregion
276
- //#region src/client/publication/subscribe.d.ts
277
- /**
278
- * @public
279
- * Manages the publication of MOQT objects to a subscriber for a specific track.
280
- * Handles live object streaming, subscription lifecycle, and stream management.
281
- */
282
- declare class SubscribePublication {
283
- #private;
284
- private readonly client;
285
- readonly track: Track;
286
- private readonly subscribeMsg;
287
- private readonly requestStream;
288
- /**
289
- * The latest location that was published to the subscriber.
290
- */
291
- latestLocation: Location | undefined;
292
- /**
293
- * Creates a new SubscribePublication instance.
294
- * @param client - The MOQT client managing the subscription.
295
- * @param track - The track being published.
296
- * @param subscribeMsg - The subscribe message containing subscription details.
297
- * @param requestStream - The bidi request stream the SUBSCRIBE arrived on. Every
298
- * message this publication sends back to the subscriber goes on it.
299
- * @param largestLocation - The largest location seen so far, used for determining start location.
300
- */
301
- constructor(client: MOQtailClient, track: Track, subscribeMsg: Subscribe, requestStream: RequestStream, largestLocation?: Location);
302
- /**
303
- * Cancels the publication and cleans up resources.
304
- * Removes the publication from the client's publication map.
305
- */
306
- cancel(): void;
307
- /**
308
- * Marks the publication as done and sends a PublishDone message to the client.
309
- * @param statusCode - The status code indicating why the publication ended.
310
- * @throws :{@link InternalError} If sending the message fails.
311
- */
312
- done(statusCode: PublishDoneStatusCode): Promise<void>;
313
- /**
314
- * Updates the subscription parameters and locations based on a RequestUpdate message.
315
- * @param msg - The update message containing new request details.
316
- */
317
- update(msg: RequestUpdate): void;
318
- /**
319
- * Publishes MOQT objects to the subscriber as they become available.
320
- * Handles stream creation, object writing, and stream closure based on subscription parameters.
321
- * @throws :{@link InternalError} If the track does not support live content.
322
- */
323
- publish(): Promise<void>;
324
- }
325
- //#endregion
326
- //#region src/client/publication/fetch.d.ts
327
- declare class FetchPublication {
328
- #private;
329
- constructor(client: MOQtailClient, track: Track, fetchRequest: Fetch);
330
- cancel(): void;
331
- /**
332
- * Resets the data stream this fetch is being delivered on, which §10.9.1 requires when
333
- * a REQUEST_UPDATE for a FETCH fails.
334
- */
335
- resetDataStream(code: StreamResetCode): Promise<void>;
336
- publish(): Promise<void>;
337
- }
338
- //#endregion
339
- //#region src/client/publication/publish.d.ts
340
- /**
341
- * @public
342
- * Manages the proactive publication of MOQT objects from a publisher to the relay.
343
- * Handles live object streaming and stream management.
344
- */
345
- declare class PublishPublication {
346
- #private;
347
- private readonly client;
348
- readonly track: Track;
349
- private readonly publishMsg;
350
- /**
351
- * The latest location that was published to the relay.
352
- */
353
- latestLocation: Location | undefined;
354
- /**
355
- * Creates a new PublishPublication instance.
356
- * @param client - The MOQT client managing the connection.
357
- * @param track - The track being proactively published.
358
- * @param publishMsg - The publish message that initiated this session.
359
- */
360
- constructor(client: MOQtailClient, track: Track, publishMsg: Publish);
361
- /**
362
- * How many data streams this publication has opened, which is what a PUBLISH_DONE
363
- * reports to the subscriber.
364
- */
365
- get streamsOpened(): bigint;
366
- /**
367
- * Whether Objects are being sent right now. False while the peer holds this
368
- * publication at FORWARD=0.
369
- */
370
- get forwarding(): boolean;
371
- /**
372
- * Moves the Forward State: false parks the publication, true resumes it. The
373
- * application hears about the move through {@link MOQtailClient.onForwardStateChange},
374
- * which is where a publisher starts or stops the work behind the track -- a camera
375
- * and an encoder cost the same whether or not anything is listening.
376
- */
377
- setForwardState(forward: boolean): void;
378
- /**
379
- * Applies a REQUEST_UPDATE the peer sent on this publication's request stream. The
380
- * Forward State is the one thing it can move; what a publisher sends, and when,
381
- * is otherwise its own to decide.
382
- */
383
- update(msg: RequestUpdate): void;
384
- /**
385
- * Cancels the publication and cleans up resources.
386
- * Removes the publication from the client's publication map.
387
- */
388
- cancel(): void;
389
- /**
390
- * Publishes MOQT objects to the relay as they become available.
391
- * Handles stream creation, object writing, and stream closure.
392
- * @throws :{@link InternalError} If the track does not support live content.
393
- */
394
- publishToRelay(): Promise<void>;
395
- }
396
- //#endregion
397
296
  //#region src/client/request/publish_namespace.d.ts
398
297
  declare class PublishNamespaceRequest implements PromiseLike<RequestOk | RequestError> {
399
298
  readonly requestId: bigint;
@@ -418,6 +317,7 @@ declare class FetchRequest implements PromiseLike<FetchOk | RequestError> {
418
317
  private promise;
419
318
  controller?: ReadableStreamDefaultController<MoqtObject>;
420
319
  stream: ReadableStream<MoqtObject>;
320
+ onEndOfRange: EndOfRangeHandler | undefined;
421
321
  isActive: boolean;
422
322
  isResolved: boolean;
423
323
  constructor(message: Fetch);
@@ -428,34 +328,6 @@ declare class FetchRequest implements PromiseLike<FetchOk | RequestError> {
428
328
  finally(onfinally?: (() => void) | undefined | null): Promise<FetchOk | RequestError>;
429
329
  }
430
330
  //#endregion
431
- //#region src/client/request/subscribe.d.ts
432
- declare class SubscribeRequest implements PromiseLike<SubscribeOk | RequestError> {
433
- #private;
434
- requestId: bigint;
435
- fullTrackName: FullTrackName;
436
- isCanceled: boolean;
437
- startLocation: Location | undefined;
438
- endGroup: bigint | undefined;
439
- priority: number;
440
- forward: boolean;
441
- subscribeParameters: MessageParameter[];
442
- earlyDiscardPolicy: EarlyDiscardPolicyConfig | undefined;
443
- largestLocation: Location | undefined;
444
- streamsAccepted: bigint;
445
- expectedStreams: bigint | undefined;
446
- readonly controller: ReadableStreamDefaultController<MoqtObject>;
447
- readonly stream: ReadableStream<MoqtObject>;
448
- constructor(msg: Subscribe);
449
- update(msg: RequestUpdate): void;
450
- switch(newTrackName: FullTrackName, newParameters: MessageParameter[]): void;
451
- unsubscribe(): void;
452
- resolve(value: SubscribeOk | RequestError | PromiseLike<SubscribeOk | RequestError>): void;
453
- reject(reason?: any): void;
454
- then<TResult1 = SubscribeOk | RequestError, TResult2 = never>(onfulfilled?: ((value: SubscribeOk | RequestError) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
455
- catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<SubscribeOk | RequestError | TResult>;
456
- finally(onfinally?: (() => void) | undefined | null): Promise<SubscribeOk | RequestError>;
457
- }
458
- //#endregion
459
331
  //#region src/client/request/subscribe_namespace.d.ts
460
332
  declare class SubscribeNamespaceRequest implements PromiseLike<RequestOk | RequestError> {
461
333
  readonly requestId: bigint;
@@ -533,6 +405,39 @@ declare class TrackStatusRequest implements PromiseLike<RequestOk | RequestError
533
405
  * ```
534
406
  */
535
407
  type MOQtailRequest = PublishRequest | PublishNamespaceRequest | SubscribeNamespaceRequest | FetchRequest | SubscribeRequest | TrackStatusRequest;
408
+ /**
409
+ * Whatever holds a track alias in the client's routing table: a {@link SubscribeRequest},
410
+ * or the receiver {@link MOQtailClient.acceptPushedTrack} stands up for a track the peer
411
+ * pushes. Incoming objects are named after the holder of the alias their stream carries.
412
+ */
413
+ type TrackAliasHolder = {
414
+ requestId: bigint;
415
+ fullTrackName: FullTrackName;
416
+ };
417
+ /**
418
+ * Default for {@link MOQtailClientOptions.trackAliasResolutionTimeoutMs}: how long a
419
+ * data stream waits for the control message that establishes its track alias.
420
+ *
421
+ * A subscription's data streams and the SUBSCRIBE_OK naming their alias travel on
422
+ * separate streams, so nothing orders them; the data can arrive first. Waiting costs
423
+ * a stalled reader, giving up costs the whole subgroup, so the wait is generous.
424
+ */
425
+ declare const DEFAULT_TRACK_ALIAS_RESOLUTION_TIMEOUT_MS = 2000;
426
+ /**
427
+ * Default for {@link MOQtailClientOptions.switchDrainTimeoutMs}: how long a track a
428
+ * soft switch handed over from may stay quiet before it is retired anyway.
429
+ *
430
+ * A soft switch leaves that track delivering up to the group the new one starts at,
431
+ * so the two meet without a hole, and a PUBLISH_DONE normally ends it. This is the
432
+ * backstop for a publisher that never sends one.
433
+ */
434
+ declare const DEFAULT_SWITCH_DRAIN_TIMEOUT_MS = 2000;
435
+ /**
436
+ * @public
437
+ * The MAX_FILTER_RANGES a client advertises when its setup options set none: how
438
+ * many Range Filter ranges it applies, in total, for one subscription or fetch.
439
+ */
440
+ declare const DEFAULT_MAX_FILTER_RANGES = 32n;
536
441
  /**
537
442
  * Options for {@link MOQtailClient.new} controlling connection target, protocol negotiation, timeouts,
538
443
  * and lifecycle callbacks.
@@ -567,73 +472,100 @@ type MOQtailClientOptions = {
567
472
  protocols?: string[];
568
473
  }; /** Per *data* uni-stream idle timeout in milliseconds. */
569
474
  dataStreamTimeoutMs?: number; /** Control stream read timeout in milliseconds. */
570
- controlStreamTimeoutMs?: number; /** If true, enables datagram support for the session. */
475
+ controlStreamTimeoutMs?: number;
476
+ /**
477
+ * How long a data stream waits for the control message that establishes its track
478
+ * alias before the stream is abandoned, in milliseconds. Defaults to
479
+ * {@link DEFAULT_TRACK_ALIAS_RESOLUTION_TIMEOUT_MS}.
480
+ */
481
+ trackAliasResolutionTimeoutMs?: number;
482
+ /**
483
+ * How long a track a soft switch handed over from may stay quiet before it is
484
+ * retired anyway, in milliseconds. Defaults to
485
+ * {@link DEFAULT_SWITCH_DRAIN_TIMEOUT_MS}.
486
+ */
487
+ switchDrainTimeoutMs?: number; /** If true, enables datagram support for the session. */
571
488
  enableDatagrams?: boolean; /** callbacks for observability and logging purposes: */
572
489
  callbacks?: {
573
490
  /** Called after a control message is successfully written to the {@link ControlStream}. */onMessageSent?: (msg: ControlMessage) => void; /** Called for each incoming control message before protocol handling. */
574
491
  onMessageReceived?: (msg: ControlMessage) => void; /** Fired once when the session ends (normal or error). Receives the reason passed to {@link MOQtailClient.disconnect | disconnect}. */
575
492
  onSessionTerminated?: (reason?: unknown) => void; /** Invoked for each decoded datagram object/status arriving. */
576
493
  onDatagramReceived?: (data: Datagram) => void; /** Invoked after enqueuing each outbound datagram object/status. */
577
- onDatagramSent?: (data: Datagram) => void;
494
+ onDatagramSent?: (data: Datagram) => void; /** Invoked for each data stream's header, each of its objects, and its end. See {@link MOQtailClient.onDataEvent}. */
495
+ onDataEvent?: DataEventObserver;
578
496
  };
579
497
  };
580
498
  /**
581
499
  * Parameters for {@link MOQtailClient.subscribe | subscribing} to a track's live objects.
582
500
  *
583
- * @example Latest object
501
+ * @example From the next object
584
502
  * ```ts
585
503
  * await client.subscribe({
586
504
  * fullTrackName,
587
505
  * priority: 0,
588
506
  * groupOrder: GroupOrder.Original,
589
507
  * forward: true,
590
- * filterType: FilterType.LatestObject
508
+ * locationFilter: new LocationFilter(LocationFilterType.NextObject)
591
509
  * })
592
510
  * ```
593
- * @example Absolute range
511
+ * @example Groups 100 through 120
594
512
  * ```ts
595
513
  * await client.subscribe({
596
514
  * fullTrackName,
597
515
  * priority: 32,
598
516
  * groupOrder: GroupOrder.Original,
599
517
  * forward: true,
600
- * filterType: FilterType.AbsoluteRange,
601
- * startLocation: { group: 100n, subgroup: 0n, object: 0n },
602
- * endGroup: 120n
518
+ * locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 100n, 0n, 120n)
603
519
  * })
604
520
  * ```
521
+ * @example From the next object, filling the current group from its start
522
+ * ```ts
523
+ * await client.subscribe({
524
+ * fullTrackName,
525
+ * priority: 0,
526
+ * groupOrder: GroupOrder.Original,
527
+ * locationFilter: new LocationFilter(LocationFilterType.NextObject),
528
+ * parameters: [new FillParameters([new LocationFilter(LocationFilterType.RelativeStart, 1n)])]
529
+ * })
530
+ * ```
531
+ */
532
+ /**
533
+ * Called for an End of Range marker on a fetch stream: every Location after the
534
+ * previous Object, if any, up to and including `location`, does not exist, is unknown,
535
+ * or timed out, as `kind` says. Without it, an unknown or timed-out range looks the
536
+ * same as one that does not exist.
605
537
  */
538
+ type EndOfRangeHandler = (kind: EndOfRangeKind, location: Location) => void;
606
539
  type SubscribeOptions = {
607
540
  /** Fully qualified track identifier ({@link FullTrackName}). */fullTrackName: FullTrackName; /** Subscriber priority (0 = highest, 255 = lowest). Values outside range are clamped. Fractional values are rounded. */
608
541
  priority: number; /** Desired {@link (GroupOrder:enum)} (e.g. {@link (GroupOrder:enum).Original}) specifying delivery ordering semantics. */
609
- groupOrder: GroupOrder; /** If true, deliver objects forward (ascending); if false, reverse/backward semantics (implementation dependent). */
610
- forward: boolean; /** {@link FilterType} variant controlling starting subset (e.g. {@link FilterType.LatestObject}). */
611
- filterType: FilterType; /** Optional extension parameters appended to the SUBSCRIBE control message. */
612
- parameters?: MessageParameter[]; /** Required for {@link FilterType.AbsoluteStart} / {@link FilterType.AbsoluteRange}; earliest {@link Location} to include. */
613
- startLocation?: Location; /** Required for {@link FilterType.AbsoluteRange}; exclusive upper group boundary (coerced to bigint if number provided). */
614
- endGroup?: bigint | number; /** Per-subscription early discard policy. Overrides the client-level default set via {@link MOQtailClient.setEarlyDiscardPolicy}. */
615
- earlyDiscardPolicy?: EarlyDiscardPolicyConfig;
542
+ groupOrder: GroupOrder; /** If present, forward parameter (0x10) is sent with the provided value */
543
+ forward?: boolean; /** The {@link LocationFilter} selecting which Objects to deliver. Omitted, the subscription is unfiltered. */
544
+ locationFilter?: LocationFilter;
545
+ /**
546
+ * Optional extension parameters appended to the SUBSCRIBE control message. A
547
+ * FILL_PARAMETERS here also retrieves already-published Objects on a fill fetch stream.
548
+ */
549
+ parameters?: MessageParameter[]; /** Per-subscription early discard policy. Overrides the client-level default set via {@link MOQtailClient.setEarlyDiscardPolicy}. */
550
+ earlyDiscardPolicy?: EarlyDiscardPolicyConfig; /** Called for each End of Range marker on the subscription's fill fetch streams. */
551
+ onEndOfRange?: EndOfRangeHandler;
616
552
  };
617
553
  /**
618
- * Narrowing update constraints applied to an existing SUBSCRIBE via {@link MOQtailClient.subscribeUpdate}.
619
- *
620
- * Rules: start can only move forward (increase) and endGroup can only move backward (decrease) narrowing the window.
554
+ * Changes applied to an existing SUBSCRIBE via {@link MOQtailClient.subscribeUpdate}.
621
555
  *
622
- * @example Narrowing a live window
556
+ * @example Narrowing a live window to groups 200 through 210
623
557
  * ```ts
624
558
  * await client.subscribeUpdate({
625
- * requestId,
626
- * startLocation: { group: 200n, subgroup: 0n, object: 0n },
627
- * endGroup: 210n,
559
+ * subscriptionRequestId,
560
+ * locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 200n, 0n, 210n),
628
561
  * priority: 16,
629
562
  * forward: true
630
563
  * })
631
564
  * ```
632
565
  */
633
566
  type SubscribeUpdateOptions = {
634
- /** The original SUBSCRIBE request id (bigint) being updated. */subscriptionRequestId: bigint; /** New narrowed {@link Location} start. */
635
- startLocation: Location; /** New narrowed end group (inclusive / protocol defined) must be \> start group. */
636
- endGroup: bigint; /** Updated subscriber priority (same constraints as initial subscribe). 0 is highest, 255 is lowest. */
567
+ /** The original SUBSCRIBE request id (bigint) being updated. */subscriptionRequestId: bigint; /** The new {@link LocationFilter}. Omitted, the subscription keeps its own. */
568
+ locationFilter?: LocationFilter; /** Updated subscriber priority (same constraints as initial subscribe). 0 is highest, 255 is lowest. */
637
569
  priority: number; /** Updated direction flag. */
638
570
  forward: boolean; /** Optional additional parameters; existing parameters persist if omitted. */
639
571
  parameters?: MessageParameter[];
@@ -641,89 +573,353 @@ type SubscribeUpdateOptions = {
641
573
  /**
642
574
  * Parameters for {@link MOQtailClient.switch | switching} an existing SUBSCRIBE to a new track.
643
575
  *
644
- * @example Switching subscription to a new track
576
+ * @example Switching a subscription to a new track
645
577
  * ```ts
646
578
  * await client.switch({
647
- * fullTrackName: newFullTrackName,
648
- * subscriptionRequestId
579
+ * switchFromRequestId,
580
+ * switchMode: SwitchMode.Soft,
581
+ * newSubscribeOptions: {
582
+ * fullTrackName: newFullTrackName,
583
+ * priority: 0,
584
+ * groupOrder: GroupOrder.Original,
585
+ * forward: true,
586
+ * locationFilter: new LocationFilter(LocationFilterType.NextObject)
587
+ * }
649
588
  * })
650
589
  * ```
651
590
  */
652
591
  type SwitchOptions = {
653
- /** Fully qualified track identifier to switch to ({@link FullTrackName}). */fullTrackName: FullTrackName; /** The original SUBSCRIBE request id (bigint) being updated. */
654
- subscriptionRequestId: bigint; /** Optional additional parameters; existing parameters persist if omitted. */
655
- parameters?: MessageParameter[];
592
+ /** The original SUBSCRIBE request id (bigint) being switched from. */switchFromRequestId: bigint; /** {@link SwitchMode} controlling how the switch is applied. */
593
+ switchMode: SwitchMode; /** New subscription options to switch to. */
594
+ newSubscribeOptions: SubscribeOptions; /** Callback to determine whether to continue draining the superseded subscription. Returning true will reset the relevant stream. */
595
+ onDrainDecision?: (request: SubscribeRequest) => boolean;
656
596
  };
657
597
  /**
658
- * Options for {@link MOQtailClient.fetch | performing a FETCH} operation for historical or relative object ranges.
598
+ * Configuration for the early discard policy applied to incoming subgroup streams.
599
+ */
600
+ type EarlyDiscardPolicyConfig = {
601
+ /** Cancel a subgroup QUIC stream if it has not fully completed within this many milliseconds. */subgroupReceiveTimeout: number;
602
+ };
603
+ /**
604
+ * Options for {@link MOQtailClient.fetch | performing a FETCH} of Objects already published.
659
605
  *
660
- * @example Standalone fetch
606
+ * @example Groups 10 through 12, inclusive
661
607
  * ```ts
662
608
  * const { requestId, stream } = await client.fetch({
609
+ * fullTrackName,
663
610
  * priority: 64,
664
611
  * groupOrder: GroupOrder.Original,
665
- * typeAndProps: {
666
- * type: FetchType.Standalone,
667
- * props: { fullTrackName, startLocation, endLocation }
668
- * }
612
+ * locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 10n, 0n, 12n)
669
613
  * })
670
614
  * ```
671
- * @example Relative fetch joining a subscription
615
+ * @example The current group and the one before it
672
616
  * ```ts
673
- * const { requestId: subId } = await client.subscribe({
617
+ * await client.fetch({
674
618
  * fullTrackName,
675
- * priority: 0,
676
- * groupOrder: GroupOrder.Original,
677
- * forward: true,
678
- * filterType: FilterType.LatestObject
679
- * })
680
- * const fetchRes = await client.fetch({
681
619
  * priority: 32,
682
620
  * groupOrder: GroupOrder.Original,
683
- * typeAndProps: {
684
- * type: FetchType.Relative,
685
- * props: { joiningRequestId: subId, joiningStart: 0n }
686
- * }
621
+ * locationFilter: new LocationFilter(LocationFilterType.RelativeStart, 2n)
687
622
  * })
688
623
  * ```
689
624
  */
690
- /**
691
- * Configuration for the early discard policy applied to incoming subgroup streams.
692
- */
693
- type EarlyDiscardPolicyConfig = {
694
- /** Cancel a subgroup QUIC stream if it has not fully completed within this many milliseconds. */subgroupReceiveTimeout: number;
695
- };
696
625
  type FetchOptions = {
697
626
  /** Request priority (0 = highest, 255 = lowest). Rounded & clamped. */priority: number; /** {@link (GroupOrder:enum)} governing sequencing. */
698
- groupOrder: GroupOrder;
699
- /**
700
- * Discriminated union selecting the {@link (FetchType:enum)} mode and its specific properties:
701
- * - Standalone: full explicit range on a {@link FullTrackName} with start/end {@link Location}s.
702
- * - Relative / Absolute: join an existing {@link SubscribeRequest} (identified by `joiningRequestId`) with starting position `joiningStart`.
703
- */
704
- typeAndProps: {
705
- /** Standalone historical/segment fetch for a specific {@link FullTrackName}. */type: FetchType.Standalone; /** Properties for standalone fetch: explicit track and range. */
706
- props: {
707
- fullTrackName: FullTrackName;
708
- startLocation: Location;
709
- endLocation: Location;
710
- };
711
- } | {
712
- /** Fetch a range relative to an existing {@link SubscribeRequest} identified by `joiningRequestId`. */type: FetchType.Relative; /** Properties for relative fetch: subscription id and starting position. */
713
- props: {
714
- joiningRequestId: bigint;
715
- joiningStart: bigint;
716
- };
717
- } | {
718
- /** Fetch an absolute group/object range relative to a {@link SubscribeRequest}. */type: FetchType.Absolute; /** Properties for absolute fetch: subscription id and starting position. */
719
- props: {
720
- joiningRequestId: bigint;
721
- joiningStart: bigint;
722
- };
723
- }; /** Optional parameters block. */
724
- parameters?: MessageParameter[];
627
+ groupOrder: GroupOrder; /** Fully qualified track identifier ({@link FullTrackName}). */
628
+ fullTrackName: FullTrackName;
629
+ /**
630
+ * Which Objects to fetch; the end, when the filter has one, is the last Object
631
+ * sent. Without a filter the whole track up to the Largest Object is fetched, and
632
+ * a filter without an end also stops at the Largest Object.
633
+ */
634
+ locationFilter?: LocationFilter; /** Optional parameters block. */
635
+ parameters?: MessageParameter[]; /** Called for each End of Range marker in the response. */
636
+ onEndOfRange?: EndOfRangeHandler;
725
637
  };
726
638
  //#endregion
639
+ //#region src/client/request/subscribe.d.ts
640
+ /**
641
+ * Represents an active subscription request in MOQT, implementing `PromiseLike`
642
+ * for convenient async resolution when subscription setup succeeds or fails.
643
+ */
644
+ declare class SubscribeRequest implements PromiseLike<SubscribeOk | RequestError> {
645
+ #private;
646
+ requestId: bigint;
647
+ fullTrackName: FullTrackName;
648
+ isCanceled: boolean;
649
+ startLocation: Location | undefined;
650
+ endGroup: bigint | undefined;
651
+ priority: number;
652
+ forward: boolean;
653
+ subscribeParameters: MessageParameter[];
654
+ earlyDiscardPolicy: EarlyDiscardPolicyConfig | undefined;
655
+ onEndOfRange: EndOfRangeHandler | undefined;
656
+ largestLocation: Location | undefined;
657
+ /**
658
+ * The publisher's Largest Object as of the last SUBSCRIBE_OK or REQUEST_UPDATE_OK,
659
+ * which is where a fill fetch stream stops.
660
+ */
661
+ fillBoundary: Location | undefined;
662
+ /** EXPIRES from the last SUBSCRIBE_OK or REQUEST_UPDATE_OK, in milliseconds. */
663
+ expires: bigint | undefined;
664
+ streamsAccepted: bigint;
665
+ expectedStreams: bigint | undefined;
666
+ /** The Subscription managing this request's output stream once switching is involved. */
667
+ manager?: Subscription;
668
+ readonly controller: ReadableStreamDefaultController<MoqtObject>;
669
+ readonly stream: ReadableStream<MoqtObject>;
670
+ constructor(msg: Subscribe);
671
+ /**
672
+ * Updates subscription parameters in-place when a `RequestUpdate` message is received.
673
+ */
674
+ update(msg: RequestUpdate): void;
675
+ /**
676
+ * Marks this subscription request as canceled.
677
+ */
678
+ unsubscribe(): void;
679
+ /**
680
+ * Resolves the internal promise with a `SubscribeOk` or `RequestError`.
681
+ */
682
+ resolve(value: SubscribeOk | RequestError | PromiseLike<SubscribeOk | RequestError>): void;
683
+ /**
684
+ * Rejects the internal promise with an error/reason.
685
+ */
686
+ reject(reason?: any): void;
687
+ then<TResult1 = SubscribeOk | RequestError, TResult2 = never>(onfulfilled?: ((value: SubscribeOk | RequestError) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
688
+ catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<SubscribeOk | RequestError | TResult>;
689
+ finally(onfinally?: (() => void) | undefined | null): Promise<SubscribeOk | RequestError>;
690
+ }
691
+ /**
692
+ * Owns the single consumer-facing stream for a SUBSCRIBE that may be switched to a
693
+ * new track one or more times. A soft switch can keep producing from the old track
694
+ * for an unknown time after SUBSCRIBE_OK, and a second switch may be issued before the
695
+ * first target ever delivers anything, so only the first object actually delivered by
696
+ * the newest tracked request is the guarantee that nothing older will send again.
697
+ *
698
+ * That first delivery is the handover, not the end of the old track: a soft switch
699
+ * leaves it delivering up to the group the new one starts at, so the two meet without
700
+ * a hole. Those objects keep coming through here until the publisher says the
701
+ * subscription is done, or until it has been quiet long enough to say so itself.
702
+ */
703
+ declare class Subscription {
704
+ #private;
705
+ readonly controller: ReadableStreamDefaultController<MoqtObject>;
706
+ readonly stream: ReadableStream<MoqtObject>;
707
+ /** Set once by `MOQtailClient.switch`; invoked with everything older on cutover. */
708
+ onSuperseded?: (superseded: SubscribeRequest[]) => void;
709
+ /** Set by the client to decide whether draining a request should continue. */
710
+ onDrainDecision: (request: SubscribeRequest) => boolean;
711
+ /**
712
+ * How long a drained request may stay quiet before it is retired anyway, in
713
+ * milliseconds. The publisher normally ends the drain with a PUBLISH_DONE; this is
714
+ * what keeps a request that never gets one from being tracked forever.
715
+ */
716
+ drainTimeoutMs: number;
717
+ constructor(initial: SubscribeRequest);
718
+ /** Requests still tracked, oldest first, draining ones last. */
719
+ get requests(): readonly SubscribeRequest[];
720
+ /** The request most recently switched to; must deliver data to win the handover. */
721
+ get newest(): SubscribeRequest;
722
+ /**
723
+ * Track a newly issued switch target alongside whatever is still delivering.
724
+ *
725
+ * `drainSuperseded` says what its handover does to the requests it takes over from:
726
+ * a soft switch leaves them delivering to the end of what the publisher was told to
727
+ * finish, a hard one retires them on the spot.
728
+ */
729
+ addSwitchTarget(request: SubscribeRequest, drainSuperseded?: boolean): void;
730
+ /** Stop tracking `request` (e.g. it naturally completed without ever losing/winning a handover). */
731
+ drop(request: SubscribeRequest): void;
732
+ /** Stop tracking everything (used when the whole switch chain is torn down at once). */
733
+ clear(): void;
734
+ /**
735
+ * Delivers an object received for `request`. The first object delivered by the
736
+ * newest tracked request retires everything older — only then is it guaranteed no
737
+ * more data is coming from them.
738
+ *
739
+ * Returns `true` if the object was delivered to the caller,
740
+ * `false` if it was not consumed, and client should cancel the stream.
741
+ */
742
+ deliver(request: SubscribeRequest, obj: MoqtObject): boolean;
743
+ }
744
+ //#endregion
745
+ //#region src/client/request_stream.d.ts
746
+ /** Observers for the messages a request stream carries, for logging or debugging. */
747
+ type RequestStreamHooks = {
748
+ onMessageSent?: (msg: ControlMessage) => void;
749
+ onMessageReceived?: (msg: ControlMessage) => void;
750
+ };
751
+ /**
752
+ * Wraps a WebTransport bidirectional stream carrying one MOQT request.
753
+ * Because a response is correlated by the stream it arrives on, nothing here needs a
754
+ * request id.
755
+ */
756
+ declare class RequestStream {
757
+ #private;
758
+ readonly stream: ReadableStream<ControlMessage>;
759
+ /**
760
+ * The message this side opened the stream with, kept so the request can be re-issued
761
+ * on a fresh stream when the peer migrates it with a GOAWAY (§10.4). Undefined on a
762
+ * peer-opened stream, which is the peer's request to re-issue, not ours.
763
+ */
764
+ first?: ControlMessage;
765
+ /**
766
+ * The type of the message that opened this stream, whichever side opened it. It is
767
+ * what the request on this stream *is*, which decides what may follow — a
768
+ * REQUEST_UPDATE is only valid for the types §10.9 lists.
769
+ */
770
+ openingType?: ControlMessageType;
771
+ /** Set when the request this stream carried has been re-issued on a new stream. */
772
+ migrated: boolean;
773
+ constructor(biStream: WebTransportBidirectionalStream, hooks?: RequestStreamHooks);
774
+ /**
775
+ * Opens a new bidi stream and writes `first` on it.
776
+ *
777
+ * @throws :{@link ProtocolViolationError} If `first` is not one of the seven types
778
+ * Table 5 marks `First`; those are the only ones allowed to open a request stream.
779
+ */
780
+ static open(webTransport: WebTransport, first: ControlMessage, hooks?: RequestStreamHooks): Promise<RequestStream>;
781
+ /**
782
+ * Reads the next control message off this stream, or `undefined` once the peer has
783
+ * closed or reset it.
784
+ *
785
+ * Takes ownership of {@link RequestStream.stream}'s reader on first use, so callers
786
+ * must not mix `next()` with `stream.getReader()`.
787
+ */
788
+ next(): Promise<ControlMessage | undefined>;
789
+ send(message: ControlMessage): Promise<void>;
790
+ close(): Promise<void>;
791
+ /**
792
+ * Cancels the request by resetting its stream with `code`.
793
+ */
794
+ reset(code: StreamResetCode): Promise<void>;
795
+ }
796
+ //#endregion
797
+ //#region src/client/publication/subscribe.d.ts
798
+ /**
799
+ * @public
800
+ * Manages the publication of MOQT objects to a subscriber for a specific track.
801
+ * Handles live object streaming, subscription lifecycle, and stream management.
802
+ */
803
+ declare class SubscribePublication {
804
+ #private;
805
+ private readonly client;
806
+ readonly track: Track;
807
+ private readonly subscribeMsg;
808
+ private readonly requestStream;
809
+ /**
810
+ * The latest location that was published to the subscriber.
811
+ */
812
+ latestLocation: Location | undefined;
813
+ /**
814
+ * Creates a new SubscribePublication instance.
815
+ * @param client - The MOQT client managing the subscription.
816
+ * @param track - The track being published.
817
+ * @param subscribeMsg - The subscribe message containing subscription details.
818
+ * @param requestStream - The bidi request stream the SUBSCRIBE arrived on. Every
819
+ * message this publication sends back to the subscriber goes on it.
820
+ * @param largestLocation - The largest location seen so far, used for determining start location.
821
+ */
822
+ constructor(client: MOQtailClient, track: Track, subscribeMsg: Subscribe, requestStream: RequestStream, largestLocation?: Location);
823
+ /**
824
+ * Cancels the publication and cleans up resources.
825
+ * Removes the publication from the client's publication map.
826
+ */
827
+ cancel(): void;
828
+ /**
829
+ * Marks the publication as done and sends a PublishDone message to the client.
830
+ * @param statusCode - The status code indicating why the publication ended.
831
+ * @throws :{@link InternalError} If sending the message fails.
832
+ */
833
+ done(statusCode: PublishDoneStatusCode): Promise<void>;
834
+ /**
835
+ * Updates the subscription parameters and locations based on a RequestUpdate message.
836
+ * @param msg - The update message containing new request details.
837
+ * @throws :{@link InvalidFilterError} If the Range Filters the subscription would be
838
+ * left with cannot be applied; nothing is updated.
839
+ */
840
+ update(msg: RequestUpdate): void;
841
+ /**
842
+ * Publishes MOQT objects to the subscriber as they become available.
843
+ * Handles stream creation, object writing, and stream closure based on subscription parameters.
844
+ * @throws :{@link InternalError} If the track does not support live content.
845
+ */
846
+ publish(): Promise<void>;
847
+ }
848
+ //#endregion
849
+ //#region src/client/publication/fetch.d.ts
850
+ declare class FetchPublication {
851
+ #private;
852
+ /** `start` and `end` are the FETCH's range resolved against the Largest Object, inclusive. */
853
+ constructor(client: MOQtailClient, track: Track, fetchRequest: Fetch, start: Location, end: Location);
854
+ cancel(): void;
855
+ /**
856
+ * Resets the data stream this fetch is being delivered on, which §10.9.1 requires when
857
+ * a REQUEST_UPDATE for a FETCH fails.
858
+ */
859
+ resetDataStream(code: StreamResetCode): Promise<void>;
860
+ publish(): Promise<void>;
861
+ }
862
+ //#endregion
863
+ //#region src/client/publication/publish.d.ts
864
+ /**
865
+ * @public
866
+ * Manages the proactive publication of MOQT objects from a publisher to the relay.
867
+ * Handles live object streaming and stream management.
868
+ */
869
+ declare class PublishPublication {
870
+ #private;
871
+ private readonly client;
872
+ readonly track: Track;
873
+ private readonly publishMsg;
874
+ /**
875
+ * The latest location that was published to the relay.
876
+ */
877
+ latestLocation: Location | undefined;
878
+ /**
879
+ * Creates a new PublishPublication instance.
880
+ * @param client - The MOQT client managing the connection.
881
+ * @param track - The track being proactively published.
882
+ * @param publishMsg - The publish message that initiated this session.
883
+ */
884
+ constructor(client: MOQtailClient, track: Track, publishMsg: Publish);
885
+ /**
886
+ * How many data streams this publication has opened, which is what a PUBLISH_DONE
887
+ * reports to the subscriber.
888
+ */
889
+ get streamsOpened(): bigint;
890
+ /**
891
+ * Whether Objects are being sent right now. False while the peer holds this
892
+ * publication at FORWARD=0.
893
+ */
894
+ get forwarding(): boolean;
895
+ /**
896
+ * Moves the Forward State: false parks the publication, true resumes it. The
897
+ * application hears about the move through {@link MOQtailClient.onForwardStateChange},
898
+ * which is where a publisher starts or stops the work behind the track -- a camera
899
+ * and an encoder cost the same whether or not anything is listening.
900
+ */
901
+ setForwardState(forward: boolean): void;
902
+ /**
903
+ * Applies a REQUEST_UPDATE the peer sent on this publication's request stream. It
904
+ * can move the Forward State and the Range Filters; what a publisher sends, and
905
+ * when, is otherwise its own to decide.
906
+ * @throws :{@link InvalidFilterError} If the Range Filters the publication would be
907
+ * left with cannot be applied; nothing is updated.
908
+ */
909
+ update(msg: RequestUpdate): void;
910
+ /**
911
+ * Cancels the publication and cleans up resources.
912
+ * Removes the publication from the client's publication map.
913
+ */
914
+ cancel(): void;
915
+ /**
916
+ * Publishes MOQT objects to the relay as they become available.
917
+ * Handles stream creation, object writing, and stream closure.
918
+ * @throws :{@link InternalError} If the track does not support live content.
919
+ */
920
+ publishToRelay(): Promise<void>;
921
+ }
922
+ //#endregion
727
923
  //#region src/client/datagram_stream.d.ts
728
924
  /**
729
925
  * Sends MoqtObjects as WebTransport datagrams.
@@ -836,7 +1032,7 @@ declare class RecvDatagramStream {
836
1032
  * const client = await MOQtailClient.new({ url });
837
1033
  * const result = await client.subscribe({
838
1034
  * fullTrackName,
839
- * filterType: FilterType.LatestObject,
1035
+ * locationFilter: new LocationFilter(LocationFilterType.NextObject),
840
1036
  * forward: true,
841
1037
  * groupOrder: GroupOrder.Original,
842
1038
  * priority: 0
@@ -912,11 +1108,6 @@ declare class MOQtailClient {
912
1108
  * Maps track aliases to full track names for quick resolution during data handling.
913
1109
  */
914
1110
  readonly aliasFullTrackNameMap: Map<bigint, FullTrackName>;
915
- /**
916
- * Pending state updates keyed by requestId and applied once a new track alias is seen.
917
- * Used to avoid premature state updates.
918
- */
919
- readonly pendingStateUpdates: Map<bigint, (newTrackAlias: bigint) => boolean>;
920
1111
  /** Underlying WebTransport session (set after successful construction in MOQtailClient.new). */
921
1112
  webTransport: WebTransport;
922
1113
  /** Outgoing / incoming control message stream pair. */
@@ -925,6 +1116,16 @@ declare class MOQtailClient {
925
1116
  dataStreamTimeoutMs?: number;
926
1117
  /** Timeout (ms) for control stream read operations; undefined =\> no explicit timeout. */
927
1118
  controlStreamTimeoutMs?: number;
1119
+ /**
1120
+ * How long (ms) an incoming data stream waits for the control message that establishes
1121
+ * its track alias before the stream is abandoned.
1122
+ */
1123
+ trackAliasResolutionTimeoutMs: number;
1124
+ /**
1125
+ * How long (ms) a track a soft switch handed over from may stay quiet before it is
1126
+ * retired anyway, if no PUBLISH_DONE ends its drain first.
1127
+ */
1128
+ switchDrainTimeoutMs: number;
928
1129
  /**
929
1130
  * TODO: onNamespaceAnnounced may be a better name
930
1131
  * Fired when an PUBLISH_NAMESPACE control message is processed for a track namespace.
@@ -940,7 +1141,7 @@ declare class MOQtailClient {
940
1141
  onGoaway?: (msg: GoAway) => void;
941
1142
  /**
942
1143
  * Whether the peer has sent a GOAWAY on the control stream. Once it has, this side
943
- * should not start new requests (§10.4); a second one closes the session with
1144
+ * should not start new requests; a second one closes the session with
944
1145
  * PROTOCOL_VIOLATION.
945
1146
  */
946
1147
  goawayReceived: boolean;
@@ -980,6 +1181,13 @@ declare class MOQtailClient {
980
1181
  * Informational event.
981
1182
  */
982
1183
  onDataSent?: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void;
1184
+ /**
1185
+ * Invoked for every data stream this client opens or accepts: once for its header, once
1186
+ * per object (identity and payload length only), and once when the stream ends.
1187
+ * Use for counters and diagnostics.
1188
+ * Informational event.
1189
+ */
1190
+ onDataEvent?: DataEventObserver;
983
1191
  /**
984
1192
  * General-purpose error callback for surfaced exceptions not thrown to caller synchronously.
985
1193
  * Use to log or display errors.
@@ -1011,15 +1219,28 @@ declare class MOQtailClient {
1011
1219
  onForwardStateChange?: (requestId: bigint, forward: boolean) => void;
1012
1220
  /** Fired when an inbound SUBSCRIBE_NAMESPACE control message is received. */
1013
1221
  onPeerSubscribeNamespace?: (msg: SubscribeNamespace) => void;
1014
- /** Fired when an inbound SUBSCRIBE_TRACKS control message is received. */
1222
+ /**
1223
+ * Fired when an inbound SUBSCRIBE_TRACKS control message is received. The PUBLISH
1224
+ * sent for each matching track:
1225
+ * - states the request's settings as its parameters, from
1226
+ * `MessageParameter.publishParametersFor(msg.parameters)`: FORWARD, GROUP_ORDER and
1227
+ * the LOCATION_FILTER the subscription starts from, but never the request's
1228
+ * AUTHORIZATION_TOKEN;
1229
+ * - goes without Track Properties when
1230
+ * `MessageParameter.includesProperties(msg.parameters)` is false.
1231
+ *
1232
+ * A request carrying FILL_PARAMETERS also asks for a fill of what each track has
1233
+ * already published. This client cannot open a fill for a pushed track, so such a
1234
+ * subscriber gets only the live Objects.
1235
+ */
1015
1236
  onPeerSubscribeTracks?: (msg: SubscribeTracks) => void;
1016
1237
  /**
1017
- * Fired when a PUBLISH_BLOCKED arrives on a {@link MOQtailClient.subscribeTracks}
1238
+ * Fired when a PUBLISH_SKIPPED arrives on a {@link MOQtailClient.subscribeTracks}
1018
1239
  * stream: the peer has a matching track but no bidi stream to send its PUBLISH on
1019
1240
  * until its stream limit lifts (§10.20). `prefix` is the prefix this side subscribed
1020
1241
  * with, which is what the message's suffix hangs off.
1021
1242
  */
1022
- onPeerPublishBlocked?: (prefix: Tuple, msg: PublishBlocked) => void;
1243
+ onPeerPublishSkipped?: (prefix: Tuple, msg: PublishSkipped) => void;
1023
1244
  /** Fired when a NAMESPACE message arrives on a SUBSCRIBE_NAMESPACE bi-stream (prefix + suffix). */
1024
1245
  onPeerNamespace?: (prefix: Tuple, suffix: Tuple) => void;
1025
1246
  /** Fired when a NAMESPACE_DONE message arrives on a SUBSCRIBE_NAMESPACE bi-stream (prefix + suffix). */
@@ -1042,6 +1263,21 @@ declare class MOQtailClient {
1042
1263
  * @returns The {@link Setup} instance the server sent back during handshake.
1043
1264
  */
1044
1265
  get serverSetup(): Setup;
1266
+ /**
1267
+ * How many filter ranges the server allows in one request: its MAX_FILTER_RANGES,
1268
+ * or 0 when it sent none, which allows no Range Filter at all.
1269
+ */
1270
+ /**
1271
+ * How many filter ranges this client allows the server in one request: the
1272
+ * MAX_FILTER_RANGES it advertised, {@link DEFAULT_MAX_FILTER_RANGES} unless the
1273
+ * caller's setup options set one.
1274
+ */
1275
+ get maxFilterRanges(): bigint;
1276
+ /**
1277
+ * How many filter ranges the server allows in one request: its MAX_FILTER_RANGES,
1278
+ * or 0 when it sent none, which allows no Range Filter at all.
1279
+ */
1280
+ get peerMaxFilterRanges(): bigint;
1045
1281
  /**
1046
1282
  * Returns true if datagram support is currently active
1047
1283
  */
@@ -1081,6 +1317,7 @@ declare class MOQtailClient {
1081
1317
  * transportOptions: { congestionControl: 'default' },
1082
1318
  * dataStreamTimeoutMs: 5000,
1083
1319
  * controlStreamTimeoutMs: 2000,
1320
+ * trackAliasResolutionTimeoutMs: 2000,
1084
1321
  * enableDatagrams: true,
1085
1322
  * callbacks: {
1086
1323
  * onMessageSent: msg => console.log('Sent:', msg),
@@ -1277,25 +1514,25 @@ declare class MOQtailClient {
1277
1514
  *
1278
1515
  * - `forward: true` tells the relay to forward objects to this subscriber as they arrive.
1279
1516
  * - `forward: false` means the relay subscribes upstream but buffers objects locally, not forwarding them to you.
1280
- * - `filterType: AbsoluteStart` lets you specify a start position in the future; the stream waits for that object. If the start location is \< the latest object
1281
- * observed at the publisher then it behaves as `filterType: LatestObject`
1282
- * - `filterType: AbsoluteRange` lets you specify a start and end group, both of should be in the future; the stream waits for those objects. If the start location is \< the latest object
1283
- * observed at the publisher then it behaves as `filterType: LatestObject`.
1517
+ * - `locationFilter` selects which Objects are delivered; omitted, the subscription is unfiltered. An absolute start in the
1518
+ * future waits for that object.
1519
+ * - A {@link FillParameters} in `parameters` also retrieves Objects already published, on a fill fetch stream.
1284
1520
  *
1285
- * The method returns either a {@link RequestError} (on refusal) or an object with the subscription `requestId` and a `ReadableStream` of {@link MoqtObject}s.
1521
+ * The method returns either a {@link RequestError} (on refusal) or an object with the subscription `requestId`, the `trackAlias` and a `ReadableStream` of {@link MoqtObject}s.
1286
1522
  * Use the `requestId` for {@link MOQtailClient.unsubscribe} or {@link MOQtailClient.subscribeUpdate}. Use the `stream` to decode and display objects.
1287
1523
  *
1288
1524
  * @param args - {@link SubscribeOptions} describing the subscription window and relay forwarding behavior.
1289
- * @returns Either a {@link RequestError} or `{ requestId, stream }` for consuming objects.
1525
+ * @returns Either a {@link RequestError} or `{ requestId, trackAlias, stream }` for consuming objects.
1290
1526
  * @throws : {@link MOQtailError} If the client is destroyed.
1291
1527
  * @throws : {@link ProtocolViolationError} If required fields are missing or inconsistent.
1528
+ * @throws : {@link InvalidFilterError} If the Range Filters exceed the server's MAX_FILTER_RANGES; nothing is sent.
1292
1529
  * @throws : {@link InternalError} On transport/protocol failure (disconnect is triggered before rethrow).
1293
1530
  *
1294
1531
  * @example Subscribe to the latest object and receive future objects as they arrive
1295
1532
  * ```ts
1296
1533
  * const result = await client.subscribe({
1297
1534
  * fullTrackName,
1298
- * filterType: FilterType.LatestObject,
1535
+ * locationFilter: new LocationFilter(LocationFilterType.NextObject),
1299
1536
  * forward: true,
1300
1537
  * groupOrder: GroupOrder.Original,
1301
1538
  * priority: 32
@@ -1307,13 +1544,11 @@ declare class MOQtailClient {
1307
1544
  * }
1308
1545
  * ```
1309
1546
  *
1310
- * @example Subscribe to a future range (waits for those objects to arrive)
1547
+ * @example Subscribe to a future range of groups (waits for those objects to arrive)
1311
1548
  * ```ts
1312
1549
  * const result = await client.subscribe({
1313
1550
  * fullTrackName,
1314
- * filterType: FilterType.AbsoluteRange,
1315
- * startLocation: futureStart,
1316
- * endGroup: futureEnd,
1551
+ * locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, startGroup, 0n, endGroup),
1317
1552
  * forward: true,
1318
1553
  * groupOrder: GroupOrder.Original,
1319
1554
  * priority: 128
@@ -1322,6 +1557,7 @@ declare class MOQtailClient {
1322
1557
  */
1323
1558
  subscribe(args: SubscribeOptions): Promise<RequestError | {
1324
1559
  requestId: bigint;
1560
+ trackAlias: bigint;
1325
1561
  stream: ReadableStream<MoqtObject>;
1326
1562
  }>;
1327
1563
  /**
@@ -1344,7 +1580,7 @@ declare class MOQtailClient {
1344
1580
  *
1345
1581
  * @example Subscribe and later unsubscribe
1346
1582
  * ```ts
1347
- * const sub = await client.subscribe({ fullTrackName, filterType: FilterType.LatestObject, forward: true, groupOrder: GroupOrder.Original, priority: 0 });
1583
+ * const sub = await client.subscribe({ fullTrackName, locationFilter: new LocationFilter(LocationFilterType.NextObject), forward: true, groupOrder: GroupOrder.Original, priority: 0 });
1348
1584
  * if (!(sub instanceof RequestError)) {
1349
1585
  * // ...consume objects...
1350
1586
  * await client.unsubscribe(sub.requestId);
@@ -1384,43 +1620,60 @@ declare class MOQtailClient {
1384
1620
  *
1385
1621
  * @example Trim start forward
1386
1622
  * ```ts
1387
- * await client.subscribeUpdate({ requestId, startLocation: laterLoc, endGroup, forward: true, priority });
1623
+ * await client.subscribeUpdate({ subscriptionRequestId, locationFilter: new LocationFilter(LocationFilterType.AbsoluteStart, laterGroup, 0n), forward: true, priority });
1388
1624
  * ```
1389
1625
  *
1390
1626
  * @example Convert tailing subscription into bounded slice
1391
1627
  * ```ts
1392
- * await client.subscribeUpdate({ requestId, startLocation: origStart, endGroup: cutoffGroup, forward: false, priority });
1628
+ * await client.subscribeUpdate({ subscriptionRequestId, locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, startGroup, 0n, cutoffGroup), forward: false, priority });
1393
1629
  * ```
1394
1630
  *
1395
1631
  * @example Lower priority only
1396
1632
  * ```ts
1397
- * await client.subscribeUpdate({ requestId, startLocation: currentStart, endGroup: currentEnd, forward: true, priority: 200 });
1633
+ * await client.subscribeUpdate({ subscriptionRequestId, forward: true, priority: 200 });
1398
1634
  * ```
1399
1635
  */
1400
1636
  subscribeUpdate(args: SubscribeUpdateOptions): Promise<void>;
1401
1637
  /**
1402
- * Switches an active subscription to a different track while retaining the same subscription parameters.
1638
+ * Switches an active subscription to a different track while retaining the same subscription's
1639
+ * output stream.
1403
1640
  *
1404
- * Use this to change the subscribed track without tearing down and re-establishing a new subscription.
1641
+ * Sends a fresh SUBSCRIBE carrying a SwitchFrom parameter referencing `switchFromRequestId`. A soft
1642
+ * switch may keep delivering objects from the old track for a while after SUBSCRIBE_OK, and this can
1643
+ * be called again before the previous target has produced anything; only the first object actually
1644
+ * delivered by the newest switch target retires everything older.
1405
1645
  *
1406
- * @param args - {@link SwitchOptions} referencing the original subscription `requestId` and new track name.
1407
- * @returns Promise that resolves when the switch control frame is sent.
1646
+ * @param args - {@link SwitchOptions} referencing the subscription to switch from and the new subscription options.
1647
+ * @returns Either a {@link RequestError} (refusal) or `{ requestId, stream }`, where `stream` is the
1648
+ * same {@link https://developer.mozilla.org/docs/Web/API/ReadableStream | ReadableStream} object returned by the original `subscribe()` call.
1408
1649
  * @throws :{@link MOQtailError} If the client is destroyed.
1650
+ * @throws :{@link ProtocolViolationError} If `switchFromRequestId` does not name an active subscription.
1409
1651
  * @throws :{@link InternalError} On transport/control failure (disconnect is triggered before rethrow).
1410
1652
  *
1411
- * @remarks
1412
- * - Only applies to active SUBSCRIBE requests; ignored if the request is not a subscription.
1413
- * - All other subscription parameters (window, forwarding, priority) remain unchanged.
1414
- *
1415
1653
  * @example Switch to a different track
1416
1654
  * ```ts
1417
- * await client.switch({ subscriptionRequestId, fullTrackName: newTrackName });
1655
+ * await client.switch({
1656
+ * switchFromRequestId,
1657
+ * switchMode: SwitchMode.Soft,
1658
+ * newSubscribeOptions: { fullTrackName: newTrackName, priority: 0, groupOrder: GroupOrder.Original, forward: true, locationFilter: new LocationFilter(LocationFilterType.NextObject) },
1659
+ * onDrainDecision: (request) => true
1660
+ * });
1418
1661
  * ```
1419
1662
  */
1420
1663
  switch(args: SwitchOptions): Promise<RequestError | {
1421
1664
  requestId: bigint;
1422
1665
  stream: ReadableStream<MoqtObject>;
1423
1666
  }>;
1667
+ /**
1668
+ * Ends a subscription whose publisher has said how many streams it opened and has
1669
+ * now delivered all of them, and reports whether that happened.
1670
+ *
1671
+ * Both halves of that arrive on their own: a PUBLISH_DONE carries the count, and
1672
+ * the streams finish whenever they finish. Either can be last, so this is checked
1673
+ * from both -- a drained switch target has usually finished its streams well
1674
+ * before the PUBLISH_DONE that ends it.
1675
+ */
1676
+ completeSubscription(request: SubscribeRequest, force?: boolean): boolean;
1424
1677
  /**
1425
1678
  * One-shot retrieval of a bounded object span, optionally anchored to an existing subscription, returning a stream of {@link MoqtObject}s.
1426
1679
  *
@@ -1452,15 +1705,13 @@ declare class MOQtailClient {
1452
1705
  * - Result stream is finite; reader close occurs automatically when last object delivered.
1453
1706
  * - Use {@link MOQtailClient.fetchCancel} only for early termination (not yet fully implemented: see TODO in code).
1454
1707
  *
1455
- * @example Standalone window
1708
+ * @example Groups 10 through 12, inclusive
1456
1709
  * ```ts
1457
1710
  * const r = await client.fetch({
1711
+ * fullTrackName,
1458
1712
  * priority: 64,
1459
1713
  * groupOrder: GroupOrder.Original,
1460
- * typeAndProps: {
1461
- * type: FetchType.Standalone,
1462
- * props: { fullTrackName, startLocation, endLocation }
1463
- * }
1714
+ * locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 10n, 0n, 12n)
1464
1715
  * })
1465
1716
  * if (!(r instanceof RequestError)) {
1466
1717
  * for await (const obj of r.stream as any) {
@@ -1469,16 +1720,14 @@ declare class MOQtailClient {
1469
1720
  * }
1470
1721
  * ```
1471
1722
  *
1472
- * @example Relative to live subscription (e.g. last 5 groups)
1723
+ * @example The last 5 groups, counting the current one
1473
1724
  * ```ts
1474
- * const sub = await client.subscribe({ fullTrackName, filterType: FilterType.LatestObject, forward: true, groupOrder: GroupOrder.Original, priority: 0 })
1475
- * if (!(sub instanceof RequestError)) {
1476
- * const slice = await client.fetch({
1477
- * priority: 32,
1478
- * groupOrder: GroupOrder.Original,
1479
- * typeAndProps: { type: FetchType.Relative, props: { joiningRequestId: sub.requestId, joiningStart: 0n } }
1480
- * })
1481
- * }
1725
+ * const slice = await client.fetch({
1726
+ * fullTrackName,
1727
+ * priority: 32,
1728
+ * groupOrder: GroupOrder.Original,
1729
+ * locationFilter: new LocationFilter(LocationFilterType.RelativeStart, 5n)
1730
+ * })
1482
1731
  * ```
1483
1732
  */
1484
1733
  fetch(args: FetchOptions): Promise<RequestError | {
@@ -1507,7 +1756,7 @@ declare class MOQtailClient {
1507
1756
  *
1508
1757
  * @example Cancel shortly after starting
1509
1758
  * ```ts
1510
- * const r = await client.fetch({ priority: 32, groupOrder: GroupOrder.Original, typeAndProps: { type: FetchType.Standalone, props: { fullTrackName, startLocation, endLocation } } })
1759
+ * const r = await client.fetch({ fullTrackName, priority: 32, groupOrder: GroupOrder.Original, locationFilter })
1511
1760
  * if (!(r instanceof RequestError)) {
1512
1761
  * // user navigated away
1513
1762
  * await client.fetchCancel(r.requestId)
@@ -1582,7 +1831,7 @@ declare class MOQtailClient {
1582
1831
  * const resp = await client.publishNamespace(["room","1234"], params)
1583
1832
  * ```
1584
1833
  */
1585
- publishNamespace(trackNamespace: Tuple, parameters?: MessageParameter[]): Promise<RequestOk | RequestError>;
1834
+ publishNamespace(trackNamespace: Tuple, parameters?: MessageParameter[]): Promise<RequestError | RequestOk>;
1586
1835
  /**
1587
1836
  * Withdraw a previously announced namespace so new subscribers no longer discover its tracks.
1588
1837
  *
@@ -1658,6 +1907,18 @@ declare class MOQtailClient {
1658
1907
  * ```
1659
1908
  */
1660
1909
  trackStatus(fullTrackName: FullTrackName, trackAlias: bigint, parameters?: MessageParameter[]): Promise<RequestOk | RequestError>;
1910
+ /**
1911
+ * Opens a bidi request stream for `first` and starts reading responses off it.
1912
+ *
1913
+ * @param requestId - The requestId carried by `first`; the key the stream is filed under.
1914
+ */
1915
+ /**
1916
+ * Hands a data stream {@link MOQtailClient.onDataEvent}, read at call time so an observer assigned
1917
+ * after connecting still sees streams that are already open.
1918
+ *
1919
+ * @internal
1920
+ */
1921
+ dataStreamObserver(fullTrackNameOf?: DataStreamObserver['fullTrackNameOf']): DataStreamObserver;
1661
1922
  /**
1662
1923
  * Re-issues one request on a fresh stream after the peer sent a GOAWAY on its request
1663
1924
  * stream (§10.4). Only that request moves: the session, and every other request on it,
@@ -1682,7 +1943,8 @@ declare class SendStream {
1682
1943
  readonly header: Header;
1683
1944
  readonly onDataSent?: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void;
1684
1945
  private constructor();
1685
- static new(writeStream: WritableStream<Uint8Array>, header: Header, onDataSent?: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void, groupOrder?: GroupOrder): Promise<SendStream>;
1946
+ /** @param observer - Receives a {@link DataEvent} for the header, each object, and the stream's end. */
1947
+ static new(writeStream: WritableStream<Uint8Array>, header: Header, onDataSent?: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void, groupOrder?: GroupOrder, observer?: DataStreamObserver): Promise<SendStream>;
1686
1948
  write(object: FetchObject | SubgroupObject): Promise<void>;
1687
1949
  close(): Promise<void>;
1688
1950
  /** Abruptly tears the stream down, so the peer reads back `code` (§3.3.3). */
@@ -1697,10 +1959,11 @@ declare class RecvStream {
1697
1959
  /**
1698
1960
  * @param resolveGroupOrder - Consulted once the FETCH header names its request, since
1699
1961
  * Group ID deltas on the stream are signed by the Group Order the request negotiated.
1962
+ * @param observer - Receives a {@link DataEvent} for the header, each object, and the stream's end.
1700
1963
  */
1701
- static new(readStream: ReadableStream<Uint8Array>, partialDataTimeout?: number, onDataReceived?: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void, resolveGroupOrder?: (header: Header) => GroupOrder): Promise<RecvStream>;
1964
+ static new(readStream: ReadableStream<Uint8Array>, partialDataTimeout?: number, onDataReceived?: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void, resolveGroupOrder?: (header: Header) => GroupOrder, observer?: DataStreamObserver): Promise<RecvStream>;
1702
1965
  /** Asks the peer to stop sending on this stream, reporting `code` (§3.3.3). */
1703
1966
  stopSending(code: StreamResetCode): Promise<void>;
1704
1967
  }
1705
1968
  //#endregion
1706
- export { ControlRecvStream, ControlSendStream, ControlStream, EarlyDiscardPolicyConfig, FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, LiveObjectSource, LiveTrackSource, MOQtailClient, MOQtailClientOptions, MOQtailRequest, MemoryObjectCache, ObjectCache, PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RequestStream, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, SubscribeOptions, SubscribePublication, SubscribeRequest, SubscribeUpdateOptions, SwitchOptions, Track, TrackSource, TrackStatusRequest };
1969
+ export { ControlRecvStream, ControlSendStream, ControlStream, DEFAULT_MAX_FILTER_RANGES, DEFAULT_SWITCH_DRAIN_TIMEOUT_MS, DEFAULT_TRACK_ALIAS_RESOLUTION_TIMEOUT_MS, DataDirection, DataEvent, DataEventBase, DataEventObserver, DataHeaderEvent, DataObjectEvent, DataStreamEndEvent, DataStreamObserver, DataStreamReporter, EarlyDiscardPolicyConfig, EndOfRangeHandler, FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, LiveObjectSource, LiveTrackSource, MOQtailClient, MOQtailClientOptions, MOQtailRequest, MemoryObjectCache, ObjectCache, PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RequestStream, RequestStreamHooks, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, SubscribeOptions, SubscribePublication, SubscribeRequest, SubscribeUpdateOptions, Subscription, SwitchOptions, Track, TrackAliasHolder, TrackSource, TrackStatusRequest };