@nifrajs/web 5.5.1 → 5.7.0

package/src/live/bus.ts

@@ -0,0 +1,104 @@
+/**
+ * The live bus: one ordered log of changes and revocations that every process serving the app reads.
+ * Its sequence numbers never leave the server.
+ *
+ * A bus assigns each appended event a seq from a hybrid logical clock in microseconds: never below
+ * `Date.now() * 1000` at the authority, always above the previous seq. A restarted authority therefore
+ * keeps counting upward, and an entry's age can be read off its seq.
+ */
+
+import { KEY_PATTERN } from "./keyring.ts"
+
+/** Something a loader declared with `ctx.live` changed. */
+export interface LiveChange {
+  readonly type: "change"
+  readonly keys: readonly string[]
+}
+
+/**
+ * Grants issued before this event stop working: every grant (`sub` and `key` null), one subject's
+ * (`key` null), or, with `key`, any grant holding that key (for everyone, or for `sub`).
+ */
+export interface LiveRevocation {
+  readonly type: "revoke"
+  readonly sub: string | null
+  readonly key: string | null
+}
+
+export type LiveBusInput = LiveChange | LiveRevocation
+
+export type LiveBusEvent = LiveBusInput & { readonly seq: number }
+
+export interface LiveBusListener {
+  /** The next event, in seq order. */
+  event(event: LiveBusEvent): void
+  /**
+   * Events up to `head` may be lost (a trimmed stream, a reconnect): what happened before `head` is
+   * unknown, and delivery resumes with the events after it.
+   */
+  gap(head: number): void
+  /**
+   * The bus is unreachable; the next {@link gap} reports where delivery resumes. `error` is what the
+   * last read failed with, when the bus knows.
+   */
+  down(error?: unknown): void
+}
+
+export interface LiveBusSubscription {
+  /** The seq of the last event before delivery starts. */
+  readonly head: number
+  close(): void
+}
+
+export interface LiveBus {
+  /** Append one event; resolves with its seq. */
+  append(input: LiveBusInput): Promise<number>
+  /** Deliver every event after the returned head to `listener`, in seq order. */
+  subscribe(listener: LiveBusListener): Promise<LiveBusSubscription>
+}
+
+/** The seq a clock reading allows, never at or below `last`. */
+export const nextSeq = (last: number, nowMs: number): number => Math.max(last + 1, nowMs * 1000)
+
+/**
+ * The single-process bus: an in-memory clock, events delivered to every subscriber before `append`
+ * resolves. Processes do not share it; run several behind a shared bus instead.
+ */
+export function memoryBus(): LiveBus {
+  let last = nextSeq(0, Date.now())
+  const listeners = new Set<LiveBusListener>()
+  return {
+    async append(input) {
+      last = nextSeq(last, Date.now())
+      const event: LiveBusEvent = { ...input, seq: last }
+      for (const listener of listeners) listener.event(event)
+      return last
+    },
+    async subscribe(listener) {
+      listeners.add(listener)
+      return { head: last, close: () => listeners.delete(listener) }
+    },
+  }
+}
+
+/**
+ * Publish changes from a process that serves no live pages: a worker, or another app whose writes
+ * change what the pages show. Give it the bus the serving processes read; each applies the change as
+ * if it had published it. It needs no grant secret, and reads nothing from the bus.
+ *
+ * ```ts
+ * const publish = livePublisher(redisLiveBus({ send: (command, args) => redis.call(command, ...args) }))
+ * await publish(`org:${orgId}:usage`)
+ * ```
+ */
+export function livePublisher(bus: Pick<LiveBus, "append">): (...keys: string[]) => Promise<void> {
+  return async (...keys) => {
+    for (const key of keys) {
+      if (typeof key !== "string" || !KEY_PATTERN.test(key)) {
+        throw new TypeError("[nifra/web] livePublisher takes keys in the ctx.live() charset")
+      }
+    }
+    if (keys.length === 0) return
+    await bus.append({ type: "change", keys: [...new Set(keys)] })
+  }
+}

