tapimo 0.0.0 → 0.0.2

package/src/internal/Cursor.ts

@@ -0,0 +1,149 @@
+/**
+ * Opaque keyset-pagination cursor: a positional tuple encoding the sort-key of
+ * the last returned row (e.g. `[block, index]` for an append-only feed, or
+ * `[balance, address]` for a balance ranking). Pages are anchored to this
+ * position rather than a numeric offset, so rows arriving at the head of a feed
+ * cannot shift items across page boundaries (the duplicate/skip hazard of offset
+ * pagination over a live feed).
+ *
+ * The token is opaque on purpose: callers must treat it as a blob and pass back
+ * the `nextCursor` from the previous page verbatim. Because cursor values are
+ * inlined into upstream SQL, every field is validated on decode against its
+ * declared `Field` kind and re-serialized into a safe SQL literal via `literal`,
+ * so a malformed or forged cursor degrades to "start from the head" rather than
+ * reaching the query.
+ */
+export type Cursor = (string | number)[]
+
+/** The kind of a cursor field, determining its validation and SQL literal form. */
+export type Field = 'int' | 'uint' | 'address' | 'timestamp'
+
+/** Encodes a positional tuple as an opaque, URL-safe token. */
+export function encode(values: Cursor): string {
+  return base64UrlEncode(JSON.stringify(values))
+}
+
+/**
+ * Splits a keyset query result (fetched with one extra row, `LIMIT n + 1`) into
+ * a page. Returns the page `rows` (capped at `limit`), whether `hasMore` rows
+ * follow, and the `nextCursor` anchoring the next page below the last row.
+ *
+ * `key` derives the next-page cursor tuple from the last row of the page,
+ * returning `undefined` when the row's sort-key can't be extracted (then
+ * `nextCursor` is `null`). Callers build their typed `data` from `rows`.
+ */
+export function paginate<row>(options: {
+  /** The raw query result, fetched with one extra row (`LIMIT limit + 1`). */
+  rows: readonly row[]
+  /** The requested page size. */
+  limit: number
+  /** Derives the next-page cursor tuple from the last row of the page. */
+  key: (row: row) => Cursor | undefined
+}): { hasMore: boolean; nextCursor: string | null; rows: row[] } {
+  const { rows, limit, key } = options
+  const pageRows = rows.slice(0, limit)
+  const hasMore = rows.length > limit
+  const last = pageRows.at(-1)
+  const tuple = hasMore && last !== undefined ? key(last) : undefined
+  return { hasMore, nextCursor: tuple ? encode(tuple) : null, rows: pageRows }
+}
+
+/**
+ * Decodes a cursor token, validating arity and each field against `fields`.
+ * Returns `undefined` for anything malformed/forged so a bad cursor falls back
+ * to the head page instead of erroring (or reaching SQL).
+ */
+export function decode(token: string, fields: readonly Field[]): Cursor | undefined {
+  try {
+    const parsed = JSON.parse(base64UrlDecode(token)) as unknown
+    if (!Array.isArray(parsed) || parsed.length !== fields.length) return undefined
+    for (let i = 0; i < fields.length; i++) if (!isValid(parsed[i], fields[i]!)) return undefined
+    return parsed as Cursor
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Renders a (decode-validated) cursor value as a safe SQL literal: integers and
+ * uint256 decimals are inlined bare; addresses are lowercased and quoted;
+ * timestamps are quoted. Only ever call with values returned from `decode`.
+ */
+export function literal(value: string | number, field: Field): string {
+  switch (field) {
+    case 'int':
+    case 'uint':
+      return String(value)
+    case 'address':
+      return `'${String(value).toLowerCase()}'`
+    case 'timestamp':
+      return `'${String(value)}'`
+  }
+}
+
+/**
+ * Builds a strict lexicographic keyset predicate for the given ORDER BY columns
+ * and direction. Columns carry pre-rendered `literal`s.
+ *
+ * When every column sorts the same way, this emits a row-value (tuple)
+ * comparison, e.g. for `ORDER BY a DESC, b DESC` after `(va, vb)`:
+ * `((a, b) < (va, vb))`. This single-predicate form is the only one the
+ * indexer's signature-decoded queries accept (they reject the equivalent
+ * `OR`-expansion), and standard Postgres / ClickHouse support it too.
+ *
+ * When directions are mixed (e.g. a ranking `ORDER BY balance DESC, addr ASC`),
+ * a tuple comparison can't express it, so it falls back to the `OR` expansion:
+ * `((a < va) OR (a = va AND b > vb))`. Mixed-direction keysets only run against
+ * ClickHouse, which accepts the `OR` form.
+ *
+ * Multi-column keysets additionally AND a redundant non-strict bound on the
+ * first column (`a <= va`): neither the tuple nor the `OR` form alone lets the
+ * ClickHouse planner prune the primary-key range, so without the bare bound a
+ * deep cursor page scans from the tip (see the Q1 notes in `activities.ts`).
+ */
+export function keyset(
+  columns: readonly { name: string; literal: string; order: 'asc' | 'desc' }[],
+): string {
+  const first = columns[0]!
+  const bound =
+    columns.length > 1
+      ? `${first.name} ${first.order === 'asc' ? '>=' : '<='} ${first.literal} AND `
+      : ''
+  const uniform = columns.every((column) => column.order === first.order)
+  if (uniform) {
+    const op = first.order === 'asc' ? '>' : '<'
+    const names = columns.map((column) => column.name).join(', ')
+    const literals = columns.map((column) => column.literal).join(', ')
+    return `(${bound}(${names}) ${op} (${literals}))`
+  }
+
+  const clauses: string[] = []
+  for (let i = 0; i < columns.length; i++) {
+    const parts = columns.slice(0, i).map((column) => `${column.name} = ${column.literal}`)
+    const op = columns[i]!.order === 'asc' ? '>' : '<'
+    parts.push(`${columns[i]!.name} ${op} ${columns[i]!.literal}`)
+    clauses.push(`(${parts.join(' AND ')})`)
+  }
+  return `(${bound}(${clauses.join(' OR ')}))`
+}
+
+function isValid(value: unknown, field: Field): boolean {
+  switch (field) {
+    case 'int':
+      return typeof value === 'number' && Number.isInteger(value) && value >= 0
+    case 'uint':
+      return typeof value === 'string' && /^\d+$/.test(value)
+    case 'address':
+      return typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value)
+    case 'timestamp':
+      return typeof value === 'string' && !Number.isNaN(Date.parse(value))
+  }
+}
+
+function base64UrlEncode(value: string): string {
+  return btoa(value).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '')
+}
+
+function base64UrlDecode(value: string): string {
+  return atob(value.replaceAll('-', '+').replaceAll('_', '/'))
+}

