@nxtedition/nxt-undici 7.4.1 → 7.4.3

package/lib/sqlite-cache-store.js

@@ -2,18 +2,43 @@ import { DatabaseSync } from 'node:sqlite'
 import { parseRangeHeader, getFastNow } from './utils.js'
 
 // Bump version when the URL key format or schema changes to invalidate old caches.
-const VERSION = 10
-
-/** @typedef {{ gc: () => void, clear: () => void } } */
+const VERSION = 11
+
+// Registry of live stores so process-level broadcasts (nxt:offPeak,
+// nxt:clearCache) can reach them. Stores are held via WeakRef so that a store
+// dropped without close() is not pinned forever (together with its open
+// DatabaseSync handle and page cache) — GC can still collect it. close()
+// remains the recommended, deterministic cleanup path.
+/** @type {Set<WeakRef<SqliteCacheStore>>} */
 const stores = new Set()
 
+// Removes a collected store's WeakRef entry once the store has been GC'd.
+// The callback runs after the store is already gone, so it must not (and
+// cannot) touch the store or its DatabaseSync — the native handle has its own
+// lifecycle and is released by GC/process exit. This only drops bookkeeping.
+const registry = new FinalizationRegistry((ref) => {
+  stores.delete(ref)
+})
+
+/**
+ * @param {(store: SqliteCacheStore) => void} fn
+ */
+function forEachStore(fn) {
+  for (const ref of stores) {
+    const store = ref.deref()
+    if (store === undefined) {
+      stores.delete(ref)
+    } else {
+      fn(store)
+    }
+  }
+}
+
 {
   const offPeakBC = new BroadcastChannel('nxt:offPeak')
   offPeakBC.unref()
   offPeakBC.onmessage = () => {
-    for (const store of stores) {
-      store.gc()
-    }
+    forEachStore((store) => store.gc())
   }
 }
 
@@ -21,15 +46,14 @@ const stores = new Set()
   const clearCacheBC = new BroadcastChannel('nxt:clearCache')
   clearCacheBC.unref()
   clearCacheBC.onmessage = () => {
-    for (const store of stores) {
-      store.clear()
-    }
+    forEachStore((store) => store.clear())
   }
 }
 
 /**
- * @typedef {import('undici-types/cache-interceptor.d.ts').default.CacheStore} CacheStore
- * @implements {CacheStore}
+ * Synchronous get/set/delete cache store backed by node:sqlite. Note: this is
+ * NOT undici's stream-based CacheStore interface (createWriteStream); the
+ * cache interceptor in this package drives it directly.
  *
  * @typedef {{
  *  id: Readonly<number>,
@@ -43,6 +67,7 @@ const stores = new Set()
  *  etag?: string
  *  cacheControlDirectives?: string
  *  cachedAt: number
+ *  staleAt: number
  *  deleteAt: number
  * }} SqliteStoreValue
  */