package/src/live/core.ts

@@ -0,0 +1,52 @@
+/**
+ * What a process applies the ordered live events to, wherever they come from: a bus every process
+ * reads, or the Workers hub that owns the log.
+ */
+import type { LiveBusEvent, LiveRevocation } from "./bus.ts"
+import type { History } from "./history.ts"
+import type { LiveHub } from "./hub.ts"
+import { KEY_PATTERN, type Keyring } from "./keyring.ts"
+import type { Revocations } from "./revocations.ts"
+
+export interface LiveCore {
+  readonly ring: Keyring
+  readonly history: History
+  readonly revocations: Revocations
+  readonly hub: LiveHub
+}
+
+/**
+ * Apply one event. A change is recorded in history and then fanned out in one synchronous step; a
+ * revocation is stored before any socket hears of it. Throws on an event it cannot apply, which
+ * leaves history and revocations unknown: the caller forgets everything up to its seq.
+ */
+export async function applyEvent(
+  core: LiveCore,
+  event: LiveBusEvent,
+  hash: (key: string) => number,
+): Promise<void> {
+  if (event.type === "change") {
+    const keys = event.keys.filter((key) => typeof key === "string" && KEY_PATTERN.test(key))
+    const tags = await Promise.all(keys.map((key) => core.hub.tagsOf(key)))
+    core.history.record(
+      event.seq,
+      keys.map((key) => hash(key)),
+      Date.now(),
+    )
+    core.hub.change(keys, tags)
+    return
+  }
+  if (!validRevocation(event)) throw new TypeError("malformed revocation")
+  const tags = event.key === null ? [] : await core.hub.tagsOf(event.key)
+  core.revocations.apply(event, Date.now())
+  core.history.advance(event.seq, Date.now())
+  core.hub.revoke(event, tags)
+}
+
+export function validRevocation(event: LiveBusEvent): event is LiveRevocation & {
+  readonly seq: number
+} {
+  if (event.type !== "revoke") return false
+  if (event.sub !== null && typeof event.sub !== "string") return false
+  return event.key === null || (typeof event.key === "string" && KEY_PATTERN.test(event.key))
+}

package/src/live/history.ts

