tapimo 0.14.0 → 0.15.1

package/src/internal/Store.ts

@@ -51,6 +51,8 @@ export type Store = {
   deleteIf?: ((key: string, expected: null | string) => Promise<boolean>) | undefined
   /** Gets a string value. Returns `null` for missing or expired keys. */
   get(key: string): Promise<null | string>
+  /** Gets multiple string values through a backend-native bulk read when available. */
+  getMany?: ((keys: readonly string[]) => Promise<ReadonlyMap<string, null | string>>) | undefined
   /**
    * Optional native counter: increments an integer value and returns the new
    * count. A missing or expired key restarts at `1`; `ttl` applies like
@@ -62,14 +64,22 @@ export type Store = {
   increment?: ((key: string, options?: Store.PutOptions) => Promise<number>) | undefined
   /** Lists keys. */
   list(options?: {
+    /** Continue after a previous bounded page. */
+    cursor?: string | undefined
+    /** Maximum matching keys to return. */
+    limit?: number | undefined
     /** Restrict results to keys with this prefix. */
     prefix?: string | undefined
   }): Promise<{
+    /** Cursor for a following page, when more keys remain. */
+    cursor?: string | undefined
     /** Matching keys. */
     keys: readonly {
       /** Key name. */
       name: string
     }[]
+    /** Whether every matching key has been returned. */
+    listComplete?: boolean | undefined
   }>
   /** Writes a string value, optionally with a time-to-live. */
   put(key: string, value: string, options?: Store.PutOptions): Promise<void>
@@ -147,6 +157,17 @@ export declare namespace from {
   type Output<store extends Input> = store extends { type: 'cache' } ? Store : State
 }
 
+/** Gets multiple values, falling back to serial reads when the store has no native bulk operation. */
+export async function getMany(
+  store: Store,
+  keys: readonly string[],
+): Promise<ReadonlyMap<string, null | string>> {
+  if (store.getMany) return store.getMany(keys)
+  const values = new Map<string, null | string>()
+  for (const key of keys) values.set(key, await store.get(key))
+  return values
+}
+
 /**
  * Increments an integer counter on a store and returns the new value. A
  * missing or expired key restarts at `1`; `ttl` applies like {@link Store.put}.
@@ -300,12 +321,20 @@ export function memory(options: memory.Options = {}): State {
       return count
     },
     async list(options = {}) {
-      const keys = Array.from(cells.keys())
+      const matching = Array.from(cells.keys())
         .filter((key) => (!options.prefix || key.startsWith(options.prefix)) && read(key))
         .sort()
-        .map((name) => ({ name }))
-
-      return { keys }
+        .filter((key) => options.cursor === undefined || key > options.cursor)
+      const names = options.limit === undefined ? matching : matching.slice(0, options.limit)
+      const keys = names.map((name) => ({ name }))
+
+      if (options.limit === undefined) return { keys }
+      const listComplete = matching.length <= options.limit
+      return {
+        ...(listComplete ? {} : { cursor: names.at(-1) }),
+        keys,
+        listComplete,
+      }
     },
     async put(key, value, options = {}) {
       const expiresAt = options.ttl === undefined ? undefined : Date.now() + options.ttl
@@ -381,9 +410,28 @@ export function cloudflareKv(namespace: cloudflareKv.Namespace): State {
     async get(key) {
       return namespace.get(key)
     },
+    async getMany(keys) {
+      const batches = Array.from({ length: Math.ceil(keys.length / 100) }, (_, index) =>
+        keys.slice(index * 100, (index + 1) * 100),
+      )
+      const results = await Promise.all(batches.map((batch) => namespace.get(batch)))
+      return new Map(results.flatMap((result) => [...result]))
+    },
     async list(options = {}) {
+      if (options.limit !== undefined) {
+        const result = await namespace.list({
+          ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
+          limit: Math.min(options.limit, 1_000),
+          ...(options.prefix === undefined ? {} : { prefix: options.prefix }),
+        })
+        return {
+          ...(result.cursor === undefined ? {} : { cursor: result.cursor }),
+          keys: result.keys.map(({ name }) => ({ name })),
+          listComplete: result.list_complete,
+        }
+      }
       const keys: { name: string }[] = []
-      let cursor: string | undefined
+      let cursor = options.cursor
 
       for (;;) {
         const result = await namespace.list(
@@ -419,8 +467,12 @@ export declare namespace cloudflareKv {
     delete(key: string): Promise<void>
     /** Gets a text value. */
     get(key: string): Promise<null | string>
+    /** Gets a batch of text values. */
+    get(keys: string[]): Promise<Map<string, null | string>>
     /** Lists keys. */
     list(options?: {
+      /** Maximum keys to return. */
+      limit?: number | undefined
       /** Restrict results to keys with this prefix. */
       prefix?: string | undefined
       /** Continue from a previous page. */
@@ -487,14 +539,24 @@ function durableObjectStorage(storage: durableObject.Storage): State {
       return (await durableObjectRead(storage, key, await storage.get(key)))?.value ?? null
     },
     async list(options = {}) {
-      const values = await storage.list<unknown>(options)
+      const values = await storage.list<unknown>({
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+        ...(options.prefix === undefined ? {} : { prefix: options.prefix }),
+        ...(options.cursor === undefined ? {} : { startAfter: options.cursor }),
+      })
       const keys: { name: string }[] = []
 
       for (const [key, value] of values) {
         if (await durableObjectRead(storage, key, value)) keys.push({ name: key })
       }
 
-      return { keys }
+      if (options.limit === undefined) return { keys }
+      const listComplete = values.size < options.limit
+      return {
+        ...(listComplete ? {} : { cursor: [...values.keys()].at(-1) }),
+        keys,
+        listComplete,
+      }
     },
     async put(key, value, options = {}) {
       if (options.ttl !== undefined && options.ttl <= 0) {
@@ -640,7 +702,10 @@ export async function memoize<value>(
     })
 
   if (!noCache) {
-    const raw = await store.get(key)
+    const raw = await Timeout.run(() => store.get(key), {
+      error: new MemoizeTimeoutError(flightTimeout),
+      timeout: flightTimeout,
+    })
     // Old cache entries used ambiguous untagged bigint strings. Refresh them
     // instead of guessing whether a matching string was originally a bigint.
     if (raw?.startsWith(jsonCodecPrefix)) {
@@ -652,7 +717,9 @@ export async function memoize<value>(
     }
   }
 
-  const flights = flightsFor(store)
+  // Request wrappers isolate flights: sharing a request-owned Promise across
+  // Cloudflare invocations leaks its I/O context into the follower request.
+  const flights = flightsFor(options.store)
   const existing = flights.get(key)
   if (existing) return existing as Promise<value>
 

package/src/internal/Tidx.test.ts

@@ -112,22 +112,73 @@ describe('providerFailure', () => {
   })
 })
 
-describe('responseFailure', () => {
-  test('classifies failed 200 bodies without consuming the response', async () => {
-    const response = Response.json({ error: 'secret upstream detail', ok: false })
+describe('inspectResponse', () => {
+  test('classifies failed 200 bodies and replays their exact bytes', async () => {
+    const payload = '{"error":"secret upstream detail","ok":false}'
+    const response = new Response(payload)
 
-    expect(await Tidx.responseFailure(response)).toEqual({
+    const inspection = await Tidx.inspectResponse(response)
+
+    expect(inspection.failure).toEqual({
       failure: 'payload',
       id: 'tidx',
       operation: 'query',
     })
-    expect(await response.json()).toEqual({ error: 'secret upstream detail', ok: false })
+    expect(await new Response(inspection.body).text()).toBe(payload)
+  })
+
+  test('ignores successful 200 bodies and replays their exact bytes', async () => {
+    const payload = '{"ok":true,"rows":[[1]]}'
+    const response = new Response(payload)
+
+    const inspection = await Tidx.inspectResponse(response)
+
+    expect(inspection.failure).toBeUndefined()
+    expect(await new Response(inspection.body).text()).toBe(payload)
   })
 
-  test('ignores successful 200 bodies', async () => {
-    const response = Response.json({ ok: true })
+  test('bounds a single oversized chunk and replays every byte', async () => {
+    const encoder = new TextEncoder()
+    const chunks = [new Uint8Array(128 * 1_024), encoder.encode('"]]}')]
+    let pulls = 0
+    const response = new Response(
+      new ReadableStream({
+        pull(controller) {
+          const chunk = chunks[pulls]
+          pulls += 1
+          if (chunk) controller.enqueue(chunk)
+          else controller.close()
+        },
+      }),
+    )
 
-    expect(await Tidx.responseFailure(response)).toBeUndefined()
+    const inspection = await Tidx.inspectResponse(response)
+
+    expect(inspection.failure).toBeUndefined()
+    const reader = inspection.body!.getReader()
+    const first = await reader.read()
+    expect(first.value?.byteLength).toBe(64 * 1_024)
+    const replayedChunks = [first.value!]
+    for (;;) {
+      const read = await reader.read()
+      if (read.done) break
+      replayedChunks.push(read.value)
+    }
+    const replayed = new Uint8Array(
+      replayedChunks.reduce((total, chunk) => total + chunk.byteLength, 0),
+    )
+    let replayedOffset = 0
+    for (const chunk of replayedChunks) {
+      replayed.set(chunk, replayedOffset)
+      replayedOffset += chunk.byteLength
+    }
+    const expected = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.byteLength, 0))
+    let offset = 0
+    for (const chunk of chunks) {
+      expected.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+    expect(replayed).toEqual(expected)
   })
 })
 

package/src/internal/Tidx.ts

@@ -258,20 +258,92 @@ export function providerFailure(cause: unknown): Log.ProviderFailure {
   return { ...base, failure: 'unknown' }
 }
 
-/** Returns bounded failure metadata when a TIDX response represents a failed query. */
-export async function responseFailure(
-  response: Response,
-): Promise<Log.ProviderFailure | undefined> {
-  if (!response.ok) return providerFailure(response)
-
-  // Parsing is observational; clone the response so the raw route can return its body unchanged.
-  const body: unknown = await response
-    .clone()
-    .json()
-    .catch(() => undefined)
-  if (typeof body === 'object' && body !== null && 'ok' in body && body.ok === true)
-    return undefined
-  return { failure: 'payload', id: 'tidx', operation: 'query' }
+const maxResponseInspectionBytes = 64 * 1_024
+
+/** Inspects a bounded TIDX response prefix and returns its exact replayable body. */
+export async function inspectResponse(response: Response): Promise<inspectResponse.Result> {
+  if (!response.ok) return { body: response.body, failure: providerFailure(response) }
+
+  const contentLength = Number(response.headers.get('content-length'))
+  if (Number.isFinite(contentLength) && contentLength > maxResponseInspectionBytes)
+    return { body: response.body }
+  if (!response.body)
+    return {
+      body: null,
+      failure: { failure: 'payload', id: 'tidx', operation: 'query' },
+    }
+
+  const reader = response.body.getReader()
+  const chunks: Uint8Array<ArrayBuffer>[] = []
+  let remainder: Uint8Array<ArrayBuffer> | undefined
+  let size = 0
+  let complete = false
+  while (size <= maxResponseInspectionBytes) {
+    const read = await reader.read()
+    if (read.done) {
+      complete = true
+      break
+    }
+    const remaining = maxResponseInspectionBytes - size
+    if (read.value.byteLength > remaining) {
+      if (remaining > 0) chunks.push(read.value.slice(0, remaining))
+      remainder = read.value.subarray(remaining)
+      size += remaining
+      break
+    }
+    chunks.push(read.value)
+    size += read.value.byteLength
+  }
+
+  let index = 0
+  const body = new ReadableStream<Uint8Array<ArrayBuffer>>({
+    cancel: (reason) => reader.cancel(reason),
+    async pull(controller) {
+      const chunk = chunks[index]
+      if (chunk) {
+        index += 1
+        controller.enqueue(chunk)
+        return
+      }
+      if (remainder) {
+        controller.enqueue(remainder)
+        remainder = undefined
+        return
+      }
+      const read = await reader.read()
+      if (read.done) controller.close()
+      else controller.enqueue(read.value)
+    },
+  })
+  if (!complete) return { body }
+
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  const parsed: unknown = (() => {
+    try {
+      return JSON.parse(new TextDecoder().decode(bytes)) as unknown
+    } catch {
+      return undefined
+    }
+  })()
+  if (typeof parsed === 'object' && parsed !== null && 'ok' in parsed && parsed.ok === true)
+    return { body }
+  return {
+    body,
+    failure: { failure: 'payload', id: 'tidx', operation: 'query' },
+  }
+}
+
+export declare namespace inspectResponse {
+  /** Bounded inspection result with the exact upstream body bytes. */
+  type Result = {
+    body: ReadableStream<Uint8Array<ArrayBuffer>> | null
+    failure?: Log.ProviderFailure | undefined
+  }
 }
 
 /** Whether a TIDX response is a deterministic rejection of the caller's query. */

package/src/internal/Timing.test.ts

@@ -19,4 +19,81 @@ describe('middleware', () => {
     expect(timing?.includes('example.work;dur=')).toMatchInlineSnapshot(`true`)
     expect(timing?.includes('request;dur=')).toMatchInlineSnapshot(`true`)
   })
+
+  test('appends outer timings without replacing app timings', () => {
+    const response = new Response('ok', { headers: { 'Server-Timing': 'request;dur=10' } })
+
+    expect(
+      Timing.append(response, [
+        { duration: 2.25, name: 'edge rate limit' },
+        { duration: 12.5, name: 'worker' },
+      ]),
+    ).toBe(response)
+    expect(response.headers.get('server-timing')).toBe(
+      'request;dur=10, edge_rate_limit;dur=2.3, worker;dur=12.5',
+    )
+  })
+
+  test('merges timings seeded before the app receives the request', async () => {
+    const app = new Hono<{ Variables: Timing.Variables }>()
+    app.use('*', Timing.middleware())
+    app.get('/', (c) => c.text('ok'))
+    const request = new Request('http://localhost/')
+    Timing.seed(request, {
+      active: [{ name: 'worker', start: performance.now() }],
+      metrics: [{ duration: 3, name: 'edge_rate_limit' }],
+    })
+
+    const response = await app.fetch(request)
+
+    expect(response.headers.get('server-timing')).toContain('edge_rate_limit;dur=3.0')
+    expect(response.headers.get('server-timing')).toContain('request;dur=')
+    expect(response.headers.get('server-timing')).toContain('worker;dur=')
+  })
+
+  test('accumulates repeated work under one server timing metric', async () => {
+    vi.useFakeTimers()
+    try {
+      const app = new Hono<{ Variables: Timing.Variables }>()
+      app.use('*', Timing.middleware())
+      app.get('/', async (c) => {
+        await Timing.sum(c, 'page_work', () => vi.advanceTimersByTime(20))
+        await Timing.sum(c, 'page_work', () => vi.advanceTimersByTime(5))
+        return c.text('ok')
+      })
+
+      const response = await app.request('/')
+      const timing = response.headers.get('server-timing')
+
+      expect(timing?.match(/page_work/g)).toHaveLength(1)
+      expect(timing).toContain('page_work;dur=25.0')
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('counts overlapping work once', async () => {
+    vi.useFakeTimers()
+    try {
+      const app = new Hono<{ Variables: Timing.Variables }>()
+      app.use('*', Timing.middleware())
+      app.get('/', async (c) => {
+        const releases: (() => void)[] = []
+        const work = () => new Promise<void>((resolve) => releases.push(resolve))
+        const pending = [Timing.sum(c, 'parallel_work', work), Timing.sum(c, 'parallel_work', work)]
+        vi.advanceTimersByTime(20)
+        for (const release of releases) release()
+        await Promise.all(pending)
+        return c.text('ok')
+      })
+
+      const response = await app.request('/')
+      const timing = response.headers.get('server-timing')
+
+      expect(timing?.match(/parallel_work/g)).toHaveLength(1)
+      expect(timing).toContain('parallel_work;dur=20.0')
+    } finally {
+      vi.useRealTimers()
+    }
+  })
 })

package/src/internal/Timing.ts

@@ -4,6 +4,8 @@ import type { Context, MiddlewareHandler } from 'hono'
 export type Variables = {
   /** Operations that have started but not finished. */
   activeTimings?: Active[] | undefined
+  /** State used to collapse overlapping samples of one logical operation. */
+  timingSums?: Map<string, Sum> | undefined
   /** Metrics emitted in the `Server-Timing` response header. */
   serverTiming?: Metric[] | undefined
 }
@@ -29,26 +31,63 @@ export type Active = {
   start: number
 }
 
+/** Request-scoped state for one overlap-aware accumulated metric. */
+export type Sum = {
+  /** Number of currently overlapping samples. */
+  active: number
+  /** Start of the current uninterrupted interval. */
+  start: number
+}
+
+/** Timings started by an outer runtime before the Hono app receives a request. */
+export type Seed = {
+  /** Operations still running when request middleware begins. */
+  active?: readonly Active[] | undefined
+  /** Operations already completed before request middleware begins. */
+  metrics?: readonly Metric[] | undefined
+}
+
+const requestSeeds = new WeakMap<Request, Seed>()
+
+/** Seeds timings collected by an outer runtime onto the same request object. */
+export function seed(request: Request, value: Seed): void {
+  requestSeeds.set(request, value)
+}
+
 /** Adds a `Server-Timing` header with total request duration. */
 export function middleware<
   environment extends Environment = Environment,
 >(): MiddlewareHandler<environment> {
   return async (c, next) => {
-    const active: Active[] = []
-    const metrics: Metric[] = []
+    const seeded = requestSeeds.get(c.req.raw)
+    requestSeeds.delete(c.req.raw)
+    const outerActive = [...(seeded?.active ?? [])]
+    const active: Active[] = [...outerActive]
+    const metrics: Metric[] = [...(seeded?.metrics ?? [])]
     c.set('activeTimings', active)
     c.set('serverTiming', metrics)
+    c.set('timingSums', new Map())
 
     const start = performance.now()
     await next()
     metrics.push({ duration: performance.now() - start, name: 'request' })
-
-    const value = format(metrics)
-    const existing = c.res.headers.get('Server-Timing')
-    c.res.headers.set('Server-Timing', existing ? `${existing}, ${value}` : value)
+    for (const timing of outerActive) {
+      active.splice(active.indexOf(timing), 1)
+      metrics.push({ duration: performance.now() - timing.start, name: timing.name })
+    }
+    append(c.res, metrics)
   }
 }
 
+/** Appends metrics to a response's `Server-Timing` header and returns it. */
+export function append(response: Response, metrics: readonly Metric[]): Response {
+  if (metrics.length === 0) return response
+  const value = format(metrics)
+  const existing = response.headers.get('Server-Timing')
+  response.headers.set('Server-Timing', existing ? `${existing}, ${value}` : value)
+  return response
+}
+
 /** Measures one async operation and adds it to the current request timings. */
 export async function time<environment extends Environment, value>(
   c: Context<environment>,
@@ -67,6 +106,44 @@ export async function time<environment extends Environment, value>(
   }
 }
 
+/**
+ * Measures async work and accumulates its wall-clock union under one metric
+ * name. Sequential samples add up while overlapping samples count only once,
+ * keeping repeated page and parallel chain work bounded and latency-shaped.
+ */
+export async function sum<environment extends Environment, value>(
+  c: Context<environment>,
+  name: string,
+  fn: () => Promise<value> | value,
+) {
+  const start = performance.now()
+  const active = { name, start }
+  c.get('activeTimings')?.push(active)
+  const sums = c.get('timingSums') as Map<string, Sum> | undefined
+  let sum = sums?.get(name)
+  if (!sum && sums) {
+    sum = { active: 0, start }
+    sums.set(name, sum)
+  }
+  if (sum) {
+    if (sum.active === 0) sum.start = start
+    sum.active++
+  }
+  try {
+    return await fn()
+  } finally {
+    const activeTimings = c.get('activeTimings')
+    if (activeTimings) activeTimings.splice(activeTimings.indexOf(active), 1)
+    const metrics = c.get('serverTiming') as Metric[] | undefined
+    if (!sum || --sum.active === 0) {
+      const duration = performance.now() - (sum?.start ?? start)
+      const existing = metrics?.find((metric) => metric.name === name)
+      if (existing) existing.duration += duration
+      else metrics?.push({ duration, name })
+    }
+  }
+}
+
 function format(metrics: readonly Metric[]) {
   return metrics
     .map((metric) => `${name(metric.name)};dur=${metric.duration.toFixed(1)}`)