@@ -77,10 +102,30 @@ export class SqliteCacheStore {
    */
   #evictQuery
 
+  /**
+   * @type {import('node:sqlite').StatementSync}
+   */
+  #deleteByUrlQuery
+
+  /**
+   * @type {import('node:sqlite').StatementSync}
+   */
+  #supersedeFullQuery
+
+  /**
+   * @type {import('node:sqlite').StatementSync}
+   */
+  #supersede206Query
+
   #insertBatch = []
   #insertSeq = 0
   #closed = false
 
+  /**
+   * @type {WeakRef<SqliteCacheStore>}
+   */
+  #ref
+
   /**
    * @param {import('undici-types/cache-interceptor.d.ts').default.SqliteCacheStoreOpts & { maxSize?: number } | undefined} opts
    */
@@ -108,6 +153,7 @@ export class SqliteCacheStore {
         body BLOB NULL,
         start INTEGER NOT NULL,
         end INTEGER NOT NULL,
+        staleAt INTEGER NOT NULL,
         deleteAt INTEGER NOT NULL,
         statusCode INTEGER NOT NULL,
         statusMessage TEXT NOT NULL,
@@ -120,14 +166,65 @@ export class SqliteCacheStore {
 
       CREATE INDEX IF NOT EXISTS idx_cacheInterceptorV${VERSION}_getValuesQuery ON cacheInterceptorV${VERSION}(url, method, start, deleteAt);
       CREATE INDEX IF NOT EXISTS idx_cacheInterceptorV${VERSION}_deleteExpiredValuesQuery ON cacheInterceptorV${VERSION}(deleteAt);
+      -- Covers the supersede-on-flush DELETEs (#supersedeFullQuery /
+      -- #supersede206Query), whose predicate is url+method+vary (+statusCode,
+      -- and start/end for 206) — so a re-cache supersedes via an index seek
+      -- instead of scanning every row for a hot url+method with many Vary
+      -- variants or partial windows.
+      CREATE INDEX IF NOT EXISTS idx_cacheInterceptorV${VERSION}_supersedeQuery ON cacheInterceptorV${VERSION}(url, method, vary, statusCode, start, end);
     `)
 
+    // Drop tables left behind by previous schema versions. gc(), clear() and
+    // the SQLITE_FULL eviction only ever touch the current version's table, so
+    // after a VERSION bump the old table's pages would otherwise stay allocated
+    // to its b-tree forever while max_page_count caps the whole file — new
+    // inserts hit SQLITE_FULL almost immediately and eviction frees nothing.
+    // Dropping returns the pages to SQLite's freelist, which subsequent inserts
+    // reuse, so no VACUUM is needed. SQLite drops the table's indexes and its
+    // sqlite_sequence row along with it.
+    try {
+      // LIKE is only a coarse pre-filter; the regexp restricts matches to
+      // digit-only version suffixes so user tables sharing the prefix (e.g.
+      // "cacheInterceptorVBackup") in a shared database file are never dropped.
+      const staleTables = this.#db
+        .prepare(
+          `SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'cacheInterceptorV%'`,
+        )
+        .all()
+        .filter(
+          ({ name }) =>
+            /^cacheInterceptorV\d+$/.test(name) && name !== `cacheInterceptorV${VERSION}`,
+        )
+      if (staleTables.length > 0) {
+        this.#db.exec('BEGIN')
+        try {
+          for (const { name } of staleTables) {
+            // name comes from sqlite_master; quote it defensively anyway.
+            this.#db.exec(`DROP TABLE IF EXISTS "${String(name).replaceAll('"', '""')}"`)
+          }
+          this.#db.exec('COMMIT')
+        } catch (err) {
+          try {
+            this.#db.exec('ROLLBACK')
+          } catch {
+            // already rolled back automatically
+          }
+          throw err
+        }
+      }
+    } catch (err) {
+      // A failed cleanup must not brick construction — the current version's
+      // table still works, the stale one just keeps occupying pages.
+      process.emitWarning(err)
+    }
+
     this.#getValuesQuery = this.#db.prepare(`
       SELECT
         id,
         body,
         start,
         end,
+        staleAt,
         deleteAt,
         statusCode,
         statusMessage,