@@ -0,0 +1,109 @@
+/**
+ * Which keys changed since a watermark: a ring of `(seq, key hash)` pairs, 16 bytes each, with the
+ * newest seq per hash beside it. History is complete for every seq above {@link History.floor}; a
+ * watermark at or below it, or one this process has not reached, is unknown and reads as changed.
+ */
+
+export const HISTORY_ENTRIES = 100_000
+export const HISTORY_MS = 120_000
+
+export class History {
+  private readonly seqs: Float64Array
+  private readonly hashes: Float64Array
+  private readonly latest = new Map<number, number>()
+  private start = 0
+  private size = 0
+  /** Every event with a seq above this is recorded. */
+  floor: number
+  /** The last recorded event's seq. */
+  last: number
+
+  constructor(
+    head: number,
+    private readonly capacity = HISTORY_ENTRIES,
+    private readonly maxAgeMs = HISTORY_MS,
+  ) {
+    this.seqs = new Float64Array(capacity)
+    this.hashes = new Float64Array(capacity)
+    this.floor = head
+    this.last = head
+  }
+
+  record(seq: number, hashes: readonly number[], nowMs: number): void {
+    for (const hash of hashes) {
+      if (this.size === this.capacity) this.evict()
+      const at = (this.start + this.size) % this.capacity
+      this.seqs[at] = seq
+      this.hashes[at] = hash
+      this.size++
+      this.latest.set(hash, seq)
+    }
+    this.last = seq
+    this.prune(nowMs)
+  }
+
+  /** Mark history up to `seq` as seen with nothing to record (a revocation). */
+  advance(seq: number, nowMs: number): void {
+    this.last = seq
+    this.prune(nowMs)
+  }
+
+  /** `true` when the key may have changed after `watermark`. */
+  changedSince(hash: number, watermark: number): boolean {
+    if (!this.known(watermark)) return true
+    const seq = this.latest.get(hash)
+    return seq !== undefined && seq > watermark
+  }
+
+  known(watermark: number): boolean {
+    return watermark >= this.floor && watermark <= this.last
+  }
+
+  /** Forget everything: what happened up to `head` is unknown. */
+  reset(head: number): void {
+    this.latest.clear()
+    this.start = 0
+    this.size = 0
+    this.floor = head
+    this.last = head
+  }
+
+  /** Seqs count microseconds, so an entry's age is read off its seq. */
+  private prune(nowMs: number): void {
+    const oldest = (nowMs - this.maxAgeMs) * 1000
+    while (this.size > 0 && (this.seqs[this.start] ?? 0) < oldest) this.evict()
+  }
+
+  private evict(): void {
+    const seq = this.seqs[this.start] ?? 0
+    const hash = this.hashes[this.start] ?? 0
+    if (this.latest.get(hash) === seq) this.latest.delete(hash)
+    if (seq > this.floor) this.floor = seq
+    this.start = (this.start + 1) % this.capacity
+    this.size--
+  }
+}
+
+/**
+ * A 53-bit keyed hash (cyrb53 with per-process seeds). A collision only costs a spurious reload, and
+ * the seeds keep anyone from choosing keys that collide with another.
+ */
+export function keyHasher(): (key: string) => number {
+  const seeds = crypto.getRandomValues(new Uint32Array(2))
+  const seed1 = seeds[0] ?? 0
+  const seed2 = seeds[1] ?? 0
+  return (key) => {
+    let h1 = 0xdeadbeef ^ seed1
+    let h2 = 0x41c6ce57 ^ seed2
+    for (let i = 0; i < key.length; i++) {
+      const ch = key.charCodeAt(i)
+      h1 = Math.imul(h1 ^ ch, 2654435761)
+      h2 = Math.imul(h2 ^ ch, 1597334677)
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507)
+    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909)
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507)
+    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909)
+    return 4294967296 * (2097151 & h2) + (h1 >>> 0)
+  }
+}

package/src/live/hub-protocol.ts

