tapimo 0.7.1 → 0.8.0

package/src/internal/Log.test-d.ts

@@ -1,21 +1,54 @@
-import type * as FundingQuotes from './FundingQuotes.js'
+import type * as FundingProvider from './funding/Provider.js'
 import type * as Log from './Log.js'
 
-test('bounds funding provider metric identifiers', () => {
-  const provider = null as never as FundingQuotes.ProviderId
+test('accepts deployment-supplied funding provider identifiers', () => {
+  const provider = null as never as FundingProvider.ProviderId
   const id: Log.FundingProviderAttempt['id'] = provider
-  const provider_roundTrip: FundingQuotes.ProviderId = id
+  const provider_roundTrip: FundingProvider.ProviderId = id
   void provider_roundTrip
 
   const attempt = {
     durationMs: 1,
     id: 'relay',
-    operation: 'quote/v2',
+    operation: 'getQuote',
     outcome: 'available',
   } satisfies Log.FundingProviderAttempt
   void attempt
 
-  // @ts-expect-error arbitrary provider names would create unbounded metric tags
-  const invalid: Log.FundingProviderAttempt['id'] = 'user-controlled-provider'
-  void invalid
+  const custom: Log.FundingProviderAttempt['id'] = 'custom-bridge'
+  void custom
+})
+
+test('bounds sponsorship diagnostics', () => {
+  const reasons = [
+    'api_key_forbidden',
+    'api_key_required',
+    'billing_past_due',
+    'billing_required',
+    'chain_id_unsupported',
+    'fee_token_unsupported',
+    'internal_error',
+    'production_api_key_required',
+    'spend_limit_exceeded',
+    'tx_fee_limit_exceeded',
+  ] as const satisfies readonly Log.SponsorshipReason[]
+  expectTypeOf<(typeof reasons)[number]>().toEqualTypeOf<Log.SponsorshipReason>()
+
+  const sponsorship = {
+    chainId: 4217,
+    method: 'eth_signRawTransaction',
+    outcome: 'rejected',
+    payloadHash: `0x${'aa'.repeat(32)}`,
+    reason: 'production_api_key_required',
+    rejections: 1,
+  } satisfies Log.Sponsorship
+  void sponsorship
+
+  // @ts-expect-error arbitrary method names would create unbounded log values
+  const method: Log.SponsorshipMethod = 'wallet_userControlled'
+  void method
+
+  // @ts-expect-error arbitrary reasons would create unbounded log values
+  const reason: Log.SponsorshipReason = 'user_controlled_reason'
+  void reason
 })

package/src/internal/Log.test.ts

@@ -1,5 +1,6 @@
 import { Hono } from 'hono'
 import { requestId } from 'hono/request-id'
+import type { Hex } from 'ox'
 
 import * as Log from './Log.js'
 import * as Response from './Response.js'
@@ -50,12 +51,64 @@ describe('middleware', () => {
     `)
   })
 
+  test('includes a failed optional funding transfer count', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.get('/v1/funding/transfers', (c) => {
+      c.set('fundingTransferCountFailed', true)
+      return c.json({ data: [], nextCursor: null }, 200)
+    })
+
+    await api.request('/v1/funding/transfers?include=totalCount')
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "fundingTransferCountFailed": true,
+        "level": "info",
+        "method": "GET",
+        "path": "/v1/funding/transfers",
+        "query": "include=totalCount",
+        "route": "/v1/funding/transfers",
+        "status": 200,
+      }
+    `)
+  })
+
+  test('keeps the longest duration when a timing name repeats', async () => {
+    vi.useFakeTimers()
+    try {
+      const entries: Log.Entry[] = []
+      const api = app({ emit: (entry) => void entries.push(entry) })
+      api.get('/', async (c) => {
+        await Timing.time(c, 'transactions', () => vi.advanceTimersByTime(20))
+        await Timing.time(c, 'transactions', () => vi.advanceTimersByTime(5))
+        return c.json({ ok: true }, 200)
+      })
+
+      await api.request('/')
+
+      expect(entries[0]?.timings).toMatchInlineSnapshot(`
+        {
+          "transactions": 20,
+        }
+      `)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   test('includes the caller principal, never the raw token', async () => {
     const entries: Log.Entry[] = []
     const api = app({ emit: (entry) => void entries.push(entry) })
     api.use('*', async (c, next) => {
       c.set('principal', {
-        apiKey: { environment: 'production', id: 'key_1', orgId: 'org_1', scopes: ['data:read'] },
+        apiKey: {
+          allowedIps: [],
+          environment: 'production',
+          id: 'key_1',
+          orgId: 'org_1',
+          scopes: ['data:read'],
+        },
         environment: 'production',
         id: 'key_1',
         orgId: 'org_1',
@@ -174,6 +227,92 @@ describe('middleware', () => {
     `)
   })
 
+  test('includes bounded sponsorship rejection diagnostics', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.post('/rpc/sponsor', (c) => {
+      const body = {
+        error: {
+          code: -32602,
+          data: { code: 'production_api_key_required' },
+          message: 'Sponsorship rejected.',
+        },
+        id: 1,
+        jsonrpc: '2.0',
+      }
+      c.set('rpcResponse', Log.rpcErrors(body))
+      c.set('sponsorship', {
+        chainId: 4217,
+        method: 'eth_signRawTransaction',
+        outcome: 'rejected',
+        payloadHash: `0x${'aa'.repeat(32)}` as Hex.Hex,
+        reason: 'production_api_key_required',
+        rejections: 1,
+      })
+      return c.json(body)
+    })
+
+    await api.request('/rpc/sponsor', { method: 'POST' })
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "level": "warn",
+        "method": "POST",
+        "path": "/rpc/sponsor",
+        "route": "/rpc/sponsor",
+        "rpc": {
+          "code": -32602,
+          "dataCode": "production_api_key_required",
+          "errors": 1,
+        },
+        "sponsorship": {
+          "chainId": 4217,
+          "method": "eth_signRawTransaction",
+          "outcome": "rejected",
+          "payloadHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "reason": "production_api_key_required",
+          "rejections": 1,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('records an MPP relay failure returned with HTTP 200', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.post('/v1/mpp/validate', (c) => {
+      c.set('mpp', {
+        chainId: 4217,
+        errorCode: 'unknown',
+        feePayer: false,
+        operation: 'verify',
+        outcome: 'failure',
+      })
+      return c.json({ success: false }, 200)
+    })
+
+    const response = await api.request('/v1/mpp/validate', { method: 'POST' })
+
+    expect(response.status).toBe(200)
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "level": "error",
+        "method": "POST",
+        "mpp": {
+          "chainId": 4217,
+          "errorCode": "unknown",
+          "feePayer": false,
+          "operation": "verify",
+          "outcome": "failure",
+        },
+        "path": "/v1/mpp/validate",
+        "route": "/v1/mpp/validate",
+        "status": 200,
+      }
+    `)
+  })
+
   test('logs JSON-RPC server errors at error level', async () => {
     const entries: Log.Entry[] = []
     const api = app({ emit: (entry) => void entries.push(entry) })
@@ -196,7 +335,24 @@ describe('middleware', () => {
     expect(entries[0]?.level).toBe('error')
   })
 
-  test('counts batch JSON-RPC errors without retaining mixed codes', async () => {
+  test('logs internal sponsorship failures at error level', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.post('/rpc/sponsor', (c) => {
+      c.set('sponsorship', {
+        internalErrors: 1,
+        outcome: 'rejected',
+        rejections: 1,
+      })
+      return c.json({ id: 1, jsonrpc: '2.0', result: {} })
+    })
+
+    await api.request('/rpc/sponsor', { method: 'POST' })
+
+    expect(entries[0]?.level).toBe('error')
+  })
+
+  test('escalates mixed JSON-RPC batches containing server errors', async () => {
     const entries: Log.Entry[] = []
     const api = app({ emit: (entry) => void entries.push(entry) })
     api.post('/rpc/relay', (c) => {
@@ -217,12 +373,43 @@ describe('middleware', () => {
 
     expect(stable(entries[0]!)).toMatchInlineSnapshot(`
       {
-        "level": "warn",
+        "level": "error",
         "method": "POST",
         "path": "/rpc/relay",
         "route": "/rpc/relay",
         "rpc": {
           "errors": 2,
+          "serverErrors": 1,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('keeps routine node rejections out of server-error alerts', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.post('/rpc/relay', (c) => {
+      const body = {
+        error: { code: -32_000, message: 'insufficient funds' },
+        id: 1,
+        jsonrpc: '2.0',
+      }
+      c.set('rpcResponse', Log.rpcErrors(body))
+      return c.json(body)
+    })
+
+    await api.request('/rpc/relay', { method: 'POST' })
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "level": "warn",
+        "method": "POST",
+        "path": "/rpc/relay",
+        "route": "/rpc/relay",
+        "rpc": {
+          "code": -32000,
+          "errors": 1,
         },
         "status": 200,
       }
@@ -237,7 +424,7 @@ describe('middleware', () => {
         code: 'UNAUTHORIZED',
         failure: 'http',
         id: 'relay',
-        operation: 'quote/v2',
+        operation: 'getQuote',
         status: 401,
       })
       return Response.error(c, {
@@ -259,7 +446,7 @@ describe('middleware', () => {
           "code": "UNAUTHORIZED",
           "failure": "http",
           "id": "relay",
-          "operation": "quote/v2",
+          "operation": "getQuote",
           "status": 401,
         },
         "route": "/provider",
@@ -276,14 +463,14 @@ describe('middleware', () => {
         {
           durationMs: 12.5,
           id: 'relay',
-          operation: 'quote/v2',
+          operation: 'getQuote',
           outcome: 'available',
         },
         {
           durationMs: 25,
           failure: 'timeout',
           id: 'across',
-          operation: 'swap/approval',
+          operation: 'getQuote',
           outcome: 'failed',
         },
       ])
@@ -298,14 +485,14 @@ describe('middleware', () => {
           {
             "durationMs": 12.5,
             "id": "relay",
-            "operation": "quote/v2",
+            "operation": "getQuote",
             "outcome": "available",
           },
           {
             "durationMs": 25,
             "failure": "timeout",
             "id": "across",
-            "operation": "swap/approval",
+            "operation": "getQuote",
             "outcome": "failed",
           },
         ],

package/src/internal/Log.ts

@@ -1,24 +1,42 @@
 import type { MiddlewareHandler } from 'hono'
 import type { RequestIdVariables } from 'hono/request-id'
+import type { Hex } from 'ox'
 
 import * as ApiKey from '../ApiKey.js'
 import type * as Auth from './Auth.js'
 import type * as EdgeCache from './EdgeCache.js'
-import type * as FundingQuotes from './FundingQuotes.js'
+import type * as FundingProvider from './funding/Provider.js'
 import type * as Timing from './Timing.js'
 
 /** Hono variables read by the request logger and written by other layers. */
 export type Variables = {
+  /** Whether the original request exception was already reported. */
+  errorCaptured?: boolean | undefined
   /** Stable error code recorded by `Response.error` for the request log entry. */
   errorCode?: string | undefined
+  /** Bounded MPP relay outcome emitted by the credential routes. */
+  mpp?: Entry['mpp'] | undefined
   /** Bounded outcomes for funding providers attempted by the request. */
   fundingProviderAttempts?: Entry['fundingProviderAttempts'] | undefined
-  /** Redacted provider failure details recorded by an upstream adapter. */
+  /** Whether the optional funding transfer count query failed. */
+  fundingTransferCountFailed?: true | undefined
+  /** Redacted provider failure details recorded by an upstream provider. */
   providerFailure?: Entry['provider'] | undefined
-  /** Redacted provider failures when multiple upstream adapters fail. */
+  /** Redacted provider failures when multiple upstream providers fail. */
   providerFailures?: Entry['providerFailures'] | undefined
   /** Bounded JSON-RPC failure metadata recorded by a composed RPC handler. */
   rpcResponse?: Entry['rpc'] | undefined
+  /** Bounded sponsorship rejection details recorded by the relay app. */
+  sponsorship?: Sponsorship | undefined
+}
+
+type ErrorMetadata = {
+  /** Bounded provider attempts attached to a caught error. */
+  fundingProviderAttempts?: Entry['fundingProviderAttempts'] | undefined
+  /** Redacted first provider failure attached to a caught error. */
+  providerFailure?: Entry['provider'] | undefined
+  /** Redacted provider failures attached to a caught error. */
+  providerFailures?: Entry['providerFailures'] | undefined
 }
 
 /** Hono environment shape used by the request logger. */
@@ -37,10 +55,12 @@ export type Level = 'error' | 'info' | 'warn'
 
 /** Redacted upstream provider failure details. */
 export type ProviderFailure = {
+  /** Chain whose upstream request failed, when the request selected one. */
+  chainId?: number | undefined
   /** Stable provider error code, when one is safe to retain. */
   code?: string | undefined
   /** Failure boundary that rejected the provider request. */
-  failure: 'http' | 'network' | 'payload' | 'rate_limit' | 'timeout' | 'unknown'
+  failure: 'http' | 'network' | 'payload' | 'query' | 'rate_limit' | 'timeout' | 'unknown'
   /** Provider identifier. */
   id: string
   /** Provider operation identifier. */
@@ -56,23 +76,65 @@ export type FundingProviderAttempt = {
   /** Failure class, present only when the provider attempt failed. */
   failure?: ProviderFailure['failure'] | undefined
   /** Provider identifier. */
-  id: FundingQuotes.ProviderId
+  id: FundingProvider.ProviderId
   /** Stable upstream operation identifier. */
-  operation: string
+  operation: FundingProvider.ProviderOperation
   /** Provider attempt outcome. */
   outcome: 'available' | 'failed' | 'thin' | 'unavailable'
 }
 
+/** JSON-RPC methods that can request managed sponsorship. */
+export type SponsorshipMethod =
+  | 'eth_fillTransaction'
+  | 'eth_sendRawTransaction'
+  | 'eth_sendRawTransactionSync'
+  | 'eth_signRawTransaction'
+
+/** Stable client error codes for sponsorship rejections. */
+export type SponsorshipReason =
+  | 'api_key_forbidden'
+  | 'api_key_required'
+  | 'billing_past_due'
+  | 'billing_required'
+  | 'chain_id_unsupported'
+  | 'fee_token_unsupported'
+  | 'internal_error'
+  | 'production_api_key_required'
+  | 'spend_limit_exceeded'
+  | 'tx_fee_limit_exceeded'
+
+/** Bounded diagnostics for sponsorship rejections in one JSON-RPC request. */
+export type Sponsorship = {
+  /** Common target chain, absent when rejected batch items disagree or are invalid. */
+  chainId?: number | undefined
+  /** Number of internal sponsorship failures, capped at 65,535; absent when zero. */
+  internalErrors?: number | undefined
+  /** Common sponsorship method, absent when rejected batch items use different methods. */
+  method?: SponsorshipMethod | undefined
+  /** Sponsorship request outcome. */
+  outcome: 'rejected'
+  /** Keccak256 of the caller's raw transaction, present only for a single-request body. */
+  payloadHash?: Hex.Hex | undefined
+  /** Common client error code, absent when rejected batch items have different codes. */
+  reason?: SponsorshipReason | undefined
+  /** Number of sponsorship policy rejections, capped at 65,535. */
+  rejections: number
+}
+
 /** One canonical request log entry. */
 export type Entry = {
   /** `'hit'` when the edge response cache served the request without reaching the origin handlers. */
   cache?: 'hit' | undefined
   /** Total request duration in milliseconds. */
   duration: number
+  /** Whether the original request exception was already reported. */
+  errorCaptured?: boolean | undefined
   /** Stable error code when the response is a JSON error envelope (e.g. `not_found`, `api_key_invalid`). */
   errorCode?: string | undefined
   /** Bounded funding provider attempts made while serving the request. */
   fundingProviderAttempts?: readonly FundingProviderAttempt[] | undefined
+  /** Whether the optional funding transfer count query failed. */
+  fundingTransferCountFailed?: true | undefined
   /** Log level: 5xx `error`; 4xx or JSON-RPC failure `warn`; otherwise `info`. */
   level: Level
   /** Request method. */
@@ -81,6 +143,21 @@ export type Entry = {
   path: string
   /** MPP payment reason when the request was paid per call. */
   payment?: Auth.Payment['reason'] | undefined
+  /** Bounded outcome for an MPP relay operation. */
+  mpp?: {
+    /** Resolved Tempo chain selected by the credential. */
+    chainId: number
+    /** Stable relay failure code, absent when the operation succeeded. */
+    errorCode?: string | undefined
+    /** Idempotency claim outcome for broadcast operations. */
+    idempotency?: 'claimed' | 'pending' | 'replay' | undefined
+    /** Whether a fee payer was supplied for the credential. */
+    feePayer: boolean
+    /** Relay route operation. */
+    operation: 'broadcast' | 'verify'
+    /** Relay operation outcome, independent of the HTTP status. */
+    outcome: 'failure' | 'success'
+  }
   /** Caller identity. Raw API-key tokens and the super admin secret are never logged. */
   principal?:
     | {
@@ -100,9 +177,9 @@ export type Entry = {
         type: 'api_key' | 'public' | 'session' | 'super_admin'
       }
     | undefined
-  /** Redacted upstream provider failure details, when an adapter request fails. */
+  /** Redacted upstream provider failure details, when a provider request fails. */
   provider?: ProviderFailure | undefined
-  /** Redacted failures for every provider when multiple adapters fail. */
+  /** Redacted failures for every provider when multiple providers fail. */
   providerFailures?: readonly ProviderFailure[] | undefined
   /** Raw query string (no leading `?`) with API-key tokens redacted, when present. */
   query?: string | undefined
@@ -131,10 +208,14 @@ export type Entry = {
     dataCode?: string | undefined
     /** Number of failed responses in the single or batch JSON-RPC response. */
     errors: number
+    /** Number of JSON-RPC server errors, capped at 65,535; absent when zero. */
+    serverErrors?: number | undefined
   }
+  /** Bounded sponsorship rejection diagnostics, without request or response bodies. */
+  sponsorship?: Sponsorship | undefined
   /** 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). */
+  /** Longest upstream operation duration per Server-Timing name, in milliseconds (e.g. RPC and TIDX calls). */
   timings?: Record<string, number> | undefined
 }
 
@@ -169,14 +250,23 @@ 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 principal = c.get('principal' as never) as Auth.Principal | undefined
+    const errorCaptured = c.get('errorCaptured' as never) as boolean | undefined
     const errorCode = c.get('errorCode' as never) as string | undefined
-    const fundingProviderAttempts = c.get('fundingProviderAttempts' as never) as
-      | Entry['fundingProviderAttempts']
+    const fundingProviderAttempts =
+      error?.fundingProviderAttempts ??
+      (c.get('fundingProviderAttempts' as never) as Entry['fundingProviderAttempts'] | undefined)
+    const fundingTransferCountFailed = c.get('fundingTransferCountFailed' as never) as
+      | true
       | undefined
-    const provider = c.get('providerFailure' as never) as Entry['provider']
-    const providerFailures = c.get('providerFailures' as never) as Entry['providerFailures']
+    const mpp = c.get('mpp' as never) as Entry['mpp']
+    const provider =
+      error?.providerFailure ?? (c.get('providerFailure' as never) as Entry['provider'])
+    const providerFailures =
+      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.
@@ -184,7 +274,14 @@ export function middleware<environment extends Environment = Environment>(
       (metric) => metric.name !== 'request',
     )
     const timings = metrics?.length
-      ? Object.fromEntries(metrics.map((metric) => [metric.name, round(metric.duration)]))
+      ? Object.fromEntries(
+          metrics.reduce((result, metric) => {
+            const duration = round(metric.duration)
+            const existing = result.get(metric.name)
+            if (existing === undefined || duration > existing) result.set(metric.name, duration)
+            return result
+          }, new Map<string, number>()),
+        )
       : undefined
 
     const rateLimit = (() => {
@@ -204,15 +301,22 @@ export function middleware<environment extends Environment = Environment>(
     const result = fn({
       ...(c.get('edgeCacheStatus' as never) === 'hit' ? { cache: 'hit' as const } : {}),
       duration: round(duration),
+      ...(errorCaptured === undefined ? {} : { errorCaptured }),
       ...(errorCode === undefined ? {} : { errorCode }),
       ...(fundingProviderAttempts === undefined ? {} : { fundingProviderAttempts }),
+      ...(fundingTransferCountFailed === undefined ? {} : { fundingTransferCountFailed }),
       level:
-        status >= 500 || rpcServerError(rpc?.code)
+        status >= 500 ||
+        rpcServerError(rpc?.code) ||
+        (rpc?.serverErrors ?? 0) > 0 ||
+        (sponsorship?.internalErrors ?? 0) > 0 ||
+        mpp?.errorCode === 'unknown'
           ? 'error'
-          : status >= 400 || rpc
+          : status >= 400 || rpc || sponsorship
             ? 'warn'
             : 'info',
       method: c.req.method,
+      ...(mpp === undefined ? {} : { mpp }),
       path: url.pathname,
       ...(principal?.payment === undefined ? {} : { payment: principal.payment.reason }),
       ...(principal === undefined
@@ -239,6 +343,7 @@ export function middleware<environment extends Environment = Environment>(
       requestId: c.get('requestId' as never) as string,
       route: c.req.routePath,
       ...(rpc === undefined ? {} : { rpc }),
+      ...(sponsorship === undefined ? {} : { sponsorship }),
       status,
       ...(timings === undefined ? {} : { timings }),
     })
@@ -289,17 +394,19 @@ export function rpcErrors(body: unknown): Entry['rpc'] {
 
   const codes = new Set(errors.map((error) => error.code))
   const dataCodes = new Set(errors.map((error) => error.dataCode).filter(Boolean))
+  const serverErrors = errors.filter((error) => rpcServerError(error.code)).length
   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),
+    ...(serverErrors === 0 ? {} : { serverErrors: Math.min(serverErrors, 65_535) }),
   }
 }
 
 function rpcServerError(code: number | undefined) {
-  return code === -32603 || (code !== undefined && code >= -32099 && code <= -32000)
+  return code === -32603
 }
 
 export declare namespace middleware {