tapimo 0.11.0 → 0.13.0

package/src/internal/Fetch.ts

@@ -0,0 +1,56 @@
+import * as Timeout from './Timeout.js'
+
+/** Installs the default outbound fetch timeout once for this runtime. */
+export function install(): void {
+  if (isInstalled(globalThis.fetch)) return
+
+  const fetch = withTimeout(globalThis.fetch.bind(globalThis), { timeout: Timeout.duration })
+  Object.defineProperty(fetch, timeoutMarker, { value: true })
+  globalThis.fetch = fetch
+}
+
+/** Adds a default maximum duration to fetch calls that do not carry a signal. */
+export function withTimeout(
+  fetch: typeof globalThis.fetch,
+  options: withTimeout.Options,
+): typeof globalThis.fetch {
+  return ((input, init) => {
+    const signal = resolveSignal(input, { init, timeout: options.timeout })
+    return fetch(input, { ...init, signal })
+  }) as typeof globalThis.fetch
+}
+
+/** Resolves a caller signal or creates the default fetch deadline signal. */
+export function resolveSignal(
+  input: Parameters<typeof globalThis.fetch>[0],
+  options: resolveSignal.Options,
+): AbortSignal {
+  return (
+    options.init?.signal ??
+    (input instanceof Request ? input.signal : Timeout.signal({ timeout: options.timeout }))
+  )
+}
+
+export declare namespace resolveSignal {
+  /** Options for {@link resolveSignal}. */
+  type Options = {
+    /** Optional fetch initialization carrying a caller signal. */
+    init?: Parameters<typeof globalThis.fetch>[1]
+    /** Default maximum duration in milliseconds. */
+    timeout: number
+  }
+}
+
+export declare namespace withTimeout {
+  /** Options for {@link withTimeout}. */
+  type Options = {
+    /** Maximum fetch duration in milliseconds. */
+    timeout: number
+  }
+}
+
+const timeoutMarker = Symbol.for('tempo.api.fetch.timeout')
+
+function isInstalled(fetch: typeof globalThis.fetch): boolean {
+  return timeoutMarker in fetch
+}

package/src/internal/Log.test.ts

