@moqtap/codec 0.7.0 → 0.8.0

package/src/core/accessors.ts

@@ -0,0 +1,120 @@
+/**
+ * Draft-agnostic readers for decoded control messages.
+ *
+ * The codec keeps one message model per draft, because the drafts genuinely
+ * disagree: a track alias travels in SUBSCRIBE through draft-11 and in
+ * SUBSCRIBE_OK from draft-12; a request was a `subscribe_id` through draft-10
+ * and a `request_id` after it; a joining FETCH points at a
+ * `joining_subscribe_id` through draft-13 and a `joining_request_id` after it.
+ * Faithfulness to each draft is the point of the codec.
+ *
+ * What consumers usually want is the answer, not the archaeology — and every
+ * one of them that has asked has written the same field-spelling ladder by
+ * hand. These accessors are that ladder, written once.
+ *
+ * Each returns `undefined` when the message does not carry the field, which
+ * includes the cases where the draft has not assigned it yet: `trackAliasOf`
+ * on a draft-14 SUBSCRIBE is `undefined` because the publisher has not chosen
+ * the alias until SUBSCRIBE_OK.
+ *
+ * Both snake_case (what this codec emits) and camelCase spellings are read, so
+ * these also work on messages recovered from qlog-style traces written by
+ * other tools.
+ */
+
+/** Any decoded control message, from any draft. */
+export type AnyMessage = Readonly<Record<string, unknown>>
+
+/** A track's full identity: the namespace tuple plus the name within it. */
+export interface TrackIdentity {
+  readonly namespace: string[]
+  readonly name: string
+}
+
+/** First defined value among several spellings of one field. */
+function pick(msg: AnyMessage, names: readonly string[]): unknown {
+  for (const name of names) {
+    const value = msg[name]
+    if (value != null) return value
+  }
+  return undefined
+}
+
+function bigintOf(value: unknown): bigint | undefined {
+  if (value == null) return undefined
+  if (typeof value === 'bigint') return value
+  if (typeof value === 'number' || typeof value === 'string') {
+    try {
+      return BigInt(value)
+    } catch {
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * The request this message belongs to.
+ *
+ * Named `subscribe_id` through draft-10 and `request_id` from draft-11, when
+ * the id space widened to cover every request type rather than subscriptions
+ * alone.
+ *
+ * Returns `undefined` for draft-17+ responses, which carry no id at all: each
+ * request there has its own bidirectional stream, and that stream — not a
+ * field — is what ties a response to its request.
+ */
+export function requestIdOf(msg: AnyMessage): bigint | undefined {
+  return bigintOf(pick(msg, ['request_id', 'requestId', 'subscribe_id', 'subscribeId']))
+}
+
+/**
+ * The track alias this message assigns or refers to, if any.
+ *
+ * Which message carries it moved: SUBSCRIBE through draft-11, then SUBSCRIBE_OK
+ * from draft-12, when assigning the alias became the publisher's job. PUBLISH
+ * carries it alongside the track name in every draft that has PUBLISH.
+ */
+export function trackAliasOf(msg: AnyMessage): bigint | undefined {
+  return bigintOf(pick(msg, ['track_alias', 'trackAlias']))
+}
+
+/**
+ * The track this message names, or `undefined` if it names none.
+ *
+ * Covers SUBSCRIBE, PUBLISH, TRACK_STATUS and a standalone FETCH — whose track
+ * sits under `standalone` in most drafts and flat in draft-07, which predates
+ * joining fetch. A joining FETCH names no track of its own; use
+ * {@link joiningRequestIdOf} to find the request whose track it continues.
+ *
+ * PUBLISH_NAMESPACE and its relatives are namespace-only and yield
+ * `undefined`: a namespace is not a track.
+ */
+export function trackOf(msg: AnyMessage): TrackIdentity | undefined {
+  const source = (pick(msg, ['standalone']) ?? msg) as AnyMessage
+  const name = pick(source, ['track_name', 'trackName'])
+  if (typeof name !== 'string') return undefined
+  const namespace = pick(source, ['track_namespace', 'trackNamespace'])
+  return {
+    namespace: Array.isArray(namespace) ? namespace.map(String) : [],
+    name,
+  }
+}
+
+/**
+ * For a joining FETCH, the request whose track it continues.
+ *
+ * Spelled `joining_subscribe_id` through draft-13 and `joining_request_id`
+ * after it, nested under `joining` in every draft that has one.
+ */
+export function joiningRequestIdOf(msg: AnyMessage): bigint | undefined {
+  const source = (pick(msg, ['joining']) ?? msg) as AnyMessage
+  return bigintOf(
+    pick(source, [
+      'joining_request_id',
+      'joiningRequestId',
+      'joining_subscribe_id',
+      'joiningSubscribeId',
+    ]),
+  )
+}

package/src/drafts/draft14/codec.ts

@@ -333,8 +333,8 @@ function encodeSubscribePayload(
   w.writeVarInt(msg.request_id)
   w.writeTuple(msg.track_namespace)
   w.writeString(msg.track_name)
-  w.writeUint8(Number(msg.subscriber_priority))
-  w.writeUint8(Number(msg.group_order))
+  w.writeUint8(msg.subscriber_priority)
+  w.writeUint8(msg.group_order)
   w.writeVarInt(msg.forward)
   w.writeVarInt(msg.filter_type)
   const ft = msg.filter_type
@@ -355,7 +355,7 @@ function encodeSubscribeOkPayload(
   w.writeVarInt(msg.request_id)
   w.writeVarInt(msg.track_alias)
   w.writeVarInt(msg.expires)
-  w.writeUint8(Number(msg.group_order))
+  w.writeUint8(msg.group_order)
   w.writeVarInt(msg.content_exists)
   if (msg.content_exists === 1n) {
     w.writeVarInt(msg.largest_location!.group)
@@ -373,7 +373,7 @@ function encodeSubscribeUpdatePayload(
   w.writeVarInt(msg.start_group)
   w.writeVarInt(msg.start_object)
   w.writeVarInt(msg.end_group)
-  w.writeUint8(Number(msg.subscriber_priority))
+  w.writeUint8(msg.subscriber_priority)
   w.writeVarInt(msg.forward)
   encodeMessageParams(msg.parameters, w)
 }
@@ -399,7 +399,7 @@ function encodePublishPayload(msg: Draft14Message & { type: 'publish' }, w: Buff
   w.writeTuple(msg.track_namespace)
   w.writeString(msg.track_name)
   w.writeVarInt(msg.track_alias)
-  w.writeUint8(Number(msg.group_order))
+  w.writeUint8(msg.group_order)
   w.writeVarInt(msg.content_exists)
   if (msg.content_exists === 1n) {
     w.writeVarInt(msg.largest_location!.group)
@@ -415,8 +415,8 @@ function encodePublishOkPayload(
 ): void {
   w.writeVarInt(msg.request_id)
   w.writeVarInt(msg.forward)
-  w.writeUint8(Number(msg.subscriber_priority))
-  w.writeUint8(Number(msg.group_order))
+  w.writeUint8(msg.subscriber_priority)
+  w.writeUint8(msg.group_order)
   w.writeVarInt(msg.filter_type)
   const ft = msg.filter_type
   if (ft >= FilterType.AbsoluteStart) {
@@ -525,27 +525,27 @@ function encodeUnsubscribeNamespacePayload(
 
 function encodeFetchPayload(msg: Draft14Message & { type: 'fetch' }, w: BufferWriter): void {
   w.writeVarInt(msg.request_id)
-  w.writeUint8(Number(msg.subscriber_priority))
-  w.writeUint8(Number(msg.group_order))
+  w.writeUint8(msg.subscriber_priority)
+  w.writeUint8(msg.group_order)
   w.writeVarInt(msg.fetch_type)
   const ft = msg.fetch_type
-  if (ft === FetchType.Standalone) {
-    w.writeTuple(msg.track_namespace!)
-    w.writeString(msg.track_name!)
-    w.writeVarInt(msg.start_group!)
-    w.writeVarInt(msg.start_object!)
-    w.writeVarInt(msg.end_group!)
-    w.writeVarInt(msg.end_object!)
-  } else {
-    w.writeVarInt(msg.joining_request_id!)
-    w.writeVarInt(msg.joining_start!)
+  if (ft === FetchType.Standalone && msg.standalone) {
+    w.writeTuple(msg.standalone.track_namespace)
+    w.writeString(msg.standalone.track_name)
+    w.writeVarInt(msg.standalone.start_group)
+    w.writeVarInt(msg.standalone.start_object)
+    w.writeVarInt(msg.standalone.end_group)
+    w.writeVarInt(msg.standalone.end_object)
+  } else if (msg.joining) {
+    w.writeVarInt(msg.joining.joining_request_id)
+    w.writeVarInt(msg.joining.joining_start)
   }
   encodeMessageParams(msg.parameters, w)
 }
 
 function encodeFetchOkPayload(msg: Draft14Message & { type: 'fetch_ok' }, w: BufferWriter): void {
   w.writeVarInt(msg.request_id)
-  w.writeUint8(Number(msg.group_order))
+  w.writeUint8(msg.group_order)
   w.writeVarInt(msg.end_of_track)
   w.writeVarInt(msg.end_location.group)
   w.writeVarInt(msg.end_location.object)
@@ -575,8 +575,8 @@ function encodeTrackStatusPayload(
   w.writeVarInt(msg.request_id)
   w.writeTuple(msg.track_namespace)
   w.writeString(msg.track_name)
-  w.writeUint8(Number(msg.subscriber_priority))
-  w.writeUint8(Number(msg.group_order))
+  w.writeUint8(msg.subscriber_priority)
+  w.writeUint8(msg.group_order)
   w.writeVarInt(msg.forward)
   w.writeVarInt(msg.filter_type)
   const ft = msg.filter_type
@@ -594,7 +594,7 @@ function encodeTrackStatusOkPayload(
   w.writeVarInt(msg.request_id)
   w.writeVarInt(msg.track_alias)
   w.writeVarInt(msg.expires)
-  w.writeUint8(Number(msg.group_order))
+  w.writeUint8(msg.group_order)
   w.writeVarInt(msg.content_exists)
   if (msg.content_exists === 1n) {
     w.writeVarInt(msg.largest_location!.group)
@@ -659,8 +659,8 @@ function decodeSubscribePayload(r: BufferReader): Draft14Message {
   const request_id = r.readVarInt()
   const track_namespace = r.readTuple()
   const track_name = r.readString()
-  const subscriber_priority = BigInt(r.readUint8())
-  const group_order = BigInt(r.readUint8())
+  const subscriber_priority = r.readUint8()
+  const group_order = r.readUint8()
   const forward = r.readVarInt()
   const filter_type = r.readVarInt()
 
@@ -705,7 +705,7 @@ function decodeSubscribeOkPayload(r: BufferReader): Draft14Message {
   const request_id = r.readVarInt()
   const track_alias = r.readVarInt()
   const expires = r.readVarInt()
-  const group_order = BigInt(r.readUint8())
+  const group_order = r.readUint8()
   const content_exists = r.readVarInt()
 
   let largest_location: Location | undefined
@@ -736,7 +736,7 @@ function decodeSubscribeUpdatePayload(r: BufferReader): Draft14Message {
   const start_group = r.readVarInt()
   const start_object = r.readVarInt()
   const end_group = r.readVarInt()
-  const subscriber_priority = BigInt(r.readUint8())
+  const subscriber_priority = r.readUint8()
   const forward = r.readVarInt()
   const parameters = decodeMessageParams(r)
   return {
@@ -769,7 +769,7 @@ function decodePublishPayload(r: BufferReader): Draft14Message {
   const track_namespace = r.readTuple()
   const track_name = r.readString()
   const track_alias = r.readVarInt()
-  const group_order = BigInt(r.readUint8())
+  const group_order = r.readUint8()
   const content_exists = r.readVarInt()
   let largest_location: Location | undefined
   if (content_exists === 1n) {
@@ -797,8 +797,8 @@ function decodePublishPayload(r: BufferReader): Draft14Message {
 function decodePublishOkPayload(r: BufferReader): Draft14Message {
   const request_id = r.readVarInt()
   const forward = r.readVarInt()
-  const subscriber_priority = BigInt(r.readUint8())
-  const group_order = BigInt(r.readUint8())
+  const subscriber_priority = r.readUint8()
+  const group_order = r.readUint8()
   const filter_type = r.readVarInt()
 
   let start_group: bigint | undefined
@@ -931,8 +931,8 @@ function decodeUnsubscribeNamespacePayload(r: BufferReader): Draft14Message {
 
 function decodeFetchPayload(r: BufferReader): Draft14Message {
   const request_id = r.readVarInt()
-  const subscriber_priority = BigInt(r.readUint8())
-  const group_order = BigInt(r.readUint8())
+  const subscriber_priority = r.readUint8()
+  const group_order = r.readUint8()
   const fetch_type = r.readVarInt()
 
   if (fetch_type < FetchType.Standalone || fetch_type > FetchType.AbsoluteJoining) {
@@ -940,12 +940,14 @@ function decodeFetchPayload(r: BufferReader): Draft14Message {
   }
 
   if (fetch_type === FetchType.Standalone) {
-    const track_namespace = r.readTuple()
-    const track_name = r.readString()
-    const start_group = r.readVarInt()
-    const start_object = r.readVarInt()
-    const end_group = r.readVarInt()
-    const end_object = r.readVarInt()
+    const standalone = {
+      track_namespace: r.readTuple(),
+      track_name: r.readString(),
+      start_group: r.readVarInt(),
+      start_object: r.readVarInt(),
+      end_group: r.readVarInt(),
+      end_object: r.readVarInt(),
+    }
     const parameters = decodeMessageParams(r)
     return {
       type: 'fetch',
@@ -953,17 +955,14 @@ function decodeFetchPayload(r: BufferReader): Draft14Message {
       subscriber_priority,
       group_order,
       fetch_type,
-      track_namespace,
-      track_name,
-      start_group,
-      start_object,
-      end_group,
-      end_object,
+      standalone,
       parameters,
     }
   } else {
-    const joining_request_id = r.readVarInt()
-    const joining_start = r.readVarInt()
+    const joining = {
+      joining_request_id: r.readVarInt(),
+      joining_start: r.readVarInt(),
+    }
     const parameters = decodeMessageParams(r)
     return {
       type: 'fetch',
@@ -971,8 +970,7 @@ function decodeFetchPayload(r: BufferReader): Draft14Message {
       subscriber_priority,
       group_order,
       fetch_type,
-      joining_request_id,
-      joining_start,
+      joining,
       parameters,
     }
   }
@@ -980,7 +978,7 @@ function decodeFetchPayload(r: BufferReader): Draft14Message {
 
 function decodeFetchOkPayload(r: BufferReader): Draft14Message {
   const request_id = r.readVarInt()
-  const group_order = BigInt(r.readUint8())
+  const group_order = r.readUint8()
   const end_of_track = r.readVarInt()
   const end_location: Location = {
     group: r.readVarInt(),
@@ -1013,8 +1011,8 @@ function decodeTrackStatusPayload(r: BufferReader): Draft14Message {
   const request_id = r.readVarInt()
   const track_namespace = r.readTuple()
   const track_name = r.readString()
-  const subscriber_priority = BigInt(r.readUint8())
-  const group_order = BigInt(r.readUint8())
+  const subscriber_priority = r.readUint8()
+  const group_order = r.readUint8()
   const forward = r.readVarInt()
   const filter_type = r.readVarInt()
 
@@ -1048,7 +1046,7 @@ function decodeTrackStatusOkPayload(r: BufferReader): Draft14Message {
   const request_id = r.readVarInt()
   const track_alias = r.readVarInt()
   const expires = r.readVarInt()
-  const group_order = BigInt(r.readUint8())
+  const group_order = r.readUint8()
   const content_exists = r.readVarInt()
 
   let largest_location: Location | undefined

package/src/drafts/draft14/types.ts

@@ -115,8 +115,8 @@ export interface Draft14Subscribe extends Draft14BaseMessage {
   readonly request_id: bigint
   readonly track_namespace: string[]
   readonly track_name: string
-  readonly subscriber_priority: bigint
-  readonly group_order: bigint
+  readonly subscriber_priority: number // uint8
+  readonly group_order: number // uint8
   readonly forward: bigint
   readonly filter_type: bigint
   readonly start_group?: bigint
@@ -130,7 +130,7 @@ export interface Draft14SubscribeOk extends Draft14BaseMessage {
   readonly request_id: bigint
   readonly track_alias: bigint
   readonly expires: bigint
-  readonly group_order: bigint
+  readonly group_order: number // uint8
   readonly content_exists: bigint
   readonly largest_location?: Location
   readonly parameters: Draft14Params
@@ -143,7 +143,7 @@ export interface Draft14SubscribeUpdate extends Draft14BaseMessage {
   readonly start_group: bigint
   readonly start_object: bigint
   readonly end_group: bigint
-  readonly subscriber_priority: bigint
+  readonly subscriber_priority: number // uint8
   readonly forward: bigint
   readonly parameters: Draft14Params
 }
@@ -167,7 +167,7 @@ export interface Draft14Publish extends Draft14BaseMessage {
   readonly track_namespace: string[]
   readonly track_name: string
   readonly track_alias: bigint
-  readonly group_order: bigint
+  readonly group_order: number // uint8
   readonly content_exists: bigint
   readonly largest_location?: Location
   readonly forward: bigint
@@ -178,8 +178,8 @@ export interface Draft14PublishOk extends Draft14BaseMessage {
   readonly type: 'publish_ok'
   readonly request_id: bigint
   readonly forward: bigint
-  readonly subscriber_priority: bigint
-  readonly group_order: bigint
+  readonly subscriber_priority: number // uint8
+  readonly group_order: number // uint8
   readonly filter_type: bigint
   readonly start_group?: bigint
   readonly start_object?: bigint
@@ -261,29 +261,37 @@ export interface Draft14UnsubscribeNamespace extends Draft14BaseMessage {
 }
 
 // Fetch
+export interface StandaloneFetch {
+  readonly track_namespace: string[]
+  readonly track_name: string
+  readonly start_group: bigint
+  readonly start_object: bigint
+  readonly end_group: bigint
+  readonly end_object: bigint
+}
+
+export interface JoiningFetch {
+  readonly joining_request_id: bigint
+  readonly joining_start: bigint
+}
+
 export interface Draft14Fetch extends Draft14BaseMessage {
   readonly type: 'fetch'
   readonly request_id: bigint
-  readonly subscriber_priority: bigint
-  readonly group_order: bigint
+  readonly subscriber_priority: number // uint8
+  readonly group_order: number // uint8
   readonly fetch_type: bigint
-  // Standalone fields (fetch_type=1)
-  readonly track_namespace?: string[]
-  readonly track_name?: string
-  readonly start_group?: bigint
-  readonly start_object?: bigint
-  readonly end_group?: bigint
-  readonly end_object?: bigint
-  // Joining fields (fetch_type=2 or 3)
-  readonly joining_request_id?: bigint
-  readonly joining_start?: bigint
+  /** Present when fetch_type = 1 */
+  readonly standalone?: StandaloneFetch
+  /** Present when fetch_type = 2 or 3 */
+  readonly joining?: JoiningFetch
   readonly parameters: Draft14Params
 }
 
 export interface Draft14FetchOk extends Draft14BaseMessage {
   readonly type: 'fetch_ok'
   readonly request_id: bigint
-  readonly group_order: bigint
+  readonly group_order: number // uint8
   readonly end_of_track: bigint
   readonly end_location: Location
   readonly parameters: Draft14Params
@@ -307,8 +315,8 @@ export interface Draft14TrackStatus extends Draft14BaseMessage {
   readonly request_id: bigint
   readonly track_namespace: string[]
   readonly track_name: string
-  readonly subscriber_priority: bigint
-  readonly group_order: bigint
+  readonly subscriber_priority: number // uint8
+  readonly group_order: number // uint8
   readonly forward: bigint
   readonly filter_type: bigint
   readonly start_group?: bigint
@@ -321,7 +329,7 @@ export interface Draft14TrackStatusOk extends Draft14BaseMessage {
   readonly request_id: bigint
   readonly track_alias: bigint
   readonly expires: bigint
-  readonly group_order: bigint
+  readonly group_order: number // uint8
   readonly content_exists: bigint
   readonly largest_location?: Location
   readonly parameters: Draft14Params

package/src/index.ts

@@ -151,6 +151,14 @@ export function createCodec(
   }
 }
 
+// Draft-agnostic readers for decoded messages
+export type { AnyMessage, TrackIdentity } from './core/accessors.js'
+export {
+  joiningRequestIdOf,
+  requestIdOf,
+  trackAliasOf,
+  trackOf,
+} from './core/accessors.js'
 export type {
   BaseCodec,
   CodecOptions,