Data tracks - Packet serialization + deserialialization, plus some error handling changes

.changeset/busy-ends-shake.md

@@ -0,0 +1,5 @@
+---
+'livekit-client': patch
+---
+
+Add data track packet serialization + deserialization logic

.github/workflows/test.yaml

@@ -26,10 +26,13 @@ jobs:
     - name: Prettier
       run: pnpm format:check
 
+    - name: Throws check
+      run: pnpm throws:check
+
     - name: Run Tests
       run: pnpm test
 
     - name: Check browser target compatibility
       run: |
         pnpm build:clean
-        pnpm compat
+        pnpm compat

package.json

@@ -49,6 +49,7 @@
     "deploy": "gh-pages -d examples/demo/dist",
     "format": "prettier --write src examples/**/*.ts",
     "format:check": "prettier --check src examples/**/*.ts",
+    "throws:check": "pnpm dlx tsx ./throws-transformer/cli.ts 'src/!(*.test).ts' 'src/**/!(*.test).ts'",
     "ci:publish": "pnpm build:clean && pnpm compat && changeset publish",
     "downlevel-dts": "downlevel-dts ./dist/src ./dist/ts4.2 --to=4.2",
     "compat": "eslint --config ./eslint.config.dist.mjs --no-inline-config  ./dist/livekit-client.esm.mjs",
@@ -98,6 +99,7 @@
     "eslint-plugin-import-x": "^4.16.1",
     "eslint-plugin-prettier": "^5.5.4",
     "gh-pages": "6.3.0",
+    "glob": "^13.0.0",
     "happy-dom": "^17.2.0",
     "jsdom": "^26.1.0",
     "prettier": "^3.4.2",

src/index.ts

@@ -149,5 +149,11 @@ export type {
   ReconnectPolicy,
   RoomEventCallbacks,
 };
+export { DataTrackPacket, type DataTrackPacketHeader } from './room/data-track/packet';
+export {
+  type DataTrackExtensions,
+  type DataTrackUserTimestampExtension,
+  type DataTrackE2eeExtension,
+} from './room/data-track/packet/extensions';
 
 export { LocalTrackRecorder } from './room/track/record';

src/room/data-track/handle.test.ts

@@ -0,0 +1,13 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { DataTrackHandle } from './handle';
+
+describe('DataTrackHandle', () => {
+  it('should parse handle raw inputs', () => {
+    expect(DataTrackHandle.fromNumber(3).value).toEqual(3);
+    expect(() => DataTrackHandle.fromNumber(0)).toThrow('0x0 is a reserved value');
+    expect(() => DataTrackHandle.fromNumber(9999999)).toThrow(
+      'Value too large to be a valid track handle',
+    );
+  });
+});

src/room/data-track/handle.ts

@@ -0,0 +1,80 @@
+import { type Throws } from '../../utils/throws';
+import { LivekitReasonedError } from '../errors';
+import { U16_MAX_SIZE } from './utils';
+
+export enum DataTrackHandleErrorReason {
+  Reserved = 0,
+  TooLarge = 1,
+}
+
+export class DataTrackHandleError<
+  Reason extends DataTrackHandleErrorReason = DataTrackHandleErrorReason,
+> extends LivekitReasonedError<DataTrackHandleErrorReason> {
+  readonly name = 'DataTrackHandleError';
+
+  reason: Reason;
+
+  reasonName: string;
+
+  constructor(message: string, reason: Reason) {
+    super(19, message);
+    this.reason = reason;
+    this.reasonName = DataTrackHandleErrorReason[reason];
+  }
+
+  isReason<R extends DataTrackHandleErrorReason>(reason: R): this is DataTrackHandleError<R> {
+    return (this.reason as unknown as R) === reason;
+  }
+
+  static tooLarge() {
+    return new DataTrackHandleError(
+      'Value too large to be a valid track handle',
+      DataTrackHandleErrorReason.TooLarge,
+    );
+  }
+
+  static reserved(value: number) {
+    return new DataTrackHandleError(
+      `0x${value.toString(16)} is a reserved value.`,
+      DataTrackHandleErrorReason.Reserved,
+    );
+  }
+}
+
+export class DataTrackHandle {
+  public value: number;
+
+  static fromNumber(
+    raw: number,
+  ): Throws<
+    DataTrackHandle,
+    | DataTrackHandleError<DataTrackHandleErrorReason.TooLarge>
+    | DataTrackHandleError<DataTrackHandleErrorReason.Reserved>
+  > {
+    if (raw === 0) {
+      throw DataTrackHandleError.reserved(raw);
+    }
+    if (raw > U16_MAX_SIZE) {
+      throw DataTrackHandleError.tooLarge();
+    }
+    return new DataTrackHandle(raw);
+  }
+
+  constructor(raw: number) {
+    this.value = raw;
+  }
+}
+
+/** Manage allocating new handles which don't conflict over the lifetime of the client. */
+export class DataTrackHandleAllocator {
+  static value = 0;
+
+  /** Returns a unique track handle for the next publication, if one can be obtained. */
+  static get(): DataTrackHandle | null {
+    this.value += 1;
+    if (this.value > U16_MAX_SIZE) {
+      return null;
+    }
+    return new DataTrackHandle(this.value);
+  }
+}

src/room/data-track/packet/constants.ts

@@ -0,0 +1,27 @@
+// Number type sizes
+export const U8_LENGTH_BYTES = 1;
+export const U16_LENGTH_BYTES = 2;
+export const U32_LENGTH_BYTES = 4;
+export const U64_LENGTH_BYTES = 8;
+
+/// Constants used for serialization and deserialization.
+export const SUPPORTED_VERSION = 0;
+export const BASE_HEADER_LEN = 12;
+
+// Bitfield shifts and masks for header flags
+export const VERSION_SHIFT = 5;
+export const VERSION_MASK = 0x07;
+
+export const FRAME_MARKER_SHIFT = 3;
+export const FRAME_MARKER_MASK = 0x3;
+
+export const FRAME_MARKER_START = 0x2;
+export const FRAME_MARKER_FINAL = 0x1;
+export const FRAME_MARKER_INTER = 0x0;
+export const FRAME_MARKER_SINGLE = 0x3;
+
+export const EXT_WORDS_INDICATOR_SIZE = 2;
+export const EXT_FLAG_SHIFT = 0x2;
+export const EXT_FLAG_MASK = 0x1;
+export const EXT_MARKER_LEN = 4;
+export const EXT_TAG_PADDING = 0;