@@ -457,6 +457,27 @@ describe('middleware', () => {
     `)
   })
 
+  test('preserves the request error and unfinished stages', async () => {
+    const entries: Log.Entry[] = []
+    const causes: Error[] = []
+    const api = app({
+      emit: (entry, cause) => {
+        entries.push(entry)
+        if (cause) causes.push(cause)
+      },
+    })
+    const cause = new Error('Memoized cache-miss flight timed out after 15000ms.')
+    api.get('/activities', (c) => {
+      void Timing.time(c, 'transaction_activity_mpp', () => new Promise(() => {}))
+      return Response.upstream(c, cause)
+    })
+
+    await api.request('/activities')
+
+    expect(causes[0]).toBe(cause)
+    expect(entries[0]?.pendingTimings?.['transaction_activity_mpp']).toBeGreaterThanOrEqual(0)
+  })
+
   test('includes bounded funding provider attempts', async () => {
     const entries: Log.Entry[] = []
     const api = app({ emit: (entry) => void entries.push(entry) })

package/src/internal/Log.ts

@@ -151,6 +151,8 @@ export type Entry = {
   path: string
   /** MPP payment reason when the request was paid per call. */
   payment?: Auth.Payment['reason'] | undefined
+  /** Operations still running when the response completed, with elapsed milliseconds. */
+  pendingTimings?: Record<string, number> | undefined
   /** Bounded outcome for an MPP relay operation. */
   mpp?: {
     /** Resolved Tempo chain selected by the credential. */
@@ -228,7 +230,7 @@ export type Entry = {
 }
 
 /** Sink receiving one {@link Entry} per request. */
-export type Emit = (entry: Entry) => Promise<void> | void
+export type Emit = (entry: Entry, cause?: Error) => Promise<void> | void
 
 /**
  * Emits one canonical structured log entry per request, after the response is
@@ -258,7 +260,8 @@ export function middleware<environment extends Environment = Environment>(
     // Hono cannot resolve variable types through the generic `environment`,
     // so shared-variable reads are cast from the environment contract above
     // (the same pattern EdgeCache uses for its cross-layer reads).
-    const error = c.error as ErrorMetadata | undefined
+    const cause = c.error
+    const error = cause as (Error & ErrorMetadata) | undefined
     const principal = c.get('principal' as never) as Auth.Principal | undefined
     const errorCaptured = c.get('errorCaptured' as never) as boolean | undefined
     const chainId = c.get('chainId' as never) as number | undefined
@@ -279,7 +282,6 @@ export function middleware<environment extends Environment = Environment>(
       error?.providerFailures ?? (c.get('providerFailures' as never) as Entry['providerFailures'])
     const rpc = c.get('rpcResponse' as never) as Entry['rpc']
     const sponsorship = c.get('sponsorship' as never) as Entry['sponsorship']
-
     // The `request` total metric duplicates `duration` (measured here, one
     // layer further out), so only operation timings are kept.
     const metrics = (c.get('serverTiming' as never) as Timing.Metric[] | undefined)?.filter(
@@ -295,6 +297,17 @@ export function middleware<environment extends Environment = Environment>(
           }, new Map<string, number>()),
         )
       : undefined
+    const activeTimings = c.get('activeTimings' as never) as Timing.Active[] | undefined
+    const pendingTimings = activeTimings?.length
+      ? Object.fromEntries(
+          activeTimings.reduce((result, timing) => {
+            const duration = round(performance.now() - timing.start)
+            const existing = result.get(timing.name)
+            if (existing === undefined || duration > existing) result.set(timing.name, duration)
+            return result
+          }, new Map<string, number>()),
+        )
+      : undefined
 
     const rateLimit = (() => {
       const limit = c.res.headers.get('RateLimit-Limit')
@@ -310,7 +323,7 @@ export function middleware<environment extends Environment = Environment>(
       }
     })()
 
-    const result = fn({
+    const entry = {
       ...(c.get('edgeCacheStatus' as never) === 'hit' ? { cache: 'hit' as const } : {}),
       ...(chainId === undefined ? {} : { chainId }),
       duration: round(duration),
@@ -333,6 +346,7 @@ export function middleware<environment extends Environment = Environment>(
       ...(mpp === undefined ? {} : { mpp }),
       path: url.pathname,
       ...(principal?.payment === undefined ? {} : { payment: principal.payment.reason }),
+      ...(pendingTimings === undefined ? {} : { pendingTimings }),
       ...(principal === undefined
         ? {}
         : {
@@ -360,7 +374,8 @@ export function middleware<environment extends Environment = Environment>(
       ...(sponsorship === undefined ? {} : { sponsorship }),
       status,
       ...(timings === undefined ? {} : { timings }),
-    })
+    } satisfies Entry
+    const result = fn(entry, cause)
 
     if (result instanceof Promise) {
       const promise = result.catch((error) => console.error('request log sink failed', error))

package/src/internal/OpenApi.ts

@@ -1,6 +1,13 @@
 import type { Context, Env, MiddlewareHandler, ValidationTargets } from 'hono'
 import type { HasRequiredKeys } from 'hono/utils/types'
-import { resolver, type ResponsesWithResolver, validator } from 'hono-openapi'
+import {
+  describeRoute as core_describeRoute,
+  type DescribeRouteOptions,
+  resolver,
+  type ResponsesWithResolver,
+  uniqueSymbol,
+  validator,
+} from 'hono-openapi'
 import * as z from 'zod/mini'
 import * as Response from './Response.js'
 import * as Schema from './Schema.js'
@@ -41,7 +48,6 @@ const schemaOptions = { options: { override: recoverExamples, unrepresentable: '
 // re-exports because `uniqueSymbol` is a `unique symbol` whose identity is
 // lost when copied through a `const` declaration.
 export {
-  describeRoute,
   type HandlerUniqueProperty,
   resolver,
   type ResponsesWithResolver,
@@ -49,12 +55,53 @@ export {
   validator,
 } from 'hono-openapi'
 
+function cloneResponseContainers(spec: DescribeRouteOptions): DescribeRouteOptions {
+  if (!spec.responses) return spec
+  return {
+    ...spec,
+    responses: Object.fromEntries(
+      Object.entries(spec.responses).map(([status, response]) => [
+        status,
+        !response || !('content' in response)
+          ? response
+          : {
+              ...response,
+              content: Object.fromEntries(
+                Object.entries(response.content ?? {}).map(([mediaType, media]) => [
+                  mediaType,
+                  { ...media },
+                ]),
+              ),
+            },
+      ]),
+    ),
+  }
+}
+
+/** Describes a route without allowing spec generation to mutate reusable response definitions. */
+export function describeRoute(spec: DescribeRouteOptions): MiddlewareHandler {
+  const handler = core_describeRoute(spec)
+  Object.defineProperty(handler, uniqueSymbol, {
+    get: () => ({ spec: cloneResponseContainers(spec) }),
+  })
+  return handler
+}
+
+/** Emits a named OpenAPI component and uses its `$ref` wherever the schema appears. */
+export function component<const schema extends z.ZodMiniType>(
+  schema: schema,
+  name: string,
+): schema {
+  const cloned = schema.clone()
+  z.globalRegistry.add(cloned, { ...z.globalRegistry.get(schema), ref: name })
+  return cloned as schema
+}
+
 /**
  * Standard machine-readable `error.code` values per status, shared API-wide.
  * The reference enumerates `error.code` to these so generated clients narrow it
- * to a literal union instead of an open `string`. 400 and 404 vary per
- * operation; the values here are the API-wide supersets, narrowable per route
- * via the `codes` override in {@link responses.Options}.
+ * to a literal union instead of an open `string`. The values here are shared
+ * defaults; operation-specific codes are supplied through {@link responses.Options}.
  */
 export const errorCodes = {
   400: [
@@ -80,7 +127,7 @@ export const errorCodes = {
     'api_key_malformed',
   ],
   401: ['api_key_missing', 'api_key_invalid', 'unauthorized'],
-  403: ['api_key_forbidden', 'api_key_ip_forbidden', 'limit_exceeded'],
+  403: ['api_key_forbidden', 'api_key_ip_forbidden', 'forbidden'],
   404: [
     'not_found',
     'token_not_found',
@@ -101,6 +148,7 @@ export const errorCodes = {
   500: ['internal_error'],
   501: ['billing_unconfigured'],
   502: ['upstream_error'],
+  504: ['request_timeout'],
 } as const satisfies Record<number, readonly [string, ...string[]]>
 
 /**
@@ -164,11 +212,79 @@ export const rateLimitHeaders = {
 /** Representative `requestId` used in error-body examples. */
 const exampleRequestId = '0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9'
 
-/** Builds the `application/json` content for a standard error response: the enumerated-code envelope plus an example body. */
-function errorContent(codes: readonly [string, ...string[]] | undefined, message: string) {
+const standardErrorNames = {
+  400: 'InvalidRequestError',
+  401: 'AuthenticationError',
+  403: 'ForbiddenError',
+  404: 'ResourceNotFoundError',
+  429: 'RateLimitError',
+  500: 'InternalError',
+  501: 'NotImplementedError',
+  502: 'UpstreamError',
+  504: 'RequestTimeoutError',
+} as const satisfies Record<keyof typeof errorCodes, string>
+
+const reservedErrorNames = new Set<string>(Object.values(standardErrorNames))
+const errorSchemas = new Map<string, z.ZodMiniType>()
+
+function errorName(status: number, codes: readonly string[]) {
+  const standard = errorCodes[status as keyof typeof errorCodes]
+  if (
+    standard &&
+    standard.length === codes.length &&
+    [...standard].sort().every((code, index) => code === codes[index])
+  )
+    return standardErrorNames[status as keyof typeof standardErrorNames]
+  const name = `${codes
+    .map((code) =>
+      code
+        .split('_')
+        .map((part) => `${part[0]?.toUpperCase()}${part.slice(1)}`)
+        .join(''),
+    )
+    .join('Or')}Error`
+  if (reservedErrorNames.has(name)) return `${name.slice(0, -'Error'.length)}${status}Error`
+  return name
+}
+
+function errorSchema(status: number, codes: readonly [string, ...string[]] | undefined) {
+  const defaults = errorCodes[status as keyof typeof errorCodes]
+  if (!codes && !defaults) {
+    const cached = errorSchemas.get('*')
+    if (cached) return cached
+    const schema = component(Schema.errorResponse(), 'ErrorResponse')
+    errorSchemas.set('*', schema)
+    return schema
+  }
+  const normalized = [...(codes ?? defaults ?? [])].sort() as [string, ...string[]]
+  const key = normalized.join('\0')
+  const cached = errorSchemas.get(key)
+  if (cached) return cached
+  const schema = component(Schema.errorResponse(normalized), errorName(status, normalized))
+  errorSchemas.set(key, schema)
+  return schema
+}
+
+function mergeErrorCodes(
+  status: number,
+  codes: readonly string[] | undefined,
+): readonly [string, ...string[]] | undefined {
+  if (!codes) return errorCodes[status as keyof typeof errorCodes]
+  if (status !== 400 && status !== 403)
+    return codes.length ? (codes as [string, ...string[]]) : undefined
+  const baseline = status === 400 ? (['api_key_malformed'] as const) : errorCodes[403]
+  return [...new Set([...baseline, ...codes])] as [string, ...string[]]
+}
+
+/** Builds the `application/json` content for a standard error response: the named enumerated-code envelope plus an example body. */
+function errorContent(
+  status: number,
+  codes: readonly [string, ...string[]] | undefined,
+  message: string,
+) {
   return {
     'application/json': {
-      schema: resolver(Schema.errorResponse(codes), schemaOptions),
+      schema: resolver(errorSchema(status, codes), schemaOptions),
       example: { error: { code: codes?.[0] ?? 'error', message }, requestId: exampleRequestId },
     },
   }
@@ -186,32 +302,35 @@ export const paymentChallenge = {
   headers: { 'WWW-Authenticate': headerRef('WwwAuthenticate') },
 } as const
 
-/** Shared `429` rate-limit response, registered as `components.responses.RateLimited`. */
-const rateLimitedResponse = {
-  content: errorContent(errorCodes[429], 'Rate limit exceeded.'),
-  description:
-    'Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead.',
-  headers: { ...rateLimitHeaders },
-}
-
-/** Shared `500` internal-error response, registered as `components.responses.InternalError`. */
-const serverErrorResponse = {
-  content: errorContent(errorCodes[500], 'Internal server error.'),
-  description: 'Internal server error.',
-}
+type ResponseComponentName = 'InternalError' | 'PaymentRequired' | 'RateLimited' | 'RequestTimeout'
 
 /**
  * Reusable responses registered under `components.responses` (see `App.create`)
- * and `$ref`-erenced from operations, so the uniform `402`/`429`/`500` responses
- * are defined once instead of inlined on every operation.
+ * and `$ref`-erenced from operations, so the uniform `402`/`429`/`500`/`504`
+ * responses are defined once instead of inlined on every operation.
  */
-export const responseComponents: ResponsesWithResolver = {
-  InternalError: serverErrorResponse,
-  PaymentRequired: paymentChallenge,
-  RateLimited: rateLimitedResponse,
+export function responseComponents(): ResponsesWithResolver {
+  return {
+    InternalError: {
+      content: errorContent(500, errorCodes[500], 'Internal server error.'),
+      description: 'Internal server error.',
+    },
+    PaymentRequired: paymentChallenge,
+    RateLimited: {
+      content: errorContent(429, errorCodes[429], 'Rate limit exceeded.'),
+      description:
+        'Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead.',
+      headers: { ...rateLimitHeaders },
+    },
+    RequestTimeout: {
+      content: errorContent(504, errorCodes[504], 'Request timed out'),
+      description:
+        'Request timed out. The request did not complete within the 60-second deadline; retry it.',
+    },
+  }
 }
 
-const responseRef = (name: keyof typeof responseComponents) => ({
+const responseRef = (name: ResponseComponentName) => ({
   $ref: `#/components/responses/${name}`,
 })
 
