@dejadex/web 0.0.0-stage → 0.1.1

package/src/usage/store.ts

@@ -0,0 +1,282 @@
+/**
+ * The device's usage queue: what was counted waits here, across reloads,
+ * until the host has delivered it. IndexedDB in the browser; an in-memory
+ * store for tests and for runtimes without IndexedDB (where usage then lives
+ * only as long as the page).
+ *
+ * Two stages:
+ *   - a **tally** per (lease, session) collects the cards first identified in
+ *     that session and the number of calls, as answers come in;
+ *   - `seal` turns every open tally into a `UsageReport` with the lease's next
+ *     `seq` and a fresh `reportId`, atomically. A sealed report never changes,
+ *     so delivering it twice is harmless (the service dedupes by `reportId`).
+ *
+ * Database `dejadex-usage`, version 1:
+ *   tallies  key `<leaseId>\n<sessionId>` → Tally
+ *   reports  keyPath `report.reportId`, index `order` → { order, report }
+ *   meta     `deviceId`, `order`, `seq:<leaseId>`, `reported:<leaseId>`
+ *
+ * The connection is never held against the host: on `versionchange` (the
+ * host's `indexedDB.deleteDatabase('dejadex-usage')` on sign-out, or a newer
+ * page upgrading it) the store closes itself, so the delete proceeds. A closed
+ * store rejects every later call with a `ScannerError`; nothing is dropped
+ * without the caller hearing of it.
+ */
+import { ScannerError } from '../errors.js'
+import type { UsageReport } from '../types.js'
+
+export interface Tally {
+  readonly leaseId: string
+  readonly sessionId: string
+  /** Distinct, in first-seen order. */
+  readonly cardIds: readonly string[]
+  readonly calls: number
+  /** Device clock (ms) of the latest addition. */
+  readonly at: number
+}
+
+export interface UsageStore {
+  /** A random per-install id (at least 128 bits), created on first use. */
+  deviceId(): Promise<string>
+  /** Adds cards (deduplicated) and calls to the open tally of (lease, session). */
+  tally(leaseId: string, sessionId: string, cardIds: readonly string[], calls: number, at: number): Promise<void>
+  /** Seals every open tally into a queued report; returns how many were sealed. */
+  seal(newReportId: () => string): Promise<number>
+  /** The oldest `limit` queued reports, in queue order. */
+  peek(limit: number): Promise<readonly UsageReport[]>
+  remove(reportIds: readonly string[]): Promise<void>
+  /** Records that these reports were delivered: each lease's highest delivered `seq`. */
+  markReported(reports: readonly UsageReport[]): Promise<void>
+  /** The highest delivered `seq` of a lease, or null when none was. */
+  reportedThrough(leaseId: string): Promise<number | null>
+  /** Queued reports plus open tallies. */
+  size(): Promise<number>
+  /**
+   * Releases what the store holds open (the IndexedDB connection). Later calls
+   * reject with `ScannerError` `INVALID_OPTIONS`. Optional for stores a host
+   * implements; the identifier closes only a store it opened itself.
+   */
+  close?(): void
+}
+
+export function randomId(bytes = 16): string {
+  const b = new Uint8Array(bytes)
+  crypto.getRandomValues(b)
+  let out = ''
+  for (const x of b) out += x.toString(16).padStart(2, '0')
+  return out
+}
+
+const tallyKey = (leaseId: string, sessionId: string): string => `${leaseId}\n${sessionId}`
+
+function merge(prev: Tally | undefined, leaseId: string, sessionId: string, cardIds: readonly string[], calls: number, at: number): Tally {
+  const cards = [...(prev?.cardIds ?? [])]
+  for (const id of cardIds) if (!cards.includes(id)) cards.push(id)
+  return { leaseId, sessionId, cardIds: cards, calls: (prev?.calls ?? 0) + calls, at }
+}
+
+const toReport = (t: Tally, seq: number, reportId: string): UsageReport => ({
+  reportId,
+  leaseId: t.leaseId,
+  seq,
+  sessionId: t.sessionId,
+  distinctCards: t.cardIds.length,
+  cardIds: [...t.cardIds],
+  calls: t.calls,
+  at: t.at,
+})
+
+export function memoryUsageStore(): UsageStore {
+  let device: string | null = null
+  const seq = new Map<string, number>()
+  const tallies = new Map<string, Tally>()
+  const queue: UsageReport[] = []
+  const reported = new Map<string, number>()
+  return {
+    async deviceId() {
+      device ??= randomId()
+      return device
+    },
+    async tally(leaseId, sessionId, cardIds, calls, at) {
+      const key = tallyKey(leaseId, sessionId)
+      tallies.set(key, merge(tallies.get(key), leaseId, sessionId, cardIds, calls, at))
+    },
+    async seal(newReportId) {
+      const open = [...tallies.values()]
+      tallies.clear()
+      for (const t of open) {
+        const next = (seq.get(t.leaseId) ?? 0) + 1
+        seq.set(t.leaseId, next)
+        queue.push(toReport(t, next, newReportId()))
+      }
+      return open.length
+    },
+    async peek(limit) {
+      return queue.slice(0, limit)
+    },
+    async remove(ids) {
+      const drop = new Set(ids)
+      for (let i = queue.length - 1; i >= 0; i--) if (drop.has((queue[i] as UsageReport).reportId)) queue.splice(i, 1)
+    },
+    async markReported(reports) {
+      for (const r of reports) reported.set(r.leaseId, Math.max(reported.get(r.leaseId) ?? 0, r.seq))
+    },
+    async reportedThrough(leaseId) {
+      return reported.get(leaseId) ?? null
+    },
+    async size() {
+      return queue.length + tallies.size
+    },
+    /** Nothing to release: memory lives as long as the page. */
+    close() {},
+  }
+}
+
+const DB_NAME = 'dejadex-usage'
+const DB_VERSION = 1
+
+function request<T>(req: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result)
+    req.onerror = () => reject(req.error ?? new Error('IndexedDB request failed'))
+  })
+}
+
+function done(tx: IDBTransaction): Promise<void> {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve()
+    tx.onabort = () => reject(tx.error ?? new Error('IndexedDB transaction aborted'))
+    tx.onerror = () => reject(tx.error ?? new Error('IndexedDB transaction failed'))
+  })
+}
+
+interface QueuedRow {
+  readonly order: number
+  readonly report: UsageReport
+}
+
+/** The IndexedDB store. `factory` defaults to the global `indexedDB`. */
+export async function indexedDbUsageStore(factory: IDBFactory = indexedDB): Promise<UsageStore> {
+  const open = factory.open(DB_NAME, DB_VERSION)
+  open.onupgradeneeded = () => {
+    const db = open.result
+    if (!db.objectStoreNames.contains('tallies')) db.createObjectStore('tallies')
+    if (!db.objectStoreNames.contains('reports')) {
+      db.createObjectStore('reports', { keyPath: 'report.reportId' }).createIndex('order', 'order', { unique: true })
+    }
+    if (!db.objectStoreNames.contains('meta')) db.createObjectStore('meta')
+  }
+  const db = await request(open)
+
+  /** Why the connection is gone, once it is. */
+  let closed: string | null = null
+  const shut = (why: string) => {
+    if (closed !== null) return
+    closed = why
+    db.close()
+  }
+  // Another party wants the database (a host's deleteDatabase, a newer
+  // version): let go, or its request is blocked for the life of the document.
+  db.onversionchange = () => shut('it was deleted or upgraded elsewhere')
+  // The browser closed it (storage cleared, the disk went away).
+  db.onclose = () => {
+    closed ??= 'the browser closed it'
+  }
+  const transaction = (names: string | string[], mode: IDBTransactionMode): IDBTransaction => {
+    if (closed !== null) throw new ScannerError('INVALID_OPTIONS', `the usage store is closed: ${closed}`)
+    return db.transaction(names, mode)
+  }
+
+  return {
+    async deviceId() {
+      const tx = transaction('meta', 'readwrite')
+      const meta = tx.objectStore('meta')
+      let id = (await request(meta.get('deviceId'))) as unknown
+      if (typeof id !== 'string') {
+        id = randomId()
+        meta.put(id, 'deviceId')
+      }
+      await done(tx)
+      return id as string
+    },
+    async tally(leaseId, sessionId, cardIds, calls, at) {
+      const tx = transaction('tallies', 'readwrite')
+      const store = tx.objectStore('tallies')
+      const key = tallyKey(leaseId, sessionId)
+      const prev = (await request(store.get(key))) as Tally | undefined
+      store.put(merge(prev, leaseId, sessionId, cardIds, calls, at), key)
+      await done(tx)
+    },
+    async seal(newReportId) {
+      const tx = transaction(['tallies', 'reports', 'meta'], 'readwrite')
+      const tallies = tx.objectStore('tallies')
+      const reports = tx.objectStore('reports')
+      const meta = tx.objectStore('meta')
+      const open = (await request(tallies.getAll())) as Tally[]
+      let order = ((await request(meta.get('order'))) as number | undefined) ?? 0
+      const seqs = new Map<string, number>()
+      for (const t of open) {
+        const key = `seq:${t.leaseId}`
+        let last = seqs.get(key)
+        if (last === undefined) last = ((await request(meta.get(key))) as number | undefined) ?? 0
+        const next = last + 1
+        seqs.set(key, next)
+        reports.put({ order: ++order, report: toReport(t, next, newReportId()) } satisfies QueuedRow)
+      }
+      for (const [key, value] of seqs) meta.put(value, key)
+      meta.put(order, 'order')
+      tallies.clear()
+      await done(tx)
+      return open.length
+    },
+    async peek(limit) {
+      const tx = transaction('reports', 'readonly')
+      const rows = (await request(tx.objectStore('reports').index('order').getAll(null, limit))) as QueuedRow[]
+      await done(tx)
+      return rows.map((r) => r.report)
+    },
+    async remove(ids) {
+      const tx = transaction('reports', 'readwrite')
+      const store = tx.objectStore('reports')
+      for (const id of ids) store.delete(id)
+      await done(tx)
+    },
+    async markReported(reports) {
+      const tx = transaction('meta', 'readwrite')
+      const meta = tx.objectStore('meta')
+      const top = new Map<string, number>()
+      for (const r of reports) top.set(r.leaseId, Math.max(top.get(r.leaseId) ?? 0, r.seq))
+      for (const [leaseId, seq] of top) {
+        const key = `reported:${leaseId}`
+        const prev = (await request(meta.get(key))) as number | undefined
+        if (prev === undefined || seq > prev) meta.put(seq, key)
+      }
+      await done(tx)
+    },
+    async reportedThrough(leaseId) {
+      const tx = transaction('meta', 'readonly')
+      const v = (await request(tx.objectStore('meta').get(`reported:${leaseId}`))) as number | undefined
+      await done(tx)
+      return v ?? null
+    },
+    async size() {
+      const tx = transaction(['reports', 'tallies'], 'readonly')
+      const [a, b] = await Promise.all([request(tx.objectStore('reports').count()), request(tx.objectStore('tallies').count())])
+      await done(tx)
+      return a + b
+    },
+    close() {
+      shut('close() was called')
+    },
+  }
+}
+
+/** IndexedDB where it opens, else memory (private windows can refuse it). */
+export async function defaultUsageStore(): Promise<UsageStore> {
+  try {
+    if (typeof indexedDB !== 'undefined') return await indexedDbUsageStore()
+  } catch {
+    // fall through to memory
+  }
+  return memoryUsageStore()
+}