@@ -143,7 +240,7 @@ export class SqliteCacheStore {
         AND start <= ?
         AND deleteAt > ?
       ORDER BY
-        cachedAt DESC, id DESC
+        id DESC
     `)
 
     this.#insertValueQuery = this.#db.prepare(`
@@ -153,6 +250,7 @@ export class SqliteCacheStore {
         body,
         start,
         end,
+        staleAt,
         deleteAt,
         statusCode,
         statusMessage,
@@ -161,7 +259,7 @@ export class SqliteCacheStore {
         cacheControlDirectives,
         vary,
         cachedAt
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `)
 
     this.#deleteExpiredValuesQuery = this.#db.prepare(
@@ -174,7 +272,40 @@ export class SqliteCacheStore {
       `DELETE FROM cacheInterceptorV${VERSION} WHERE id IN (SELECT id FROM cacheInterceptorV${VERSION} ORDER BY deleteAt ASC LIMIT ?)`,
     )
 
-    stores.add(this)
+    // RFC 9111 §4.4 invalidation: a successful unsafe request invalidates every
+    // stored response for the URI, across methods and vary variants.
+    this.#deleteByUrlQuery = this.#db.prepare(
+      `DELETE FROM cacheInterceptorV${VERSION} WHERE url = ?`,
+    )
+
+    // Supersede queries: a newly flushed row replaces prior rows for the same
+    // representation so hot keys don't accumulate dead duplicates until gc.
+    // Receipt order (insertion order), NOT cachedAt, decides who wins — the
+    // same semantics as upstream undici's update-in-place set(). cachedAt is
+    // backdated by the corrected initial age (RFC 9111 §4.2.3), so a
+    // replacement fetched through a relay advertising a large Age (or a 304
+    // freshening with a skewed origin Date) can carry an OLDER cachedAt than
+    // the stale row it replaces; keying supersede or the read sort on
+    // cachedAt would let the stale row win every read, forever. `vary IS ?`
+    // is NULL-safe and compares the serialized-JSON text, deterministic
+    // because both sides are produced by the same CacheHandler code path
+    // (key order = Vary header order). A new full (non-206) representation
+    // supersedes all prior full ones regardless of byte window; a 206 only
+    // supersedes the exact same window so distinct partials coexist, and
+    // never a 200 row (matchesValue routes range and non-range requests to
+    // different rows).
+    this.#supersedeFullQuery = this.#db.prepare(
+      `DELETE FROM cacheInterceptorV${VERSION} WHERE url = ? AND method = ? AND vary IS ? AND statusCode != 206`,
+    )
+    this.#supersede206Query = this.#db.prepare(
+      `DELETE FROM cacheInterceptorV${VERSION} WHERE url = ? AND method = ? AND vary IS ? AND statusCode = 206 AND start = ? AND end = ?`,
+    )
+
+    this.#ref = new WeakRef(this)
+    stores.add(this.#ref)
+    // The store itself doubles as the unregister token so close() can drop
+    // the registry entry deterministically.
+    registry.register(this, this.#ref, this)
   }
 
   gc() {
@@ -222,7 +353,8 @@ export class SqliteCacheStore {
   }
 
   close() {
-    stores.delete(this)
+    stores.delete(this.#ref)
+    registry.unregister(this)
     // Drain the entire batch synchronously before closing. A plain #flush()
     // only commits one time-budget slice and reschedules the rest via
     // setImmediate; that deferred flush would see #closed and discard the
@@ -294,7 +426,7 @@ export class SqliteCacheStore {
       setImmediate(this.#flush)
     }
 
-    this.#insertBatch.push({
+    const entry = {
       // Monotonic per-store sequence used only to break cachedAt ties in
       // #findValue (newest write wins). Not persisted — #flush ignores it.
       seq: this.#insertSeq++,
@@ -303,6 +435,9 @@ export class SqliteCacheStore {
       body,
       start: value.start,
       end: value.end,
+      // staleAt column is NOT NULL; default to deleteAt when the caller omits
+      // it (pre-v11 value shape) — matches this package's staleAt === deleteAt.
+      staleAt: value.staleAt ?? value.deleteAt,
       deleteAt: value.deleteAt,
       statusCode: value.statusCode,
       statusMessage: value.statusMessage,
@@ -313,7 +448,56 @@ export class SqliteCacheStore {
         : null,
       vary: value.vary ? JSON.stringify(value.vary) : null,
       cachedAt: value.cachedAt,
-    })
+    }
+
+    // Coalesce within the pending batch: a stampede of identical misses would
+    // otherwise commit N identical rows. Receipt order wins (see the
+    // #supersede* query comments): the entry being added supersedes every
+    // pending entry for the same representation.
+    for (let i = this.#insertBatch.length - 1; i >= 0; i--) {
+      const other = this.#insertBatch[i]
+      if (
+        other.url === entry.url &&
+        other.method === entry.method &&
+        other.vary === entry.vary &&
+        (entry.statusCode !== 206
+          ? other.statusCode !== 206
+          : other.statusCode === 206 && other.start === entry.start && other.end === entry.end)
+      ) {
+        this.#insertBatch.splice(i, 1)
+      }
+    }
+
+    this.#insertBatch.push(entry)
+  }
+
+  /**
+   * Invalidates every stored response for the key's URI (RFC 9111 §4.4) —
+   * across methods and vary variants. Pending batched inserts for the URI are
+   * dropped as well: a batch entry flushed after the DELETE would otherwise
+   * resurrect the invalidated response. Note this only covers THIS process's
+   * batch — with a shared on-disk store, another process's in-flight batch
+   * can still transiently resurrect an entry (bounded by its ~10ms flush
+   * slice); cross-process invalidation is inherently best-effort.
+   *
+   * @param {import('undici-types/cache-interceptor.d.ts').default.CacheKey} key
+   */
+  delete(key) {
+    assertCacheKey(key)
+
+    if (this.#closed) {
+      return
+    }
+
+    const url = makeValueUrl(key)
+
+    for (let i = this.#insertBatch.length - 1; i >= 0; i--) {
+      if (this.#insertBatch[i].url === url) {
+        this.#insertBatch.splice(i, 1)
+      }
+    }
+
+    this.#deleteByUrlQuery.run(url)
   }
 
   #flush = (final = false) => {
@@ -335,6 +519,7 @@ export class SqliteCacheStore {
               body,
               start,
               end,
+              staleAt,
               deleteAt,
               statusCode,
               statusMessage,
@@ -344,12 +529,21 @@ export class SqliteCacheStore {
               vary,
               cachedAt,
             } = this.#insertBatch[n++]
+            // Supersede prior rows for the same representation (see the
+            // #supersede* query comments) inside the same transaction, so a
+            // re-cache replaces instead of accumulating.
+            if (statusCode === 206) {
+              this.#supersede206Query.run(url, method, vary, start, end)
+            } else {
+              this.#supersedeFullQuery.run(url, method, vary)
+            }
             this.#insertValueQuery.run(
               url,
               method,
               body,
               start,
               end,
+              staleAt,
               deleteAt,
               statusCode,
               statusMessage,
@@ -457,16 +651,14 @@ export class SqliteCacheStore {
       return undefined
     }
 
-    // Newest representation wins. cachedAt is millisecond-resolution, so a
-    // re-cache within the same millisecond produces a tie; break it
-    // deterministically toward the freshest write: pending batch entries
-    // (tagged with a monotonic seq) are always newer than any flushed DB row,
-    // and within each source a higher seq/id wins.
+    // Most recently WRITTEN representation wins — receipt order, not
+    // cachedAt (see the #supersede* query comments: cachedAt is backdated by
+    // the corrected initial age, so a fresher write can carry an older
+    // cachedAt). Pending batch entries (tagged with a monotonic seq) are
+    // always newer than any flushed DB row, and within each source a higher
+    // seq/id wins.
     if (values.length > 1) {
       values.sort((a, b) => {
-        if (a.cachedAt !== b.cachedAt) {
-          return b.cachedAt - a.cachedAt
-        }
         const aBatch = a.seq != null
         const bBatch = b.seq != null
         if (aBatch !== bBatch) {
@@ -580,6 +772,7 @@ function makeResult(value) {
       ? JSON.parse(value.cacheControlDirectives)
       : undefined,
     cachedAt: value.cachedAt,
+    staleAt: value.staleAt,
     deleteAt: value.deleteAt,
   }
 }
@@ -627,6 +820,16 @@ function assertCacheValue(value) {
     }
   }
 
+  // staleAt is optional for backward compatibility: pre-v11 callers of the
+  // public SqliteCacheStore.set() omit it, and set() defaults it to deleteAt
+  // (this package's staleAt === deleteAt semantics). Validate the type only
+  // when supplied.
+  if (value.staleAt !== undefined && typeof value.staleAt !== 'number') {
+    throw new TypeError(
+      `expected value.staleAt to be number, got ${printType(value.staleAt)} [${value.staleAt}]`,
+    )
+  }
+
   if (typeof value.statusMessage !== 'string') {
     throw new TypeError(
       `expected value.statusMessage to be string, got ${printType(value.statusMessage)} [${value.statusMessage}]`,