package/src/internal/EdgeCache.test.ts

@@ -0,0 +1,234 @@
+import { Hono } from 'hono'
+import * as EdgeCache from './EdgeCache.js'
+import type * as Store from './Store.js'
+
+describe('middleware', () => {
+  test('serves GETs from cache, skipping downstream middleware', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    const first = await app.request('/cached')
+    const second = await app.request('/cached')
+
+    // The second request is served from the edge cache, so the downstream
+    // (auth/rate-limit) middleware runs only once.
+    expect(downstreamCalls()).toMatchInlineSnapshot(`1`)
+    expect(store.size).toMatchInlineSnapshot(`1`)
+
+    expect(await first.json()).toMatchInlineSnapshot(`
+      {
+        "ok": true,
+      }
+    `)
+    expect(await second.json()).toMatchInlineSnapshot(`
+      {
+        "ok": true,
+      }
+    `)
+
+    // The miss returns the route's own (private, metered) response; the stored
+    // copy served on the hit is public and stripped of per-request headers.
+    expect(first.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"9"`)
+    expect(second.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`null`)
+    expect(second.headers.get('server-timing')).toMatchInlineSnapshot(`null`)
+    expect(second.headers.get('cache-control')).toMatchInlineSnapshot(
+      `"public, max-age=30, s-maxage=30, stale-while-revalidate=300"`,
+    )
+    expect(second.headers.get('vary')).toMatchInlineSnapshot(`"Accept-Encoding"`)
+  })
+
+  test('serves authenticated requests from the same shared cache entry', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    // An authenticated request warms the cache; subsequent requests — whether
+    // authenticated (with any key) or anonymous — are all served from the one
+    // shared entry without re-running downstream auth/rate-limiting.
+    await app.request('/cached', { headers: { authorization: 'Bearer one' } })
+    await app.request('/cached', { headers: { 'tempo-api-key': 'two' } })
+    await app.request('/cached')
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`1`)
+    expect(store.size).toMatchInlineSnapshot(`1`)
+  })
+
+  test('refreshes the entry when the request sends `Cache-Control: no-cache`', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    await app.request('/cached')
+    // `no-cache` skips the stored hit, re-runs downstream, and overwrites the
+    // entry with the fresh response.
+    const refreshed = await app.request('/cached', {
+      headers: { 'cache-control': 'no-cache' },
+    })
+    const after = await app.request('/cached')
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+    expect(store.size).toMatchInlineSnapshot(`1`)
+    // The refresh returns the route's own (private, metered) response, and the
+    // following request is served from the rewritten entry.
+    expect(refreshed.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"9"`)
+    expect(after.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`null`)
+  })
+
+  test('refreshes the entry when the request sends `Pragma: no-cache`', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    await app.request('/cached')
+    // `Pragma` is the HTTP/1.0 fallback for `Cache-Control: no-cache`.
+    await app.request('/cached', { headers: { pragma: 'no-cache' } })
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+    expect(store.size).toMatchInlineSnapshot(`1`)
+  })
+
+  test('strips CDN telemetry headers from stored copies', async () => {
+    const { app } = createApp()
+
+    // The miss response carries `Age`/`CF-Cache-Status` (e.g. stamped by
+    // Cloudflare on an inner Cache API hit); the stored copy must not freeze
+    // them, or every later hit would report the same stale telemetry.
+    await app.request('/cached')
+    const hit = await app.request('/cached')
+
+    expect(hit.headers.get('age')).toMatchInlineSnapshot(`null`)
+    expect(hit.headers.get('cf-cache-status')).toMatchInlineSnapshot(`null`)
+  })
+
+  test('bypasses the cache entirely when the request sends `Cache-Control: no-store`', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    await app.request('/cached')
+    // `no-store` neither serves nor writes the cache: the entry from the first
+    // request stays, but this request always runs downstream.
+    const bypassed = await app.request('/cached', {
+      headers: { 'cache-control': 'no-store' },
+    })
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+    expect(store.size).toMatchInlineSnapshot(`1`)
+    expect(bypassed.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"9"`)
+  })
+
+  test('does not cache non-2xx responses', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    await app.request('/error')
+    await app.request('/error')
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+    expect(store.size).toMatchInlineSnapshot(`0`)
+  })
+
+  test('does not cache routes that did not opt in', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    await app.request('/uncached')
+    await app.request('/uncached')
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+    expect(store.size).toMatchInlineSnapshot(`0`)
+  })
+
+  test('answers conditional requests from a cached ETag with 304', async () => {
+    const { app } = createApp()
+
+    const first = await app.request('/cached')
+    const etag = first.headers.get('etag') ?? ''
+    const conditional = await app.request('/cached', { headers: { 'if-none-match': etag } })
+
+    expect(etag).toMatchInlineSnapshot(`""abc""`)
+    expect(conditional.status).toMatchInlineSnapshot(`304`)
+    expect(await conditional.text()).toMatchInlineSnapshot(`""`)
+    expect(conditional.headers.get('etag')).toMatchInlineSnapshot(`""abc""`)
+  })
+
+  test('round-trips binary bodies through the text store without corruption', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    const miss = await app.request('/binary')
+    const hit = await app.request('/binary')
+
+    // The second request is served from the cache (downstream ran once).
+    expect(downstreamCalls()).toMatchInlineSnapshot(`1`)
+    expect(store.size).toMatchInlineSnapshot(`1`)
+    expect(hit.headers.get('content-type')).toMatchInlineSnapshot(`"image/png"`)
+
+    const expected = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0x00]
+    expect([...new Uint8Array(await miss.arrayBuffer())]).toEqual(expected)
+    expect([...new Uint8Array(await hit.arrayBuffer())]).toEqual(expected)
+  })
+
+  test('is a no-op when no edge cache is available', async () => {
+    const { app, downstreamCalls } = createApp({ store: undefined })
+
+    await app.request('/cached')
+    await app.request('/cached')
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+  })
+})
+
+type Environment = { Variables: EdgeCache.Variables }
+
+// In-memory `Store.Store` so the edge cache and origin cache share one shape.
+function memoryStore() {
+  const map = new Map<string, string>()
+  return {
+    async delete(key: string) {
+      map.delete(key)
+    },
+    async get(key: string) {
+      return map.get(key) ?? null
+    },
+    async list() {
+      return { keys: [...map.keys()].map((name) => ({ name })) }
+    },
+    async put(key: string, value: string) {
+      map.set(key, value)
+    },
+    get size() {
+      return map.size
+    },
+    type: 'state',
+  } satisfies Store.Store & { readonly size: number }
+}
+
+function createApp(options: { store?: Store.Store | undefined } = {}) {
+  const store = memoryStore()
+  const edgeStore = 'store' in options ? options.store : store
+  let downstream = 0
+
+  const app = new Hono<Environment>()
+  app.use('*', EdgeCache.middleware<Environment>({ store: edgeStore }))
+  app.use('*', async (_c, next) => {
+    downstream++
+    await next()
+  })
+  app.get('/cached', (c) => {
+    c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
+    c.header('Age', '123')
+    c.header('CF-Cache-Status', 'HIT')
+    c.header('ETag', '"abc"')
+    c.header('Server-Timing', 'app;dur=1')
+    c.header('RateLimit-Remaining', '9')
+    return c.json({ ok: true })
+  })
+  app.get('/error', (c) => {
+    c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
+    return c.json({ ok: false }, 500)
+  })
+  app.get('/binary', (c) => {
+    c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
+    // Bytes that are not valid UTF-8 (PNG signature) — corrupted if stored via
+    // `.text()` instead of base64.
+    return c.body(
+      new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0x00]),
+      200,
+      {
+        'Content-Type': 'image/png',
+      },
+    )
+  })
+  app.get('/uncached', (c) => c.json({ ok: true }))
+
+  return { app, store, downstreamCalls: () => downstream }
+}

package/src/internal/EdgeCache.ts

@@ -0,0 +1,224 @@
+import type { Env, MiddlewareHandler } from 'hono'
+import { Base64 } from 'ox'
+
+import type * as Store from './Store.js'
+
+/**
+ * Per-request edge-cache policy published by `Cache.response` for routes that
+ * opted into response caching. Its presence is what marks a response as safe to
+ * persist in the shared edge cache.
+ */
+export type Policy = {
+  /** Shared max-age / s-maxage in seconds for the stored response. */
+  maxAge: number
+  /** Stale-while-revalidate window in seconds, if any. */
+  staleWhileRevalidate?: number | undefined
+}
+
+/** Hono variables published by the edge-cache layer. */
+export type Variables = {
+  /** Edge-cache policy for the current route, set by `Cache.response`. */
+  edgeCache?: Policy | undefined
+  /** `'hit'` when the edge cache served the response without reaching the origin handlers. */
+  edgeCacheStatus?: 'hit' | undefined
+}
+
+// Per-request headers that must never be persisted in a shared cache entry.
+// `age`/`cf-cache-status` are CDN telemetry stamped by Cloudflare on Cache API
+// hits (e.g. the inner `Cache.response` layer); storing them would freeze a
+// stale `Age` into every copy served from this cache.
+const volatileHeaders = [
+  'age',
+  'cf-cache-status',
+  'content-encoding',
+  'content-length',
+  'server-timing',
+  'set-cookie',
+  'ratelimit-limit',
+  'ratelimit-remaining',
+  'ratelimit-reset',
+  'tempo-request-id',
+]
+
+/**
+ * Serves GET responses from the edge cache store BEFORE auth and rate-limiting
+ * run, so cache hits skip the per-request store round-trips that dominate
+ * latency — for every caller, authenticated or not. Place this ahead of the
+ * auth middleware.
+ *
+ * Only 2xx responses from routes that opted into caching (via `Cache.response`,
+ * which publishes the `edgeCache` policy) are stored, and the policy is only
+ * published for routes whose responses are public and URL-keyed (no per-principal
+ * data), so a single shared entry is safe to serve to all callers. The trade-off
+ * is that cache hits bypass origin metering: they are not counted against
+ * rate-limit quotas.
+ *
+ * The cache is a plain `Store.Store` — the same store the origin read cache uses
+ * — holding the response serialized to a string under a URL key. It is a no-op
+ * when no store is supplied.
+ *
+ * Standard request `Cache-Control` directives let a caller invalidate without an
+ * out-of-band purge: `no-cache` forces a refresh (skip the stored hit, re-fetch,
+ * overwrite the entry) and `no-store` bypasses the cache entirely. Both fall
+ * through to the origin and are metered normally. The store is colo-local, so a
+ * refresh only affects the data center serving that request.
+ */
+export function middleware<environment extends Env>(
+  options: middleware.Options = {},
+): MiddlewareHandler<environment> {
+  return async (c, next) => {
+    const { store } = options
+    const eligible =
+      store !== undefined && c.req.method === 'GET' && !c.req.raw.headers.has('range')
+    const key = eligible ? cacheKey(c.req.url) : undefined
+
+    // Honor the standard request `Cache-Control` directives so a caller can
+    // refresh a stale entry on the colo serving them without any out-of-band
+    // purge: `no-cache` skips the stored hit but still re-stores the fresh
+    // response (revalidate), and `no-store` bypasses the cache on both sides.
+    // `Pragma: no-cache` is the HTTP/1.0 fallback, honored only when
+    // `Cache-Control` is absent (RFC 9111 §5.4). A forced miss falls through
+    // to `next()` and is metered like any other origin request, so this is
+    // not an unmetered-access vector.
+    const directives = (c.req.header('cache-control') ?? c.req.header('pragma') ?? '').toLowerCase()
+    const noStore = directives.includes('no-store')
+    const noCache = noStore || directives.includes('no-cache')
+
+    if (store && key && !noCache) {
+      const hit = await store.get(key)
+      if (hit) {
+        // Mark the hit for the canonical request log line; routing never runs
+        // for hits, so this is the only signal that the cache answered.
+        c.set('edgeCacheStatus' as never, 'hit' as never)
+        return serveHit(c.req.header('if-none-match'), hit)
+      }
+    }
+
+    await next()
+
+    if (!store || !key || noStore) return
+    const policy = c.get('edgeCache' as never) as Policy | undefined
+    if (!policy) return
+    if (c.res.status < 200 || c.res.status >= 300) return
+    if (c.res.headers.has('set-cookie')) return
+    if (c.res.headers.get('content-type')?.includes('text/event-stream')) return
+
+    // Store a public, sanitized copy; the client still receives the original
+    // (private, metered) response for this miss.
+    const value = await serialize(c.res, policy)
+    const put = store.put(key, value, { ttl: policy.maxAge * 1_000 })
+    const waitUntil = getWaitUntil(c)
+    if (waitUntil) waitUntil(put)
+    else await put.catch(() => {})
+    return
+  }
+}
+
+export declare namespace middleware {
+  /** Options for the edge-cache middleware. */
+  type Options = {
+    /** Store backing the edge cache. The layer is a no-op when omitted. */
+    store?: Store.Store | undefined
+  }
+}
+
+/** A response serialized for storage in the string-keyed edge cache. */
+type Stored = {
+  /** Response body. UTF-8 text, or base64 when `encoding` is `'base64'`. */
+  body: string
+  /** Set to `'base64'` when `body` holds base64-encoded binary bytes. */
+  encoding?: 'base64' | undefined
+  /** Response headers, already sanitized for shared caching. */
+  headers: [string, string][]
+  /** Response status code. */
+  status: number
+}
+
+async function serialize(response: Response, policy: Policy): Promise<string> {
+  const headers = new Headers(response.headers)
+  for (const name of volatileHeaders) headers.delete(name)
+  headers.set('Cache-Control', cacheControl(policy))
+  headers.set('Vary', 'Accept-Encoding')
+  // The store is text-only, so binary bodies (e.g. PNG token logos) must be
+  // base64-encoded or the round trip through `.text()` corrupts them. Text
+  // bodies (JSON, SVG, HTML) stay verbatim to avoid the 33% base64 overhead.
+  const textual = isTextual(headers.get('content-type'))
+  const stored: Stored = {
+    body: textual
+      ? await response.clone().text()
+      : Base64.fromBytes(new Uint8Array(await response.clone().arrayBuffer())),
+    ...(textual ? {} : { encoding: 'base64' as const }),
+    headers: [...headers],
+    status: response.status,
+  }
+  return JSON.stringify(stored)
+}
+
+function serveHit(ifNoneMatch: string | undefined, value: string): Response {
+  const { body, encoding, headers, status } = JSON.parse(value) as Stored
+  const responseHeaders = new Headers(headers)
+  const etag = responseHeaders.get('etag')
+  if (etag && ifNoneMatch && etagMatches(etag, ifNoneMatch)) {
+    const notModified = new Headers()
+    for (const name of ['Cache-Control', 'ETag', 'Vary']) {
+      const header = responseHeaders.get(name)
+      if (header) notModified.set(name, header)
+    }
+    return new Response(null, { headers: notModified, status: 304, statusText: 'Not Modified' })
+  }
+  if (encoding === 'base64') {
+    // Copy the decoded bytes into an exact `ArrayBuffer`: `Base64.toBytes`
+    // returns a `Uint8Array` view, which this TS lib does not accept as a
+    // `BodyInit`.
+    const bytes = Base64.toBytes(body)
+    const buffer = new ArrayBuffer(bytes.byteLength)
+    new Uint8Array(buffer).set(bytes)
+    return new Response(buffer, { headers: responseHeaders, status })
+  }
+  return new Response(body, { headers: responseHeaders, status })
+}
+
+// A body is safe to store as verbatim text when its content type is textual;
+// everything else (images, octet-stream) is treated as binary and base64-coded.
+function isTextual(contentType: string | null): boolean {
+  if (!contentType) return false
+  return /^(?:text\/|application\/(?:json|xml|javascript|[\w.-]+\+(?:json|xml))|image\/svg\+xml)/i.test(
+    contentType,
+  )
+}
+
+// Sort query params so semantically identical URLs share one cache entry.
+function cacheKey(requestUrl: string) {
+  const url = new URL(requestUrl)
+  url.searchParams.sort()
+  return url.toString()
+}
+
+function getWaitUntil(c: { executionCtx?: { waitUntil(promise: Promise<unknown>): void } }) {
+  // `c.executionCtx` throws on runtimes without one (e.g. Node), so probe it
+  // defensively and fall back to awaiting the write inline.
+  try {
+    const ctx = c.executionCtx
+    return ctx ? ctx.waitUntil.bind(ctx) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function etagMatches(etag: string, ifNoneMatch: string) {
+  const strip = (tag: string) => tag.trim().replace(/^W\//, '')
+  return ifNoneMatch.split(',').some((tag) => strip(tag) === strip(etag))
+}
+
+/**
+ * Builds the shared-cache `Cache-Control` value for a stored copy: `public`
+ * with `max-age`/`s-maxage` bound to the policy plus an optional
+ * `stale-while-revalidate` window. Used for this layer's stored copies and by
+ * `Cache.response` to bound the inner response cache's entry lifetime.
+ */
+export function cacheControl(policy: Policy) {
+  const directives = ['public', `max-age=${policy.maxAge}`, `s-maxage=${policy.maxAge}`]
+  if (policy.staleWhileRevalidate)
+    directives.push(`stale-while-revalidate=${policy.staleWhileRevalidate}`)
+  return directives.join(', ')
+}

package/src/internal/Errors.ts

@@ -0,0 +1,14 @@
+import { Tidx } from 'tidx.ts'
+
+/**
+ * Extract a status code from a TIDX fetch error or any error that carries a
+ * numeric `status` property. Returns undefined when the error has none.
+ */
+export function getStatus(cause: unknown) {
+  if (cause instanceof Tidx.FetchRequestError) return cause.status
+  if (typeof cause === 'object' && cause && 'status' in cause) {
+    const { status } = cause as { status?: unknown }
+    if (typeof status === 'number') return status
+  }
+  return undefined
+}