@@ -0,0 +1,133 @@
+/**
+ * The private calls between a Workers isolate and the app's live hub, over the Durable Object binding.
+ * Nothing on the internet reaches a Durable Object except through the app's own isolate, which
+ * forwards only the socket handshake; the paths below are refused on every public route.
+ */
+import type { LiveBusInput } from "./bus.ts"
+import { KEY_PATTERN, type Keyring, MAX_KEYS_PER_FRAME } from "./keyring.ts"
+import type { RevocationSnapshot } from "./revocations.ts"
+
+/** A Durable Object namespace, as far as the runtime uses one (no Cloudflare types dependency). */
+export interface LiveHubNamespace {
+  idFromName(name: string): unknown
+  get(id: unknown): { fetch(request: Request): Promise<Response> }
+}
+
+export const HUB_APPEND_PATH = "/__nifra_live_hub/append"
+export const HUB_AUTHORITY_PATH = "/__nifra_live_hub/authority"
+/** The host the calls name; a Durable Object stub ignores it. */
+export const HUB_ORIGIN = "https://nifra-live-hub"
+
+/** One hub per app. */
+export const hubName = (appId: string): string => `nifra-live:${appId}`
+
+/**
+ * What an isolate's live runtime and its hub must agree on, sent with every call: the grant lifetime
+ * sets how long the hub keeps a revocation, so a hub with a shorter one would forget revocations of
+ * grants still valid. The secret is named by its public id only.
+ */
+export const HUB_CONFIG_HEADER = "x-nifra-live-config"
+
+export const hubConfigOf = (ring: Keyring): string =>
+  `${ring.ttl} ${ring.secretIds[0] ?? 0} ${encodeURIComponent(ring.appId)}`
+
+/** The caller's newest secret must be one the hub holds; the hub may already hold a newer one. */
+export function hubConfigMatches(ring: Keyring, header: string | null): boolean {
+  const parts = header?.split(" ")
+  if (parts?.length !== 3) return false
+  const [ttl, id, appId] = parts
+  return (
+    ttl === String(ring.ttl) &&
+    ring.secretIds.some((own) => String(own) === id) &&
+    appId === encodeURIComponent(ring.appId)
+  )
+}
+
+/** Grants a load presents, at most. */
+const MAX_SUBJECTS = 3
+const MAX_KEYS = MAX_SUBJECTS * MAX_KEYS_PER_FRAME
+/** Keys one append carries; a larger publish goes out as several. */
+export const MAX_APPEND_KEYS = MAX_KEYS
+export const MAX_SUBJECT_CHARS = 1024
+
+export interface AuthorityRequest {
+  readonly subjects: readonly string[]
+  readonly keys: readonly string[]
+}
+
+export interface AuthorityReply extends RevocationSnapshot {
+  /** The hub's seq: a load's watermark. */
+  readonly seq: number
+}
+
+export function parseAppend(value: unknown): LiveBusInput | undefined {
+  if (!isRecord(value)) return undefined
+  if (value.type === "change") {
+    const keys = value.keys
+    if (!Array.isArray(keys) || keys.length === 0 || keys.length > MAX_APPEND_KEYS) return undefined
+    const list: string[] = []
+    for (const key of keys) {
+      if (typeof key !== "string" || !KEY_PATTERN.test(key)) return undefined
+      list.push(key)
+    }
+    return { type: "change", keys: list }
+  }
+  if (value.type !== "revoke") return undefined
+  const { sub, key } = value
+  if (sub !== null && !subjectLike(sub)) return undefined
+  if (key !== null && (typeof key !== "string" || !KEY_PATTERN.test(key))) return undefined
+  return { type: "revoke", sub, key }
+}
+
+export function parseAuthorityRequest(value: unknown): AuthorityRequest | undefined {
+  if (!isRecord(value)) return undefined
+  const { subjects, keys } = value
+  if (!Array.isArray(subjects) || subjects.length > MAX_SUBJECTS) return undefined
+  if (!Array.isArray(keys) || keys.length > MAX_KEYS) return undefined
+  const subjectList: string[] = []
+  for (const sub of subjects) {
+    if (!subjectLike(sub)) return undefined
+    subjectList.push(sub)
+  }
+  const keyList: string[] = []
+  for (const key of keys) {
+    if (typeof key !== "string" || !KEY_PATTERN.test(key)) return undefined
+    keyList.push(key)
+  }
+  return { subjects: subjectList, keys: keyList }
+}
+
+export function parseAuthorityReply(value: unknown): AuthorityReply | undefined {
+  if (!isRecord(value)) return undefined
+  const { seq, floor } = value
+  if (!seqLike(seq) || !seqLike(floor)) return undefined
+  const subjects = stampsOf(value.subjects)
+  const keys = stampsOf(value.keys)
+  const subjectKeys = stampsOf(value.subjectKeys)
+  if (subjects === undefined || keys === undefined || subjectKeys === undefined) return undefined
+  return { seq, floor, subjects, keys, subjectKeys }
+}
+
+export function parseSeq(value: unknown): number | undefined {
+  return isRecord(value) && seqLike(value.seq) && value.seq > 0 ? value.seq : undefined
+}
+
+/** Built from entries, so a subject named `__proto__` keeps its stamp. */
+function stampsOf(value: unknown): Record<string, number> | undefined {
+  if (!isRecord(value)) return undefined
+  const out: [string, number][] = []
+  for (const [name, seq] of Object.entries(value)) {
+    if (!seqLike(seq)) return undefined
+    out.push([name, seq])
+  }
+  return Object.fromEntries(out)
+}
+
+const seqLike = (value: unknown): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+
+const subjectLike = (value: unknown): value is string =>
+  typeof value === "string" && value.length <= MAX_SUBJECT_CHARS
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)