moqtail 0.7.0 → 0.8.0

package/README.md

@@ -491,17 +491,20 @@ console.log(`Average latency: ${telemetry.latency} ms`)
 
 ### Clock Synchronization
 
-The `AkamaiOffset` utility provides clock synchronization with Akamai's time service:
+The `ClockNormalizer` utility provides clock synchronization with a given time service:
 
 ```typescript
-import { AkamaiOffset } from './util/get_akamai_offset'
+import { ClockNormalizer } from './util/clock_normalizer'
 
-// Get clock skew relative to Akamai time servers
-const clockSkew = await AkamaiOffset.getClockSkew()
-console.log(`Local clock is ${clockSkew}ms ahead of network time`)
+// Get clock skew relative to a given time server
+const numSamples = 5 // default is 5
+const timeServerUrl = 'https://time.akamai.com/?ms'
+const offset = await ClockNormalizer.calculateSkew(timeServerUrl, numSamples)
+const clockNormalizer = new ClockNormalizer(timeServerUrl, offset, numSamples)
+console.log(`Local clock is ${offset}ms ahead of network time`)
 
 // Adjust local timestamps for network synchronization
-const networkTime = Date.now() - clockSkew
+const networkTime = Date.now() - offset
 ```
 
 **Features:**

package/dist/{byte_buffer-BOK6VPTF.d.cts → byte_buffer-BM4uNj4n.d.cts}

@@ -364,13 +364,22 @@ declare class ReasonPhrase {
  */
 /**
  * @public
- * Object datagram status types for MOQT objects.
- * - `WithoutExtensions`: Object datagram without extensions.
- * - `WithExtensions`: Object datagram with extensions.
+ * Object datagram status types for MOQT objects (Draft-14).
+ * Status datagrams use types 0x20-0x21.
+ *
+ * Type bit layout:
+ * - Bit 0: Extensions Present (0 = no, 1 = yes)
+ *
+ * | Type | Extensions Present | Object ID Present |
+ * |------|-------------------|------------------|
+ * | 0x20 | No                | Yes              |
+ * | 0x21 | Yes               | Yes              |
  */
 declare enum ObjectDatagramStatusType {
-    WithoutExtensions = 2,
-    WithExtensions = 3
+    /** Status without extensions (0x20) */
+    WithoutExtensions = 32,
+    /** Status with extensions (0x21) */
+    WithExtensions = 33
 }
 /**
  * @public
@@ -384,16 +393,51 @@ declare namespace ObjectDatagramStatusType {
      * @throws Error if the value is not valid.
      */
     function tryFrom(value: number | bigint): ObjectDatagramStatusType;
+    /**
+     * Returns true if the type has extensions.
+     * @param t - The ObjectDatagramStatusType.
+     */
+    function hasExtensions(t: ObjectDatagramStatusType): boolean;
 }
 /**
  * @public
- * Object datagram types for MOQT objects.
- * - `WithoutExtensions`: Object datagram without extensions.
- * - `WithExtensions`: Object datagram with extensions.
+ * Object datagram types for MOQT objects (Draft-14).
+ *
+ * Type bit layout for 0x00-0x07:
+ * - Bit 0: Extensions Present (0 = no, 1 = yes)
+ * - Bit 1: End of Group (0 = no, 1 = yes)
+ * - Bit 2: Object ID Present (0 = Object ID omitted & is 0, 1 = Object ID present)
+ *
+ * Note: Bit 2 is inverted - when set, Object ID is ABSENT (and assumed 0)
+ *
+ * | Type | End of Group | Extensions | Object ID Present | Content |
+ * |------|-------------|------------|------------------|--------|
+ * | 0x00 | No          | No         | Yes              | Payload |
+ * | 0x01 | No          | Yes        | Yes              | Payload |
+ * | 0x02 | Yes         | No         | Yes              | Payload |
+ * | 0x03 | Yes         | Yes        | Yes              | Payload |
+ * | 0x04 | No          | No         | No (ID=0)        | Payload |
+ * | 0x05 | No          | Yes        | No (ID=0)        | Payload |
+ * | 0x06 | Yes         | No         | No (ID=0)        | Payload |
+ * | 0x07 | Yes         | Yes        | No (ID=0)        | Payload |
  */
 declare enum ObjectDatagramType {
-    WithoutExtensions = 0,
-    WithExtensions = 1
+    /** No End of Group, No Extensions, Object ID Present (0x00) */
+    Type0x00 = 0,
+    /** No End of Group, With Extensions, Object ID Present (0x01) */
+    Type0x01 = 1,
+    /** End of Group, No Extensions, Object ID Present (0x02) */
+    Type0x02 = 2,
+    /** End of Group, With Extensions, Object ID Present (0x03) */
+    Type0x03 = 3,
+    /** No End of Group, No Extensions, Object ID = 0 (0x04) */
+    Type0x04 = 4,
+    /** No End of Group, With Extensions, Object ID = 0 (0x05) */
+    Type0x05 = 5,
+    /** End of Group, No Extensions, Object ID = 0 (0x06) */
+    Type0x06 = 6,
+    /** End of Group, With Extensions, Object ID = 0 (0x07) */
+    Type0x07 = 7
 }
 /**
  * @public
@@ -407,6 +451,29 @@ declare namespace ObjectDatagramType {
      * @throws Error if the value is not valid.
      */
     function tryFrom(value: number | bigint): ObjectDatagramType;
