@blockcast/mmt-base 0.1.0 → 0.3.0-main.288475b64b3e

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,49 @@
+/**
+ * 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
+}