moqtail 0.10.0 → 0.11.0

package/dist/client.cjs

@@ -5123,6 +5123,7 @@ var SubscribeRequest = class {
   priority;
   forward;
   subscribeParameters;
+  earlyDiscardPolicy;
   largestLocation;
   // Updated on each received object
   streamsAccepted = 0n;
@@ -5958,6 +5959,11 @@ var handlerRequestsBlocked = async (_client, msg) => {
   logger.debug("handler/requests_blocked", "not implemented", msg);
 };
 
+// src/client/util/validators.ts
+function isValidTrackAlias(trackAlias) {
+  return trackAlias !== void 0 && trackAlias >= 0n;
+}
+
 // src/client/handler/subscribe.ts
 var handlerSubscribe = async (client, msg) => {
   logger.debug("handler/subscribe", `received requestId=${msg.requestId} ftn="${msg.fullTrackName}"`);
@@ -5990,7 +5996,7 @@ var handlerSubscribe = async (client, msg) => {
     await client.controlStream.send(response);
     return;
   }
-  if (!track.trackAlias) throw new Error("Expected track alias to be set");
+  if (!isValidTrackAlias(track.trackAlias)) throw new Error("Expected track alias to be set");
   const largestLocation = track.trackSource.live.largestLocation;
   const parameters = [...msg.parameters];
   if (largestLocation) {
@@ -6456,6 +6462,8 @@ var MOQtailClient = class _MOQtailClient {
   #isDestroyed = false;
   /** Internal monotonically increasing client-assigned request id counter (even/odd parity scheme advances by 2). */
   #dontUseRequestId = 0n;
+  /** Active early discard policy; undefined means no per-stream deadline is applied. */
+  #earlyDiscardPolicy;
   /**
    * TODO: onNamespaceAnnounced may be a better name
    * Fired when an PUBLISH_NAMESPACE control message is processed for a track namespace.
@@ -6907,6 +6915,28 @@ var MOQtailClient = class _MOQtailClient {
       return FullTrackName.tryNew("unknown", `track-${trackAlias}`);
     }
   }
+  /**
+   * Sets (or replaces) the client-level default early discard policy for incoming subgroup streams.
+   *
+   * When set, each incoming subgroup QUIC stream is given a deadline of `subgroupReceiveTimeout` ms to
+   * complete. If the stream has not finished within that window it is cancelled — objects already
+   * delivered to the subscription are kept, but no further objects arrive from that stream.
+   *
+   * This is a client-wide default. Individual subscriptions can override it via the `earlyDiscardPolicy`
+   * field in {@link SubscribeOptions}, which takes precedence over this setting.
+   *
+   * The policy takes effect on the next stream accepted after this call. Passing a new config
+   * replaces the previous one. Pass `undefined` to remove the default.
+   *
+   * @example
+   * ```ts
+   * client.setEarlyDiscardPolicy({ subgroupReceiveTimeout: 2000 })
+   * ```
+   */
+  setEarlyDiscardPolicy(config) {
+    this.#ensureActive();
+    this.#earlyDiscardPolicy = config;
+  }
   /**
    * Gracefully terminates this {@link MOQtailClient} session and releases underlying {@link https://developer.mozilla.org/docs/Web/API/WebTransport | WebTransport} resources.
    *
@@ -6991,7 +7021,7 @@ var MOQtailClient = class _MOQtailClient {
    */
   addOrUpdateTrack(track) {
     this.#ensureActive();
-    if (!track.trackAlias) {
+    if (!isValidTrackAlias(track.trackAlias)) {
       track.trackAlias = random60bitId();
     }
     this.trackSources.set(track.fullTrackName.toString(), track);
@@ -7123,6 +7153,7 @@ var MOQtailClient = class _MOQtailClient {
           break;
       }
       const request = new SubscribeRequest(msg);
+      request.earlyDiscardPolicy = args.earlyDiscardPolicy;
       this.requests.set(request.requestId, request);
       this.requestIdMap.addMapping(request.requestId, request.fullTrackName);
       logger.debug("MOQtailClient", `subscribe: sending SUBSCRIBE requestId=${msg.requestId} ftn="${fullTrackName}"`);
@@ -7271,7 +7302,7 @@ var MOQtailClient = class _MOQtailClient {
         const request = this.requests.get(subscriptionRequestId);
         if (request instanceof SubscribeRequest) {
           const trackAlias = this.subscriptionAliasMap.get(subscriptionRequestId);
-          if (!trackAlias)
+          if (!isValidTrackAlias(trackAlias))
             throw new InternalError("MOQtailClient.subscribeUpdate", "Request exists but track alias mapping does not");
           const subscription = this.subscriptions.get(trackAlias);
           if (!subscription)
@@ -7324,7 +7355,7 @@ var MOQtailClient = class _MOQtailClient {
       if (!(request instanceof SubscribeRequest))
         throw new ProtocolViolationError("MOQtailClient.switch", "Request id is not a subscription");
       const trackAlias = this.subscriptionAliasMap.get(subscriptionRequestId);
-      if (!trackAlias)
+      if (!isValidTrackAlias(trackAlias))
         throw new InternalError("MOQtailClient.switch", "Request exists but track alias mapping does not");
       const subscription = this.subscriptions.get(trackAlias);
       if (!subscription) throw new InternalError("MOQtailClient.switch", "Request exists but subscription does not");
@@ -7988,43 +8019,55 @@ var MOQtailClient = class _MOQtailClient {
         if (subscription) {
           subscription.streamsAccepted++;
           let firstObjectId = null;
-          while (true) {
-            const { done, value: nextObject } = await reader.read();
-            if (done) {
-              break;
-            }
-            if (nextObject) {
-              if (nextObject instanceof SubgroupObject) {
-                if (!firstObjectId) {
-                  firstObjectId = nextObject.objectId;
-                }
-                let subgroupId = null;
-                if (SubgroupHeaderType.isSubgroupIdZero(header.type)) {
-                  subgroupId = 0n;
-                } else if (SubgroupHeaderType.isSubgroupIdFirstObjectId(header.type)) {
-                  subgroupId = firstObjectId ?? null;
-                } else if (SubgroupHeaderType.hasExplicitSubgroupId(header.type)) {
-                  subgroupId = header.subgroupId ?? null;
-                }
-                const fullTrackName = this.aliasFullTrackNameMap.get(header.trackAlias);
-                if (!fullTrackName) {
-                  throw new ProtocolViolationError("MOQtailClient", "No full track name for received track alias");
+          let subgroupTimeoutId;
+          const effectiveDiscardPolicy = subscription.earlyDiscardPolicy ?? this.#earlyDiscardPolicy;
+          if (effectiveDiscardPolicy?.subgroupReceiveTimeout !== void 0) {
+            subgroupTimeoutId = setTimeout(() => {
+              reader.cancel("early discard: subgroupReceiveTimeout exceeded").catch(() => {
+              });
+            }, effectiveDiscardPolicy.subgroupReceiveTimeout);
+          }
+          try {
+            while (true) {
+              const { done, value: nextObject } = await reader.read();
+              if (done) {
+                break;
+              }
+              if (nextObject) {
+                if (nextObject instanceof SubgroupObject) {
+                  if (!firstObjectId) {
+                    firstObjectId = nextObject.objectId;
+                  }
+                  let subgroupId = null;
+                  if (SubgroupHeaderType.isSubgroupIdZero(header.type)) {
+                    subgroupId = 0n;
+                  } else if (SubgroupHeaderType.isSubgroupIdFirstObjectId(header.type)) {
+                    subgroupId = firstObjectId ?? null;
+                  } else if (SubgroupHeaderType.hasExplicitSubgroupId(header.type)) {
+                    subgroupId = header.subgroupId ?? null;
+                  }
+                  const fullTrackName = this.aliasFullTrackNameMap.get(header.trackAlias);
+                  if (!fullTrackName) {
+                    throw new ProtocolViolationError("MOQtailClient", "No full track name for received track alias");
+                  }
+                  const moqtObject = MoqtObject.fromSubgroupObject(
+                    nextObject,
+                    header.groupId,
+                    header.publisherPriority,
+                    subgroupId,
+                    fullTrackName
+                  );
+                  if (!subscription.largestLocation) subscription.largestLocation = moqtObject.location;
+                  if (subscription.largestLocation.compare(moqtObject.location) == -1)
+                    subscription.largestLocation = moqtObject.location;
+                  subscription.controller?.enqueue(moqtObject);
+                  continue;
                 }
-                const moqtObject = MoqtObject.fromSubgroupObject(
-                  nextObject,
-                  header.groupId,
-                  header.publisherPriority,
-                  subgroupId,
-                  fullTrackName
-                );
-                if (!subscription.largestLocation) subscription.largestLocation = moqtObject.location;
-                if (subscription.largestLocation.compare(moqtObject.location) == -1)
-                  subscription.largestLocation = moqtObject.location;
-                subscription.controller?.enqueue(moqtObject);
-                continue;
+                throw new ProtocolViolationError("MOQtailClient", "Received fetch object after subgroup header");
               }
-              throw new ProtocolViolationError("MOQtailClient", "Received fetch object after subgroup header");
             }
+          } finally {
+            if (subgroupTimeoutId !== void 0) clearTimeout(subgroupTimeoutId);
           }
           if (subscription.expectedStreams && subscription.expectedStreams === subscription.streamsAccepted) {
             subscription.controller?.close();

package/dist/client.d.cts

@@ -494,6 +494,7 @@ declare class SubscribeRequest implements PromiseLike<SubscribeOk | RequestError
     priority: number;
     forward: boolean;
     subscribeParameters: MessageParameter[];
+    earlyDiscardPolicy: EarlyDiscardPolicyConfig | undefined;
     largestLocation: Location | undefined;
     streamsAccepted: bigint;
     expectedStreams: bigint | undefined;
@@ -716,6 +717,8 @@ type SubscribeOptions = {
     startLocation?: Location;
     /** Required for {@link FilterType.AbsoluteRange}; exclusive upper group boundary (coerced to bigint if number provided). */
     endGroup?: bigint | number;
+    /** Per-subscription early discard policy. Overrides the client-level default set via {@link MOQtailClient.setEarlyDiscardPolicy}. */
+    earlyDiscardPolicy?: EarlyDiscardPolicyConfig;
 };
 /**
  * Narrowing update constraints applied to an existing SUBSCRIBE via {@link MOQtailClient.subscribeUpdate}.
@@ -799,6 +802,13 @@ type SwitchOptions = {
  * })
  * ```
  */
+/**
+ * Configuration for the early discard policy applied to incoming subgroup streams.
+ */
+type EarlyDiscardPolicyConfig = {
+    /** Cancel a subgroup QUIC stream if it has not fully completed within this many milliseconds. */
+    subgroupReceiveTimeout: number;
+};
 type FetchOptions = {
     /** Request priority (0 = highest, 255 = lowest). Rounded & clamped. */
     priority: number;
@@ -1277,6 +1287,25 @@ declare class MOQtailClient {
      * ```
      */
     sendDatagram(trackAlias: bigint, object: MoqtObject): Promise<void>;
+    /**
+     * Sets (or replaces) the client-level default early discard policy for incoming subgroup streams.
+     *
+     * When set, each incoming subgroup QUIC stream is given a deadline of `subgroupReceiveTimeout` ms to
+     * complete. If the stream has not finished within that window it is cancelled — objects already
+     * delivered to the subscription are kept, but no further objects arrive from that stream.
+     *
+     * This is a client-wide default. Individual subscriptions can override it via the `earlyDiscardPolicy`
+     * field in {@link SubscribeOptions}, which takes precedence over this setting.
+     *
+     * The policy takes effect on the next stream accepted after this call. Passing a new config
+     * replaces the previous one. Pass `undefined` to remove the default.
+     *
+     * @example
+     * ```ts
+     * client.setEarlyDiscardPolicy({ subgroupReceiveTimeout: 2000 })
+     * ```
+     */
+    setEarlyDiscardPolicy(config: EarlyDiscardPolicyConfig | undefined): void;
     /**
      * Gracefully terminates this {@link MOQtailClient} session and releases underlying {@link https://developer.mozilla.org/docs/Web/API/WebTransport | WebTransport} resources.
      *
@@ -1820,4 +1849,4 @@ declare class RecvStream {
     static new(readStream: ReadableStream<Uint8Array>, partialDataTimeout?: number, onDataReceived?: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void): Promise<RecvStream>;
 }
 
-export { ControlStream, type FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, type LiveObjectSource, LiveTrackSource, MOQtailClient, type MOQtailClientOptions, type MOQtailRequest, MemoryObjectCache, type ObjectCache, type PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, type SubscribeOptions, SubscribePublication, SubscribeRequest, type SubscribeUpdateOptions, type SwitchOptions, type Track, type TrackSource, TrackStatusRequest };
+export { ControlStream, type EarlyDiscardPolicyConfig, type FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, type LiveObjectSource, LiveTrackSource, MOQtailClient, type MOQtailClientOptions, type MOQtailRequest, MemoryObjectCache, type ObjectCache, type PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, type SubscribeOptions, SubscribePublication, SubscribeRequest, type SubscribeUpdateOptions, type SwitchOptions, type Track, type TrackSource, TrackStatusRequest };

package/dist/client.d.ts

@@ -494,6 +494,7 @@ declare class SubscribeRequest implements PromiseLike<SubscribeOk | RequestError
     priority: number;
     forward: boolean;
     subscribeParameters: MessageParameter[];
+    earlyDiscardPolicy: EarlyDiscardPolicyConfig | undefined;
     largestLocation: Location | undefined;
     streamsAccepted: bigint;
     expectedStreams: bigint | undefined;
@@ -716,6 +717,8 @@ type SubscribeOptions = {
     startLocation?: Location;
     /** Required for {@link FilterType.AbsoluteRange}; exclusive upper group boundary (coerced to bigint if number provided). */
     endGroup?: bigint | number;
+    /** Per-subscription early discard policy. Overrides the client-level default set via {@link MOQtailClient.setEarlyDiscardPolicy}. */
+    earlyDiscardPolicy?: EarlyDiscardPolicyConfig;
 };
 /**
  * Narrowing update constraints applied to an existing SUBSCRIBE via {@link MOQtailClient.subscribeUpdate}.
@@ -799,6 +802,13 @@ type SwitchOptions = {
  * })
  * ```
  */
+/**
+ * Configuration for the early discard policy applied to incoming subgroup streams.
+ */
+type EarlyDiscardPolicyConfig = {
+    /** Cancel a subgroup QUIC stream if it has not fully completed within this many milliseconds. */
+    subgroupReceiveTimeout: number;
+};
 type FetchOptions = {
     /** Request priority (0 = highest, 255 = lowest). Rounded & clamped. */
     priority: number;
@@ -1277,6 +1287,25 @@ declare class MOQtailClient {
      * ```
      */
     sendDatagram(trackAlias: bigint, object: MoqtObject): Promise<void>;
+    /**
+     * Sets (or replaces) the client-level default early discard policy for incoming subgroup streams.
+     *
+     * When set, each incoming subgroup QUIC stream is given a deadline of `subgroupReceiveTimeout` ms to
+     * complete. If the stream has not finished within that window it is cancelled — objects already
+     * delivered to the subscription are kept, but no further objects arrive from that stream.
+     *
+     * This is a client-wide default. Individual subscriptions can override it via the `earlyDiscardPolicy`
+     * field in {@link SubscribeOptions}, which takes precedence over this setting.
+     *
+     * The policy takes effect on the next stream accepted after this call. Passing a new config
+     * replaces the previous one. Pass `undefined` to remove the default.
+     *
+     * @example
+     * ```ts
+     * client.setEarlyDiscardPolicy({ subgroupReceiveTimeout: 2000 })
+     * ```
+     */
+    setEarlyDiscardPolicy(config: EarlyDiscardPolicyConfig | undefined): void;
     /**
      * Gracefully terminates this {@link MOQtailClient} session and releases underlying {@link https://developer.mozilla.org/docs/Web/API/WebTransport | WebTransport} resources.
      *
@@ -1820,4 +1849,4 @@ declare class RecvStream {
     static new(readStream: ReadableStream<Uint8Array>, partialDataTimeout?: number, onDataReceived?: (data: SubgroupObject | SubgroupHeader | FetchObject | FetchHeader) => void): Promise<RecvStream>;
 }
 
-export { ControlStream, type FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, type LiveObjectSource, LiveTrackSource, MOQtailClient, type MOQtailClientOptions, type MOQtailRequest, MemoryObjectCache, type ObjectCache, type PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, type SubscribeOptions, SubscribePublication, SubscribeRequest, type SubscribeUpdateOptions, type SwitchOptions, type Track, type TrackSource, TrackStatusRequest };
+export { ControlStream, type EarlyDiscardPolicyConfig, type FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, type LiveObjectSource, LiveTrackSource, MOQtailClient, type MOQtailClientOptions, type MOQtailRequest, MemoryObjectCache, type ObjectCache, type PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, type SubscribeOptions, SubscribePublication, SubscribeRequest, type SubscribeUpdateOptions, type SwitchOptions, type Track, type TrackSource, TrackStatusRequest };

package/dist/client.js

@@ -5121,6 +5121,7 @@ var SubscribeRequest = class {
   priority;
   forward;
   subscribeParameters;
+  earlyDiscardPolicy;
   largestLocation;
   // Updated on each received object
   streamsAccepted = 0n;
@@ -5956,6 +5957,11 @@ var handlerRequestsBlocked = async (_client, msg) => {
   logger.debug("handler/requests_blocked", "not implemented", msg);
 };
 
+// src/client/util/validators.ts
+function isValidTrackAlias(trackAlias) {
+  return trackAlias !== void 0 && trackAlias >= 0n;
+}
+
 // src/client/handler/subscribe.ts
 var handlerSubscribe = async (client, msg) => {
   logger.debug("handler/subscribe", `received requestId=${msg.requestId} ftn="${msg.fullTrackName}"`);
@@ -5988,7 +5994,7 @@ var handlerSubscribe = async (client, msg) => {
     await client.controlStream.send(response);
     return;
   }
-  if (!track.trackAlias) throw new Error("Expected track alias to be set");
+  if (!isValidTrackAlias(track.trackAlias)) throw new Error("Expected track alias to be set");
   const largestLocation = track.trackSource.live.largestLocation;
   const parameters = [...msg.parameters];
   if (largestLocation) {
@@ -6454,6 +6460,8 @@ var MOQtailClient = class _MOQtailClient {
   #isDestroyed = false;
   /** Internal monotonically increasing client-assigned request id counter (even/odd parity scheme advances by 2). */
   #dontUseRequestId = 0n;
+  /** Active early discard policy; undefined means no per-stream deadline is applied. */
+  #earlyDiscardPolicy;
   /**
    * TODO: onNamespaceAnnounced may be a better name
    * Fired when an PUBLISH_NAMESPACE control message is processed for a track namespace.
@@ -6905,6 +6913,28 @@ var MOQtailClient = class _MOQtailClient {
       return FullTrackName.tryNew("unknown", `track-${trackAlias}`);
     }
   }
+  /**
+   * Sets (or replaces) the client-level default early discard policy for incoming subgroup streams.
+   *
+   * When set, each incoming subgroup QUIC stream is given a deadline of `subgroupReceiveTimeout` ms to
+   * complete. If the stream has not finished within that window it is cancelled — objects already
+   * delivered to the subscription are kept, but no further objects arrive from that stream.
+   *
+   * This is a client-wide default. Individual subscriptions can override it via the `earlyDiscardPolicy`
+   * field in {@link SubscribeOptions}, which takes precedence over this setting.
+   *
+   * The policy takes effect on the next stream accepted after this call. Passing a new config
+   * replaces the previous one. Pass `undefined` to remove the default.
+   *
+   * @example
+   * ```ts
+   * client.setEarlyDiscardPolicy({ subgroupReceiveTimeout: 2000 })
+   * ```
+   */
+  setEarlyDiscardPolicy(config) {
+    this.#ensureActive();
+    this.#earlyDiscardPolicy = config;
+  }
   /**
    * Gracefully terminates this {@link MOQtailClient} session and releases underlying {@link https://developer.mozilla.org/docs/Web/API/WebTransport | WebTransport} resources.
    *
@@ -6989,7 +7019,7 @@ var MOQtailClient = class _MOQtailClient {
    */
   addOrUpdateTrack(track) {
     this.#ensureActive();
-    if (!track.trackAlias) {
+    if (!isValidTrackAlias(track.trackAlias)) {
       track.trackAlias = random60bitId();
     }
     this.trackSources.set(track.fullTrackName.toString(), track);
@@ -7121,6 +7151,7 @@ var MOQtailClient = class _MOQtailClient {
           break;
       }
       const request = new SubscribeRequest(msg);
+      request.earlyDiscardPolicy = args.earlyDiscardPolicy;
       this.requests.set(request.requestId, request);
       this.requestIdMap.addMapping(request.requestId, request.fullTrackName);
       logger.debug("MOQtailClient", `subscribe: sending SUBSCRIBE requestId=${msg.requestId} ftn="${fullTrackName}"`);
@@ -7269,7 +7300,7 @@ var MOQtailClient = class _MOQtailClient {
         const request = this.requests.get(subscriptionRequestId);
         if (request instanceof SubscribeRequest) {
           const trackAlias = this.subscriptionAliasMap.get(subscriptionRequestId);
-          if (!trackAlias)
+          if (!isValidTrackAlias(trackAlias))
             throw new InternalError("MOQtailClient.subscribeUpdate", "Request exists but track alias mapping does not");
           const subscription = this.subscriptions.get(trackAlias);
           if (!subscription)
@@ -7322,7 +7353,7 @@ var MOQtailClient = class _MOQtailClient {
       if (!(request instanceof SubscribeRequest))
         throw new ProtocolViolationError("MOQtailClient.switch", "Request id is not a subscription");
       const trackAlias = this.subscriptionAliasMap.get(subscriptionRequestId);
-      if (!trackAlias)
+      if (!isValidTrackAlias(trackAlias))
         throw new InternalError("MOQtailClient.switch", "Request exists but track alias mapping does not");
       const subscription = this.subscriptions.get(trackAlias);
       if (!subscription) throw new InternalError("MOQtailClient.switch", "Request exists but subscription does not");
@@ -7986,43 +8017,55 @@ var MOQtailClient = class _MOQtailClient {
         if (subscription) {
           subscription.streamsAccepted++;
           let firstObjectId = null;
-          while (true) {
-            const { done, value: nextObject } = await reader.read();
-            if (done) {
-              break;
-            }
-            if (nextObject) {
-              if (nextObject instanceof SubgroupObject) {
-                if (!firstObjectId) {
-                  firstObjectId = nextObject.objectId;
-                }
-                let subgroupId = null;
-                if (SubgroupHeaderType.isSubgroupIdZero(header.type)) {
-                  subgroupId = 0n;
-                } else if (SubgroupHeaderType.isSubgroupIdFirstObjectId(header.type)) {
-                  subgroupId = firstObjectId ?? null;
-                } else if (SubgroupHeaderType.hasExplicitSubgroupId(header.type)) {
-                  subgroupId = header.subgroupId ?? null;
-                }
-                const fullTrackName = this.aliasFullTrackNameMap.get(header.trackAlias);
-                if (!fullTrackName) {
-                  throw new ProtocolViolationError("MOQtailClient", "No full track name for received track alias");
+          let subgroupTimeoutId;
+          const effectiveDiscardPolicy = subscription.earlyDiscardPolicy ?? this.#earlyDiscardPolicy;
+          if (effectiveDiscardPolicy?.subgroupReceiveTimeout !== void 0) {
+            subgroupTimeoutId = setTimeout(() => {
+              reader.cancel("early discard: subgroupReceiveTimeout exceeded").catch(() => {
+              });
+            }, effectiveDiscardPolicy.subgroupReceiveTimeout);
+          }
+          try {
+            while (true) {
+              const { done, value: nextObject } = await reader.read();
+              if (done) {
+                break;
+              }
+              if (nextObject) {
+                if (nextObject instanceof SubgroupObject) {
+                  if (!firstObjectId) {
+                    firstObjectId = nextObject.objectId;
+                  }
+                  let subgroupId = null;
+                  if (SubgroupHeaderType.isSubgroupIdZero(header.type)) {
+                    subgroupId = 0n;
+                  } else if (SubgroupHeaderType.isSubgroupIdFirstObjectId(header.type)) {
+                    subgroupId = firstObjectId ?? null;
+                  } else if (SubgroupHeaderType.hasExplicitSubgroupId(header.type)) {
+                    subgroupId = header.subgroupId ?? null;
+                  }
+                  const fullTrackName = this.aliasFullTrackNameMap.get(header.trackAlias);
+                  if (!fullTrackName) {
+                    throw new ProtocolViolationError("MOQtailClient", "No full track name for received track alias");
+                  }
+                  const moqtObject = MoqtObject.fromSubgroupObject(
+                    nextObject,
+                    header.groupId,
+                    header.publisherPriority,
+                    subgroupId,
+                    fullTrackName
+                  );
+                  if (!subscription.largestLocation) subscription.largestLocation = moqtObject.location;
+                  if (subscription.largestLocation.compare(moqtObject.location) == -1)
+                    subscription.largestLocation = moqtObject.location;
+                  subscription.controller?.enqueue(moqtObject);
+                  continue;
                 }
-                const moqtObject = MoqtObject.fromSubgroupObject(
-                  nextObject,
-                  header.groupId,
-                  header.publisherPriority,
-                  subgroupId,
-                  fullTrackName
-                );
-                if (!subscription.largestLocation) subscription.largestLocation = moqtObject.location;
-                if (subscription.largestLocation.compare(moqtObject.location) == -1)
-                  subscription.largestLocation = moqtObject.location;
-                subscription.controller?.enqueue(moqtObject);
-                continue;
+                throw new ProtocolViolationError("MOQtailClient", "Received fetch object after subgroup header");
               }
-              throw new ProtocolViolationError("MOQtailClient", "Received fetch object after subgroup header");
             }
+          } finally {
+            if (subgroupTimeoutId !== void 0) clearTimeout(subgroupTimeoutId);
           }
           if (subscription.expectedStreams && subscription.expectedStreams === subscription.streamsAccepted) {
             subscription.controller?.close();

package/dist/index.cjs

@@ -5617,6 +5617,7 @@ var SubscribeRequest = class {
   priority;
   forward;
   subscribeParameters;
+  earlyDiscardPolicy;
   largestLocation;
   // Updated on each received object
   streamsAccepted = 0n;
@@ -6452,6 +6453,11 @@ var handlerRequestsBlocked = async (_client, msg) => {
   logger.debug("handler/requests_blocked", "not implemented", msg);
 };
 
+// src/client/util/validators.ts
+function isValidTrackAlias(trackAlias) {
+  return trackAlias !== void 0 && trackAlias >= 0n;
+}
+
 // src/client/handler/subscribe.ts
 var handlerSubscribe = async (client, msg) => {
   logger.debug("handler/subscribe", `received requestId=${msg.requestId} ftn="${msg.fullTrackName}"`);
@@ -6484,7 +6490,7 @@ var handlerSubscribe = async (client, msg) => {
     await client.controlStream.send(response);
     return;
   }
-  if (!track.trackAlias) throw new Error("Expected track alias to be set");
+  if (!isValidTrackAlias(track.trackAlias)) throw new Error("Expected track alias to be set");
   const largestLocation = track.trackSource.live.largestLocation;
   const parameters = [...msg.parameters];
   if (largestLocation) {
@@ -6950,6 +6956,8 @@ var MOQtailClient = class _MOQtailClient {
   #isDestroyed = false;
   /** Internal monotonically increasing client-assigned request id counter (even/odd parity scheme advances by 2). */
   #dontUseRequestId = 0n;
+  /** Active early discard policy; undefined means no per-stream deadline is applied. */
+  #earlyDiscardPolicy;
   /**
    * TODO: onNamespaceAnnounced may be a better name
    * Fired when an PUBLISH_NAMESPACE control message is processed for a track namespace.
@@ -7401,6 +7409,28 @@ var MOQtailClient = class _MOQtailClient {
       return FullTrackName.tryNew("unknown", `track-${trackAlias}`);
     }
   }
+  /**
+   * Sets (or replaces) the client-level default early discard policy for incoming subgroup streams.
+   *
+   * When set, each incoming subgroup QUIC stream is given a deadline of `subgroupReceiveTimeout` ms to
+   * complete. If the stream has not finished within that window it is cancelled — objects already
+   * delivered to the subscription are kept, but no further objects arrive from that stream.
+   *
+   * This is a client-wide default. Individual subscriptions can override it via the `earlyDiscardPolicy`
+   * field in {@link SubscribeOptions}, which takes precedence over this setting.
+   *
+   * The policy takes effect on the next stream accepted after this call. Passing a new config
+   * replaces the previous one. Pass `undefined` to remove the default.
+   *
+   * @example
+   * ```ts
+   * client.setEarlyDiscardPolicy({ subgroupReceiveTimeout: 2000 })
+   * ```
+   */
+  setEarlyDiscardPolicy(config) {
+    this.#ensureActive();
+    this.#earlyDiscardPolicy = config;
+  }
   /**
    * Gracefully terminates this {@link MOQtailClient} session and releases underlying {@link https://developer.mozilla.org/docs/Web/API/WebTransport | WebTransport} resources.
    *
@@ -7485,7 +7515,7 @@ var MOQtailClient = class _MOQtailClient {
    */
   addOrUpdateTrack(track) {
     this.#ensureActive();
-    if (!track.trackAlias) {
+    if (!isValidTrackAlias(track.trackAlias)) {
       track.trackAlias = random60bitId();
     }
     this.trackSources.set(track.fullTrackName.toString(), track);
@@ -7617,6 +7647,7 @@ var MOQtailClient = class _MOQtailClient {
           break;
       }
       const request = new SubscribeRequest(msg);
+      request.earlyDiscardPolicy = args.earlyDiscardPolicy;
       this.requests.set(request.requestId, request);
       this.requestIdMap.addMapping(request.requestId, request.fullTrackName);
       logger.debug("MOQtailClient", `subscribe: sending SUBSCRIBE requestId=${msg.requestId} ftn="${fullTrackName}"`);
@@ -7765,7 +7796,7 @@ var MOQtailClient = class _MOQtailClient {
         const request = this.requests.get(subscriptionRequestId);
         if (request instanceof SubscribeRequest) {
           const trackAlias = this.subscriptionAliasMap.get(subscriptionRequestId);
-          if (!trackAlias)
+          if (!isValidTrackAlias(trackAlias))
             throw new InternalError("MOQtailClient.subscribeUpdate", "Request exists but track alias mapping does not");
           const subscription = this.subscriptions.get(trackAlias);
           if (!subscription)
@@ -7818,7 +7849,7 @@ var MOQtailClient = class _MOQtailClient {
       if (!(request instanceof SubscribeRequest))
         throw new ProtocolViolationError("MOQtailClient.switch", "Request id is not a subscription");
       const trackAlias = this.subscriptionAliasMap.get(subscriptionRequestId);
-      if (!trackAlias)
+      if (!isValidTrackAlias(trackAlias))
         throw new InternalError("MOQtailClient.switch", "Request exists but track alias mapping does not");
       const subscription = this.subscriptions.get(trackAlias);
       if (!subscription) throw new InternalError("MOQtailClient.switch", "Request exists but subscription does not");
@@ -8482,43 +8513,55 @@ var MOQtailClient = class _MOQtailClient {
         if (subscription) {
           subscription.streamsAccepted++;
           let firstObjectId = null;
-          while (true) {
-            const { done, value: nextObject } = await reader.read();
-            if (done) {
-              break;
-            }
-            if (nextObject) {
-              if (nextObject instanceof SubgroupObject) {
-                if (!firstObjectId) {
-                  firstObjectId = nextObject.objectId;
-                }
-                let subgroupId = null;
-                if (exports.SubgroupHeaderType.isSubgroupIdZero(header.type)) {
-                  subgroupId = 0n;
-                } else if (exports.SubgroupHeaderType.isSubgroupIdFirstObjectId(header.type)) {
-                  subgroupId = firstObjectId ?? null;
-                } else if (exports.SubgroupHeaderType.hasExplicitSubgroupId(header.type)) {
-                  subgroupId = header.subgroupId ?? null;
-                }
-                const fullTrackName = this.aliasFullTrackNameMap.get(header.trackAlias);
-                if (!fullTrackName) {
-                  throw new ProtocolViolationError("MOQtailClient", "No full track name for received track alias");
+          let subgroupTimeoutId;
+          const effectiveDiscardPolicy = subscription.earlyDiscardPolicy ?? this.#earlyDiscardPolicy;
+          if (effectiveDiscardPolicy?.subgroupReceiveTimeout !== void 0) {
+            subgroupTimeoutId = setTimeout(() => {
+              reader.cancel("early discard: subgroupReceiveTimeout exceeded").catch(() => {
+              });
+            }, effectiveDiscardPolicy.subgroupReceiveTimeout);
+          }
+          try {
+            while (true) {
+              const { done, value: nextObject } = await reader.read();
+              if (done) {
+                break;
+              }
+              if (nextObject) {
+                if (nextObject instanceof SubgroupObject) {
+                  if (!firstObjectId) {
+                    firstObjectId = nextObject.objectId;
+                  }
+                  let subgroupId = null;
+                  if (exports.SubgroupHeaderType.isSubgroupIdZero(header.type)) {
+                    subgroupId = 0n;
+                  } else if (exports.SubgroupHeaderType.isSubgroupIdFirstObjectId(header.type)) {
+                    subgroupId = firstObjectId ?? null;
+                  } else if (exports.SubgroupHeaderType.hasExplicitSubgroupId(header.type)) {
+                    subgroupId = header.subgroupId ?? null;
+                  }
+                  const fullTrackName = this.aliasFullTrackNameMap.get(header.trackAlias);
+                  if (!fullTrackName) {
+                    throw new ProtocolViolationError("MOQtailClient", "No full track name for received track alias");
+                  }
+                  const moqtObject = MoqtObject.fromSubgroupObject(
+                    nextObject,
+                    header.groupId,
+                    header.publisherPriority,
+                    subgroupId,
+                    fullTrackName
+                  );
+                  if (!subscription.largestLocation) subscription.largestLocation = moqtObject.location;
+                  if (subscription.largestLocation.compare(moqtObject.location) == -1)
+                    subscription.largestLocation = moqtObject.location;
+                  subscription.controller?.enqueue(moqtObject);
+                  continue;
                 }
-                const moqtObject = MoqtObject.fromSubgroupObject(
-                  nextObject,
-                  header.groupId,
-                  header.publisherPriority,
-                  subgroupId,
-                  fullTrackName
-                );
-                if (!subscription.largestLocation) subscription.largestLocation = moqtObject.location;
-                if (subscription.largestLocation.compare(moqtObject.location) == -1)
-                  subscription.largestLocation = moqtObject.location;
-                subscription.controller?.enqueue(moqtObject);
-                continue;
+                throw new ProtocolViolationError("MOQtailClient", "Received fetch object after subgroup header");
               }
-              throw new ProtocolViolationError("MOQtailClient", "Received fetch object after subgroup header");
             }
+          } finally {
+            if (subgroupTimeoutId !== void 0) clearTimeout(subgroupTimeoutId);
           }
           if (subscription.expectedStreams && subscription.expectedStreams === subscription.streamsAccepted) {
             subscription.controller?.close();

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { ControlStream, FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, LiveObjectSource, LiveTrackSource, MOQtailClient, MOQtailClientOptions, MOQtailRequest, MemoryObjectCache, ObjectCache, PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, SubscribeOptions, SubscribePublication, SubscribeRequest, SubscribeUpdateOptions, SwitchOptions, Track, TrackSource, TrackStatusRequest } from './client.cjs';
+export { ControlStream, EarlyDiscardPolicyConfig, FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, LiveObjectSource, LiveTrackSource, MOQtailClient, MOQtailClientOptions, MOQtailRequest, MemoryObjectCache, ObjectCache, PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, SubscribeOptions, SubscribePublication, SubscribeRequest, SubscribeUpdateOptions, SwitchOptions, Track, TrackSource, TrackStatusRequest } from './client.cjs';
 export { AudioLevel, CMSF, CMSFCatalog, CMSFTrack, CaptureTimestamp, CastingError, ExtensionHeader, ExtensionHeaders, ImmutableExtensionsObjectExtension, InternalError, InvalidTypeError, InvalidUTF8Error, KeyValueFormattingError, LengthExceedsMaxError, MOQtailError, NotEnoughBytesError, ObjectExtension, PriorGroupIdGapExtension, PriorObjectIdGapExtension, ProtocolViolationError, RequestIdError, Switch, TerminationCode, TerminationError, TimeoutError, TrackNameError, UnknownObjectExtension, VarIntOverflowError, VideoConfig, VideoFrameMarking } from './model.cjs';
 export { A as AuthTokenVariant, a as AuthorizationToken, B as BaseByteBuffer, b as ByteBuffer, C as ClientSetup, c as ControlMessage, d as ControlMessageType, D as Datagram, e as DefaultPublisherGroupOrderExtension, f as DefaultPublisherPriorityExtension, g as DeliveryTimeout, h as DeliveryTimeoutExtension, i as DynamicGroupsExtension, E as EndOfRangeKind, j as Expires, F as Fetch, k as FetchCancel, l as FetchHeader, m as FetchHeaderType, n as FetchObject, o as FetchObjectContext, p as FetchOk, q as FetchType, r as FilterType, s as Forward, t as FrozenByteBuffer, u as FullTrackName, G as GoAway, v as GroupOrder, w as GroupOrderParam, H as Header, I as ImmutableExtensionsExtension, K as KeyValuePair, L as LOCHeaderExtensionId, x as LargestObject, y as Location, M as MAX_FULL_TRACK_NAME_LENGTH, z as MAX_NAMESPACE_TUPLE_COUNT, J as MAX_REASON_PHRASE_LEN, N as MaxAuthTokenCacheSize, O as MaxCacheDurationExtension, P as MaxRequestId, Q as MaxRequestIdParameter, R as MessageParameter, S as MessageParameterType, T as MessageParameters, U as MoqtObject, V as Namespace, W as NamespaceDone, X as NamespaceSubscribeOptions, Y as NewGroupRequest, Z as ObjectDatagramType, _ as ObjectForwardingPreference, $ as ObjectStatus, a0 as Parameter, a1 as Path, a2 as Publish, a3 as PublishDone, a4 as PublishDoneStatusCode, a5 as PublishNamespace, a6 as PublishNamespaceCancel, a7 as PublishNamespaceDone, a8 as PublishOk, a9 as ReasonPhrase, aa as RequestError, ab as RequestErrorCode, ac as RequestIdMap, ad as RequestOk, ae as RequestUpdate, af as RequestsBlocked, ag as SUPPORTED_VERSIONS, ah as ServerSetup, ai as SetupParameter, aj as SetupParameterType, ak as SetupParameters, al as SubgroupHeader, am as SubgroupHeaderType, an as SubgroupObject, ao as Subscribe, ap as SubscribeNamespace, aq as SubscribeOk, ar as SubscriberPriority, as as SubscriptionFilter, at as TokenAliasType, au as TrackExtension, av as TrackExtensionType, aw as TrackStatus, ax as TrackStatusCode, ay as Tuple, az as TupleField, aA as UnknownTrackExtension, aB as Unsubscribe, aC as UnsubscribeNamespace, aD as applyMessageParameterUpdate, aE as controlMessageTypeFromBigInt, aF as fetchTypeFromBigInt, aG as filterTypeFromBigInt, aH as groupOrderFromNumber, aI as isBytes, aJ as isVarInt, aK as locHeaderExtensionIdFromNumber, aL as messageParameterTypeFromNumber, aM as publishDoneStatusCodeFromBigInt, aN as requestErrorCodeFromBigInt, aO as setupParameterTypeFromNumber, aP as tokenAliasTypeFromNumber, aQ as trackStatusCodeFromBigInt } from './setup_parameter-BOeGq6Mv.cjs';
 export { ClockNormalizer, NetworkTelemetry } from './util.cjs';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { ControlStream, FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, LiveObjectSource, LiveTrackSource, MOQtailClient, MOQtailClientOptions, MOQtailRequest, MemoryObjectCache, ObjectCache, PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, SubscribeOptions, SubscribePublication, SubscribeRequest, SubscribeUpdateOptions, SwitchOptions, Track, TrackSource, TrackStatusRequest } from './client.js';
+export { ControlStream, EarlyDiscardPolicyConfig, FetchOptions, FetchPublication, FetchRequest, HybridTrackSource, LiveObjectSource, LiveTrackSource, MOQtailClient, MOQtailClientOptions, MOQtailRequest, MemoryObjectCache, ObjectCache, PastObjectSource, PublishNamespaceRequest, PublishPublication, PublishRequest, RecvDatagramStream, RecvStream, RingBufferObjectCache, SendDatagramStream, SendStream, StaticTrackSource, SubscribeNamespaceRequest, SubscribeOptions, SubscribePublication, SubscribeRequest, SubscribeUpdateOptions, SwitchOptions, Track, TrackSource, TrackStatusRequest } from './client.js';
 export { AudioLevel, CMSF, CMSFCatalog, CMSFTrack, CaptureTimestamp, CastingError, ExtensionHeader, ExtensionHeaders, ImmutableExtensionsObjectExtension, InternalError, InvalidTypeError, InvalidUTF8Error, KeyValueFormattingError, LengthExceedsMaxError, MOQtailError, NotEnoughBytesError, ObjectExtension, PriorGroupIdGapExtension, PriorObjectIdGapExtension, ProtocolViolationError, RequestIdError, Switch, TerminationCode, TerminationError, TimeoutError, TrackNameError, UnknownObjectExtension, VarIntOverflowError, VideoConfig, VideoFrameMarking } from './model.js';
 export { A as AuthTokenVariant, a as AuthorizationToken, B as BaseByteBuffer, b as ByteBuffer, C as ClientSetup, c as ControlMessage, d as ControlMessageType, D as Datagram, e as DefaultPublisherGroupOrderExtension, f as DefaultPublisherPriorityExtension, g as DeliveryTimeout, h as DeliveryTimeoutExtension, i as DynamicGroupsExtension, E as EndOfRangeKind, j as Expires, F as Fetch, k as FetchCancel, l as FetchHeader, m as FetchHeaderType, n as FetchObject, o as FetchObjectContext, p as FetchOk, q as FetchType, r as FilterType, s as Forward, t as FrozenByteBuffer, u as FullTrackName, G as GoAway, v as GroupOrder, w as GroupOrderParam, H as Header, I as ImmutableExtensionsExtension, K as KeyValuePair, L as LOCHeaderExtensionId, x as LargestObject, y as Location, M as MAX_FULL_TRACK_NAME_LENGTH, z as MAX_NAMESPACE_TUPLE_COUNT, J as MAX_REASON_PHRASE_LEN, N as MaxAuthTokenCacheSize, O as MaxCacheDurationExtension, P as MaxRequestId, Q as MaxRequestIdParameter, R as MessageParameter, S as MessageParameterType, T as MessageParameters, U as MoqtObject, V as Namespace, W as NamespaceDone, X as NamespaceSubscribeOptions, Y as NewGroupRequest, Z as ObjectDatagramType, _ as ObjectForwardingPreference, $ as ObjectStatus, a0 as Parameter, a1 as Path, a2 as Publish, a3 as PublishDone, a4 as PublishDoneStatusCode, a5 as PublishNamespace, a6 as PublishNamespaceCancel, a7 as PublishNamespaceDone, a8 as PublishOk, a9 as ReasonPhrase, aa as RequestError, ab as RequestErrorCode, ac as RequestIdMap, ad as RequestOk, ae as RequestUpdate, af as RequestsBlocked, ag as SUPPORTED_VERSIONS, ah as ServerSetup, ai as SetupParameter, aj as SetupParameterType, ak as SetupParameters, al as SubgroupHeader, am as SubgroupHeaderType, an as SubgroupObject, ao as Subscribe, ap as SubscribeNamespace, aq as SubscribeOk, ar as SubscriberPriority, as as SubscriptionFilter, at as TokenAliasType, au as TrackExtension, av as TrackExtensionType, aw as TrackStatus, ax as TrackStatusCode, ay as Tuple, az as TupleField, aA as UnknownTrackExtension, aB as Unsubscribe, aC as UnsubscribeNamespace, aD as applyMessageParameterUpdate, aE as controlMessageTypeFromBigInt, aF as fetchTypeFromBigInt, aG as filterTypeFromBigInt, aH as groupOrderFromNumber, aI as isBytes, aJ as isVarInt, aK as locHeaderExtensionIdFromNumber, aL as messageParameterTypeFromNumber, aM as publishDoneStatusCodeFromBigInt, aN as requestErrorCodeFromBigInt, aO as setupParameterTypeFromNumber, aP as tokenAliasTypeFromNumber, aQ as trackStatusCodeFromBigInt } from './setup_parameter-BOeGq6Mv.js';
 export { ClockNormalizer, NetworkTelemetry } from './util.js';

package/dist/index.js

@@ -5615,6 +5615,7 @@ var SubscribeRequest = class {
   priority;
   forward;
   subscribeParameters;
+  earlyDiscardPolicy;
   largestLocation;
   // Updated on each received object
   streamsAccepted = 0n;
@@ -6450,6 +6451,11 @@ var handlerRequestsBlocked = async (_client, msg) => {
   logger.debug("handler/requests_blocked", "not implemented", msg);
 };
 
+// src/client/util/validators.ts
+function isValidTrackAlias(trackAlias) {
+  return trackAlias !== void 0 && trackAlias >= 0n;
+}
+
 // src/client/handler/subscribe.ts
 var handlerSubscribe = async (client, msg) => {
   logger.debug("handler/subscribe", `received requestId=${msg.requestId} ftn="${msg.fullTrackName}"`);
@@ -6482,7 +6488,7 @@ var handlerSubscribe = async (client, msg) => {
     await client.controlStream.send(response);
     return;
   }
-  if (!track.trackAlias) throw new Error("Expected track alias to be set");
+  if (!isValidTrackAlias(track.trackAlias)) throw new Error("Expected track alias to be set");
   const largestLocation = track.trackSource.live.largestLocation;
   const parameters = [...msg.parameters];
   if (largestLocation) {
@@ -6948,6 +6954,8 @@ var MOQtailClient = class _MOQtailClient {
   #isDestroyed = false;
   /** Internal monotonically increasing client-assigned request id counter (even/odd parity scheme advances by 2). */
   #dontUseRequestId = 0n;
+  /** Active early discard policy; undefined means no per-stream deadline is applied. */
+  #earlyDiscardPolicy;
   /**
    * TODO: onNamespaceAnnounced may be a better name
    * Fired when an PUBLISH_NAMESPACE control message is processed for a track namespace.
@@ -7399,6 +7407,28 @@ var MOQtailClient = class _MOQtailClient {
       return FullTrackName.tryNew("unknown", `track-${trackAlias}`);
     }
   }
+  /**
+   * Sets (or replaces) the client-level default early discard policy for incoming subgroup streams.
+   *
+   * When set, each incoming subgroup QUIC stream is given a deadline of `subgroupReceiveTimeout` ms to
+   * complete. If the stream has not finished within that window it is cancelled — objects already
+   * delivered to the subscription are kept, but no further objects arrive from that stream.
+   *
+   * This is a client-wide default. Individual subscriptions can override it via the `earlyDiscardPolicy`
+   * field in {@link SubscribeOptions}, which takes precedence over this setting.
+   *
+   * The policy takes effect on the next stream accepted after this call. Passing a new config
+   * replaces the previous one. Pass `undefined` to remove the default.
+   *
+   * @example
+   * ```ts
+   * client.setEarlyDiscardPolicy({ subgroupReceiveTimeout: 2000 })
+   * ```
+   */
+  setEarlyDiscardPolicy(config) {
+    this.#ensureActive();
+    this.#earlyDiscardPolicy = config;
+  }
   /**
    * Gracefully terminates this {@link MOQtailClient} session and releases underlying {@link https://developer.mozilla.org/docs/Web/API/WebTransport | WebTransport} resources.
    *
@@ -7483,7 +7513,7 @@ var MOQtailClient = class _MOQtailClient {
    */
   addOrUpdateTrack(track) {
     this.#ensureActive();
-    if (!track.trackAlias) {
+    if (!isValidTrackAlias(track.trackAlias)) {
       track.trackAlias = random60bitId();
     }
     this.trackSources.set(track.fullTrackName.toString(), track);
@@ -7615,6 +7645,7 @@ var MOQtailClient = class _MOQtailClient {
           break;
       }
       const request = new SubscribeRequest(msg);
+      request.earlyDiscardPolicy = args.earlyDiscardPolicy;
       this.requests.set(request.requestId, request);
       this.requestIdMap.addMapping(request.requestId, request.fullTrackName);
       logger.debug("MOQtailClient", `subscribe: sending SUBSCRIBE requestId=${msg.requestId} ftn="${fullTrackName}"`);
@@ -7763,7 +7794,7 @@ var MOQtailClient = class _MOQtailClient {
         const request = this.requests.get(subscriptionRequestId);
         if (request instanceof SubscribeRequest) {
           const trackAlias = this.subscriptionAliasMap.get(subscriptionRequestId);
-          if (!trackAlias)
+          if (!isValidTrackAlias(trackAlias))
             throw new InternalError("MOQtailClient.subscribeUpdate", "Request exists but track alias mapping does not");
           const subscription = this.subscriptions.get(trackAlias);
           if (!subscription)
@@ -7816,7 +7847,7 @@ var MOQtailClient = class _MOQtailClient {
       if (!(request instanceof SubscribeRequest))
         throw new ProtocolViolationError("MOQtailClient.switch", "Request id is not a subscription");
       const trackAlias = this.subscriptionAliasMap.get(subscriptionRequestId);
-      if (!trackAlias)
+      if (!isValidTrackAlias(trackAlias))
         throw new InternalError("MOQtailClient.switch", "Request exists but track alias mapping does not");
       const subscription = this.subscriptions.get(trackAlias);
       if (!subscription) throw new InternalError("MOQtailClient.switch", "Request exists but subscription does not");
@@ -8480,43 +8511,55 @@ var MOQtailClient = class _MOQtailClient {
         if (subscription) {
           subscription.streamsAccepted++;
           let firstObjectId = null;
-          while (true) {
-            const { done, value: nextObject } = await reader.read();
-            if (done) {
-              break;
-            }
-            if (nextObject) {
-              if (nextObject instanceof SubgroupObject) {
-                if (!firstObjectId) {
-                  firstObjectId = nextObject.objectId;
-                }
-                let subgroupId = null;
-                if (SubgroupHeaderType.isSubgroupIdZero(header.type)) {
-                  subgroupId = 0n;
-                } else if (SubgroupHeaderType.isSubgroupIdFirstObjectId(header.type)) {
-                  subgroupId = firstObjectId ?? null;
-                } else if (SubgroupHeaderType.hasExplicitSubgroupId(header.type)) {
-                  subgroupId = header.subgroupId ?? null;
-                }
-                const fullTrackName = this.aliasFullTrackNameMap.get(header.trackAlias);
-                if (!fullTrackName) {
-                  throw new ProtocolViolationError("MOQtailClient", "No full track name for received track alias");
+          let subgroupTimeoutId;
+          const effectiveDiscardPolicy = subscription.earlyDiscardPolicy ?? this.#earlyDiscardPolicy;
+          if (effectiveDiscardPolicy?.subgroupReceiveTimeout !== void 0) {
+            subgroupTimeoutId = setTimeout(() => {
+              reader.cancel("early discard: subgroupReceiveTimeout exceeded").catch(() => {
+              });
+            }, effectiveDiscardPolicy.subgroupReceiveTimeout);
+          }
+          try {
+            while (true) {
+              const { done, value: nextObject } = await reader.read();
+              if (done) {
+                break;
+              }
+              if (nextObject) {
+                if (nextObject instanceof SubgroupObject) {
+                  if (!firstObjectId) {
+                    firstObjectId = nextObject.objectId;
+                  }
+                  let subgroupId = null;
+                  if (SubgroupHeaderType.isSubgroupIdZero(header.type)) {
+                    subgroupId = 0n;
+                  } else if (SubgroupHeaderType.isSubgroupIdFirstObjectId(header.type)) {
+                    subgroupId = firstObjectId ?? null;
+                  } else if (SubgroupHeaderType.hasExplicitSubgroupId(header.type)) {
+                    subgroupId = header.subgroupId ?? null;
+                  }
+                  const fullTrackName = this.aliasFullTrackNameMap.get(header.trackAlias);
+                  if (!fullTrackName) {
+                    throw new ProtocolViolationError("MOQtailClient", "No full track name for received track alias");
+                  }
+                  const moqtObject = MoqtObject.fromSubgroupObject(
+                    nextObject,
+                    header.groupId,
+                    header.publisherPriority,
+                    subgroupId,
+                    fullTrackName
+                  );
+                  if (!subscription.largestLocation) subscription.largestLocation = moqtObject.location;
+                  if (subscription.largestLocation.compare(moqtObject.location) == -1)
+                    subscription.largestLocation = moqtObject.location;
+                  subscription.controller?.enqueue(moqtObject);
+                  continue;
                 }
-                const moqtObject = MoqtObject.fromSubgroupObject(
-                  nextObject,
-                  header.groupId,
-                  header.publisherPriority,
-                  subgroupId,
-                  fullTrackName
-                );
-                if (!subscription.largestLocation) subscription.largestLocation = moqtObject.location;
-                if (subscription.largestLocation.compare(moqtObject.location) == -1)
-                  subscription.largestLocation = moqtObject.location;
-                subscription.controller?.enqueue(moqtObject);
-                continue;
+                throw new ProtocolViolationError("MOQtailClient", "Received fetch object after subgroup header");
               }
-              throw new ProtocolViolationError("MOQtailClient", "Received fetch object after subgroup header");
             }
+          } finally {
+            if (subgroupTimeoutId !== void 0) clearTimeout(subgroupTimeoutId);
           }
           if (subscription.expectedStreams && subscription.expectedStreams === subscription.streamsAccepted) {
             subscription.controller?.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moqtail",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Media Over QUIC Transport client implementation",
   "type": "module",
   "license": "Apache-2.0",