@blockcast/mmt-base 0.1.0 → 0.3.0

package/src/ntp-short.ts

@@ -0,0 +1,67 @@
+/**
+ * NTP short format (RFC 5905 §6): an unsigned 32-bit, 16.16 fixed-point count
+ * of seconds. The MMTP header `timestamp` field (ISO/IEC 23008-1 §9.2.2)
+ * carries each packet's UTC sending instant in this format, so the value wraps
+ * to 0 every 2^16 s (~18.2 h).
+ *
+ * Plain numeric order on these values breaks at every wrap: a retained
+ * `Math.max` stays at the pre-wrap value and every later instant compares as
+ * older. Order send times only with {@link compareNtpShort}, which applies
+ * RFC 1982 serial-number arithmetic over the field's width.
+ */
+
+/** Width in bits of the MMTP `timestamp` field (NTP short). */
+export const NTP_SHORT_BITS = 32
+
+/** Number of distinct NTP-short values; the field wraps to 0 here. */
+export const NTP_SHORT_MODULUS = 2 ** NTP_SHORT_BITS
+
+/**
+ * RFC 1982 §3.2's `2^(SERIAL_BITS - 1)`. Two values whose forward distance is
+ * below this are ordered; exactly this far apart they are not ordered at all.
+ * Two instants must be less than this far apart (2^15 s, ~9.1 h of send time)
+ * for the comparison to give their true order.
+ */
+export const NTP_SHORT_HALF_RANGE = 2 ** (NTP_SHORT_BITS - 1)
+
+/**
+ * Serial order of one NTP-short value relative to another.
+ *
+ * `'unordered'` is RFC 1982's undefined case: the values are exactly
+ * {@link NTP_SHORT_HALF_RANGE} apart, so neither precedes the other. It is
+ * never folded into `'before'` or `'after'`; each caller decides what an
+ * unorderable pair means for it.
+ */
+export type NtpShortOrder = 'before' | 'equal' | 'after' | 'unordered'
+
+/** True when `value` is an NTP-short value: an integer in [0, NTP_SHORT_MODULUS). */
+export function isNtpShort(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value < NTP_SHORT_MODULUS
+}
+
+/**
+ * RFC 1982 serial comparison of NTP-short `a` against `b`: `'after'` when `a`
+ * is the later instant, `'before'` when it is the earlier one.
+ *
+ * The answer is the true order only while the two instants are less than
+ * {@link NTP_SHORT_HALF_RANGE} apart. Past that a 32-bit field cannot tell
+ * later from earlier, and the result names whichever direction is nearer.
+ * This is not a total order (it is not transitive across the whole space), so
+ * it must never be used to sort.
+ *
+ * @throws {RangeError} if either operand is not an NTP-short value
+ */
+export function compareNtpShort(a: number, b: number): NtpShortOrder {
+  if (!isNtpShort(a) || !isNtpShort(b)) {
+    throw new RangeError(
+      `NTP-short values must be integers in [0, 2^${NTP_SHORT_BITS}), got ${String(a)} and ${String(b)}`,
+    )
+  }
+  if (a === b) return 'equal'
+  // Forward distance from b to a, reduced into [1, NTP_SHORT_MODULUS). Both
+  // operands are below 2^32, so every step is exact in a double.
+  const forward = (a - b + NTP_SHORT_MODULUS) % NTP_SHORT_MODULUS
+  if (forward < NTP_SHORT_HALF_RANGE) return 'after'
+  if (forward > NTP_SHORT_HALF_RANGE) return 'before'
+  return 'unordered'
+}

package/src/serial-number.ts

