tapimo 0.6.0 → 0.7.1

package/src/internal/Log.ts

@@ -17,6 +17,8 @@ export type Variables = {
   providerFailure?: Entry['provider'] | undefined
   /** Redacted provider failures when multiple upstream adapters fail. */
   providerFailures?: Entry['providerFailures'] | undefined
+  /** Bounded JSON-RPC failure metadata recorded by a composed RPC handler. */
+  rpcResponse?: Entry['rpc'] | undefined
 }
 
 /** Hono environment shape used by the request logger. */
@@ -71,7 +73,7 @@ export type Entry = {
   errorCode?: string | undefined
   /** Bounded funding provider attempts made while serving the request. */
   fundingProviderAttempts?: readonly FundingProviderAttempt[] | undefined
-  /** Log level derived from the response status: 5xx `error`, 4xx `warn`, else `info`. */
+  /** Log level: 5xx `error`; 4xx or JSON-RPC failure `warn`; otherwise `info`. */
   level: Level
   /** Request method. */
   method: string
@@ -121,7 +123,16 @@ export type Entry = {
   requestId: string
   /** Matched handler path (bounded cardinality), e.g. `/v1/tokens/:address`; `/*` when a middleware (e.g. an edge-cache hit) short-circuited routing. */
   route: string
-  /** Response status code. */
+  /** JSON-RPC failures returned in an otherwise successful HTTP response. */
+  rpc?: {
+    /** Numeric JSON-RPC error code when every failed response shares one code. */
+    code?: number | undefined
+    /** Stable application error code from `error.data.code`, when shared by every failed response. */
+    dataCode?: string | undefined
+    /** Number of failed responses in the single or batch JSON-RPC response. */
+    errors: number
+  }
+  /** HTTP response status code. JSON-RPC failures retain their protocol-native `200`. */
   status: number
   /** Upstream operation durations in milliseconds, from the request's Server-Timing metrics (e.g. RPC and TIDX calls). */
   timings?: Record<string, number> | undefined
@@ -138,8 +149,9 @@ export type Emit = (entry: Entry) => Promise<void> | void
  *
  * The entry derives everything from state other layers already produce —
  * `requestId`, the auth principal, `RateLimit-*` headers, Server-Timing
- * metrics, the `errorCode` recorded by `Response.error`, and the edge-cache
- * hit marker — so handlers never log per-request lines themselves.
+ * metrics, the `errorCode` recorded by `Response.error`, JSON-RPC response
+ * errors, and the edge-cache hit marker, so handlers never log per-request
+ * lines themselves.
  */
 export function middleware<environment extends Environment = Environment>(
   options: middleware.Options = {},
@@ -164,6 +176,7 @@ export function middleware<environment extends Environment = Environment>(
       | undefined
     const provider = c.get('providerFailure' as never) as Entry['provider']
     const providerFailures = c.get('providerFailures' as never) as Entry['providerFailures']
+    const rpc = c.get('rpcResponse' as never) as Entry['rpc']
 
     // The `request` total metric duplicates `duration` (measured here, one
     // layer further out), so only operation timings are kept.
@@ -193,7 +206,12 @@ export function middleware<environment extends Environment = Environment>(
       duration: round(duration),
       ...(errorCode === undefined ? {} : { errorCode }),
       ...(fundingProviderAttempts === undefined ? {} : { fundingProviderAttempts }),
-      level: status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info',
+      level:
+        status >= 500 || rpcServerError(rpc?.code)
+          ? 'error'
+          : status >= 400 || rpc
+            ? 'warn'
+            : 'info',
       method: c.req.method,
       path: url.pathname,
       ...(principal?.payment === undefined ? {} : { payment: principal.payment.reason }),
@@ -220,6 +238,7 @@ export function middleware<environment extends Environment = Environment>(
       ...(rateLimit === undefined ? {} : { rateLimit }),
       requestId: c.get('requestId' as never) as string,
       route: c.req.routePath,
+      ...(rpc === undefined ? {} : { rpc }),
       status,
       ...(timings === undefined ? {} : { timings }),
     })
@@ -238,6 +257,51 @@ export function middleware<environment extends Environment = Environment>(
   }
 }
 
+const rpcDataCode = /^[a-z][a-z0-9_]{0,63}$/
+
+/** Extracts bounded error metadata from an already-parsed JSON-RPC response. */
+export function rpcErrors(body: unknown): Entry['rpc'] {
+  const values = Array.isArray(body) ? body : [body]
+  const errors = values.flatMap((value) => {
+    if (!value || typeof value !== 'object') return []
+    const record = value as Record<string, unknown>
+    if (record['jsonrpc'] !== '2.0' || !record['error'] || typeof record['error'] !== 'object')
+      return []
+    const error = record['error'] as Record<string, unknown>
+    if (
+      !Number.isInteger(error['code']) ||
+      Number(error['code']) < -2_147_483_648 ||
+      Number(error['code']) > 2_147_483_647
+    )
+      return []
+    const data = error['data']
+    const dataCode_value =
+      data && typeof data === 'object' ? (data as Record<string, unknown>)['code'] : undefined
+    const dataCode = typeof dataCode_value === 'string' ? dataCode_value : undefined
+    return [
+      {
+        code: error['code'] as number,
+        ...(dataCode && rpcDataCode.test(dataCode) ? { dataCode } : {}),
+      },
+    ]
+  })
+  if (errors.length === 0) return undefined
+
+  const codes = new Set(errors.map((error) => error.code))
+  const dataCodes = new Set(errors.map((error) => error.dataCode).filter(Boolean))
+  return {
+    ...(codes.size === 1 ? { code: errors[0]!.code } : {}),
+    ...(dataCodes.size === 1 && errors.every((error) => error.dataCode !== undefined)
+      ? { dataCode: errors[0]!.dataCode }
+      : {}),
+    errors: Math.min(errors.length, 65_535),
+  }
+}
+
+function rpcServerError(code: number | undefined) {
+  return code === -32603 || (code !== undefined && code >= -32099 && code <= -32000)
+}
+
 export declare namespace middleware {
   /** Options for the request logger middleware. */
   type Options = {

package/src/internal/MetricSink.test.ts

@@ -10,6 +10,61 @@ type MetricEvent = {
 }
 
 describe('requests', () => {
+  test('records JSON-RPC errors with bounded code tags', () => {
+    const events: MetricEvent[] = []
+    const metrics = Metrics.from({
+      count(name, value, tags) {
+        events.push({ name, tags, type: 'count', value })
+      },
+      flush() {},
+      gauge() {},
+      histogram() {},
+    })
+    const record = MetricSink.requests(metrics)
+
+    record({
+      duration: 10,
+      level: 'warn',
+      method: 'POST',
+      path: '/rpc/relay',
+      requestId: 'request_private',
+      route: '/rpc/relay',
+      rpc: { code: -32602, dataCode: 'billing_required', errors: 2 },
+      status: 200,
+    })
+
+    expect(events).toMatchInlineSnapshot(`
+      [
+        {
+          "name": "http_response_count",
+          "tags": {
+            "cache": "miss",
+            "method": "POST",
+            "principal_environment": "none",
+            "principal_type": "unknown",
+            "route": "/rpc/relay",
+            "status": 200,
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "rpc_response_error_count",
+          "tags": {
+            "cache": "miss",
+            "method": "POST",
+            "principal_environment": "none",
+            "principal_type": "unknown",
+            "route": "/rpc/relay",
+            "rpc_error_code": "-32602",
+          },
+          "type": "count",
+          "value": 2,
+        },
+      ]
+    `)
+  })
+
   test('records bounded funding provider attempts without caller data', () => {
     const events: MetricEvent[] = []
     let flushes = 0

package/src/internal/MetricSink.ts

@@ -85,6 +85,12 @@ export function requests(backend: Metrics): RequestSink {
     })
     backend.histogram('http_response_duration_ms', entry.duration, tags)
 
+    if (entry.rpc)
+      backend.count('rpc_response_error_count', entry.rpc.errors, {
+        ...tags,
+        rpc_error_code: rpcErrorCode(entry.rpc.code),
+      })
+
     if (entry.status === 429 || entry.errorCode === 'rate_limit_exceeded')
       backend.count('http_rate_limit_count', 1, {
         ...tags,
@@ -109,6 +115,14 @@ export function requests(backend: Metrics): RequestSink {
   }
 }
 
+/** Maps arbitrary upstream JSON-RPC codes into bounded metric tags. */
+function rpcErrorCode(code: number | undefined) {
+  if (code === undefined) return 'mixed'
+  if ([-32700, -32600, -32601, -32602, -32603].includes(code)) return String(code)
+  if (code >= -32099 && code <= -32000) return 'server'
+  return 'other'
+}
+
 function routeTags(entry: Log.Entry): RouteTags {
   return {
     cache: entry.cache ?? 'miss',

package/src/internal/Response.test.ts

@@ -0,0 +1,28 @@
+import { Hono } from 'hono'
+
+import * as Response from './Response.js'
+
+describe('upstream', () => {
+  test('returns a stable message and preserves the cause on context', async () => {
+    const app = new Hono()
+    const cause = new Error('provider URL contains secret credentials')
+    let captured: Error | undefined
+
+    app.use(async (c, next) => {
+      await next()
+      captured = c.error
+    })
+    app.get('/', (c) => Response.upstream(c, cause))
+
+    const response = await app.request('/')
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "upstream_error",
+          "message": "Upstream service could not complete the request",
+        },
+      }
+    `)
+    expect(captured).toBe(cause)
+  })
+})

package/src/internal/Response.ts

@@ -39,12 +39,20 @@ export function unsupportedChainId(c: Context, chainId: number, supported: Itera
 }
 
 /**
- * Maps an unexpected upstream failure to a 502 JSON error envelope. Rethrows
- * non-`Error` causes so the global handler can convert them.
+ * Maps an unexpected upstream failure to a stable 502 JSON error envelope.
+ * Preserves `Error` causes for reporting and rethrows non-`Error` causes.
  */
 export function upstream(c: Context, cause: unknown) {
-  if (cause instanceof Error)
-    return error(c, { code: 'upstream_error', message: cause.message, status: 502 })
+  if (cause instanceof Error) {
+    // Preserve the original error for error-reporting middleware without
+    // exposing provider URLs, payloads, or credentials in the response.
+    c.error = cause
+    return error(c, {
+      code: 'upstream_error',
+      message: 'Upstream service could not complete the request',
+      status: 502,
+    })
+  }
   throw cause
 }
 

package/src/internal/Schema.test.ts

@@ -32,3 +32,16 @@ describe('ChainIdQuery', () => {
     expect(Schema.ChainIdQuery.parse('42431')).toMatchInlineSnapshot(`42431`)
   })
 })
+
+describe('timestampBound', () => {
+  test('normalizes RFC 3339 offsets to UTC', () => {
+    const bound = Schema.timestampBound('swaps', 'from')
+
+    expect(bound.parse('2026-06-04T12:00:00+05:30')).toMatchInlineSnapshot(
+      `"2026-06-04T06:30:00.000Z"`,
+    )
+    expect(bound.parse('2026-06-04T12:00:00-05:00')).toMatchInlineSnapshot(
+      `"2026-06-04T17:00:00.000Z"`,
+    )
+  })
+})

package/src/internal/Schema.ts

@@ -495,16 +495,23 @@ export function blockNumberBound(noun: string, bound: 'from' | 'to') {
 
 /**
  * Optional inclusive ISO-8601 timestamp bound query parameter (`timestamp.from`
- * / `timestamp.to`). `noun` is the resource being listed (e.g. `transfers`).
+ * / `timestamp.to`), normalized to UTC. `noun` is the listed resource.
  */
 export function timestampBound(noun: string, bound: 'from' | 'to') {
   const direction = bound === 'from' ? 'at or after' : 'at or before'
-  return z.optional(z.iso.datetime({ offset: true })).check(
-    z.describe(`Only include ${noun} ${direction} this ISO 8601 timestamp.`),
-    z.meta({
-      examples: [bound === 'from' ? '2024-01-01T00:00:00Z' : '2024-12-31T23:59:59Z'],
-    }),
-  )
+  return z
+    .optional(
+      z.pipe(
+        z.iso.datetime({ offset: true }),
+        z.transform((value) => new Date(value).toISOString()),
+      ),
+    )
+    .check(
+      z.describe(`Only include ${noun} ${direction} this ISO 8601 timestamp.`),
+      z.meta({
+        examples: [bound === 'from' ? '2024-01-01T00:00:00Z' : '2024-12-31T23:59:59Z'],
+      }),
+    )
 }
 
 /**