+    /**
+     * Returns true if the type has extensions (bit 0 set).
+     * @param t - The ObjectDatagramType.
+     */
+    function hasExtensions(t: ObjectDatagramType): boolean;
+    /**
+     * Returns true if the type indicates End of Group (bit 1 set).
+     * @param t - The ObjectDatagramType.
+     */
+    function isEndOfGroup(t: ObjectDatagramType): boolean;
+    /**
+     * Returns true if Object ID is present in the wire format.
+     * When bit 2 is set (0x04-0x07), Object ID is ABSENT and assumed to be 0.
+     * @param t - The ObjectDatagramType.
+     */
+    function hasObjectId(t: ObjectDatagramType): boolean;
+    /**
+     * Determines the appropriate type for given properties.
+     * @param hasExtensions - Whether extensions are present.
+     * @param endOfGroup - Whether this is the last object in the group.
+     * @param objectIdIsZero - Whether the objectId is 0.
+     */
+    function fromProperties(hasExtensions: boolean, endOfGroup: boolean, objectIdIsZero: boolean): ObjectDatagramType;
 }
 /**
  * @public
@@ -539,18 +606,40 @@ declare namespace ObjectStatus {
  * limitations under the License.
  */
 
+/**
+ * Represents an OBJECT_DATAGRAM message (Draft-14).
+ *
+ * Type values 0x00-0x07 indicate payload datagrams with varying properties:
+ * - Bit 0: Extensions Present
+ * - Bit 1: End of Group
+ * - Bit 2: Object ID NOT present (when set, Object ID is 0)
+ */
 declare class DatagramObject {
     readonly type: ObjectDatagramType;
     readonly publisherPriority: number;
     readonly extensionHeaders: KeyValuePair[] | null;
     readonly payload: Uint8Array;
+    readonly endOfGroup: boolean;
     readonly trackAlias: bigint;
     readonly location: Location;
     private constructor();
     get groupId(): bigint;
     get objectId(): bigint;
-    static newWithExtensions(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, extensionHeaders: KeyValuePair[], payload: Uint8Array): DatagramObject;
-    static newWithoutExtensions(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, payload: Uint8Array): DatagramObject;
+    /**
+     * Create a new DatagramObject with all properties specified.
+     * The type is automatically determined based on extensions, endOfGroup, and objectId.
+     */
+    static new(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, extensionHeaders: KeyValuePair[] | null, payload: Uint8Array, endOfGroup?: boolean): DatagramObject;
+    /**
+     * Create a DatagramObject with extensions.
+     * @deprecated Use DatagramObject.new() instead for Draft-14 compliance.
+     */
+    static newWithExtensions(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, extensionHeaders: KeyValuePair[], payload: Uint8Array, endOfGroup?: boolean): DatagramObject;
+    /**
+     * Create a DatagramObject without extensions.
+     * @deprecated Use DatagramObject.new() instead for Draft-14 compliance.
+     */
+    static newWithoutExtensions(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, payload: Uint8Array, endOfGroup?: boolean): DatagramObject;
     serialize(): FrozenByteBuffer;
     static deserialize(buf: BaseByteBuffer): DatagramObject;
 }