@@ -232,22 +351,24 @@ export function standardError(
 ): ResponsesWithResolver[string] {
   if (status === 429) return responseRef('RateLimited')
   if (status === 500) return responseRef('InternalError')
-  return { content: errorContent(codes ?? errorCodes[status], description), description }
+  if (status === 504) return responseRef('RequestTimeout')
+  return { content: errorContent(status, mergeErrorCodes(status, codes), description), description }
 }
 
 /**
  * Builds an OpenAPI `responses` map with the API's standard error responses
  * pre-filled, plus the success response (with rate-limit headers):
  *
- * - `400` invalid request, `401` missing/invalid key, `429` rate limited,
- *   `500` internal error, and `502` upstream failure on every operation;
- * - `403`/`404`/`409`/`412`/`413`/`415` only when an `errors` entry is set.
+ * - `400` invalid request, `401` missing/invalid key, `403` forbidden, `429`
+ *   rate limited, `500` internal error, `502` upstream failure, and `504`
+ *   request timeout on every operation;
+ * - `404`/`409`/`412`/`413`/`415` only when an `errors` entry is set.
  *
- * `error.code` is enumerated per status from {@link errorCodes}; narrow 400/404
- * to a route's exact codes by passing `{ description, codes }` for that status.
- * `429`/`500` `$ref` the shared {@link responseComponents}. `402` is not emitted
- * here — it is injected per operation from the route's MPP policy during spec
- * generation (see `App.ts`).
+ * `error.code` is enumerated per status from {@link errorCodes}. Operation-level
+ * 400/403 codes merge with shared auth codes; other overrides replace defaults.
+ * The default `429` and `500` `$ref` shared {@link responseComponents}; an exact
+ * operation-level `429` override is emitted inline with the standard headers.
+ * `402` is injected per operation from the route's MPP policy in `App.ts`.
  */
 export function responses<schema extends z.ZodMiniType>(
   options: responses.Options<schema>,
@@ -257,10 +378,11 @@ export function responses<schema extends z.ZodMiniType>(
     const override = errors?.[status as 400]
     const description =
       typeof override === 'string' ? override : (override?.description ?? fallback)
-    const codes =
-      (typeof override === 'object' ? override.codes : undefined) ??
-      errorCodes[status as keyof typeof errorCodes]
-    return { content: errorContent(codes, description), description }
+    const codes = mergeErrorCodes(status, typeof override === 'object' ? override.codes : undefined)
+    return {
+      content: errorContent(status, codes, description),
+      description,
+    }
   }
   return {
     200: {
@@ -279,39 +401,41 @@ export function responses<schema extends z.ZodMiniType>(
     },
     400: error(400, 'Invalid request.'),
     401: error(401, 'Missing or invalid API key.'),
-    ...(errors?.[403] && { 403: error(403, 'Forbidden.') }),
+    403: error(403, 'Forbidden.'),
     ...(errors?.[404] && { 404: error(404, 'Not found.') }),
     ...(errors?.[409] && { 409: error(409, 'Conflict.') }),
     ...(errors?.[412] && { 412: error(412, 'Precondition failed.') }),
     ...(errors?.[413] && { 413: error(413, 'Payload too large.') }),
     ...(errors?.[415] && { 415: error(415, 'Unsupported media type.') }),
-    429: responseRef('RateLimited'),
+    429: errors?.[429]
+      ? { ...error(429, 'Rate limit exceeded.'), headers: { ...rateLimitHeaders } }
+      : responseRef('RateLimited'),
     500: responseRef('InternalError'),
     ...(errors?.[501] && { 501: error(501, 'Not implemented.') }),
     502: error(502, 'Upstream data failure.'),
+    504: responseRef('RequestTimeout'),
   }
 }
 
 export declare namespace responses {
   /**
    * Override for a standard error response: a description string, or an object
-   * adding the exact `codes` that status can return (narrowing the enum).
+   * adding operation codes. Codes replace defaults except shared 400/403 auth codes.
    */
   type ErrorOverride =
     | string
     | {
         /** Human-readable description of the error response. */
         description?: string | undefined
-        /** Exact `error.code` values this status returns for the operation. */
-        codes?: readonly [string, ...string[]] | undefined
+        /** Operation-specific `error.code` values for this status. */
+        codes?: readonly string[] | undefined
       }
 
   /** Options for building a standard OpenAPI responses map. */
   type Options<schema> = {
     /**
-     * Optional overrides for standard error responses (description and/or exact
-     * `error.code` enum). Setting `403`/`404`/`409`/`412`/`413`/`415` also
-     * includes that status in the map.
+     * Optional overrides for standard error responses. Setting
+     * `404`/`409`/`412`/`413`/`415` includes that status in the map.
      */
     errors?:
       | {
@@ -319,7 +443,7 @@ export declare namespace responses {
           400?: ErrorOverride | undefined
           /** Override for the 401 response. */
           401?: ErrorOverride | undefined
-          /** Override for the 403 response. Setting this includes 403 in the map. */
+          /** Add operation-specific 403 codes or override its description. */
           403?: ErrorOverride | undefined
           /** Override for the 404 response. Setting this includes 404 in the map. */
           404?: ErrorOverride | undefined
@@ -331,6 +455,8 @@ export declare namespace responses {
           413?: ErrorOverride | undefined
           /** Override for the 415 response. Setting this includes 415 in the map. */
           415?: ErrorOverride | undefined
+          /** Override the shared 429 response with operation-specific rate-limit codes. */
+          429?: ErrorOverride | undefined
           /** Override for the 501 response. Setting this includes 501 in the map. */
           501?: ErrorOverride | undefined
           /** Override for the 502 response. */

package/src/internal/Response.test.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono'
+import { Tidx } from 'tidx.ts'
 
 import * as Response from './Response.js'
 
@@ -25,4 +26,98 @@ describe('upstream', () => {
     `)
     expect(captured).toBe(cause)
   })
+
+  test('returns a query error when a positional page times out', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Request timeout',
+      new globalThis.Response(null, { status: 408 }),
+    )
+    let captured: Error | undefined
+
+    app.use(async (c, next) => {
+      await next()
+      captured = c.error
+    })
+    app.get('/', (c) => Response.upstream(c, cause, { page: 2 }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "query_invalid",
+          "message": "The requested page timed out. Use cursor pagination for deep traversal.",
+        },
+      }
+    `)
+    expect(captured).toBe(cause)
+  })
+
+  test('returns a query error when a positional page is rejected', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Query rejected',
+      new globalThis.Response(null, { status: 422 }),
+    )
+    let captured: Error | undefined
+
+    app.use(async (c, next) => {
+      await next()
+      captured = c.error
+    })
+    app.get('/', (c) => Response.upstream(c, cause, { page: 584 }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "query_invalid",
+          "message": "The requested page was rejected. Use cursor pagination for deep traversal.",
+        },
+      }
+    `)
+    expect(captured).toBe(cause)
+  })
+
+  test('keeps timeouts without a deep positional page as upstream errors', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Request timeout',
+      new globalThis.Response(null, { status: 408 }),
+    )
+    app.get('/', (c) => Response.upstream(c, cause, { page: undefined }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`502`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "upstream_error",
+          "message": "Upstream service could not complete the request",
+        },
+      }
+    `)
+  })
+
+  test('keeps query rejections without a deep positional page as upstream errors', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Query rejected',
+      new globalThis.Response(null, { status: 422 }),
+    )
+    app.get('/', (c) => Response.upstream(c, cause, { page: undefined }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`502`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "upstream_error",
+          "message": "Upstream service could not complete the request",
+        },
+      }
+    `)
+  })
 })