@@ -0,0 +1,107 @@
+/**
+ * RFC 1982 serial-number arithmetic for the 32-bit MMTP AL-FEC symbol
+ * counters (ISO/IEC 23008-1:2023 C.5.2 SS_ID, C.5.3 SS_Start).
+ *
+ * SS_ID is a 32-bit field, so a stream that runs long enough wraps it to 0.
+ * Ordering two SS_IDs (or two blocks by their first SS_ID) with `<` reads
+ * every post-wrap value as older than every pre-wrap one. Serial order
+ * agrees with `<` whenever the two values are less than 2^31 apart, so for
+ * every stream that has not reached the wrap the result is unchanged; only
+ * the order across the wrap point differs (BLO-35597 iso:5).
+ */
+
+/** 2^SERIAL_BITS for SERIAL_BITS = 32. */
+export const SERIAL32_SPAN = 0x1_0000_0000
+
+/** RFC 1982 §3.2's 2^(SERIAL_BITS - 1). */
+export const SERIAL32_HALF = 0x8000_0000
+
+function assertUint32(value: number, name: string): void {
+  if (!Number.isInteger(value) || value < 0 || value >= SERIAL32_SPAN) {
+    throw new RangeError(`${name} must be a uint32 (got ${value})`)
+  }
+}
+
+/**
+ * RFC 1982 §3.1 addition, extended to negative `n` for the matching
+ * subtraction: `(s + n) mod 2^32`. `n` must lie in (-2^31, 2^31).
+ */
+export function serial32Add(s: number, n: number): number {
+  assertUint32(s, 's')
+  if (!Number.isInteger(n) || n <= -SERIAL32_HALF || n >= SERIAL32_HALF) {
+    throw new RangeError(`serial addend must lie in (-2^31, 2^31) (got ${n})`)
+  }
+  return (s + n + SERIAL32_SPAN) % SERIAL32_SPAN
+}
+
+/** Forward distance from `from` to `to`: `(to - from) mod 2^32`. */
+export function serial32Distance(from: number, to: number): number {
+  return (to - from) >>> 0
+}
+
+/**
+ * RFC 1982 §3.2: `a` precedes `b`. Values exactly 2^31 apart are unordered
+ * (neither precedes the other).
+ */
+export function serial32Precedes(a: number, b: number): boolean {
+  const distance = serial32Distance(a, b)
+  return distance !== 0 && distance < SERIAL32_HALF
+}
+
+/**
+ * First SS_ID of block `sbn` under the K-stride numbering every current
+ * sender uses (`SS_ID = SBN * K + ESI`, C.5.2), reduced mod 2^32.
+ */
+export function kStrideBlockStart(sbn: number, k: number): number {
+  assertUint32(sbn, 'sbn')
+  if (!Number.isInteger(k) || k < 1 || k >= SERIAL32_HALF) {
+    throw new RangeError(`k must be a positive integer below 2^31 (got ${k})`)
+  }
+  // sbn < 2^32 and k < 2^31 keep the product below 2^63, but a double is
+  // exact only to 2^53; split the product so every step is exact.
+  const high = Math.floor(sbn / 0x1_0000) // < 2^16
+  const low = sbn % 0x1_0000              // < 2^16
+  return (((high * k) % SERIAL32_SPAN) * 0x1_0000 + low * k) % SERIAL32_SPAN
+}
+
+/**
+ * Whether block `a` precedes block `b`, ordering the blocks by their first
+ * SS_ID in serial arithmetic. Identical to `a < b` for any two blocks of a
+ * stream that has not wrapped SS_ID.
+ */
+export function kStrideBlockPrecedes(a: number, b: number, k: number): boolean {
+  return serial32Precedes(kStrideBlockStart(a, k), kStrideBlockStart(b, k))
+}
+
+/**
+ * How many blocks `a` lies behind `b`: 0 when `a` does not precede `b`,
+ * otherwise `ceil(distance / K)` over the SS_ID distance between their first
+ * symbols. Without a wrap that is exactly `b - a`; across the wrap the one
+ * short pre-wrap block (2^32 mod K symbols) still counts as one block.
+ */
+export function kStrideBlocksBehind(a: number, b: number, k: number): number {
+  const from = kStrideBlockStart(a, k)
+  const to = kStrideBlockStart(b, k)
+  if (!serial32Precedes(from, to)) return 0
+  return Math.ceil(serial32Distance(from, to) / k)
+}
+
+/**
+ * Whether `sbn` and `k` describe a block of the K-stride numbering:
+ * `sbn` a uint32, `k` an integer in 1..2^31-1.
+ */
+export function isKStrideBlock(sbn: number, k: number): boolean {
+  return Number.isInteger(sbn) && sbn >= 0 && sbn < SERIAL32_SPAN &&
+    Number.isInteger(k) && k >= 1 && k < SERIAL32_HALF
+}
+
+/**
+ * The block after `sbn`: `sbn + 1`, or 0 once `(sbn + 1) * K` reaches 2^32
+ * and the next SS_ID wraps (C.5.2). There are `ceil(2^32 / K)` blocks per
+ * wrap, the last of them short when K does not divide 2^32.
+ */
+export function kStrideNextBlock(sbn: number, k: number): number {
+  assertUint32(sbn, 'sbn')
+  kStrideBlockStart(sbn, k) // validates k
+  return (sbn + 1) * k >= SERIAL32_SPAN ? 0 : sbn + 1
+}