@@ -571,6 +660,16 @@ declare class DatagramObject {
  * limitations under the License.
  */
 
+/**
+ * Represents an OBJECT_DATAGRAM with status (Draft-14).
+ *
+ * Type values 0x20-0x21 indicate status datagrams:
+ * - 0x20: Without extensions, Object ID present
+ * - 0x21: With extensions, Object ID present
+ *
+ * Status datagrams always have Object ID present (unlike payload datagrams
+ * which can omit Object ID when it's 0).
+ */
 declare class DatagramStatus {
     readonly type: ObjectDatagramStatusType;
     readonly publisherPriority: number;
@@ -581,7 +680,20 @@ declare class DatagramStatus {
     private constructor();
     get groupId(): bigint;
     get objectId(): bigint;
+    /**
+     * Create a new DatagramStatus with all properties specified.
+     * The type is automatically determined based on whether extensions are present.
+     */
+    static new(trackAlias: bigint | number, location: Location, publisherPriority: number, extensionHeaders: KeyValuePair[] | null, objectStatus: ObjectStatus): DatagramStatus;
+    /**
+     * Create a DatagramStatus with extensions.
+     * @deprecated Use DatagramStatus.new() instead for Draft-14 compliance.
+     */
     static withExtensions(trackAlias: bigint | number, location: Location, publisherPriority: number, extensionHeaders: KeyValuePair[], objectStatus: ObjectStatus): DatagramStatus;
+    /**
+     * Create a DatagramStatus without extensions.
+     * @deprecated Use DatagramStatus.new() instead for Draft-14 compliance.
+     */
     static newWithoutExtensions(trackAlias: bigint | number, location: Location, publisherPriority: number, objectStatus: ObjectStatus): DatagramStatus;
     serialize(): FrozenByteBuffer;
     static deserialize(buf: BaseByteBuffer): DatagramStatus;
@@ -766,10 +878,21 @@ declare class MoqtObject {
     static newWithPayload(fullTrackName: FullTrackName, location: Location, publisherPriority: number, objectForwardingPreference: ObjectForwardingPreference, subgroupId: bigint | number | null, extensionHeaders: KeyValuePair[] | null, payload: Uint8Array): MoqtObject;
     static newWithStatus(fullTrackName: FullTrackName, location: Location, publisherPriority: number, objectForwardingPreference: ObjectForwardingPreference, subgroupId: bigint | number | null, extensionHeaders: KeyValuePair[] | null, objectStatus: ObjectStatus): MoqtObject;
     static fromDatagramObject(datagramObject: DatagramObject, fullTrackName: FullTrackName): MoqtObject;
+    /**
+     * Returns the endOfGroup flag from the source DatagramObject.
+     * This is separate from ObjectStatus.EndOfGroup - the flag indicates
+     * this is the last object in the group even with Normal status.
+     */
+    static isDatagramEndOfGroup(datagramObject: DatagramObject): boolean;
     static fromDatagramStatus(datagramStatus: DatagramStatus, fullTrackName: FullTrackName): MoqtObject;
     static fromFetchObject(fetchObject: FetchObject, fullTrackName: FullTrackName): MoqtObject;
     static fromSubgroupObject(subgroupObject: SubgroupObject, groupId: bigint | number, publisherPriority: number, subgroupId: bigint | number, fullTrackName: FullTrackName): MoqtObject;
-    tryIntoDatagramObject(trackAlias: bigint | number): DatagramObject;
+    /**
+     * Convert to DatagramObject for wire transmission.
+     * @param trackAlias - The track alias to use
+     * @param endOfGroup - Draft-14: Whether this is the last object in the group
+     */
+    tryIntoDatagramObject(trackAlias: bigint | number, endOfGroup?: boolean): DatagramObject;
     tryIntoDatagramStatus(trackAlias: bigint | number): DatagramStatus;
     tryIntoFetchObject(): FetchObject;
     tryIntoSubgroupObject(): SubgroupObject;

package/dist/{byte_buffer-BOK6VPTF.d.ts → byte_buffer-BM4uNj4n.d.ts}

@@ -364,13 +364,22 @@ declare class ReasonPhrase {
  */
 /**
  * @public
- * Object datagram status types for MOQT objects.
- * - `WithoutExtensions`: Object datagram without extensions.
- * - `WithExtensions`: Object datagram with extensions.
+ * Object datagram status types for MOQT objects (Draft-14).
+ * Status datagrams use types 0x20-0x21.
+ *
+ * Type bit layout:
+ * - Bit 0: Extensions Present (0 = no, 1 = yes)
+ *
+ * | Type | Extensions Present | Object ID Present |
+ * |------|-------------------|------------------|
+ * | 0x20 | No                | Yes              |
+ * | 0x21 | Yes               | Yes              |
  */
 declare enum ObjectDatagramStatusType {
-    WithoutExtensions = 2,
-    WithExtensions = 3
+    /** Status without extensions (0x20) */
+    WithoutExtensions = 32,
+    /** Status with extensions (0x21) */
+    WithExtensions = 33
 }
 /**
  * @public
@@ -384,16 +393,51 @@ declare namespace ObjectDatagramStatusType {
      * @throws Error if the value is not valid.
      */
     function tryFrom(value: number | bigint): ObjectDatagramStatusType;
+    /**
+     * Returns true if the type has extensions.
+     * @param t - The ObjectDatagramStatusType.
+     */
+    function hasExtensions(t: ObjectDatagramStatusType): boolean;
 }
 /**
  * @public
- * Object datagram types for MOQT objects.
- * - `WithoutExtensions`: Object datagram without extensions.
- * - `WithExtensions`: Object datagram with extensions.
+ * Object datagram types for MOQT objects (Draft-14).
+ *
+ * Type bit layout for 0x00-0x07:
+ * - Bit 0: Extensions Present (0 = no, 1 = yes)
+ * - Bit 1: End of Group (0 = no, 1 = yes)
+ * - Bit 2: Object ID Present (0 = Object ID omitted & is 0, 1 = Object ID present)
+ *
+ * Note: Bit 2 is inverted - when set, Object ID is ABSENT (and assumed 0)
+ *
+ * | Type | End of Group | Extensions | Object ID Present | Content |
+ * |------|-------------|------------|------------------|--------|
+ * | 0x00 | No          | No         | Yes              | Payload |
+ * | 0x01 | No          | Yes        | Yes              | Payload |
+ * | 0x02 | Yes         | No         | Yes              | Payload |
+ * | 0x03 | Yes         | Yes        | Yes              | Payload |
+ * | 0x04 | No          | No         | No (ID=0)        | Payload |
+ * | 0x05 | No          | Yes        | No (ID=0)        | Payload |
+ * | 0x06 | Yes         | No         | No (ID=0)        | Payload |
+ * | 0x07 | Yes         | Yes        | No (ID=0)        | Payload |
  */
 declare enum ObjectDatagramType {
-    WithoutExtensions = 0,
-    WithExtensions = 1
+    /** No End of Group, No Extensions, Object ID Present (0x00) */
+    Type0x00 = 0,
+    /** No End of Group, With Extensions, Object ID Present (0x01) */
+    Type0x01 = 1,
+    /** End of Group, No Extensions, Object ID Present (0x02) */
+    Type0x02 = 2,
+    /** End of Group, With Extensions, Object ID Present (0x03) */
+    Type0x03 = 3,
+    /** No End of Group, No Extensions, Object ID = 0 (0x04) */
+    Type0x04 = 4,
+    /** No End of Group, With Extensions, Object ID = 0 (0x05) */
+    Type0x05 = 5,
+    /** End of Group, No Extensions, Object ID = 0 (0x06) */
+    Type0x06 = 6,
+    /** End of Group, With Extensions, Object ID = 0 (0x07) */
+    Type0x07 = 7
 }
 /**
  * @public
@@ -407,6 +451,29 @@ declare namespace ObjectDatagramType {
      * @throws Error if the value is not valid.
      */
     function tryFrom(value: number | bigint): ObjectDatagramType;
+    /**
+     * Returns true if the type has extensions (bit 0 set).
+     * @param t - The ObjectDatagramType.
+     */
+    function hasExtensions(t: ObjectDatagramType): boolean;
+    /**
+     * Returns true if the type indicates End of Group (bit 1 set).
+     * @param t - The ObjectDatagramType.
+     */
+    function isEndOfGroup(t: ObjectDatagramType): boolean;
+    /**
+     * Returns true if Object ID is present in the wire format.
+     * When bit 2 is set (0x04-0x07), Object ID is ABSENT and assumed to be 0.
+     * @param t - The ObjectDatagramType.
+     */
+    function hasObjectId(t: ObjectDatagramType): boolean;
+    /**
+     * Determines the appropriate type for given properties.
+     * @param hasExtensions - Whether extensions are present.
+     * @param endOfGroup - Whether this is the last object in the group.
+     * @param objectIdIsZero - Whether the objectId is 0.
+     */
+    function fromProperties(hasExtensions: boolean, endOfGroup: boolean, objectIdIsZero: boolean): ObjectDatagramType;
 }
 /**
  * @public
@@ -539,18 +606,40 @@ declare namespace ObjectStatus {
  * limitations under the License.
  */
 
+/**
+ * Represents an OBJECT_DATAGRAM message (Draft-14).
+ *
+ * Type values 0x00-0x07 indicate payload datagrams with varying properties:
+ * - Bit 0: Extensions Present
+ * - Bit 1: End of Group
+ * - Bit 2: Object ID NOT present (when set, Object ID is 0)
+ */
 declare class DatagramObject {
     readonly type: ObjectDatagramType;
     readonly publisherPriority: number;
     readonly extensionHeaders: KeyValuePair[] | null;
     readonly payload: Uint8Array;
+    readonly endOfGroup: boolean;
     readonly trackAlias: bigint;
     readonly location: Location;
     private constructor();
     get groupId(): bigint;
     get objectId(): bigint;
-    static newWithExtensions(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, extensionHeaders: KeyValuePair[], payload: Uint8Array): DatagramObject;
-    static newWithoutExtensions(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, payload: Uint8Array): DatagramObject;
+    /**
+     * Create a new DatagramObject with all properties specified.
+     * The type is automatically determined based on extensions, endOfGroup, and objectId.
+     */
+    static new(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, extensionHeaders: KeyValuePair[] | null, payload: Uint8Array, endOfGroup?: boolean): DatagramObject;
+    /**
+     * Create a DatagramObject with extensions.
+     * @deprecated Use DatagramObject.new() instead for Draft-14 compliance.
+     */
+    static newWithExtensions(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, extensionHeaders: KeyValuePair[], payload: Uint8Array, endOfGroup?: boolean): DatagramObject;
+    /**
+     * Create a DatagramObject without extensions.
+     * @deprecated Use DatagramObject.new() instead for Draft-14 compliance.
+     */
+    static newWithoutExtensions(trackAlias: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, payload: Uint8Array, endOfGroup?: boolean): DatagramObject;
     serialize(): FrozenByteBuffer;
     static deserialize(buf: BaseByteBuffer): DatagramObject;
 }
@@ -571,6 +660,16 @@ declare class DatagramObject {
  * limitations under the License.
  */
 
+/**
+ * Represents an OBJECT_DATAGRAM with status (Draft-14).
+ *
+ * Type values 0x20-0x21 indicate status datagrams:
+ * - 0x20: Without extensions, Object ID present
+ * - 0x21: With extensions, Object ID present
+ *
+ * Status datagrams always have Object ID present (unlike payload datagrams
+ * which can omit Object ID when it's 0).
+ */
 declare class DatagramStatus {
     readonly type: ObjectDatagramStatusType;
     readonly publisherPriority: number;
@@ -581,7 +680,20 @@ declare class DatagramStatus {
     private constructor();
     get groupId(): bigint;
     get objectId(): bigint;
+    /**
+     * Create a new DatagramStatus with all properties specified.
+     * The type is automatically determined based on whether extensions are present.
+     */
+    static new(trackAlias: bigint | number, location: Location, publisherPriority: number, extensionHeaders: KeyValuePair[] | null, objectStatus: ObjectStatus): DatagramStatus;
+    /**
+     * Create a DatagramStatus with extensions.
+     * @deprecated Use DatagramStatus.new() instead for Draft-14 compliance.
+     */
     static withExtensions(trackAlias: bigint | number, location: Location, publisherPriority: number, extensionHeaders: KeyValuePair[], objectStatus: ObjectStatus): DatagramStatus;
+    /**
+     * Create a DatagramStatus without extensions.
+     * @deprecated Use DatagramStatus.new() instead for Draft-14 compliance.
+     */
     static newWithoutExtensions(trackAlias: bigint | number, location: Location, publisherPriority: number, objectStatus: ObjectStatus): DatagramStatus;
     serialize(): FrozenByteBuffer;
     static deserialize(buf: BaseByteBuffer): DatagramStatus;
@@ -766,10 +878,21 @@ declare class MoqtObject {
     static newWithPayload(fullTrackName: FullTrackName, location: Location, publisherPriority: number, objectForwardingPreference: ObjectForwardingPreference, subgroupId: bigint | number | null, extensionHeaders: KeyValuePair[] | null, payload: Uint8Array): MoqtObject;
     static newWithStatus(fullTrackName: FullTrackName, location: Location, publisherPriority: number, objectForwardingPreference: ObjectForwardingPreference, subgroupId: bigint | number | null, extensionHeaders: KeyValuePair[] | null, objectStatus: ObjectStatus): MoqtObject;
     static fromDatagramObject(datagramObject: DatagramObject, fullTrackName: FullTrackName): MoqtObject;
+    /**
+     * Returns the endOfGroup flag from the source DatagramObject.
+     * This is separate from ObjectStatus.EndOfGroup - the flag indicates
+     * this is the last object in the group even with Normal status.
+     */
+    static isDatagramEndOfGroup(datagramObject: DatagramObject): boolean;
     static fromDatagramStatus(datagramStatus: DatagramStatus, fullTrackName: FullTrackName): MoqtObject;
     static fromFetchObject(fetchObject: FetchObject, fullTrackName: FullTrackName): MoqtObject;
     static fromSubgroupObject(subgroupObject: SubgroupObject, groupId: bigint | number, publisherPriority: number, subgroupId: bigint | number, fullTrackName: FullTrackName): MoqtObject;
-    tryIntoDatagramObject(trackAlias: bigint | number): DatagramObject;
+    /**
+     * Convert to DatagramObject for wire transmission.
+     * @param trackAlias - The track alias to use
+     * @param endOfGroup - Draft-14: Whether this is the last object in the group
+     */
+    tryIntoDatagramObject(trackAlias: bigint | number, endOfGroup?: boolean): DatagramObject;
     tryIntoDatagramStatus(trackAlias: bigint | number): DatagramStatus;
     tryIntoFetchObject(): FetchObject;
     tryIntoSubgroupObject(): SubgroupObject;