moqtail 0.14.0 → 0.16.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/README.md +153 -473
- package/dist/{client-Z7egUKTO.cjs → client-DQ5aGbLR.cjs} +1100 -1099
- package/dist/client-DUzLw_Y8.d.cts +1932 -0
- package/dist/{client-BW1agDFV.mjs → client-DVi4Nh1J.mjs} +942 -947
- package/dist/client-epHqMdHm.d.mts +1932 -0
- package/dist/client.cjs +121 -4
- package/dist/client.d.cts +23 -1933
- package/dist/client.d.mts +23 -1933
- package/dist/client.mjs +117 -2
- package/dist/emitter-UbeRcbuf.mjs +109 -0
- package/dist/{logger-c2NoQqtx.cjs → emitter-qNJYD3yQ.cjs} +61 -2
- package/dist/index-B-BMK-b6.d.mts +2090 -0
- package/dist/index-BtemTtwe.d.cts +2090 -0
- package/dist/{index-DBbxKcc1.d.cts → index-CNn9BgO6.d.mts} +168 -337
- package/dist/index.cjs +39 -34
- package/dist/index.d.cts +20 -4
- package/dist/index.d.mts +20 -4
- package/dist/index.mjs +5 -4
- package/dist/logger-B8IYkljn.d.cts +64 -0
- package/dist/logger-B8IYkljn.d.mts +64 -0
- package/dist/model.cjs +208 -359
- package/dist/model.d.cts +2896 -2
- package/dist/model.d.mts +17 -2
- package/dist/model.mjs +207 -359
- package/dist/player/component.cjs +317 -0
- package/dist/player/component.d.cts +50 -0
- package/dist/player/component.d.mts +50 -0
- package/dist/player/component.mjs +315 -0
- package/dist/player-CJayEzwt.cjs +6750 -0
- package/dist/player-DcctWhyM.mjs +6599 -0
- package/dist/player.cjs +27 -0
- package/dist/player.d.cts +17 -0
- package/dist/player.d.mts +17 -0
- package/dist/player.mjs +1 -0
- package/dist/rolldown-runtime-CmQyd0Gu.cjs +27 -0
- package/dist/util.cjs +9 -10
- package/dist/util.d.cts +20 -13
- package/dist/util.d.mts +20 -13
- package/dist/util.mjs +4 -6
- package/package.json +45 -5
- package/dist/index-DBbxKcc1.d.mts +0 -3051
- package/dist/logger-ByDB8lYF.mjs +0 -56
- package/dist/logger-dEoueCj7.d.cts +0 -35
- package/dist/logger-dEoueCj7.d.mts +0 -35
|
@@ -0,0 +1,1932 @@
|
|
|
1
|
+
import { ControlMessage, ControlMessageType, Datagram, EndOfRangeKind, Fetch, FetchHeader, FetchObject, FetchOk, FullTrackName, GoAway, GroupOrder, Header, Location, LocationFilter, MessageParameter, MoqtObject, ObjectStatus, Publish, PublishDone, PublishDoneStatusCode, PublishNamespace, PublishSkipped, RequestError, RequestIdMap, RequestOk, RequestUpdate, Setup, SetupOptions, StreamResetCode, SubgroupHeader, SubgroupObject, Subscribe, SubscribeNamespace, SubscribeOk, SubscribeTracks, SwitchMode, TrackProperty, TrackStatus, Tuple } from "./model.cjs";
|
|
2
|
+
import { o as Emitter, t as LogLevel } from "./logger-B8IYkljn.cjs";
|
|
3
|
+
/** `in` for a stream the peer opened, `out` for one this client opened. */
|
|
4
|
+
type DataDirection = 'in' | 'out';
|
|
5
|
+
/** What every data event carries. */
|
|
6
|
+
type DataEventBase = {
|
|
7
|
+
direction: DataDirection;
|
|
8
|
+
/** Local to this client, unique per data stream; every later event on the stream carries it. */
|
|
9
|
+
streamId: number;
|
|
10
|
+
/**
|
|
11
|
+
* When the client wrote or read it, as `performance.now()` in ms: high resolution and
|
|
12
|
+
* monotonic, so differences between events are exact. Add `performance.timeOrigin` for
|
|
13
|
+
* wall-clock time.
|
|
14
|
+
*/
|
|
15
|
+
at: number;
|
|
16
|
+
};
|
|
17
|
+
/** A data stream opened: what its header says. */
|
|
18
|
+
type DataHeaderEvent = DataEventBase & {
|
|
19
|
+
kind: 'header';
|
|
20
|
+
stream: 'subgroup' | 'fetch';
|
|
21
|
+
/** Subgroup streams only. */
|
|
22
|
+
trackAlias?: bigint;
|
|
23
|
+
/** Subgroup streams only. */
|
|
24
|
+
groupId?: bigint;
|
|
25
|
+
/** Subgroup streams only; unknown here when the header defers it to the first Object ID. */
|
|
26
|
+
subgroupId?: bigint;
|
|
27
|
+
/** Fetch streams only. */
|
|
28
|
+
requestId?: bigint;
|
|
29
|
+
/** The track the stream belongs to, when the client knows it at header time. */
|
|
30
|
+
fullTrackName?: FullTrackName;
|
|
31
|
+
};
|
|
32
|
+
/** One object written or read. Only its identity and size are reported, never its payload. */
|
|
33
|
+
type DataObjectEvent = DataEventBase & {
|
|
34
|
+
kind: 'object';
|
|
35
|
+
groupId: bigint;
|
|
36
|
+
subgroupId?: bigint;
|
|
37
|
+
objectId: bigint;
|
|
38
|
+
payloadLength: number;
|
|
39
|
+
/** Set for an object that carries a status instead of a payload. */
|
|
40
|
+
objectStatus?: ObjectStatus;
|
|
41
|
+
/**
|
|
42
|
+
* The object's LOC Timestamp property, when it carries one: the sender's media time,
|
|
43
|
+
* in whatever unit and clock the sender chose.
|
|
44
|
+
*/
|
|
45
|
+
locTimestamp?: bigint;
|
|
46
|
+
};
|
|
47
|
+
/** A data stream ended: `fin` when it closed cleanly, `reset` when either side reset it. */
|
|
48
|
+
type DataStreamEndEvent = DataEventBase & {
|
|
49
|
+
kind: 'end';
|
|
50
|
+
reason: 'fin' | 'reset' | 'error';
|
|
51
|
+
resetCode?: StreamResetCode;
|
|
52
|
+
};
|
|
53
|
+
type DataEvent = DataHeaderEvent | DataObjectEvent | DataStreamEndEvent;
|
|
54
|
+
/** Names the track a data stream header belongs to, if known. */
|
|
55
|
+
type FullTrackNameOf = (header: Header) => FullTrackName | undefined;
|
|
56
|
+
/**
|
|
57
|
+
* Turns one data stream's activity into {@link DataEvent}s, emitted as `dataevent`.
|
|
58
|
+
* A throwing listener can't break the stream: `EventTarget` isolates it. Without an
|
|
59
|
+
* emitter no event is built, since this runs for every object.
|
|
60
|
+
*/
|
|
61
|
+
declare class DataStreamReporter {
|
|
62
|
+
#private;
|
|
63
|
+
readonly streamId: number;
|
|
64
|
+
constructor(direction: DataDirection, events?: Emitter<ClientEvents>, fullTrackNameOf?: FullTrackNameOf);
|
|
65
|
+
header(header: Header): void;
|
|
66
|
+
/** `header` is the stream's own: a subgroup object takes its group and subgroup from it. */
|
|
67
|
+
object(header: Header, object: SubgroupObject | FetchObject): void;
|
|
68
|
+
/** Reports how the stream ended. Only the first call counts. */
|
|
69
|
+
end(reason: DataStreamEndEvent['reason'], resetCode?: StreamResetCode): void;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* A request's consumer-facing object stream. The consumer may cancel it while objects are
|
|
73
|
+
* still in flight, so writes after that, or after it closed or errored, are dropped.
|
|
74
|
+
*/
|
|
75
|
+
declare class ObjectStream {
|
|
76
|
+
#private;
|
|
77
|
+
readonly readable: ReadableStream<MoqtObject>;
|
|
78
|
+
constructor();
|
|
79
|
+
/** False once closed, cancelled by the consumer, or errored: nothing written is read. */
|
|
80
|
+
get open(): boolean;
|
|
81
|
+
enqueue(object: MoqtObject): void;
|
|
82
|
+
close(): void;
|
|
83
|
+
}
|
|
84
|
+
/** Why an orderer's window is suspended: a switch in progress, or a fill fetch stream still delivering. */
|
|
85
|
+
type WindowSuspension = 'switch' | 'fill';
|
|
86
|
+
/**
|
|
87
|
+
* @public
|
|
88
|
+
* Releases one request's objects in location order, whatever streams or datagrams they
|
|
89
|
+
* arrived on. An object goes out as soon as its predecessor has; one whose predecessor
|
|
90
|
+
* is missing waits until the window is exceeded, then everything up to the oldest held
|
|
91
|
+
* object goes out and the expected locations skipped are reported through `gap`.
|
|
92
|
+
*
|
|
93
|
+
* Nothing is released yet, so the first object goes out at once only when it starts a
|
|
94
|
+
* group: a mid-group first object waits for the start of its group, which a fill fetch
|
|
95
|
+
* stream may still bring.
|
|
96
|
+
*/
|
|
97
|
+
declare class ObjectOrderer {
|
|
98
|
+
#private;
|
|
99
|
+
constructor(ordering: ObjectOrdering, onRelease: (object: MoqtObject) => void, onGap: (from: Location, to: Location) => void);
|
|
100
|
+
/** Takes an object; `previous` is the object before it on the same fetch stream. */
|
|
101
|
+
push(object: MoqtObject, previous?: Location): void;
|
|
102
|
+
/** While suspended for any reason nothing exceeds the window, so held objects wait for what's missing. */
|
|
103
|
+
suspendWindow(reason: WindowSuspension): void;
|
|
104
|
+
/** Resuming the last reason releases at once what waited longer than the window. */
|
|
105
|
+
resumeWindow(reason: WindowSuspension): void;
|
|
106
|
+
/** A stream carrying the End of Group for `group` ended cleanly with `lastObject`. */
|
|
107
|
+
endGroup(group: bigint, lastObject: bigint): void;
|
|
108
|
+
/** Releases everything held, in order, and stops the timer. Call before closing the stream. */
|
|
109
|
+
flush(): void;
|
|
110
|
+
}
|
|
111
|
+
declare class FetchRequest implements PromiseLike<FetchOk | RequestError> {
|
|
112
|
+
readonly requestId: bigint;
|
|
113
|
+
readonly message: Fetch;
|
|
114
|
+
private _resolve;
|
|
115
|
+
private _reject;
|
|
116
|
+
private promise;
|
|
117
|
+
readonly objects: ObjectStream;
|
|
118
|
+
readonly stream: ReadableStream<MoqtObject>;
|
|
119
|
+
onEndOfRange: EndOfRangeHandler | undefined;
|
|
120
|
+
orderer: ObjectOrderer | undefined;
|
|
121
|
+
isActive: boolean;
|
|
122
|
+
isResolved: boolean;
|
|
123
|
+
constructor(message: Fetch);
|
|
124
|
+
resolve(value: FetchOk | RequestError | PromiseLike<FetchOk | RequestError>): void;
|
|
125
|
+
reject(reason?: any): void;
|
|
126
|
+
then<TResult1 = FetchOk | RequestError, TResult2 = never>(onfulfilled?: ((value: FetchOk | RequestError) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
|
|
127
|
+
catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<FetchOk | RequestError | TResult>;
|
|
128
|
+
finally(onfinally?: (() => void) | undefined | null): Promise<FetchOk | RequestError>;
|
|
129
|
+
}
|
|
130
|
+
declare class PublishRequest implements PromiseLike<RequestOk | RequestError> {
|
|
131
|
+
readonly requestId: bigint;
|
|
132
|
+
readonly message: Publish;
|
|
133
|
+
private _resolve;
|
|
134
|
+
private _reject;
|
|
135
|
+
private promise;
|
|
136
|
+
constructor(msg: Publish);
|
|
137
|
+
resolve(value: RequestOk | RequestError | PromiseLike<RequestOk | RequestError>): void;
|
|
138
|
+
reject(reason?: any): void;
|
|
139
|
+
then<TResult1 = RequestOk | RequestError, TResult2 = never>(onfulfilled?: ((value: RequestOk | RequestError) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
|
|
140
|
+
catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<RequestOk | RequestError | TResult>;
|
|
141
|
+
finally(onfinally?: (() => void) | undefined | null): Promise<RequestOk | RequestError>;
|
|
142
|
+
}
|
|
143
|
+
declare class PublishNamespaceRequest implements PromiseLike<RequestOk | RequestError> {
|
|
144
|
+
readonly requestId: bigint;
|
|
145
|
+
readonly message: PublishNamespace;
|
|
146
|
+
private _resolve;
|
|
147
|
+
private _reject;
|
|
148
|
+
private promise;
|
|
149
|
+
constructor(requestId: bigint, message: PublishNamespace);
|
|
150
|
+
resolve(value: RequestOk | RequestError | PromiseLike<RequestOk | RequestError>): void;
|
|
151
|
+
reject(reason?: any): void;
|
|
152
|
+
then<TResult1 = RequestOk | RequestError, TResult2 = never>(onfulfilled?: ((value: RequestOk | RequestError) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
|
|
153
|
+
catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<RequestOk | RequestError | TResult>;
|
|
154
|
+
finally(onfinally?: (() => void) | undefined | null): Promise<RequestOk | RequestError>;
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Represents an active subscription request in MOQT, implementing `PromiseLike`
|
|
158
|
+
* for convenient async resolution when subscription setup succeeds or fails.
|
|
159
|
+
*/
|
|
160
|
+
declare class SubscribeRequest implements PromiseLike<SubscribeOk | RequestError> {
|
|
161
|
+
#private;
|
|
162
|
+
requestId: bigint;
|
|
163
|
+
fullTrackName: FullTrackName;
|
|
164
|
+
isCanceled: boolean;
|
|
165
|
+
startLocation: Location | undefined;
|
|
166
|
+
endGroup: bigint | undefined;
|
|
167
|
+
priority: number;
|
|
168
|
+
forward: boolean;
|
|
169
|
+
subscribeParameters: MessageParameter[];
|
|
170
|
+
earlyDiscardPolicy: EarlyDiscardPolicyConfig | undefined;
|
|
171
|
+
onEndOfRange: EndOfRangeHandler | undefined;
|
|
172
|
+
largestLocation: Location | undefined;
|
|
173
|
+
/**
|
|
174
|
+
* The publisher's Largest Object as of the last SUBSCRIBE_OK or REQUEST_UPDATE_OK,
|
|
175
|
+
* which is where a fill fetch stream stops.
|
|
176
|
+
*/
|
|
177
|
+
fillBoundary: Location | undefined;
|
|
178
|
+
/** A fill fetch stream opened for this subscription. */
|
|
179
|
+
fillOpened: boolean;
|
|
180
|
+
/** Fill fetch streams still delivering. */
|
|
181
|
+
openFills: number;
|
|
182
|
+
/** EXPIRES from the last SUBSCRIBE_OK or REQUEST_UPDATE_OK, in milliseconds. */
|
|
183
|
+
expires: bigint | undefined;
|
|
184
|
+
streamsAccepted: bigint;
|
|
185
|
+
expectedStreams: bigint | undefined;
|
|
186
|
+
/** The last PUBLISH_DONE received for this request. */
|
|
187
|
+
publishDone: PublishDone | undefined;
|
|
188
|
+
/** Resolves once this request is over, with {@link SubscribeRequest.publishDone}. Never rejects. */
|
|
189
|
+
readonly done: Promise<PublishDone | undefined>;
|
|
190
|
+
/** The Subscription that owns this request's consumer stream; it sets itself on construction. */
|
|
191
|
+
manager: Subscription;
|
|
192
|
+
readonly objects: ObjectStream;
|
|
193
|
+
readonly stream: ReadableStream<MoqtObject>;
|
|
194
|
+
orderer: ObjectOrderer | undefined;
|
|
195
|
+
constructor(msg: Subscribe);
|
|
196
|
+
/**
|
|
197
|
+
* Updates subscription parameters in-place when a `RequestUpdate` message is received.
|
|
198
|
+
*/
|
|
199
|
+
update(msg: RequestUpdate): void;
|
|
200
|
+
/**
|
|
201
|
+
* Puts an object on the consumer stream, through {@link SubscribeRequest.orderer} when
|
|
202
|
+
* there is one. `previous` is the object before it on the same fill fetch stream.
|
|
203
|
+
*/
|
|
204
|
+
enqueue(obj: MoqtObject, previous?: Location): void;
|
|
205
|
+
/** Writes an object the orderer released, or an unordered one, through the manager. */
|
|
206
|
+
output(obj: MoqtObject): void;
|
|
207
|
+
/** Ends the request: resolves {@link SubscribeRequest.done}. Later calls do nothing. */
|
|
208
|
+
finish(): void;
|
|
209
|
+
/**
|
|
210
|
+
* Marks this subscription request as canceled.
|
|
211
|
+
*/
|
|
212
|
+
unsubscribe(): void;
|
|
213
|
+
/**
|
|
214
|
+
* Resolves the internal promise with a `SubscribeOk` or `RequestError`.
|
|
215
|
+
*/
|
|
216
|
+
resolve(value: SubscribeOk | RequestError | PromiseLike<SubscribeOk | RequestError>): void;
|
|
217
|
+
/**
|
|
218
|
+
* Rejects the internal promise with an error/reason.
|
|
219
|
+
*/
|
|
220
|
+
reject(reason?: any): void;
|
|
221
|
+
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>;
|
|
222
|
+
catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<SubscribeOk | RequestError | TResult>;
|
|
223
|
+
finally(onfinally?: (() => void) | undefined | null): Promise<SubscribeOk | RequestError>;
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Owns the single consumer-facing stream for a SUBSCRIBE that may be switched to a
|
|
227
|
+
* new track one or more times. A soft switch can keep producing from the old track
|
|
228
|
+
* for an unknown time after SUBSCRIBE_OK, and a second switch may be issued before the
|
|
229
|
+
* first target ever delivers anything, so only the first object actually delivered by
|
|
230
|
+
* the newest tracked request is the guarantee that nothing older will send again.
|
|
231
|
+
*
|
|
232
|
+
* That first delivery is the handover, not the end of the old track: a soft switch
|
|
233
|
+
* leaves it delivering up to the group the new one starts at, so the two meet without
|
|
234
|
+
* a hole. Those objects keep coming through here until the publisher says the
|
|
235
|
+
* subscription is done, or until it has been quiet long enough to say so itself.
|
|
236
|
+
*/
|
|
237
|
+
declare class Subscription {
|
|
238
|
+
#private;
|
|
239
|
+
readonly objects: ObjectStream;
|
|
240
|
+
readonly stream: ReadableStream<MoqtObject>;
|
|
241
|
+
/**
|
|
242
|
+
* Resolves once every tracked request is over, with the newest one's PUBLISH_DONE, or
|
|
243
|
+
* `undefined` if it ended without one. Never rejects.
|
|
244
|
+
*/
|
|
245
|
+
readonly done: Promise<PublishDone | undefined>;
|
|
246
|
+
/** Set once by `MOQtailClient.switch`; invoked with everything older on cutover. */
|
|
247
|
+
onSuperseded?: (superseded: SubscribeRequest[]) => void;
|
|
248
|
+
/** Set by the client to decide whether draining a request should continue. */
|
|
249
|
+
onDrainDecision: (request: SubscribeRequest) => boolean;
|
|
250
|
+
/**
|
|
251
|
+
* How long a drained request may stay quiet before it is retired anyway, in
|
|
252
|
+
* milliseconds. The publisher normally ends the drain with a PUBLISH_DONE; this is
|
|
253
|
+
* what keeps a request that never gets one from being tracked forever.
|
|
254
|
+
*/
|
|
255
|
+
drainTimeoutMs: number;
|
|
256
|
+
constructor(initial: SubscribeRequest);
|
|
257
|
+
/** Requests still tracked, oldest first, draining ones last. */
|
|
258
|
+
get requests(): readonly SubscribeRequest[];
|
|
259
|
+
/** The request most recently switched to; must deliver data to win the handover. */
|
|
260
|
+
get newest(): SubscribeRequest;
|
|
261
|
+
/**
|
|
262
|
+
* Track a newly issued switch target alongside whatever is still delivering.
|
|
263
|
+
*
|
|
264
|
+
* `drainSuperseded` says what its handover does to the requests it takes over from:
|
|
265
|
+
* a soft switch leaves them delivering to the end of what the publisher was told to
|
|
266
|
+
* finish, a hard one retires them on the spot.
|
|
267
|
+
*/
|
|
268
|
+
addSwitchTarget(request: SubscribeRequest, drainSuperseded?: boolean): void;
|
|
269
|
+
/**
|
|
270
|
+
* Writes an object `request` released. While older requests still deliver, the newest
|
|
271
|
+
* one's ordered objects wait, so the old track's tail comes first.
|
|
272
|
+
*/
|
|
273
|
+
output(request: SubscribeRequest, obj: MoqtObject): void;
|
|
274
|
+
/** Stop tracking `request` (e.g. it naturally completed without ever losing/winning a handover). */
|
|
275
|
+
drop(request: SubscribeRequest): void;
|
|
276
|
+
/** Stop tracking everything (used when the whole switch chain is torn down at once). */
|
|
277
|
+
clear(): void;
|
|
278
|
+
/**
|
|
279
|
+
* Delivers an object received for `request`. The first object delivered by the
|
|
280
|
+
* newest tracked request retires everything older — only then is it guaranteed no
|
|
281
|
+
* more data is coming from them.
|
|
282
|
+
*
|
|
283
|
+
* Returns `true` if the object was delivered to the caller,
|
|
284
|
+
* `false` if it was not consumed, and client should cancel the stream.
|
|
285
|
+
*/
|
|
286
|
+
deliver(request: SubscribeRequest, obj: MoqtObject, previous?: Location): boolean;
|
|
287
|
+
}
|
|
288
|
+
declare class SubscribeNamespaceRequest implements PromiseLike<RequestOk | RequestError> {
|
|
289
|
+
readonly requestId: bigint;
|
|
290
|
+
readonly message: SubscribeNamespace;
|
|
291
|
+
private _resolve;
|
|
292
|
+
private _reject;
|
|
293
|
+
private promise;
|
|
294
|
+
constructor(msg: SubscribeNamespace);
|
|
295
|
+
resolve(value: RequestOk | RequestError | PromiseLike<RequestOk | RequestError>): void;
|
|
296
|
+
reject(reason?: any): void;
|
|
297
|
+
then<TResult1 = RequestOk | RequestError, TResult2 = never>(onfulfilled?: ((value: RequestOk | RequestError) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
|
|
298
|
+
catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<RequestOk | RequestError | TResult>;
|
|
299
|
+
finally(onfinally?: (() => void) | undefined | null): Promise<RequestOk | RequestError>;
|
|
300
|
+
}
|
|
301
|
+
declare class TrackStatusRequest implements PromiseLike<RequestOk | RequestError> {
|
|
302
|
+
readonly requestId: bigint;
|
|
303
|
+
readonly message: TrackStatus;
|
|
304
|
+
private _resolve;
|
|
305
|
+
private _reject;
|
|
306
|
+
private promise;
|
|
307
|
+
constructor(msg: TrackStatus);
|
|
308
|
+
resolve(value: RequestOk | RequestError | PromiseLike<RequestOk | RequestError>): void;
|
|
309
|
+
reject(reason?: any): void;
|
|
310
|
+
then<TResult1 = RequestOk | RequestError, TResult2 = never>(onfulfilled?: ((value: RequestOk | RequestError) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
|
|
311
|
+
catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<RequestOk | RequestError | TResult>;
|
|
312
|
+
finally(onfinally?: (() => void) | undefined | null): Promise<RequestOk | RequestError>;
|
|
313
|
+
}
|
|
314
|
+
/**
|
|
315
|
+
* Discriminated union of every in‑flight MOQ‑tail control request tracked by the {@link MOQtailClient}.
|
|
316
|
+
*
|
|
317
|
+
* Each concrete request type encapsulates the original control message plus coordination primitives
|
|
318
|
+
* (e.g. a {@link https://developer.mozilla.org/docs/Web/API/Promise | Promise} facade / stream controller) that resolve when a terminal protocol response
|
|
319
|
+
* (OK / ERROR / CANCEL) is received.
|
|
320
|
+
*
|
|
321
|
+
* Used internally in maps like `MOQtailClient.requests` to look up state by request id without needing
|
|
322
|
+
* multiple heterogeneous collections.
|
|
323
|
+
*
|
|
324
|
+
* Variants:
|
|
325
|
+
* - {@link PublishNamespaceRequest} – pending PUBLISH_NAMESPACE / PUBLISH_NAMESPACE_OK / PUBLISH_NAMESPACE_ERROR.
|
|
326
|
+
* - {@link SubscribeNamespaceRequest} – pending SUBSCRIBE_NAMESPACE sequence.
|
|
327
|
+
* - {@link FetchRequest} – pending FETCH handshake producing a data stream.
|
|
328
|
+
* - {@link SubscribeRequest} – pending SUBSCRIBE producing subgroup object streams.
|
|
329
|
+
*
|
|
330
|
+
* @example Looking up a request by id
|
|
331
|
+
* ```ts
|
|
332
|
+
* function isActive(requests: Map<bigint, MOQtailRequest>, id: bigint) {
|
|
333
|
+
* const req = requests.get(id)
|
|
334
|
+
* if (!req) return false
|
|
335
|
+
* // Narrow by instanceof, e.g. FetchRequest
|
|
336
|
+
* if (req instanceof FetchRequest) {
|
|
337
|
+
* console.log('Fetch still pending for', req.message.requestId)
|
|
338
|
+
* }
|
|
339
|
+
* return true
|
|
340
|
+
* }
|
|
341
|
+
* ```
|
|
342
|
+
*/
|
|
343
|
+
type MOQtailRequest = PublishRequest | PublishNamespaceRequest | SubscribeNamespaceRequest | FetchRequest | SubscribeRequest | TrackStatusRequest;
|
|
344
|
+
/**
|
|
345
|
+
* Whatever holds a track alias in the client's routing table: a {@link SubscribeRequest},
|
|
346
|
+
* or the receiver {@link MOQtailClient.acceptPushedTrack} stands up for a track the peer
|
|
347
|
+
* pushes. Incoming objects are named after the holder of the alias their stream carries.
|
|
348
|
+
*/
|
|
349
|
+
type TrackAliasHolder = {
|
|
350
|
+
requestId: bigint;
|
|
351
|
+
fullTrackName: FullTrackName;
|
|
352
|
+
};
|
|
353
|
+
/**
|
|
354
|
+
* Default for {@link MOQtailClientOptions.trackAliasResolutionTimeoutMs}: how long a
|
|
355
|
+
* data stream waits for the control message that establishes its track alias.
|
|
356
|
+
*
|
|
357
|
+
* A subscription's data streams and the SUBSCRIBE_OK naming their alias travel on
|
|
358
|
+
* separate streams, so nothing orders them; the data can arrive first. Waiting costs
|
|
359
|
+
* a stalled reader, giving up costs the whole subgroup, so the wait is generous.
|
|
360
|
+
*/
|
|
361
|
+
declare const DEFAULT_TRACK_ALIAS_RESOLUTION_TIMEOUT_MS = 2000;
|
|
362
|
+
/**
|
|
363
|
+
* Default for {@link MOQtailClientOptions.switchDrainTimeoutMs}: how long a track a
|
|
364
|
+
* soft switch handed over from may stay quiet before it is retired anyway.
|
|
365
|
+
*
|
|
366
|
+
* A soft switch leaves that track delivering up to the group the new one starts at,
|
|
367
|
+
* so the two meet without a hole, and a PUBLISH_DONE normally ends it. This is the
|
|
368
|
+
* backstop for a publisher that never sends one.
|
|
369
|
+
*/
|
|
370
|
+
declare const DEFAULT_SWITCH_DRAIN_TIMEOUT_MS = 2000;
|
|
371
|
+
/**
|
|
372
|
+
* Default for {@link MOQtailClientOptions.fillOpenTimeoutMs}: how long after SUBSCRIBE_OK
|
|
373
|
+
* a fill fetch stream may take to open before ordering stops waiting for it.
|
|
374
|
+
*/
|
|
375
|
+
declare const DEFAULT_FILL_OPEN_TIMEOUT_MS = 1000;
|
|
376
|
+
/**
|
|
377
|
+
* @public
|
|
378
|
+
* The MAX_FILTER_RANGES a client advertises when its setup options set none: how
|
|
379
|
+
* many Range Filter ranges it applies, in total, for one subscription or fetch.
|
|
380
|
+
*/
|
|
381
|
+
declare const DEFAULT_MAX_FILTER_RANGES = 32n;
|
|
382
|
+
/**
|
|
383
|
+
* Options for the {@link MOQtailClient} constructor: connection target, protocol
|
|
384
|
+
* negotiation, and timeouts. Nothing happens on the network until
|
|
385
|
+
* {@link MOQtailClient.init}.
|
|
386
|
+
*
|
|
387
|
+
* @example
|
|
388
|
+
* ```ts
|
|
389
|
+
* const client = new MOQtailClient({
|
|
390
|
+
* url: relayUrl,
|
|
391
|
+
* dataStreamTimeoutMs: 5000,
|
|
392
|
+
* controlStreamTimeoutMs: 1500,
|
|
393
|
+
* })
|
|
394
|
+
* client.on('sessionterminated', (r) => console.warn('terminated', r))
|
|
395
|
+
* await client.init()
|
|
396
|
+
* ```
|
|
397
|
+
*/
|
|
398
|
+
type MOQtailClientOptions = {
|
|
399
|
+
/** Relay / server endpoint for the underlying {@link https://developer.mozilla.org/docs/Web/API/WebTransport | WebTransport} session (can be absolute {@link https://developer.mozilla.org/en-US/docs/Web/API/URL | URL} or string).*/
|
|
400
|
+
url: string | URL;
|
|
401
|
+
/** {@link SetupOptions} customizations; if omitted a default instance is built.*/
|
|
402
|
+
setupOptions?: SetupOptions;
|
|
403
|
+
/** Passed directly to the browser's {@link https://developer.mozilla.org/docs/Web/API/WebTransport | WebTransport} constructor for {@link https://developer.mozilla.org/docs/Web/API/WebTransportOptions | WebTransportOptions}. */
|
|
404
|
+
transportOptions?: WebTransportOptions & {
|
|
405
|
+
protocols?: string[];
|
|
406
|
+
};
|
|
407
|
+
/** Per *data* uni-stream idle timeout in milliseconds. */
|
|
408
|
+
dataStreamTimeoutMs?: number;
|
|
409
|
+
/** Control stream read timeout in milliseconds. */
|
|
410
|
+
controlStreamTimeoutMs?: number;
|
|
411
|
+
/**
|
|
412
|
+
* How long a data stream waits for the control message that establishes its track
|
|
413
|
+
* alias before the stream is abandoned, in milliseconds. Defaults to
|
|
414
|
+
* {@link DEFAULT_TRACK_ALIAS_RESOLUTION_TIMEOUT_MS}.
|
|
415
|
+
*/
|
|
416
|
+
trackAliasResolutionTimeoutMs?: number;
|
|
417
|
+
/**
|
|
418
|
+
* How long a track a soft switch handed over from may stay quiet before it is
|
|
419
|
+
* retired anyway, in milliseconds. Defaults to
|
|
420
|
+
* {@link DEFAULT_SWITCH_DRAIN_TIMEOUT_MS}.
|
|
421
|
+
*/
|
|
422
|
+
switchDrainTimeoutMs?: number;
|
|
423
|
+
/**
|
|
424
|
+
* How long after SUBSCRIBE_OK a fill fetch stream may take to open before ordering
|
|
425
|
+
* stops waiting for it, in milliseconds. Defaults to {@link DEFAULT_FILL_OPEN_TIMEOUT_MS}.
|
|
426
|
+
*
|
|
427
|
+
* A fill that opens later still orders against what is held, but its objects at or
|
|
428
|
+
* before what was already released come late (`flush`) or are dropped (`drop`), and no
|
|
429
|
+
* `orderinggap` reports them. Raise it on paths whose RTT nears it.
|
|
430
|
+
*/
|
|
431
|
+
fillOpenTimeoutMs?: number;
|
|
432
|
+
/** If true, enables datagram support for the session. */
|
|
433
|
+
enableDatagrams?: boolean;
|
|
434
|
+
/** The default {@link ObjectOrdering} of the session's subscriptions and fetches. Without one, objects pass through unordered. */
|
|
435
|
+
ordering?: ObjectOrdering | 'none';
|
|
436
|
+
};
|
|
437
|
+
/**
|
|
438
|
+
* @public
|
|
439
|
+
* Releases a request's objects in location order, however the publisher maps them to
|
|
440
|
+
* streams or datagrams. An object goes out once its predecessor has; IDs are taken to
|
|
441
|
+
* increase by 1 unless a Prior Group ID Gap or Prior Object ID Gap says otherwise. An
|
|
442
|
+
* object whose predecessor is missing waits within `window`, then the client releases
|
|
443
|
+
* what it holds up to it and reports the skipped locations with `orderinggap`.
|
|
444
|
+
* Requests with descending group order are left unordered.
|
|
445
|
+
*/
|
|
446
|
+
interface ObjectOrdering {
|
|
447
|
+
/** How long an object may wait, and how many may be held, before the client stops waiting. */
|
|
448
|
+
window: {
|
|
449
|
+
durationMs?: number;
|
|
450
|
+
objects?: number;
|
|
451
|
+
};
|
|
452
|
+
/** What happens to an object that arrives after the client stopped waiting for it: released anyway (default) or dropped. */
|
|
453
|
+
onWindowExceeded?: 'flush' | 'drop';
|
|
454
|
+
/** Object IDs may skip without a Prior Object ID Gap. */
|
|
455
|
+
sparseObjectIds?: boolean;
|
|
456
|
+
/** Group IDs may skip without a Prior Group ID Gap. */
|
|
457
|
+
sparseGroupIds?: boolean;
|
|
458
|
+
}
|
|
459
|
+
/**
|
|
460
|
+
* @public
|
|
461
|
+
* Every event a {@link MOQtailClient} emits, keyed by name, with the listener signature
|
|
462
|
+
* each one calls. Attach with `on()`.
|
|
463
|
+
*/
|
|
464
|
+
interface ClientEvents {
|
|
465
|
+
/** A GOAWAY arrived: the session is winding down, or a request is moving to a new session. */
|
|
466
|
+
goaway: (msg: GoAway) => void;
|
|
467
|
+
/** The session ended, normally or on error. Fires once, with the reason given to `disconnect`. */
|
|
468
|
+
sessionterminated: (reason?: unknown) => void;
|
|
469
|
+
/** A control message was written, on the control stream or a request stream. */
|
|
470
|
+
messagesent: (msg: ControlMessage) => void;
|
|
471
|
+
/** A control message arrived, before it is handled. */
|
|
472
|
+
messagereceived: (msg: ControlMessage) => void;
|
|
473
|
+
/** A data stream header or object was decoded. */
|
|
474
|
+
datareceived: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void;
|
|
475
|
+
/** A data stream header or object was written. */
|
|
476
|
+
datasent: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void;
|
|
477
|
+
/** A data stream opened, carried an object (identity and size only), or ended. */
|
|
478
|
+
dataevent: (event: DataEvent) => void;
|
|
479
|
+
/** A datagram arrived. */
|
|
480
|
+
datagramreceived: (data: Datagram) => void;
|
|
481
|
+
/** A datagram was written. */
|
|
482
|
+
datagramsent: (data: Datagram) => void;
|
|
483
|
+
/**
|
|
484
|
+
* An ordered request stopped waiting for expected locations: from `from` (inclusive) to
|
|
485
|
+
* `to` (exclusive), the next object it released. See {@link ObjectOrdering}.
|
|
486
|
+
*/
|
|
487
|
+
orderinggap: (requestId: bigint, from: Location, to: Location) => void;
|
|
488
|
+
/** A PUBLISH_NAMESPACE arrived. */
|
|
489
|
+
namespacepublished: (msg: PublishNamespace) => void;
|
|
490
|
+
/**
|
|
491
|
+
* The peer moved the Forward State of a track this side publishes, in its PUBLISH_OK
|
|
492
|
+
* or a later REQUEST_UPDATE. `requestId` is the one {@link MOQtailClient.publish}
|
|
493
|
+
* returned. A publication that declared FORWARD=0 sends nothing until this reports `true`.
|
|
494
|
+
*/
|
|
495
|
+
forwardstatechange: (requestId: bigint, forward: boolean) => void;
|
|
496
|
+
/**
|
|
497
|
+
* The peer pushed a track. Only one reader can lock `stream`, so listeners check the
|
|
498
|
+
* track first and only the one that wants it reads it.
|
|
499
|
+
*/
|
|
500
|
+
peerpublish: (msg: Publish, stream: ReadableStream<MoqtObject>) => void;
|
|
501
|
+
/**
|
|
502
|
+
* A PUBLISH_DONE arrived. `requestId` is the request its stream opened: for a pushed
|
|
503
|
+
* track, the `requestId` of the {@link Publish} from `peerpublish`.
|
|
504
|
+
*/
|
|
505
|
+
peerpublishdone: (msg: PublishDone, requestId: bigint) => void;
|
|
506
|
+
/**
|
|
507
|
+
* The peer has a track matching a {@link MOQtailClient.subscribeTracks} prefix but no
|
|
508
|
+
* stream to send its PUBLISH on yet (§10.20). `prefix` is the subscribed prefix.
|
|
509
|
+
*/
|
|
510
|
+
peerpublishskipped: (prefix: Tuple, msg: PublishSkipped) => void;
|
|
511
|
+
/** A SUBSCRIBE_NAMESPACE arrived. */
|
|
512
|
+
peersubscribenamespace: (msg: SubscribeNamespace) => void;
|
|
513
|
+
/**
|
|
514
|
+
* A SUBSCRIBE_TRACKS arrived. The PUBLISH sent for each matching track states the
|
|
515
|
+
* request's settings from `MessageParameter.publishParametersFor(msg.parameters)`, and
|
|
516
|
+
* goes without Track Properties when `MessageParameter.includesProperties(msg.parameters)`
|
|
517
|
+
* is false.
|
|
518
|
+
*/
|
|
519
|
+
peersubscribetracks: (msg: SubscribeTracks) => void;
|
|
520
|
+
/** A NAMESPACE arrived on a SUBSCRIBE_NAMESPACE stream. */
|
|
521
|
+
peernamespace: (prefix: Tuple, suffix: Tuple) => void;
|
|
522
|
+
/** A NAMESPACE_DONE arrived on a SUBSCRIBE_NAMESPACE stream. */
|
|
523
|
+
peernamespacedone: (prefix: Tuple, suffix: Tuple) => void;
|
|
524
|
+
}
|
|
525
|
+
/**
|
|
526
|
+
* @public
|
|
527
|
+
* What {@link MOQtailClient.subscribe} returns when the subscription is accepted.
|
|
528
|
+
*/
|
|
529
|
+
interface SubscribeResult {
|
|
530
|
+
requestId: bigint;
|
|
531
|
+
/** The SUBSCRIBE_OK: track alias, parameters, and track properties. */
|
|
532
|
+
subscribeOk: SubscribeOk;
|
|
533
|
+
stream: ReadableStream<MoqtObject>;
|
|
534
|
+
/**
|
|
535
|
+
* Resolves once the subscription, and every subscription switched from it, is over:
|
|
536
|
+
* with the last one's PUBLISH_DONE, or `undefined` if it ended without one. Never rejects.
|
|
537
|
+
*/
|
|
538
|
+
done: Promise<PublishDone | undefined>;
|
|
539
|
+
}
|
|
540
|
+
/**
|
|
541
|
+
* @public
|
|
542
|
+
* What {@link MOQtailClient.fetch} returns when the fetch is accepted.
|
|
543
|
+
*/
|
|
544
|
+
interface FetchResult {
|
|
545
|
+
requestId: bigint;
|
|
546
|
+
/** The FETCH_OK: end of track, end location, and track properties. */
|
|
547
|
+
fetchOk: FetchOk;
|
|
548
|
+
stream: ReadableStream<MoqtObject>;
|
|
549
|
+
}
|
|
550
|
+
/**
|
|
551
|
+
* Called for an End of Range marker on a fetch stream: every Location after the
|
|
552
|
+
* previous Object, if any, up to and including `location`, does not exist, is unknown,
|
|
553
|
+
* or timed out, as `kind` says. Without it, an unknown or timed-out range looks the
|
|
554
|
+
* same as one that does not exist.
|
|
555
|
+
*/
|
|
556
|
+
type EndOfRangeHandler = (kind: EndOfRangeKind, location: Location) => void;
|
|
557
|
+
/**
|
|
558
|
+
* Parameters for {@link MOQtailClient.subscribe | subscribing} to a track's live objects.
|
|
559
|
+
*
|
|
560
|
+
* @example From the next object
|
|
561
|
+
* ```ts
|
|
562
|
+
* await client.subscribe({
|
|
563
|
+
* fullTrackName,
|
|
564
|
+
* priority: 0,
|
|
565
|
+
* groupOrder: GroupOrder.Original,
|
|
566
|
+
* forward: true,
|
|
567
|
+
* locationFilter: new LocationFilter(LocationFilterType.NextObject)
|
|
568
|
+
* })
|
|
569
|
+
* ```
|
|
570
|
+
* @example Groups 100 through 120
|
|
571
|
+
* ```ts
|
|
572
|
+
* await client.subscribe({
|
|
573
|
+
* fullTrackName,
|
|
574
|
+
* priority: 32,
|
|
575
|
+
* groupOrder: GroupOrder.Original,
|
|
576
|
+
* forward: true,
|
|
577
|
+
* locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 100n, 0n, 120n)
|
|
578
|
+
* })
|
|
579
|
+
* ```
|
|
580
|
+
* @example From the next object, filling the current group from its start
|
|
581
|
+
* ```ts
|
|
582
|
+
* await client.subscribe({
|
|
583
|
+
* fullTrackName,
|
|
584
|
+
* priority: 0,
|
|
585
|
+
* groupOrder: GroupOrder.Original,
|
|
586
|
+
* locationFilter: new LocationFilter(LocationFilterType.NextObject),
|
|
587
|
+
* parameters: [new FillParameters([new LocationFilter(LocationFilterType.RelativeStart, 1n)])]
|
|
588
|
+
* })
|
|
589
|
+
* ```
|
|
590
|
+
*/
|
|
591
|
+
type SubscribeOptions = {
|
|
592
|
+
/** Fully qualified track identifier ({@link FullTrackName}). */
|
|
593
|
+
fullTrackName: FullTrackName;
|
|
594
|
+
/** Subscriber priority (0 = highest, 255 = lowest). Values outside range are clamped. Fractional values are rounded. */
|
|
595
|
+
priority: number;
|
|
596
|
+
/** Desired {@link (GroupOrder:enum)} (e.g. {@link (GroupOrder:enum).Original}) specifying delivery ordering semantics. */
|
|
597
|
+
groupOrder: GroupOrder;
|
|
598
|
+
/** If present, forward parameter (0x10) is sent with the provided value */
|
|
599
|
+
forward?: boolean;
|
|
600
|
+
/** The {@link LocationFilter} selecting which Objects to deliver. Omitted, the subscription is unfiltered. */
|
|
601
|
+
locationFilter?: LocationFilter;
|
|
602
|
+
/**
|
|
603
|
+
* Optional extension parameters appended to the SUBSCRIBE control message. A
|
|
604
|
+
* FILL_PARAMETERS here also retrieves already-published Objects on a fill fetch stream.
|
|
605
|
+
*/
|
|
606
|
+
parameters?: MessageParameter[];
|
|
607
|
+
/** Per-subscription early discard policy. Overrides the client-level default set via {@link MOQtailClient.setEarlyDiscardPolicy}. */
|
|
608
|
+
earlyDiscardPolicy?: EarlyDiscardPolicyConfig;
|
|
609
|
+
/** Called for each End of Range marker on the subscription's fill fetch streams. */
|
|
610
|
+
onEndOfRange?: EndOfRangeHandler;
|
|
611
|
+
/** Orders this subscription's objects, its fill included. Overrides {@link MOQtailClientOptions.ordering}. */
|
|
612
|
+
ordering?: ObjectOrdering | 'none';
|
|
613
|
+
};
|
|
614
|
+
/**
|
|
615
|
+
* Changes applied to an existing SUBSCRIBE via {@link MOQtailClient.subscribeUpdate}.
|
|
616
|
+
*
|
|
617
|
+
* @example Narrowing a live window to groups 200 through 210
|
|
618
|
+
* ```ts
|
|
619
|
+
* await client.subscribeUpdate({
|
|
620
|
+
* subscriptionRequestId,
|
|
621
|
+
* locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 200n, 0n, 210n),
|
|
622
|
+
* priority: 16,
|
|
623
|
+
* forward: true
|
|
624
|
+
* })
|
|
625
|
+
* ```
|
|
626
|
+
*/
|
|
627
|
+
type SubscribeUpdateOptions = {
|
|
628
|
+
/** The original SUBSCRIBE request id (bigint) being updated. */
|
|
629
|
+
subscriptionRequestId: bigint;
|
|
630
|
+
/** The new {@link LocationFilter}. Omitted, the subscription keeps its own. */
|
|
631
|
+
locationFilter?: LocationFilter;
|
|
632
|
+
/** Updated subscriber priority (same constraints as initial subscribe). 0 is highest, 255 is lowest. Omitted, it's not sent and stays unchanged. */
|
|
633
|
+
priority?: number;
|
|
634
|
+
/** Updated direction flag. Omitted, it's not sent and stays unchanged. */
|
|
635
|
+
forward?: boolean;
|
|
636
|
+
/** Optional additional parameters; existing parameters persist if omitted. */
|
|
637
|
+
parameters?: MessageParameter[];
|
|
638
|
+
};
|
|
639
|
+
/**
|
|
640
|
+
* Parameters for {@link MOQtailClient.switch | switching} an existing SUBSCRIBE to a new track.
|
|
641
|
+
*
|
|
642
|
+
* @example Switching a subscription to a new track
|
|
643
|
+
* ```ts
|
|
644
|
+
* await client.switch({
|
|
645
|
+
* switchFromRequestId,
|
|
646
|
+
* switchMode: SwitchMode.Soft,
|
|
647
|
+
* newSubscribeOptions: {
|
|
648
|
+
* fullTrackName: newFullTrackName,
|
|
649
|
+
* priority: 0,
|
|
650
|
+
* groupOrder: GroupOrder.Original,
|
|
651
|
+
* locationFilter: new LocationFilter(LocationFilterType.NextObject)
|
|
652
|
+
* }
|
|
653
|
+
* })
|
|
654
|
+
* ```
|
|
655
|
+
*/
|
|
656
|
+
type SwitchOptions = {
|
|
657
|
+
/** The original SUBSCRIBE request id (bigint) being switched from. */
|
|
658
|
+
switchFromRequestId: bigint;
|
|
659
|
+
/** {@link SwitchMode} controlling how the switch is applied. */
|
|
660
|
+
switchMode: SwitchMode;
|
|
661
|
+
/** New subscription options to switch to. No `forward`: the relay controls forwarding during a switch. */
|
|
662
|
+
newSubscribeOptions: Omit<SubscribeOptions, 'forward'>;
|
|
663
|
+
/**
|
|
664
|
+
* Called for each object of a superseded subscription that a soft switch left draining.
|
|
665
|
+
* Returning false ends the drain: that subscription is retired and the new track's
|
|
666
|
+
* objects, held until then, are released.
|
|
667
|
+
*/
|
|
668
|
+
onDrainDecision?: (request: SubscribeRequest) => boolean;
|
|
669
|
+
};
|
|
670
|
+
/**
|
|
671
|
+
* Configuration for the early discard policy applied to incoming subgroup streams.
|
|
672
|
+
*/
|
|
673
|
+
type EarlyDiscardPolicyConfig = {
|
|
674
|
+
/** Cancel a subgroup QUIC stream if it has not fully completed within this many milliseconds. */
|
|
675
|
+
subgroupReceiveTimeout: number;
|
|
676
|
+
};
|
|
677
|
+
/**
|
|
678
|
+
* Options for {@link MOQtailClient.fetch | performing a FETCH} of Objects already published.
|
|
679
|
+
*
|
|
680
|
+
* @example Groups 10 through 12, inclusive
|
|
681
|
+
* ```ts
|
|
682
|
+
* const { requestId, stream } = await client.fetch({
|
|
683
|
+
* fullTrackName,
|
|
684
|
+
* priority: 64,
|
|
685
|
+
* groupOrder: GroupOrder.Original,
|
|
686
|
+
* locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 10n, 0n, 12n)
|
|
687
|
+
* })
|
|
688
|
+
* ```
|
|
689
|
+
* @example The current group and the one before it
|
|
690
|
+
* ```ts
|
|
691
|
+
* await client.fetch({
|
|
692
|
+
* fullTrackName,
|
|
693
|
+
* priority: 32,
|
|
694
|
+
* groupOrder: GroupOrder.Original,
|
|
695
|
+
* locationFilter: new LocationFilter(LocationFilterType.RelativeStart, 2n)
|
|
696
|
+
* })
|
|
697
|
+
* ```
|
|
698
|
+
*/
|
|
699
|
+
type FetchOptions = {
|
|
700
|
+
/** Request priority (0 = highest, 255 = lowest). Rounded & clamped. */
|
|
701
|
+
priority: number;
|
|
702
|
+
/** {@link (GroupOrder:enum)} governing sequencing. */
|
|
703
|
+
groupOrder: GroupOrder;
|
|
704
|
+
/** Fully qualified track identifier ({@link FullTrackName}). */
|
|
705
|
+
fullTrackName: FullTrackName;
|
|
706
|
+
/**
|
|
707
|
+
* Which Objects to fetch; the end, when the filter has one, is the last Object
|
|
708
|
+
* sent. Without a filter the whole track up to the Largest Object is fetched, and
|
|
709
|
+
* a filter without an end also stops at the Largest Object.
|
|
710
|
+
*/
|
|
711
|
+
locationFilter?: LocationFilter;
|
|
712
|
+
/** Optional parameters block. */
|
|
713
|
+
parameters?: MessageParameter[];
|
|
714
|
+
/** Called for each End of Range marker in the response. */
|
|
715
|
+
onEndOfRange?: EndOfRangeHandler;
|
|
716
|
+
/** Orders this fetch's objects. Overrides {@link MOQtailClientOptions.ordering}. */
|
|
717
|
+
ordering?: ObjectOrdering | 'none';
|
|
718
|
+
};
|
|
719
|
+
/**
|
|
720
|
+
* Send half of the control plane: a unidirectional stream this endpoint opens and
|
|
721
|
+
* whose first message must be SETUP.
|
|
722
|
+
*/
|
|
723
|
+
declare class ControlSendStream {
|
|
724
|
+
#private;
|
|
725
|
+
/** @param events - Receives `messagesent` for every message written. */
|
|
726
|
+
constructor(writeStream: WritableStream<Uint8Array>, events?: Emitter<ClientEvents>);
|
|
727
|
+
send(message: ControlMessage): Promise<void>;
|
|
728
|
+
close(): Promise<void>;
|
|
729
|
+
}
|
|
730
|
+
/**
|
|
731
|
+
* Receive half of the control plane: the unidirectional stream the peer opens,
|
|
732
|
+
* whose first message must be SETUP.
|
|
733
|
+
*/
|
|
734
|
+
declare class ControlRecvStream {
|
|
735
|
+
#private;
|
|
736
|
+
readonly stream: ReadableStream<ControlMessage>;
|
|
737
|
+
/** @param events - Receives `messagereceived` for every message decoded. */
|
|
738
|
+
constructor(readStream: ReadableStream<Uint8Array>, partialMessageTimeoutMs?: number, events?: Emitter<ClientEvents>);
|
|
739
|
+
close(): Promise<void>;
|
|
740
|
+
}
|
|
741
|
+
/**
|
|
742
|
+
* The control plane as a whole: the two independent unidirectional halves opened by
|
|
743
|
+
* each endpoint.
|
|
744
|
+
*/
|
|
745
|
+
declare class ControlStream {
|
|
746
|
+
#private;
|
|
747
|
+
readonly stream: ReadableStream<ControlMessage>;
|
|
748
|
+
constructor(sendHalf: ControlSendStream, recvHalf: ControlRecvStream);
|
|
749
|
+
send(message: ControlMessage): Promise<void>;
|
|
750
|
+
close(): Promise<void>;
|
|
751
|
+
}
|
|
752
|
+
/**
|
|
753
|
+
* In‑memory index of {@link MoqtObject} instances keyed by their {@link Location} (group/subgroup/object),
|
|
754
|
+
* providing ordered insertion and range queries.
|
|
755
|
+
*
|
|
756
|
+
* Implementations MUST keep objects sorted ascending by (groupId, objectId) so binary searches can
|
|
757
|
+
* locate insertion points / range bounds efficiently. Subgroup ordinality is currently ignored for ordering
|
|
758
|
+
* (adjust if protocol semantics require finer granularity later).
|
|
759
|
+
*
|
|
760
|
+
* @example Typical usage
|
|
761
|
+
* ```ts
|
|
762
|
+
* const cache: ObjectCache = new MemoryObjectCache()
|
|
763
|
+
* cache.add(obj)
|
|
764
|
+
* const window = cache.getRange(startLoc, endLoc)
|
|
765
|
+
* const exact = cache.getByLocation(loc)
|
|
766
|
+
* ```
|
|
767
|
+
*
|
|
768
|
+
* Concurrency: Implementations here are not thread‑safe; callers avoid concurrent mutation from workers.
|
|
769
|
+
*/
|
|
770
|
+
interface ObjectCache {
|
|
771
|
+
/** Insert a new {@link MoqtObject}, preserving sorted order (duplicates allowed or replaced impl‑defined). */
|
|
772
|
+
add(obj: MoqtObject): void;
|
|
773
|
+
/** Return a shallow copy array of objects whose Location is \>= start and \< end (end exclusive). */
|
|
774
|
+
getRange(start?: Location, end?: Location): MoqtObject[];
|
|
775
|
+
/** Return the object whose Location exactly matches (group & object) or undefined if absent. */
|
|
776
|
+
getByLocation(location: Location): MoqtObject | undefined;
|
|
777
|
+
/** Current number of cached objects. */
|
|
778
|
+
size(): number;
|
|
779
|
+
/** Remove all cached objects. */
|
|
780
|
+
clear(): void;
|
|
781
|
+
}
|
|
782
|
+
declare class MemoryObjectCache implements ObjectCache {
|
|
783
|
+
private objects;
|
|
784
|
+
add(obj: MoqtObject): void;
|
|
785
|
+
getRange(start?: Location, end?: Location): MoqtObject[];
|
|
786
|
+
getByLocation(location: Location): MoqtObject | undefined;
|
|
787
|
+
size(): number;
|
|
788
|
+
clear(): void;
|
|
789
|
+
private _findInsertIndex;
|
|
790
|
+
private _findIndex;
|
|
791
|
+
}
|
|
792
|
+
declare class RingBufferObjectCache implements ObjectCache {
|
|
793
|
+
private buffer;
|
|
794
|
+
private maxSize;
|
|
795
|
+
constructor(maxSize?: number);
|
|
796
|
+
add(obj: MoqtObject): void;
|
|
797
|
+
getRange(start?: Location, end?: Location): MoqtObject[];
|
|
798
|
+
getByLocation(location: Location): MoqtObject | undefined;
|
|
799
|
+
size(): number;
|
|
800
|
+
clear(): void;
|
|
801
|
+
private _findInsertIndex;
|
|
802
|
+
private _findIndex;
|
|
803
|
+
}
|
|
804
|
+
/**
|
|
805
|
+
* Source of already-produced (historical) objects for a track.
|
|
806
|
+
* Backed by an {@link ObjectCache} allowing range retrieval using protocol {@link Location}s.
|
|
807
|
+
* Implementations MUST return objects in ascending location order and MAY return an empty array
|
|
808
|
+
* if the requested window is outside the cached range.
|
|
809
|
+
*/
|
|
810
|
+
interface PastObjectSource {
|
|
811
|
+
/** Underlying cache from which objects are served */
|
|
812
|
+
readonly cache: ObjectCache;
|
|
813
|
+
/**
|
|
814
|
+
* Fetch a (closed) range of objects. `start`/`end` are inclusive when provided.
|
|
815
|
+
* Omitted bounds mean: from earliest cached (when `start` undefined) or up to latest cached (when `end` undefined).
|
|
816
|
+
*/
|
|
817
|
+
getRange(start?: Location, end?: Location): Promise<MoqtObject[]>;
|
|
818
|
+
}
|
|
819
|
+
/**
|
|
820
|
+
* Push-oriented live object feed. Wraps a {@link https://developer.mozilla.org/docs/Web/API/ReadableStream | ReadableStream} plus lightweight event subscription helpers.
|
|
821
|
+
* Implementations advance {@link LiveObjectSource.largestLocation | largestLocation} monotonically as objects arrive.
|
|
822
|
+
*/
|
|
823
|
+
interface LiveObjectSource {
|
|
824
|
+
/** Continuous stream yielding objects as they are produced */
|
|
825
|
+
readonly stream: ReadableStream<MoqtObject>;
|
|
826
|
+
/** Highest (latest) location observed so far; undefined until first object */
|
|
827
|
+
readonly largestLocation: Location | undefined;
|
|
828
|
+
/** Register a listener invoked (async) for each new object. Returns an unsubscribe function. */
|
|
829
|
+
onNewObject(listener: (obj: MoqtObject) => void): () => void;
|
|
830
|
+
/** Register a listener invoked when the live stream ends (normal or error). Returns an unsubscribe function. */
|
|
831
|
+
onDone(listener: () => void): () => void;
|
|
832
|
+
/** Stop ingestion and release underlying reader (idempotent). */
|
|
833
|
+
stop(): void;
|
|
834
|
+
}
|
|
835
|
+
/**
|
|
836
|
+
* Aggregates optional historical (`past`) and (`live`) sources for a single track.
|
|
837
|
+
* Either facet may be omitted:
|
|
838
|
+
* - VOD / static content: supply only {@link TrackSource.past | past}
|
|
839
|
+
* - Pure live: supply only {@link TrackSource.live | live}
|
|
840
|
+
* - Hybrid (catch-up + live tail): supply both.
|
|
841
|
+
*
|
|
842
|
+
* Priority handling note: publisher priority is defined on the Track metadata (see `Track.publisherPriority`).
|
|
843
|
+
* The library rounds non-integer values and clamps priority into [0,255] there; this interface simply
|
|
844
|
+
* expresses what content is available, independent of priority semantics.
|
|
845
|
+
*/
|
|
846
|
+
interface TrackSource {
|
|
847
|
+
/** Historical object access (optional) */
|
|
848
|
+
readonly past?: PastObjectSource;
|
|
849
|
+
/** Live object feed (optional) */
|
|
850
|
+
readonly live?: LiveObjectSource;
|
|
851
|
+
}
|
|
852
|
+
declare class StaticTrackSource implements PastObjectSource {
|
|
853
|
+
readonly cache: ObjectCache;
|
|
854
|
+
constructor(cache: ObjectCache);
|
|
855
|
+
getRange(start?: Location, end?: Location): Promise<MoqtObject[]>;
|
|
856
|
+
}
|
|
857
|
+
declare class LiveTrackSource implements LiveObjectSource {
|
|
858
|
+
#private;
|
|
859
|
+
readonly stream: ReadableStream<MoqtObject>;
|
|
860
|
+
constructor(stream: ReadableStream<MoqtObject>);
|
|
861
|
+
get largestLocation(): Location | undefined;
|
|
862
|
+
onNewObject(listener: (obj: MoqtObject) => Promise<void> | void): () => void;
|
|
863
|
+
onDone(listener: () => void): () => void;
|
|
864
|
+
stop(): void;
|
|
865
|
+
}
|
|
866
|
+
declare class HybridTrackSource implements TrackSource {
|
|
867
|
+
readonly past: PastObjectSource;
|
|
868
|
+
readonly live: LiveObjectSource;
|
|
869
|
+
constructor(cache: ObjectCache, stream: ReadableStream<MoqtObject>);
|
|
870
|
+
}
|
|
871
|
+
/**
|
|
872
|
+
* Describes a media/data track known to the client (either published locally or subscribed to).
|
|
873
|
+
*
|
|
874
|
+
*
|
|
875
|
+
* @example Live only track
|
|
876
|
+
* ```ts
|
|
877
|
+
* const liveStream: ReadableStream<MoqtObject> = buildCameraStream()
|
|
878
|
+
* const track: Track = {
|
|
879
|
+
* fullTrackName,
|
|
880
|
+
* trackSource: { live: liveStream },
|
|
881
|
+
* publisherPriority: 0
|
|
882
|
+
* }
|
|
883
|
+
* client.addOrUpdateTrack(track)
|
|
884
|
+
* ```
|
|
885
|
+
*
|
|
886
|
+
* @example Past only track (pre‑recorded cache)
|
|
887
|
+
* ```ts
|
|
888
|
+
* const cache = new MemoryObjectCache()
|
|
889
|
+
* recording.forEach(obj => cache.add(obj))
|
|
890
|
+
* const track: Track = {
|
|
891
|
+
* fullTrackName,
|
|
892
|
+
* trackSource: { past: cache },
|
|
893
|
+
* publisherPriority: 64
|
|
894
|
+
* }
|
|
895
|
+
* client.addOrUpdateTrack(track)
|
|
896
|
+
* ```
|
|
897
|
+
*
|
|
898
|
+
* @example Hybrid (cache + live)
|
|
899
|
+
* ```ts
|
|
900
|
+
* const cache = new MemoryObjectCache()
|
|
901
|
+
* const liveStream = buildLiveReadableStream()
|
|
902
|
+
* const track: Track = {
|
|
903
|
+
* fullTrackName,
|
|
904
|
+
* trackSource: { past: cache, live: liveStream },
|
|
905
|
+
* publisherPriority: 8
|
|
906
|
+
* }
|
|
907
|
+
* client.addOrUpdateTrack(track)
|
|
908
|
+
* ```
|
|
909
|
+
*/
|
|
910
|
+
type Track = {
|
|
911
|
+
/**
|
|
912
|
+
* Globally unique identifier for the track.
|
|
913
|
+
*/
|
|
914
|
+
fullTrackName: FullTrackName;
|
|
915
|
+
/**
|
|
916
|
+
* Accessors for live and/or past objects belonging to this track.
|
|
917
|
+
*/
|
|
918
|
+
trackSource: TrackSource;
|
|
919
|
+
/**
|
|
920
|
+
* 0 (highest) .. 255 (lowest) priority advertised with objects.
|
|
921
|
+
* Values are rounded to nearest integer then clamped between 0 and 255.
|
|
922
|
+
*/
|
|
923
|
+
publisherPriority: number;
|
|
924
|
+
/**
|
|
925
|
+
* Optional compact numeric alias assigned during protocol negotiation.
|
|
926
|
+
*/
|
|
927
|
+
trackAlias?: bigint;
|
|
928
|
+
/**
|
|
929
|
+
* Track properties advertised by the publisher.
|
|
930
|
+
* Set before calling `publish()` to include properties in the PUBLISH message.
|
|
931
|
+
* Populated automatically on the subscriber side when SUBSCRIBE_OK or FETCH_OK is received.
|
|
932
|
+
*/
|
|
933
|
+
trackProperties?: TrackProperty[];
|
|
934
|
+
};
|
|
935
|
+
/**
|
|
936
|
+
* Wraps a WebTransport bidirectional stream carrying one MOQT request.
|
|
937
|
+
* Because a response is correlated by the stream it arrives on, nothing here needs a
|
|
938
|
+
* request id.
|
|
939
|
+
*/
|
|
940
|
+
declare class RequestStream {
|
|
941
|
+
#private;
|
|
942
|
+
readonly stream: ReadableStream<ControlMessage>;
|
|
943
|
+
/**
|
|
944
|
+
* The message this side opened the stream with, kept so the request can be re-issued
|
|
945
|
+
* on a fresh stream when the peer migrates it with a GOAWAY (§10.4). Undefined on a
|
|
946
|
+
* peer-opened stream, which is the peer's request to re-issue, not ours.
|
|
947
|
+
*/
|
|
948
|
+
first?: ControlMessage;
|
|
949
|
+
/**
|
|
950
|
+
* The type of the message that opened this stream, whichever side opened it. It is
|
|
951
|
+
* what the request on this stream *is*, which decides what may follow — a
|
|
952
|
+
* REQUEST_UPDATE is only valid for the types §10.9 lists.
|
|
953
|
+
*/
|
|
954
|
+
openingType?: ControlMessageType;
|
|
955
|
+
/** Set when the request this stream carried has been re-issued on a new stream. */
|
|
956
|
+
migrated: boolean;
|
|
957
|
+
/** @param events - Receives `messagesent` and `messagereceived` for every message on this stream. */
|
|
958
|
+
constructor(biStream: WebTransportBidirectionalStream, events?: Emitter<ClientEvents>);
|
|
959
|
+
/**
|
|
960
|
+
* Opens a new bidi stream and writes `first` on it.
|
|
961
|
+
*
|
|
962
|
+
* @throws :{@link ProtocolViolationError} If `first` is not one of the seven types
|
|
963
|
+
* Table 5 marks `First`; those are the only ones allowed to open a request stream.
|
|
964
|
+
*/
|
|
965
|
+
static open(webTransport: WebTransport, first: ControlMessage, events?: Emitter<ClientEvents>): Promise<RequestStream>;
|
|
966
|
+
/**
|
|
967
|
+
* Reads the next control message off this stream, or `undefined` once the peer has
|
|
968
|
+
* closed or reset it.
|
|
969
|
+
*
|
|
970
|
+
* Takes ownership of {@link RequestStream.stream}'s reader on first use, so callers
|
|
971
|
+
* must not mix `next()` with `stream.getReader()`.
|
|
972
|
+
*/
|
|
973
|
+
next(): Promise<ControlMessage | undefined>;
|
|
974
|
+
send(message: ControlMessage): Promise<void>;
|
|
975
|
+
close(): Promise<void>;
|
|
976
|
+
/**
|
|
977
|
+
* Cancels the request by resetting its stream with `code`.
|
|
978
|
+
*/
|
|
979
|
+
reset(code: StreamResetCode): Promise<void>;
|
|
980
|
+
}
|
|
981
|
+
/**
|
|
982
|
+
* @public
|
|
983
|
+
* Manages the publication of MOQT objects to a subscriber for a specific track.
|
|
984
|
+
* Handles live object streaming, subscription lifecycle, and stream management.
|
|
985
|
+
*/
|
|
986
|
+
declare class SubscribePublication {
|
|
987
|
+
#private;
|
|
988
|
+
private readonly client;
|
|
989
|
+
readonly track: Track;
|
|
990
|
+
private readonly subscribeMsg;
|
|
991
|
+
private readonly requestStream;
|
|
992
|
+
/**
|
|
993
|
+
* The latest location that was published to the subscriber.
|
|
994
|
+
*/
|
|
995
|
+
latestLocation: Location | undefined;
|
|
996
|
+
/**
|
|
997
|
+
* Creates a new SubscribePublication instance.
|
|
998
|
+
* @param client - The MOQT client managing the subscription.
|
|
999
|
+
* @param track - The track being published.
|
|
1000
|
+
* @param subscribeMsg - The subscribe message containing subscription details.
|
|
1001
|
+
* @param requestStream - The bidi request stream the SUBSCRIBE arrived on. Every
|
|
1002
|
+
* message this publication sends back to the subscriber goes on it.
|
|
1003
|
+
* @param largestLocation - The largest location seen so far, used for determining start location.
|
|
1004
|
+
*/
|
|
1005
|
+
constructor(client: MOQtailClient, track: Track, subscribeMsg: Subscribe, requestStream: RequestStream, largestLocation?: Location);
|
|
1006
|
+
/**
|
|
1007
|
+
* Cancels the publication and cleans up resources.
|
|
1008
|
+
* Removes the publication from the client's publication map.
|
|
1009
|
+
*/
|
|
1010
|
+
cancel(): void;
|
|
1011
|
+
/**
|
|
1012
|
+
* Marks the publication as done and sends a PublishDone message to the client.
|
|
1013
|
+
* @param statusCode - The status code indicating why the publication ended.
|
|
1014
|
+
* @throws :{@link InternalError} If sending the message fails.
|
|
1015
|
+
*/
|
|
1016
|
+
done(statusCode: PublishDoneStatusCode): Promise<void>;
|
|
1017
|
+
/**
|
|
1018
|
+
* Updates the subscription parameters and locations based on a RequestUpdate message.
|
|
1019
|
+
* @param msg - The update message containing new request details.
|
|
1020
|
+
* @throws :{@link InvalidFilterError} If the Range Filters the subscription would be
|
|
1021
|
+
* left with cannot be applied; nothing is updated.
|
|
1022
|
+
*/
|
|
1023
|
+
update(msg: RequestUpdate): void;
|
|
1024
|
+
/**
|
|
1025
|
+
* Publishes MOQT objects to the subscriber as they become available.
|
|
1026
|
+
* Handles stream creation, object writing, and stream closure based on subscription parameters.
|
|
1027
|
+
* @throws :{@link InternalError} If the track does not support live content.
|
|
1028
|
+
*/
|
|
1029
|
+
publish(): Promise<void>;
|
|
1030
|
+
}
|
|
1031
|
+
declare class FetchPublication {
|
|
1032
|
+
#private;
|
|
1033
|
+
/** `start` and `end` are the FETCH's range resolved against the Largest Object, inclusive. */
|
|
1034
|
+
constructor(client: MOQtailClient, track: Track, fetchRequest: Fetch, start: Location, end: Location);
|
|
1035
|
+
cancel(): void;
|
|
1036
|
+
/**
|
|
1037
|
+
* Resets the data stream this fetch is being delivered on, which §10.9.1 requires when
|
|
1038
|
+
* a REQUEST_UPDATE for a FETCH fails.
|
|
1039
|
+
*/
|
|
1040
|
+
resetDataStream(code: StreamResetCode): Promise<void>;
|
|
1041
|
+
publish(): Promise<void>;
|
|
1042
|
+
}
|
|
1043
|
+
/**
|
|
1044
|
+
* @public
|
|
1045
|
+
* Manages the proactive publication of MOQT objects from a publisher to the relay.
|
|
1046
|
+
* Handles live object streaming and stream management.
|
|
1047
|
+
*/
|
|
1048
|
+
declare class PublishPublication {
|
|
1049
|
+
#private;
|
|
1050
|
+
private readonly client;
|
|
1051
|
+
readonly track: Track;
|
|
1052
|
+
private readonly publishMsg;
|
|
1053
|
+
/**
|
|
1054
|
+
* The latest location that was published to the relay.
|
|
1055
|
+
*/
|
|
1056
|
+
latestLocation: Location | undefined;
|
|
1057
|
+
/**
|
|
1058
|
+
* Creates a new PublishPublication instance.
|
|
1059
|
+
* @param client - The MOQT client managing the connection.
|
|
1060
|
+
* @param track - The track being proactively published.
|
|
1061
|
+
* @param publishMsg - The publish message that initiated this session.
|
|
1062
|
+
*/
|
|
1063
|
+
constructor(client: MOQtailClient, track: Track, publishMsg: Publish);
|
|
1064
|
+
/**
|
|
1065
|
+
* How many data streams this publication has opened, which is what a PUBLISH_DONE
|
|
1066
|
+
* reports to the subscriber.
|
|
1067
|
+
*/
|
|
1068
|
+
get streamsOpened(): bigint;
|
|
1069
|
+
/**
|
|
1070
|
+
* Whether Objects are being sent right now. False while the peer holds this
|
|
1071
|
+
* publication at FORWARD=0.
|
|
1072
|
+
*/
|
|
1073
|
+
get forwarding(): boolean;
|
|
1074
|
+
/**
|
|
1075
|
+
* Moves the Forward State: false parks the publication, true resumes it. The
|
|
1076
|
+
* application hears about the move through the client's `forwardstatechange` event,
|
|
1077
|
+
* which is where a publisher starts or stops the work behind the track -- a camera
|
|
1078
|
+
* and an encoder cost the same whether or not anything is listening.
|
|
1079
|
+
*/
|
|
1080
|
+
setForwardState(forward: boolean): void;
|
|
1081
|
+
/**
|
|
1082
|
+
* Applies a REQUEST_UPDATE the peer sent on this publication's request stream. It
|
|
1083
|
+
* can move the Forward State and the Range Filters; what a publisher sends, and
|
|
1084
|
+
* when, is otherwise its own to decide.
|
|
1085
|
+
* @throws :{@link InvalidFilterError} If the Range Filters the publication would be
|
|
1086
|
+
* left with cannot be applied; nothing is updated.
|
|
1087
|
+
*/
|
|
1088
|
+
update(msg: RequestUpdate): void;
|
|
1089
|
+
/**
|
|
1090
|
+
* Cancels the publication and cleans up resources.
|
|
1091
|
+
* Removes the publication from the client's publication map.
|
|
1092
|
+
*/
|
|
1093
|
+
cancel(): void;
|
|
1094
|
+
/**
|
|
1095
|
+
* Publishes MOQT objects to the relay as they become available.
|
|
1096
|
+
* Handles stream creation, object writing, and stream closure.
|
|
1097
|
+
* @throws :{@link InternalError} If the track does not support live content.
|
|
1098
|
+
*/
|
|
1099
|
+
publishToRelay(): Promise<void>;
|
|
1100
|
+
}
|
|
1101
|
+
/**
|
|
1102
|
+
* Sends MoqtObjects as WebTransport datagrams.
|
|
1103
|
+
* Parallel to SendStream but for datagram-based delivery.
|
|
1104
|
+
*
|
|
1105
|
+
* @example
|
|
1106
|
+
* ```ts
|
|
1107
|
+
* const sender = await SendDatagramStream.new(client.webTransport.datagrams.writable, trackAlias);
|
|
1108
|
+
* await sender.write(moqtObject);
|
|
1109
|
+
* ```
|
|
1110
|
+
*/
|
|
1111
|
+
declare class SendDatagramStream {
|
|
1112
|
+
#private;
|
|
1113
|
+
constructor(writer: WritableStreamDefaultWriter<Uint8Array>, trackAlias: bigint, events?: Emitter<ClientEvents>);
|
|
1114
|
+
/**
|
|
1115
|
+
* Create a new datagram sender for a specific track.
|
|
1116
|
+
*
|
|
1117
|
+
* @param writeStream - WebTransport datagram writable stream
|
|
1118
|
+
* @param trackAlias - Track alias for this datagram stream
|
|
1119
|
+
* @param events - Receives `datagramsent` for each datagram written
|
|
1120
|
+
* @returns SendDatagramStream instance
|
|
1121
|
+
*/
|
|
1122
|
+
static new(writeStream: WritableStream<Uint8Array>, trackAlias: bigint, events?: Emitter<ClientEvents>): Promise<SendDatagramStream>;
|
|
1123
|
+
/**
|
|
1124
|
+
* Create a datagram sender using an existing shared writer.
|
|
1125
|
+
* Use this when multiple senders need to share a single writer.
|
|
1126
|
+
*
|
|
1127
|
+
* @param writer - Existing WritableStreamDefaultWriter
|
|
1128
|
+
* @param trackAlias - Track alias for this datagram stream
|
|
1129
|
+
* @param events - Receives `datagramsent` for each datagram written
|
|
1130
|
+
* @returns SendDatagramStream instance
|
|
1131
|
+
*/
|
|
1132
|
+
static fromWriter(writer: WritableStreamDefaultWriter<Uint8Array>, trackAlias: bigint, events?: Emitter<ClientEvents>): SendDatagramStream;
|
|
1133
|
+
/**
|
|
1134
|
+
* Write a MoqtObject as a datagram.
|
|
1135
|
+
* Converts to Datagram automatically based on object state.
|
|
1136
|
+
*
|
|
1137
|
+
* @param object - MoqtObject to send (must have Datagram forwarding preference)
|
|
1138
|
+
*/
|
|
1139
|
+
write(object: MoqtObject): Promise<void>;
|
|
1140
|
+
/**
|
|
1141
|
+
* Close the datagram writer.
|
|
1142
|
+
*/
|
|
1143
|
+
close(): Promise<void>;
|
|
1144
|
+
/**
|
|
1145
|
+
* Release the writer lock without closing.
|
|
1146
|
+
*/
|
|
1147
|
+
releaseLock(): void;
|
|
1148
|
+
}
|
|
1149
|
+
/**
|
|
1150
|
+
* @public
|
|
1151
|
+
* Represents a Media Over QUIC Transport (MOQT) client session.
|
|
1152
|
+
*
|
|
1153
|
+
* Construct it, attach listeners with `on()`, then call {@link MOQtailClient.init} to open the
|
|
1154
|
+
* session. Once initialized, the client provides high-level methods for MOQT requests and publishing. If a protocol
|
|
1155
|
+
* violation occurs, the client terminates; a new client is needed to reconnect.
|
|
1156
|
+
*
|
|
1157
|
+
* ## Usage
|
|
1158
|
+
*
|
|
1159
|
+
* ### Connect and Subscribe to a Track
|
|
1160
|
+
* ```ts
|
|
1161
|
+
* const client = new MOQtailClient({ url });
|
|
1162
|
+
* client.on('sessionterminated', (reason) => console.warn('Session ended:', reason));
|
|
1163
|
+
* await client.init();
|
|
1164
|
+
* const result = await client.subscribe({
|
|
1165
|
+
* fullTrackName,
|
|
1166
|
+
* locationFilter: new LocationFilter(LocationFilterType.NextObject),
|
|
1167
|
+
* forward: true,
|
|
1168
|
+
* groupOrder: GroupOrder.Original,
|
|
1169
|
+
* priority: 0
|
|
1170
|
+
* });
|
|
1171
|
+
* if (!(result instanceof RequestError)) {
|
|
1172
|
+
* for await (const object of result.stream) {
|
|
1173
|
+
* // Consume MOQT objects
|
|
1174
|
+
* }
|
|
1175
|
+
* }
|
|
1176
|
+
* ```
|
|
1177
|
+
*
|
|
1178
|
+
* ### Publish a namespace for Publishing
|
|
1179
|
+
* ```ts
|
|
1180
|
+
* const client = new MOQtailClient({ url });
|
|
1181
|
+
* await client.init();
|
|
1182
|
+
* const publishNamespaceResult = await client.publishNamespace(["camera", "main"]);
|
|
1183
|
+
* if (!(publishNamespaceResult instanceof RequestError)) {
|
|
1184
|
+
* // Ready to publish objects under this namespace
|
|
1185
|
+
* }
|
|
1186
|
+
* ```
|
|
1187
|
+
*
|
|
1188
|
+
* ### Graceful Shutdown
|
|
1189
|
+
* ```ts
|
|
1190
|
+
* await client.disconnect();
|
|
1191
|
+
* ```
|
|
1192
|
+
*/
|
|
1193
|
+
declare class MOQtailClient extends Emitter<ClientEvents> {
|
|
1194
|
+
#private;
|
|
1195
|
+
/**
|
|
1196
|
+
* Namespace prefixes (tuples) the peer has requested announce notifications for via SUBSCRIBE_NAMESPACE.
|
|
1197
|
+
* Used to decide which locally issued ANNOUNCE messages should be forwarded (future optimization: prefix trie).
|
|
1198
|
+
*/
|
|
1199
|
+
readonly peerSubscribeNamespace: Set<Tuple>;
|
|
1200
|
+
/**
|
|
1201
|
+
* Namespace prefixes this client has subscribed to (issued SUBSCRIBE_NAMESPACE). Enables automatic filtering
|
|
1202
|
+
* of incoming NAMESPACE / NAMESPACE_DONE. Maintained locally; no dedupe of overlapping / shadowing prefixes yet.
|
|
1203
|
+
*/
|
|
1204
|
+
readonly subscribedNamespaces: Set<Tuple>;
|
|
1205
|
+
readonly subscribedTracks: Set<Tuple>;
|
|
1206
|
+
/**
|
|
1207
|
+
* Track namespaces this client has successfully published (received REQUEST_OK). Source of truth for
|
|
1208
|
+
* deciding what to withdraw on teardown or targeted removal (future optimization: prefix trie).
|
|
1209
|
+
*/
|
|
1210
|
+
readonly publishedNamespaces: Set<Tuple>;
|
|
1211
|
+
/**
|
|
1212
|
+
* Locally registered track definitions keyed by full track name string. Populated via addOrUpdateTrack.
|
|
1213
|
+
* Does not imply the track has been announced or has active publications.
|
|
1214
|
+
*/
|
|
1215
|
+
readonly trackSources: Map<string, Track>;
|
|
1216
|
+
/**
|
|
1217
|
+
* All in‑flight request objects keyed by requestId (SUBSCRIBE, FETCH, ANNOUNCE, etc). Facilitates lookup
|
|
1218
|
+
* when responses / data arrive. Entries are removed on completion or error.
|
|
1219
|
+
*/
|
|
1220
|
+
readonly requests: Map<bigint, MOQtailRequest>;
|
|
1221
|
+
/**
|
|
1222
|
+
* Active publications (SUBSCRIBE or FETCH) keyed by requestId to manage object stream controllers and lifecycle.
|
|
1223
|
+
* Subset / specialization view of `requests`.
|
|
1224
|
+
*/
|
|
1225
|
+
readonly publications: Map<bigint, SubscribePublication | FetchPublication | PublishPublication>;
|
|
1226
|
+
/**
|
|
1227
|
+
* Active SUBSCRIBE request wrappers keyed by track alias for rapid alias -\> subscription resolution during
|
|
1228
|
+
* incoming unidirectional data handling.
|
|
1229
|
+
*/
|
|
1230
|
+
readonly subscriptions: Map<bigint, any>;
|
|
1231
|
+
/**
|
|
1232
|
+
* Bidirectional track alias \<-\> subscription requestId mapping
|
|
1233
|
+
*/
|
|
1234
|
+
readonly subscriptionAliasMap: Map<bigint, bigint>;
|
|
1235
|
+
/**
|
|
1236
|
+
* Bidirectional requestId \<-\> full track name mapping to reconstruct metadata for incoming objects.
|
|
1237
|
+
*/
|
|
1238
|
+
readonly requestIdMap: RequestIdMap;
|
|
1239
|
+
/**
|
|
1240
|
+
* Maps track aliases to full track names for quick resolution during data handling.
|
|
1241
|
+
*/
|
|
1242
|
+
readonly aliasFullTrackNameMap: Map<bigint, FullTrackName>;
|
|
1243
|
+
/** Underlying WebTransport session (set by {@link MOQtailClient.init}). */
|
|
1244
|
+
webTransport: WebTransport;
|
|
1245
|
+
/** Outgoing / incoming control message stream pair. */
|
|
1246
|
+
controlStream: ControlStream;
|
|
1247
|
+
/** Timeout (ms) applied to reading incoming data streams; undefined =\> no explicit timeout. */
|
|
1248
|
+
dataStreamTimeoutMs?: number;
|
|
1249
|
+
/** Timeout (ms) for control stream read operations; undefined =\> no explicit timeout. */
|
|
1250
|
+
controlStreamTimeoutMs?: number;
|
|
1251
|
+
/**
|
|
1252
|
+
* How long (ms) an incoming data stream waits for the control message that establishes
|
|
1253
|
+
* its track alias before the stream is abandoned.
|
|
1254
|
+
*/
|
|
1255
|
+
trackAliasResolutionTimeoutMs: number;
|
|
1256
|
+
/**
|
|
1257
|
+
* How long (ms) a track a soft switch handed over from may stay quiet before it is
|
|
1258
|
+
* retired anyway, if no PUBLISH_DONE ends its drain first.
|
|
1259
|
+
*/
|
|
1260
|
+
switchDrainTimeoutMs: number;
|
|
1261
|
+
/** How long (ms) after SUBSCRIBE_OK a fill fetch stream may take to open before ordering stops waiting for it. */
|
|
1262
|
+
fillOpenTimeoutMs: number;
|
|
1263
|
+
/**
|
|
1264
|
+
* Whether the peer has sent a GOAWAY on the control stream. Once it has, this side
|
|
1265
|
+
* should not start new requests; a second one closes the session with
|
|
1266
|
+
* PROTOCOL_VIOLATION.
|
|
1267
|
+
*/
|
|
1268
|
+
goawayReceived: boolean;
|
|
1269
|
+
/**
|
|
1270
|
+
* Stream of all received MoqtObjects from datagrams across all tracks
|
|
1271
|
+
* Consumer should filter by fullTrackName as needed
|
|
1272
|
+
*
|
|
1273
|
+
* WARNING: Only one reader should be active. For multiple subscribers,
|
|
1274
|
+
* use subscribeToTrackDatagrams() instead
|
|
1275
|
+
*/
|
|
1276
|
+
readonly receivedDatagramObjects: ReadableStream<MoqtObject>;
|
|
1277
|
+
/**
|
|
1278
|
+
* Generates a safe, sequential local request ID for tracking pushed/incoming tracks.
|
|
1279
|
+
*/
|
|
1280
|
+
allocatePseudoRequestId(): bigint;
|
|
1281
|
+
/**
|
|
1282
|
+
* Gets the current server setup configuration.
|
|
1283
|
+
*
|
|
1284
|
+
* @returns The {@link Setup} instance the server sent back during handshake.
|
|
1285
|
+
*/
|
|
1286
|
+
get serverSetup(): Setup;
|
|
1287
|
+
/**
|
|
1288
|
+
* Gets the setup this client sent during handshake.
|
|
1289
|
+
*
|
|
1290
|
+
* @returns The {@link Setup} instance written first on the control stream.
|
|
1291
|
+
*/
|
|
1292
|
+
get clientSetup(): Setup;
|
|
1293
|
+
/**
|
|
1294
|
+
* How many filter ranges this client allows the server in one request: the
|
|
1295
|
+
* MAX_FILTER_RANGES it advertised, {@link DEFAULT_MAX_FILTER_RANGES} unless the
|
|
1296
|
+
* caller's setup options set one.
|
|
1297
|
+
*/
|
|
1298
|
+
get maxFilterRanges(): bigint;
|
|
1299
|
+
/**
|
|
1300
|
+
* How many filter ranges the server allows in one request: its MAX_FILTER_RANGES,
|
|
1301
|
+
* or 0 when it sent none, which allows no Range Filter at all.
|
|
1302
|
+
*/
|
|
1303
|
+
get peerMaxFilterRanges(): bigint;
|
|
1304
|
+
/**
|
|
1305
|
+
* Returns true if datagram support is currently active
|
|
1306
|
+
*/
|
|
1307
|
+
get isDatagramsEnabled(): boolean;
|
|
1308
|
+
/**
|
|
1309
|
+
* Sets the global log level for all moqtail-ts loggers.
|
|
1310
|
+
* @param level - The minimum {@link LogLevel} to output. Use `LogLevel.NONE` to silence all logs.
|
|
1311
|
+
*/
|
|
1312
|
+
static setLogLevel(level: LogLevel): void;
|
|
1313
|
+
/**
|
|
1314
|
+
* Restricts log output to the specified module names. Pass `null` to allow all modules.
|
|
1315
|
+
* @param modules - Array of module name strings, or `null` to enable all modules.
|
|
1316
|
+
*/
|
|
1317
|
+
static setLogEnabledModules(modules: string[] | null): void;
|
|
1318
|
+
/**
|
|
1319
|
+
* Stores `options`; nothing happens on the network until {@link MOQtailClient.init}, so
|
|
1320
|
+
* listeners attached in between see everything, the handshake included.
|
|
1321
|
+
*/
|
|
1322
|
+
constructor(options: MOQtailClientOptions);
|
|
1323
|
+
/**
|
|
1324
|
+
* Opens the WebTransport session and performs the MOQT setup handshake. Runs once: a
|
|
1325
|
+
* second call throws, and a failed one leaves the client unusable, so a retry needs a
|
|
1326
|
+
* new client.
|
|
1327
|
+
*
|
|
1328
|
+
* @throws :{@link MOQtailError} If called more than once, or after {@link MOQtailClient.disconnect}.
|
|
1329
|
+
* @throws :{@link ProtocolViolationError} If the server sends an unexpected or invalid message during setup.
|
|
1330
|
+
*
|
|
1331
|
+
* @example
|
|
1332
|
+
* ```ts
|
|
1333
|
+
* const client = new MOQtailClient({ url: 'https://relay.example.com/transport' })
|
|
1334
|
+
* client.on('messagesent', (msg) => console.log('Sent:', msg))
|
|
1335
|
+
* await client.init()
|
|
1336
|
+
* ```
|
|
1337
|
+
*/
|
|
1338
|
+
init(): Promise<void>;
|
|
1339
|
+
/**
|
|
1340
|
+
* Start receiving datagrams from the WebTransport connection.
|
|
1341
|
+
* Must be called before datagrams can be received (unless enableDatagrams: true was set in options).
|
|
1342
|
+
*
|
|
1343
|
+
* @throws MOQtailError if client is destroyed or datagrams already started
|
|
1344
|
+
*/
|
|
1345
|
+
startDatagrams(): Promise<void>;
|
|
1346
|
+
/**
|
|
1347
|
+
* Stop receiving datagrams and release resources.
|
|
1348
|
+
* Idempotent - safe to call multiple times.
|
|
1349
|
+
*/
|
|
1350
|
+
stopDatagrams(): Promise<void>;
|
|
1351
|
+
/**
|
|
1352
|
+
* Subscribe to receive datagrams for a specific track.
|
|
1353
|
+
* Multiple tracks can have separate handlers that run concurrently.
|
|
1354
|
+
*
|
|
1355
|
+
* @param trackAlias - Track alias to subscribe to
|
|
1356
|
+
* @param handler - Function called for each received MoqtObject on this track
|
|
1357
|
+
* @returns Unsubscribe function to remove the handler
|
|
1358
|
+
*
|
|
1359
|
+
* @example
|
|
1360
|
+
* ```ts
|
|
1361
|
+
* const unsubscribe = client.subscribeToTrackDatagrams(trackAlias, (obj) => {
|
|
1362
|
+
* console.log('Received datagram:', obj.payload);
|
|
1363
|
+
* });
|
|
1364
|
+
* // Later: unsubscribe();
|
|
1365
|
+
* ```
|
|
1366
|
+
*/
|
|
1367
|
+
subscribeToTrackDatagrams(trackAlias: bigint, handler: (obj: MoqtObject) => void): () => void;
|
|
1368
|
+
/**
|
|
1369
|
+
* Unsubscribe from datagram delivery for a specific track.
|
|
1370
|
+
*
|
|
1371
|
+
* @param trackAlias - Track alias to unsubscribe from
|
|
1372
|
+
*/
|
|
1373
|
+
unsubscribeFromTrackDatagrams(trackAlias: bigint): void;
|
|
1374
|
+
/**
|
|
1375
|
+
* Create a datagram sender for a specific track.
|
|
1376
|
+
*
|
|
1377
|
+
* @param trackAlias - Track alias for outgoing datagrams
|
|
1378
|
+
* @returns SendDatagramStream for writing MoqtObjects as datagrams
|
|
1379
|
+
* @throws MOQtailError if datagram writer not initialized (call startDatagrams() first)
|
|
1380
|
+
*
|
|
1381
|
+
* @example
|
|
1382
|
+
* ```ts
|
|
1383
|
+
* const sender = client.createDatagramSender(trackAlias);
|
|
1384
|
+
* await sender.write(moqtObject);
|
|
1385
|
+
* ```
|
|
1386
|
+
*/
|
|
1387
|
+
createDatagramSender(trackAlias: bigint): SendDatagramStream;
|
|
1388
|
+
/**
|
|
1389
|
+
* Send a single MoqtObject as a datagram.
|
|
1390
|
+
* Convenience method for one-off datagram sends.
|
|
1391
|
+
*
|
|
1392
|
+
* @param trackAlias - Track alias for this object
|
|
1393
|
+
* @param object - MoqtObject to send
|
|
1394
|
+
* @throws MOQtailError if datagram writer not initialized
|
|
1395
|
+
*
|
|
1396
|
+
* @example
|
|
1397
|
+
* ```ts
|
|
1398
|
+
* await client.sendDatagram(trackAlias, moqtObject);
|
|
1399
|
+
* ```
|
|
1400
|
+
*/
|
|
1401
|
+
sendDatagram(trackAlias: bigint, object: MoqtObject): Promise<void>;
|
|
1402
|
+
/**
|
|
1403
|
+
* The track a data stream carries. A subgroup stream can open before the response
|
|
1404
|
+
* that names its alias, so its header event may lack `fullTrackName`: ask again on a
|
|
1405
|
+
* later event of the same stream.
|
|
1406
|
+
*/
|
|
1407
|
+
trackNameOf(header: DataHeaderEvent): FullTrackName | undefined;
|
|
1408
|
+
/**
|
|
1409
|
+
* Sets (or replaces) the client-level default early discard policy for incoming subgroup streams.
|
|
1410
|
+
*
|
|
1411
|
+
* When set, each incoming subgroup QUIC stream is given a deadline of `subgroupReceiveTimeout` ms to
|
|
1412
|
+
* complete. If the stream has not finished within that window it is cancelled — objects already
|
|
1413
|
+
* delivered to the subscription are kept, but no further objects arrive from that stream.
|
|
1414
|
+
*
|
|
1415
|
+
* This is a client-wide default. Individual subscriptions can override it via the `earlyDiscardPolicy`
|
|
1416
|
+
* field in {@link SubscribeOptions}, which takes precedence over this setting.
|
|
1417
|
+
*
|
|
1418
|
+
* The policy takes effect on the next stream accepted after this call. Passing a new config
|
|
1419
|
+
* replaces the previous one. Pass `undefined` to remove the default.
|
|
1420
|
+
*
|
|
1421
|
+
* @example
|
|
1422
|
+
* ```ts
|
|
1423
|
+
* client.setEarlyDiscardPolicy({ subgroupReceiveTimeout: 2000 })
|
|
1424
|
+
* ```
|
|
1425
|
+
*/
|
|
1426
|
+
setEarlyDiscardPolicy(config: EarlyDiscardPolicyConfig | undefined): void;
|
|
1427
|
+
/**
|
|
1428
|
+
* Gracefully terminates this {@link MOQtailClient} session and releases underlying {@link https://developer.mozilla.org/docs/Web/API/WebTransport | WebTransport} resources.
|
|
1429
|
+
*
|
|
1430
|
+
* @param reason - Optional application-level reason (string or error) recorded and wrapped in an {@link InternalError}
|
|
1431
|
+
* passed to `sessionterminated` listeners. Before {@link MOQtailClient.init} it only marks the client destroyed.
|
|
1432
|
+
*
|
|
1433
|
+
* @returns Promise that resolves once shutdown logic completes. Subsequent calls are safe no-ops.
|
|
1434
|
+
*
|
|
1435
|
+
* @example Basic usage
|
|
1436
|
+
* ```ts
|
|
1437
|
+
* await client.disconnect();
|
|
1438
|
+
* ```
|
|
1439
|
+
*
|
|
1440
|
+
* @example With reason
|
|
1441
|
+
* ```ts
|
|
1442
|
+
* await client.disconnect('user logout');
|
|
1443
|
+
* ```
|
|
1444
|
+
*
|
|
1445
|
+
* @example Idempotent double call
|
|
1446
|
+
* ```ts
|
|
1447
|
+
* await client.disconnect();
|
|
1448
|
+
* await client.disconnect(); // no error
|
|
1449
|
+
* ```
|
|
1450
|
+
*
|
|
1451
|
+
* @example Page unload safety
|
|
1452
|
+
* ```ts
|
|
1453
|
+
* window.addEventListener('beforeunload', () => {
|
|
1454
|
+
* client.disconnect('page unload');
|
|
1455
|
+
* });
|
|
1456
|
+
* ```
|
|
1457
|
+
*/
|
|
1458
|
+
disconnect(reason?: unknown): Promise<void>;
|
|
1459
|
+
/**
|
|
1460
|
+
* Registers or updates a {@link Track} definition for local publishing or serving.
|
|
1461
|
+
*
|
|
1462
|
+
* A {@link Track} describes a logical media/data stream, identified by a unique name and namespace.
|
|
1463
|
+
* - If `trackSource.live` is present, the track can be served to subscribers in real-time.
|
|
1464
|
+
* - If `trackSource.past` is present, the track can be fetched for historical data.
|
|
1465
|
+
* - If both are present, the track supports both live and historical access.
|
|
1466
|
+
*
|
|
1467
|
+
* @param track - The {@link Track} instance to add or update. See {@link TrackSource} for live/past source options.
|
|
1468
|
+
* @returns void
|
|
1469
|
+
* @throws : {@link MOQtailError} If the client has been destroyed.
|
|
1470
|
+
*
|
|
1471
|
+
* @example Create a live video track from getUserMedia
|
|
1472
|
+
* ```ts
|
|
1473
|
+
* const stream = await navigator.mediaDevices.getUserMedia({ video: true });
|
|
1474
|
+
* const videoTrack = stream.getVideoTracks()[0];
|
|
1475
|
+
*
|
|
1476
|
+
* // Convert video frames to MoqtObject instances using your chosen scheme (e.g. MSF, CMAF, etc.)
|
|
1477
|
+
* // This part is application-specific and not provided by MOQtail:
|
|
1478
|
+
* const liveReadableStream: ReadableStream<MoqtObject> = ...
|
|
1479
|
+
*
|
|
1480
|
+
* // Register the track for live subscription
|
|
1481
|
+
* client.addOrUpdateTrack({
|
|
1482
|
+
* fullTrackName: { namespace: ["camera"], name: "main" },
|
|
1483
|
+
* trackSource: { live: liveReadableStream },
|
|
1484
|
+
* publisherPriority: 0 // highest priority
|
|
1485
|
+
* });
|
|
1486
|
+
*
|
|
1487
|
+
* // For a hybrid track (live + past):
|
|
1488
|
+
* import { MemoryObjectCache } from '@/client/track/object_cache';
|
|
1489
|
+
* const cache = new MemoryObjectCache(); // Caches are not yet fully supported
|
|
1490
|
+
* client.addOrUpdateTrack({
|
|
1491
|
+
* fullTrackName: { namespace: ["camera"], name: "main" },
|
|
1492
|
+
* trackSource: { live: liveReadableStream, past: cache },
|
|
1493
|
+
* publisherPriority: 8
|
|
1494
|
+
* });
|
|
1495
|
+
* ```
|
|
1496
|
+
*/
|
|
1497
|
+
addOrUpdateTrack(track: Track): void;
|
|
1498
|
+
/**
|
|
1499
|
+
* Removes a previously registered {@link Track} from this client's local catalog.
|
|
1500
|
+
*
|
|
1501
|
+
* This deletes the in-memory entry inserted via {@link MOQtailClient.addOrUpdateTrack}, so future lookups by its {@link Track.fullTrackName} will fail.
|
|
1502
|
+
* Does **not** automatically:
|
|
1503
|
+
* - Withdraw the namespace announcement (call {@link MOQtailClient.unpublishNamespace} separately if you want to inform peers)
|
|
1504
|
+
* - Cancel active subscriptions or fetches (they continue until normal completion)
|
|
1505
|
+
* - Affect already-sent objects.
|
|
1506
|
+
*
|
|
1507
|
+
* If the track was not present, the call is a silent no-op (idempotent removal).
|
|
1508
|
+
*
|
|
1509
|
+
* @param track - The exact {@link Track} instance (its canonical name is used as the key).
|
|
1510
|
+
* @throws : {@link MOQtailError} If the client has been destroyed.
|
|
1511
|
+
*
|
|
1512
|
+
* @example
|
|
1513
|
+
* ```ts
|
|
1514
|
+
* // Register a track
|
|
1515
|
+
* client.addOrUpdateTrack(track);
|
|
1516
|
+
*
|
|
1517
|
+
* // Later, when no longer publishing:
|
|
1518
|
+
* client.removeTrack(track);
|
|
1519
|
+
*
|
|
1520
|
+
* // Optionally, inform peers that the namespace is no longer available:
|
|
1521
|
+
* await client.unpublishNamespace(track.fullTrackName.namespace);
|
|
1522
|
+
* ```
|
|
1523
|
+
*/
|
|
1524
|
+
removeTrack(track: Track): void;
|
|
1525
|
+
/**
|
|
1526
|
+
* Subscribes to a track and returns a stream of {@link MoqtObject}s matching the requested window and relay forwarding mode.
|
|
1527
|
+
*
|
|
1528
|
+
* - `forward: true` tells the relay to forward objects to this subscriber as they arrive.
|
|
1529
|
+
* - `forward: false` means the relay subscribes upstream but buffers objects locally, not forwarding them to you.
|
|
1530
|
+
* - `locationFilter` selects which Objects are delivered; omitted, the subscription is unfiltered. An absolute start in the
|
|
1531
|
+
* future waits for that object.
|
|
1532
|
+
* - A {@link FillParameters} in `parameters` also retrieves Objects already published, on a fill fetch stream.
|
|
1533
|
+
*
|
|
1534
|
+
* The method returns either a {@link RequestError} (on refusal) or a {@link SubscribeResult}: the subscription `requestId`, its
|
|
1535
|
+
* SUBSCRIBE_OK, a `ReadableStream` of {@link MoqtObject}s, and a `done` promise carrying the PUBLISH_DONE that ends it.
|
|
1536
|
+
* Use the `requestId` for {@link MOQtailClient.unsubscribe} or {@link MOQtailClient.subscribeUpdate}. Use the `stream` to decode and display objects.
|
|
1537
|
+
*
|
|
1538
|
+
* @param args - {@link SubscribeOptions} describing the subscription window and relay forwarding behavior.
|
|
1539
|
+
* @returns Either a {@link RequestError} or `{ requestId, subscribeOk, stream, done }`.
|
|
1540
|
+
* @throws : {@link MOQtailError} If the client is destroyed.
|
|
1541
|
+
* @throws : {@link ProtocolViolationError} If required fields are missing or inconsistent.
|
|
1542
|
+
* @throws : {@link InvalidFilterError} If the Range Filters exceed the server's MAX_FILTER_RANGES; nothing is sent.
|
|
1543
|
+
* @throws : {@link InternalError} On transport/protocol failure (disconnect is triggered before rethrow).
|
|
1544
|
+
*
|
|
1545
|
+
* @example Subscribe to the latest object and receive future objects as they arrive
|
|
1546
|
+
* ```ts
|
|
1547
|
+
* const result = await client.subscribe({
|
|
1548
|
+
* fullTrackName,
|
|
1549
|
+
* locationFilter: new LocationFilter(LocationFilterType.NextObject),
|
|
1550
|
+
* forward: true,
|
|
1551
|
+
* groupOrder: GroupOrder.Original,
|
|
1552
|
+
* priority: 32
|
|
1553
|
+
* });
|
|
1554
|
+
* if (!(result instanceof RequestError)) {
|
|
1555
|
+
* for await (const obj of result.stream) {
|
|
1556
|
+
* // decode and display obj
|
|
1557
|
+
* }
|
|
1558
|
+
* }
|
|
1559
|
+
* ```
|
|
1560
|
+
*
|
|
1561
|
+
* @example Subscribe to a future range of groups (waits for those objects to arrive)
|
|
1562
|
+
* ```ts
|
|
1563
|
+
* const result = await client.subscribe({
|
|
1564
|
+
* fullTrackName,
|
|
1565
|
+
* locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, startGroup, 0n, endGroup),
|
|
1566
|
+
* forward: true,
|
|
1567
|
+
* groupOrder: GroupOrder.Original,
|
|
1568
|
+
* priority: 128
|
|
1569
|
+
* });
|
|
1570
|
+
* ```
|
|
1571
|
+
*/
|
|
1572
|
+
subscribe(args: SubscribeOptions): Promise<RequestError | SubscribeResult>;
|
|
1573
|
+
/**
|
|
1574
|
+
* Stops an active subscription identified by its original SUBSCRIBE `requestId`.
|
|
1575
|
+
*
|
|
1576
|
+
* Resets the subscription's request stream with `CANCELLED` if it is still active. If the id is unknown or already
|
|
1577
|
+
* cleaned up, the call is a silent no-op (hence multiple calls are idempotent).
|
|
1578
|
+
*
|
|
1579
|
+
* Use this when you no longer want incoming objects for a track (e.g. user navigated away, switching quality).
|
|
1580
|
+
* Canceling the consumer stream reader does **not** auto-unsubscribe; call this explicitly for prompt cleanup.
|
|
1581
|
+
*
|
|
1582
|
+
* @param requestId - The id returned from {@link MOQtailClient.subscribe}.
|
|
1583
|
+
* @returns Promise that resolves once the request stream has been reset.
|
|
1584
|
+
* @throws :{@link MOQtailError} If the client is destroyed.
|
|
1585
|
+
* @throws :{@link InternalError} Wrapped lower-level failure while attempting to send (session will be disconnected first).
|
|
1586
|
+
*
|
|
1587
|
+
* @remarks
|
|
1588
|
+
* - Only targets SUBSCRIBE requests, not fetches. Passing a fetch request id is ignored (no-op).
|
|
1589
|
+
* - Safe to call multiple times; extra calls have no effect.
|
|
1590
|
+
*
|
|
1591
|
+
* @example Subscribe and later unsubscribe
|
|
1592
|
+
* ```ts
|
|
1593
|
+
* const sub = await client.subscribe({ fullTrackName, locationFilter: new LocationFilter(LocationFilterType.NextObject), forward: true, groupOrder: GroupOrder.Original, priority: 0 });
|
|
1594
|
+
* if (!(sub instanceof RequestError)) {
|
|
1595
|
+
* // ...consume objects...
|
|
1596
|
+
* await client.unsubscribe(sub.requestId);
|
|
1597
|
+
* }
|
|
1598
|
+
* ```
|
|
1599
|
+
*
|
|
1600
|
+
* @example Idempotent usage
|
|
1601
|
+
* ```ts
|
|
1602
|
+
* await client.unsubscribe(123n);
|
|
1603
|
+
* await client.unsubscribe(123n); // no error
|
|
1604
|
+
* ```
|
|
1605
|
+
*/
|
|
1606
|
+
unsubscribe(requestId: bigint | number): Promise<void>;
|
|
1607
|
+
/**
|
|
1608
|
+
* Narrows or updates an active subscription window and/or relay forwarding behavior.
|
|
1609
|
+
*
|
|
1610
|
+
* Use this to:
|
|
1611
|
+
* - Move the start of the subscription forward (trim history or future window).
|
|
1612
|
+
* - Move the end group earlier (shorten the window).
|
|
1613
|
+
* - Change relay forwarding (`forward: false` stops forwarding new objects, `true` resumes).
|
|
1614
|
+
* - Adjust subscriber priority.
|
|
1615
|
+
*
|
|
1616
|
+
* Only narrowing is allowed: you cannot move the start earlier or the end group later than the original subscription.
|
|
1617
|
+
* Forwarding and priority can be changed at any time.
|
|
1618
|
+
*
|
|
1619
|
+
* @param args - {@link SubscribeUpdateOptions} referencing the original subscription `requestId` and new bounds.
|
|
1620
|
+
* @returns Promise that resolves when the update control frame is sent.
|
|
1621
|
+
* @throws :{@link MOQtailError} If the client is destroyed.
|
|
1622
|
+
* @throws :{@link ProtocolViolationError} If the update would widen the window (earlier start, later end group, or invalid ordering).
|
|
1623
|
+
* @throws :{@link InternalError} On transport/control failure (disconnect is triggered before rethrow).
|
|
1624
|
+
*
|
|
1625
|
+
* @remarks
|
|
1626
|
+
* - Only applies to active SUBSCRIBE requests; ignored if the request is not a subscription.
|
|
1627
|
+
* - Omitting a parameter (e.g. `priority`) leaves the previous value unchanged.
|
|
1628
|
+
* - Setting `forward: false` stops relay forwarding new objects after the current window drains.
|
|
1629
|
+
* - Safe to call multiple times; extra calls with unchanged bounds have no effect.
|
|
1630
|
+
*
|
|
1631
|
+
* @example Trim start forward
|
|
1632
|
+
* ```ts
|
|
1633
|
+
* await client.subscribeUpdate({ subscriptionRequestId, locationFilter: new LocationFilter(LocationFilterType.AbsoluteStart, laterGroup, 0n), forward: true, priority });
|
|
1634
|
+
* ```
|
|
1635
|
+
*
|
|
1636
|
+
* @example Convert tailing subscription into bounded slice
|
|
1637
|
+
* ```ts
|
|
1638
|
+
* await client.subscribeUpdate({ subscriptionRequestId, locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, startGroup, 0n, cutoffGroup), forward: false, priority });
|
|
1639
|
+
* ```
|
|
1640
|
+
*
|
|
1641
|
+
* @example Lower priority only
|
|
1642
|
+
* ```ts
|
|
1643
|
+
* await client.subscribeUpdate({ subscriptionRequestId, forward: true, priority: 200 });
|
|
1644
|
+
* ```
|
|
1645
|
+
*/
|
|
1646
|
+
subscribeUpdate(args: SubscribeUpdateOptions): Promise<void>;
|
|
1647
|
+
/**
|
|
1648
|
+
* Switches an active subscription to a different track while retaining the same subscription's
|
|
1649
|
+
* output stream.
|
|
1650
|
+
*
|
|
1651
|
+
* Sends a fresh SUBSCRIBE carrying a SwitchFrom parameter referencing `switchFromRequestId`. A soft
|
|
1652
|
+
* switch may keep delivering objects from the old track for a while after SUBSCRIBE_OK, and this can
|
|
1653
|
+
* be called again before the previous target has produced anything; only the first object actually
|
|
1654
|
+
* delivered by the newest switch target retires everything older.
|
|
1655
|
+
*
|
|
1656
|
+
* @param args - {@link SwitchOptions} referencing the subscription to switch from and the new subscription options.
|
|
1657
|
+
* @returns Either a {@link RequestError} (refusal) or the new request's {@link SubscribeResult}, where `stream`
|
|
1658
|
+
* is the same {@link https://developer.mozilla.org/docs/Web/API/ReadableStream | ReadableStream} object returned by the
|
|
1659
|
+
* original `subscribe()` call and `done` that subscription's, which resolves once the whole switched chain is over.
|
|
1660
|
+
* @throws :{@link MOQtailError} If the client is destroyed.
|
|
1661
|
+
* @throws :{@link ProtocolViolationError} If `switchFromRequestId` does not name an active subscription.
|
|
1662
|
+
* @throws :{@link InternalError} On transport/control failure (disconnect is triggered before rethrow).
|
|
1663
|
+
*
|
|
1664
|
+
* @example Switch to a different track
|
|
1665
|
+
* ```ts
|
|
1666
|
+
* await client.switch({
|
|
1667
|
+
* switchFromRequestId,
|
|
1668
|
+
* switchMode: SwitchMode.Soft,
|
|
1669
|
+
* newSubscribeOptions: { fullTrackName: newTrackName, priority: 0, groupOrder: GroupOrder.Original, locationFilter: new LocationFilter(LocationFilterType.NextObject) },
|
|
1670
|
+
* onDrainDecision: (request) => true
|
|
1671
|
+
* });
|
|
1672
|
+
* ```
|
|
1673
|
+
*/
|
|
1674
|
+
switch(args: SwitchOptions): Promise<RequestError | SubscribeResult>;
|
|
1675
|
+
/**
|
|
1676
|
+
* Ends a subscription whose publisher has said how many streams it opened and has
|
|
1677
|
+
* now delivered all of them, and reports whether that happened.
|
|
1678
|
+
*
|
|
1679
|
+
* Both halves of that arrive on their own: a PUBLISH_DONE carries the count, and
|
|
1680
|
+
* the streams finish whenever they finish. Either can be last, so this is checked
|
|
1681
|
+
* from both -- a drained switch target has usually finished its streams well
|
|
1682
|
+
* before the PUBLISH_DONE that ends it.
|
|
1683
|
+
*/
|
|
1684
|
+
completeSubscription(request: SubscribeRequest, force?: boolean): boolean;
|
|
1685
|
+
/**
|
|
1686
|
+
* One-shot retrieval of a bounded object span, optionally anchored to an existing subscription, returning a stream of {@link MoqtObject}s.
|
|
1687
|
+
*
|
|
1688
|
+
* Choose a fetch type via `typeAndProps.type`:
|
|
1689
|
+
* - Standalone: Historical slice of a specific {@link FullTrackName} independent of active subscriptions.
|
|
1690
|
+
* - Relative: Range relative to the JOINING subscription's current (largest) location; use when you want "N groups back" from live.
|
|
1691
|
+
* - Absolute: Absolute group/object offsets tied to an existing subscription (stable anchor) even if that subscription keeps forwarding.
|
|
1692
|
+
*
|
|
1693
|
+
* Field highlights (in {@link FetchOptions}):
|
|
1694
|
+
* - priority: 0 (highest) .. 255 (lowest); out-of-range rejected; non-integers rounded by caller expectation.
|
|
1695
|
+
* - groupOrder: {@link (GroupOrder:enum).Original} to preserve publisher order; or reorder ascending/descending if supported by server.
|
|
1696
|
+
* - typeAndProps: Discriminated union carrying parameters specific to each fetch mode (see examples).
|
|
1697
|
+
* - parameters: Optional version-specific extension block.
|
|
1698
|
+
*
|
|
1699
|
+
* Returns either a {@link RequestError} (refusal / invalid request at protocol level) or `{ requestId, fetchOk, stream }` whose `stream`
|
|
1700
|
+
* ends naturally after the bounded range completes (no explicit cancel needed for normal completion).
|
|
1701
|
+
*
|
|
1702
|
+
* Use cases:
|
|
1703
|
+
* - Grab a historical window for scrubbing UI while a separate live subscription tails.
|
|
1704
|
+
* - Late joiner fetching a short back-buffer then discarding the stream.
|
|
1705
|
+
* - Analytics batch job pulling a fixed slice without subscribing long-term.
|
|
1706
|
+
*
|
|
1707
|
+
* @throws MOQtailError If client is destroyed.
|
|
1708
|
+
* @throws ProtocolViolationError Priority out of [0-255] or missing/invalid joining subscription id for Relative/Absolute.
|
|
1709
|
+
* @throws InternalError Transport/control failure (the client disconnects first) then rethrows original error.
|
|
1710
|
+
*
|
|
1711
|
+
* @remarks
|
|
1712
|
+
* - Relative / Absolute require an existing active SUBSCRIBE `joiningRequestId`; if not found a {@link ProtocolViolationError} is thrown.
|
|
1713
|
+
* - Result stream is finite; reader close occurs automatically when last object delivered.
|
|
1714
|
+
* - Use {@link MOQtailClient.fetchCancel} only for early termination (not yet fully implemented: see TODO in code).
|
|
1715
|
+
*
|
|
1716
|
+
* @example Groups 10 through 12, inclusive
|
|
1717
|
+
* ```ts
|
|
1718
|
+
* const r = await client.fetch({
|
|
1719
|
+
* fullTrackName,
|
|
1720
|
+
* priority: 64,
|
|
1721
|
+
* groupOrder: GroupOrder.Original,
|
|
1722
|
+
* locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 10n, 0n, 12n)
|
|
1723
|
+
* })
|
|
1724
|
+
* if (!(r instanceof RequestError)) {
|
|
1725
|
+
* for await (const obj of r.stream as any) {
|
|
1726
|
+
* // consume objects then stream ends automatically
|
|
1727
|
+
* }
|
|
1728
|
+
* }
|
|
1729
|
+
* ```
|
|
1730
|
+
*
|
|
1731
|
+
* @example The last 5 groups, counting the current one
|
|
1732
|
+
* ```ts
|
|
1733
|
+
* const slice = await client.fetch({
|
|
1734
|
+
* fullTrackName,
|
|
1735
|
+
* priority: 32,
|
|
1736
|
+
* groupOrder: GroupOrder.Original,
|
|
1737
|
+
* locationFilter: new LocationFilter(LocationFilterType.RelativeStart, 5n)
|
|
1738
|
+
* })
|
|
1739
|
+
* ```
|
|
1740
|
+
*/
|
|
1741
|
+
fetch(args: FetchOptions): Promise<RequestError | FetchResult>;
|
|
1742
|
+
/**
|
|
1743
|
+
* Request early termination of an in‑flight FETCH identified by its `requestId`.
|
|
1744
|
+
*
|
|
1745
|
+
* Use when the consumer no longer needs the remaining objects (user scrubbed away, UI panel closed, replaced by a new fetch).
|
|
1746
|
+
* Resets the fetch's request stream with `CANCELLED` if the id currently maps to an active fetch; otherwise silent no-op (idempotent).
|
|
1747
|
+
*
|
|
1748
|
+
* Parameter semantics:
|
|
1749
|
+
* - requestId: bigint returned from {@link MOQtailClient.fetch}. Numbers auto-converted to bigint.
|
|
1750
|
+
*
|
|
1751
|
+
* Current behavior / limitations:
|
|
1752
|
+
* - Data stream closure after cancel is TODO (objects may still arrive briefly).
|
|
1753
|
+
* - Unknown / already finished request: ignored without error.
|
|
1754
|
+
* - Only targets FETCH requests (not subscriptions).
|
|
1755
|
+
*
|
|
1756
|
+
* @throws MOQtailError If client is destroyed.
|
|
1757
|
+
* @throws InternalError Failure while sending the cancel (client disconnects first).
|
|
1758
|
+
*
|
|
1759
|
+
* @remarks
|
|
1760
|
+
* Follow-up improvement planned: actively close associated readable stream controller immediately upon acknowledgment.
|
|
1761
|
+
*
|
|
1762
|
+
* @example Cancel shortly after starting
|
|
1763
|
+
* ```ts
|
|
1764
|
+
* const r = await client.fetch({ fullTrackName, priority: 32, groupOrder: GroupOrder.Original, locationFilter })
|
|
1765
|
+
* if (!(r instanceof RequestError)) {
|
|
1766
|
+
* // user navigated away
|
|
1767
|
+
* await client.fetchCancel(r.requestId)
|
|
1768
|
+
* }
|
|
1769
|
+
* ```
|
|
1770
|
+
*
|
|
1771
|
+
* @example Idempotent double cancel
|
|
1772
|
+
* ```ts
|
|
1773
|
+
* await client.fetchCancel(456n)
|
|
1774
|
+
* await client.fetchCancel(456n) // no error
|
|
1775
|
+
* ```
|
|
1776
|
+
*/
|
|
1777
|
+
fetchCancel(requestId: bigint | number): Promise<void>;
|
|
1778
|
+
/**
|
|
1779
|
+
* Proactively push a track to the relay/peer.
|
|
1780
|
+
*/
|
|
1781
|
+
publish(fullTrackName: FullTrackName, forward: boolean, trackAlias: bigint, parameters?: MessageParameter[], trackProperties?: TrackProperty[]): Promise<RequestError | {
|
|
1782
|
+
requestId: bigint;
|
|
1783
|
+
trackAlias: bigint;
|
|
1784
|
+
}>;
|
|
1785
|
+
/**
|
|
1786
|
+
* Signals the end of a published track to the peer/relay.
|
|
1787
|
+
* * @param publishRequestId - The original requestId used when `publish()` was called.
|
|
1788
|
+
*/
|
|
1789
|
+
publishDone(publishRequestId: bigint | number, statusCode?: number, reasonPhrase?: string): Promise<void>;
|
|
1790
|
+
/**
|
|
1791
|
+
* Registers an incoming PUBLISH announcement as a valid data receiver.
|
|
1792
|
+
* This prepares the client to ingest pushed data streams matching the published alias.
|
|
1793
|
+
* * @param msg - The incoming Publish control message
|
|
1794
|
+
* @returns - A stream of MoqtObjects being pushed by the publisher
|
|
1795
|
+
*/
|
|
1796
|
+
acceptPushedTrack(msg: Publish): ReadableStream<MoqtObject>;
|
|
1797
|
+
/**
|
|
1798
|
+
* Declare (publish) a track namespace to the peer so subscribers using matching prefixes (via {@link MOQtailClient.subscribeNamespace})
|
|
1799
|
+
* can discover and begin subscribing/fetching its tracks.
|
|
1800
|
+
*
|
|
1801
|
+
* Typical flow (publisher side):
|
|
1802
|
+
* 1. Prepare / register one or more {@link Track} objects locally (see {@link MOQtailClient.addOrUpdateTrack}).
|
|
1803
|
+
* 2. Call `publishNamespace(namespace)` once per namespace prefix to expose those tracks.
|
|
1804
|
+
* 3. Later, call {@link MOQtailClient.unpublishNamespace} when no longer publishing under that namespace.
|
|
1805
|
+
*
|
|
1806
|
+
* Parameter semantics:
|
|
1807
|
+
* - trackNamespace: Tuple representing the namespace prefix (e.g. ["camera","main"]). All tracks whose full names start with this tuple are considered within the announce scope.
|
|
1808
|
+
* - parameters: Optional {@link MessageParameters}; omitted =\> default instance.
|
|
1809
|
+
*
|
|
1810
|
+
* Returns: {@link RequestOk} on success (namespace added to `publishedNamespaces`) or {@link RequestError} explaining refusal.
|
|
1811
|
+
*
|
|
1812
|
+
* Use cases:
|
|
1813
|
+
* - Make a camera or sensor namespace available before any objects are pushed.
|
|
1814
|
+
* - Dynamically expose a newly created room / session namespace.
|
|
1815
|
+
* - Re-announce after reconnect to repopulate discovery state.
|
|
1816
|
+
*
|
|
1817
|
+
* @throws MOQtailError If client is destroyed.
|
|
1818
|
+
* @throws InternalError Transport/control failure while sending or awaiting response (client disconnects first).
|
|
1819
|
+
*
|
|
1820
|
+
* @remarks
|
|
1821
|
+
* - Duplicate announce detection is TODO (currently a second call will still send another PUBLISH_NAMESPACE; receiver behavior may vary).
|
|
1822
|
+
* - Successful announces are tracked in `publishedNamespaces`; manual removal occurs via {@link MOQtailClient.unpublishNamespace}.
|
|
1823
|
+
* - Discovery subscribers (those who issued {@link MOQtailClient.subscribeNamespace}) will receive the resulting {@link PublishNamespace} message.
|
|
1824
|
+
*
|
|
1825
|
+
* @example Minimal announce
|
|
1826
|
+
* ```ts
|
|
1827
|
+
* const res = await client.publishNamespace(["camera","main"])
|
|
1828
|
+
* if (res instanceof RequestOk) {
|
|
1829
|
+
* // ready to publish objects under tracks with this namespace prefix
|
|
1830
|
+
* }
|
|
1831
|
+
* ```
|
|
1832
|
+
*
|
|
1833
|
+
* @example PublishNamespace with parameters block
|
|
1834
|
+
* ```ts
|
|
1835
|
+
* const params = new MessageParameters().setSomeExtensionFlag(true)
|
|
1836
|
+
* const resp = await client.publishNamespace(["room","1234"], params)
|
|
1837
|
+
* ```
|
|
1838
|
+
*/
|
|
1839
|
+
publishNamespace(trackNamespace: Tuple, parameters?: MessageParameter[]): Promise<RequestOk | RequestError>;
|
|
1840
|
+
/**
|
|
1841
|
+
* Withdraw a previously announced namespace so new subscribers no longer discover its tracks.
|
|
1842
|
+
*
|
|
1843
|
+
* Use when shutting down publishing for a logical scope (camera offline, room closed, session ended).
|
|
1844
|
+
* Removes the namespace from `publishedNamespaces` locally and closes the stream its PUBLISH_NAMESPACE opened,
|
|
1845
|
+
* which is what withdraws the announcement (§3.3.2). This is also how an announce is retracted before the peer
|
|
1846
|
+
* has finished processing it.
|
|
1847
|
+
*
|
|
1848
|
+
* Parameter semantics:
|
|
1849
|
+
* - trackNamespace: Exact tuple used during {@link MOQtailClient.publishNamespace}. Must match to be removed from internal set.
|
|
1850
|
+
*
|
|
1851
|
+
* Behavior:
|
|
1852
|
+
* - Does not delete locally registered {@link Track} objects (they remain in `trackSources`).
|
|
1853
|
+
* - Does not forcibly end active subscriptions that were already established; peers simply stop discovering it for new ones.
|
|
1854
|
+
* - Silent if the namespace was not currently recorded (idempotent style).
|
|
1855
|
+
*
|
|
1856
|
+
* @throws MOQtailError If client is destroyed before sending.
|
|
1857
|
+
* @throws (rethrows original error) Any lower-level failure while sending results in a disconnect (unwrapped TODO: future wrap with InternalError for consistency).
|
|
1858
|
+
*
|
|
1859
|
+
* @remarks
|
|
1860
|
+
* Peers that issued {@link MOQtailClient.subscribeNamespace} for a matching prefix should receive the resulting NAMESPACE_DONE.
|
|
1861
|
+
* Consider calling this before {@link MOQtailClient.disconnect} to give consumers prompt notice.
|
|
1862
|
+
*
|
|
1863
|
+
* @example Basic usage
|
|
1864
|
+
* ```ts
|
|
1865
|
+
* await client.unpublishNamespace(["camera","main"])
|
|
1866
|
+
* ```
|
|
1867
|
+
*
|
|
1868
|
+
* @example Idempotent
|
|
1869
|
+
* ```ts
|
|
1870
|
+
* await client.unpublishNamespace(["camera","main"]) // first time
|
|
1871
|
+
* await client.unpublishNamespace(["camera","main"]) // no error, already removed
|
|
1872
|
+
* ```
|
|
1873
|
+
*/
|
|
1874
|
+
unpublishNamespace(trackNamespace: Tuple): Promise<void>;
|
|
1875
|
+
/**
|
|
1876
|
+
* Subscribes to namespace announcements under a prefix (§10.18). Discovery only: the
|
|
1877
|
+
* peer answers NAMESPACE and NAMESPACE_DONE for matching namespaces, and nothing is
|
|
1878
|
+
* subscribed to. To be sent the tracks themselves, use
|
|
1879
|
+
* {@link MOQtailClient.subscribeTracks}.
|
|
1880
|
+
*/
|
|
1881
|
+
subscribeNamespace(trackNamespacePrefix: Tuple, parameters?: MessageParameter[]): Promise<{
|
|
1882
|
+
response: RequestOk | RequestError;
|
|
1883
|
+
cancel: () => Promise<void>;
|
|
1884
|
+
}>;
|
|
1885
|
+
subscribeTracks(trackNamespacePrefix: Tuple, parameters?: MessageParameter[]): Promise<{
|
|
1886
|
+
response: RequestOk | RequestError;
|
|
1887
|
+
cancel: () => Promise<void>;
|
|
1888
|
+
}>;
|
|
1889
|
+
/**
|
|
1890
|
+
* Ends a prefix subscription started with {@link MOQtailClient.subscribeNamespace}.
|
|
1891
|
+
*
|
|
1892
|
+
* @param trackNamespacePrefix - The prefix that subscription was opened with.
|
|
1893
|
+
*/
|
|
1894
|
+
unsubscribeNamespace(trackNamespacePrefix: Tuple): Promise<void>;
|
|
1895
|
+
/**
|
|
1896
|
+
* Asks the peer for the current status of a track.
|
|
1897
|
+
*
|
|
1898
|
+
* TRACK_STATUS is the seventh `First`-marked type: it opens its own bidi stream and
|
|
1899
|
+
* the REQUEST_OK answering it comes back there, after which the stream is closed.
|
|
1900
|
+
*
|
|
1901
|
+
* @param fullTrackName - The track to report on.
|
|
1902
|
+
* @param trackAlias - Alias to carry in the request.
|
|
1903
|
+
* @param parameters - Optional message parameters.
|
|
1904
|
+
* @returns A {@link RequestOk} on success or a {@link RequestError} on refusal.
|
|
1905
|
+
*
|
|
1906
|
+
* @example
|
|
1907
|
+
* ```ts
|
|
1908
|
+
* const status = await client.trackStatus(fullTrackName, trackAlias)
|
|
1909
|
+
* if (!(status instanceof RequestError)) {
|
|
1910
|
+
* // track exists
|
|
1911
|
+
* }
|
|
1912
|
+
* ```
|
|
1913
|
+
*/
|
|
1914
|
+
trackStatus(fullTrackName: FullTrackName, trackAlias: bigint, parameters?: MessageParameter[]): Promise<RequestOk | RequestError>;
|
|
1915
|
+
/**
|
|
1916
|
+
* Re-issues one request on a fresh stream after the peer sent a GOAWAY on its request
|
|
1917
|
+
* stream (§10.4). Only that request moves: the session, and every other request on it,
|
|
1918
|
+
* are left alone.
|
|
1919
|
+
*
|
|
1920
|
+
* The re-issued request consumes a new Request ID (§10.1), so the opening message is
|
|
1921
|
+
* re-stamped with it. The id the caller holds keeps naming the request; only the id on
|
|
1922
|
+
* the wire changes.
|
|
1923
|
+
*
|
|
1924
|
+
* @returns True if the request was re-issued here. A GOAWAY naming a new session URI
|
|
1925
|
+
* is not: opening a session is the application's call, so it is surfaced as a
|
|
1926
|
+
* `goaway` event and the request stream is closed.
|
|
1927
|
+
*
|
|
1928
|
+
* @internal
|
|
1929
|
+
*/
|
|
1930
|
+
migrateRequest(requestId: bigint, goAway: GoAway): Promise<boolean>;
|
|
1931
|
+
}
|
|
1932
|
+
export { DataStreamReporter as $, MOQtailRequest as A, Subscription as B, DEFAULT_SWITCH_DRAIN_TIMEOUT_MS as C, FetchOptions as D, EndOfRangeHandler as E, SwitchOptions as F, WindowSuspension as G, PublishRequest as H, TrackAliasHolder as I, DataEvent as J, ObjectStream as K, TrackStatusRequest as L, SubscribeOptions as M, SubscribeResult as N, FetchResult as O, SubscribeUpdateOptions as P, DataStreamEndEvent as Q, SubscribeNamespaceRequest as R, DEFAULT_MAX_FILTER_RANGES as S, EarlyDiscardPolicyConfig as T, FetchRequest as U, PublishNamespaceRequest as V, ObjectOrderer as W, DataHeaderEvent as X, DataEventBase as Y, DataObjectEvent as Z, ControlRecvStream as _, SubscribePublication as a, ClientEvents as b, HybridTrackSource as c, PastObjectSource as d, FullTrackNameOf as et, StaticTrackSource as f, RingBufferObjectCache as g, ObjectCache as h, FetchPublication as i, ObjectOrdering as j, MOQtailClientOptions as k, LiveObjectSource as l, MemoryObjectCache as m, SendDatagramStream as n, RequestStream as o, TrackSource as p, DataDirection as q, PublishPublication as r, Track as s, MOQtailClient as t, LiveTrackSource as u, ControlSendStream as v, DEFAULT_TRACK_ALIAS_RESOLUTION_TIMEOUT_MS as w, DEFAULT_FILL_OPEN_TIMEOUT_MS as x, ControlStream as y, SubscribeRequest as z };
|