tapimo 0.0.0 → 0.0.2

package/src/internal/Log.test.ts

@@ -0,0 +1,244 @@
+import { Hono } from 'hono'
+import { requestId } from 'hono/request-id'
+
+import * as Log from './Log.js'
+import * as Response from './Response.js'
+import * as Timing from './Timing.js'
+
+function app(options: { emit: Log.Emit }) {
+  const app = new Hono<Log.Environment>()
+  app.use('*', requestId())
+  app.use('*', Log.middleware(options))
+  app.use('*', Timing.middleware())
+  return app
+}
+
+function stable(entry: Log.Entry) {
+  const { duration: _duration, requestId: _requestId, timings: _timings, ...rest } = entry
+  return rest
+}
+
+describe('middleware', () => {
+  test('emits one canonical entry per request', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.get('/things/:id', async (c) => {
+      await Timing.time(c, 'rpc.example', () => Promise.resolve())
+      return c.json({ ok: true }, 200)
+    })
+
+    await api.request('/things/42?chainId=4217')
+
+    expect(entries.length).toMatchInlineSnapshot(`1`)
+    const entry = entries[0]!
+    expect(typeof entry.duration).toMatchInlineSnapshot(`"number"`)
+    expect(typeof entry.requestId).toMatchInlineSnapshot(`"string"`)
+    expect(Object.keys(entry.timings ?? {})).toMatchInlineSnapshot(`
+      [
+        "rpc.example",
+      ]
+    `)
+    expect(stable(entry)).toMatchInlineSnapshot(`
+      {
+        "level": "info",
+        "method": "GET",
+        "path": "/things/42",
+        "query": "chainId=4217",
+        "route": "/things/:id",
+        "status": 200,
+      }
+    `)
+  })
+
+  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'] },
+        environment: 'production',
+        id: 'key_1',
+        orgId: 'org_1',
+        type: 'api_key',
+      })
+      await next()
+    })
+    api.get('/secure', (c) => c.json({ ok: true }, 200))
+
+    const token = `tempo:sk:${'a'.repeat(48)}`
+    await api.request(`/secure?apiKey=${token}`)
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "level": "info",
+        "method": "GET",
+        "path": "/secure",
+        "principal": {
+          "environment": "production",
+          "id": "key_1",
+          "orgId": "org_1",
+          "type": "api_key",
+        },
+        "query": "apiKey=tempo:sk:…",
+        "route": "/secure",
+        "status": 200,
+      }
+    `)
+  })
+
+  test('includes the MPP payment reason for paid calls', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.use('*', async (c, next) => {
+      c.set('principal', {
+        id: 'ip:203.0.113.7',
+        payment: { payer: '0xpayer', reason: 'public_over_quota', type: 'mpp' },
+        type: 'public',
+      })
+      await next()
+    })
+    api.get('/paid', (c) => c.json({ ok: true }, 200))
+
+    await api.request('/paid')
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "level": "info",
+        "method": "GET",
+        "path": "/paid",
+        "payment": "public_over_quota",
+        "principal": {
+          "id": "ip:203.0.113.7",
+          "type": "public",
+        },
+        "route": "/paid",
+        "status": 200,
+      }
+    `)
+  })
+
+  test('records the error code and warn level for error envelopes', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.get('/missing', (c) =>
+      Response.error(c, { code: 'not_found', message: 'Route not found', status: 404 }),
+    )
+
+    await api.request('/missing')
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "errorCode": "not_found",
+        "level": "warn",
+        "method": "GET",
+        "path": "/missing",
+        "route": "/missing",
+        "status": 404,
+      }
+    `)
+  })
+
+  test('logs thrown errors at error level', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.onError((_, c) => c.json({ error: true }, 500))
+    api.get('/boom', () => {
+      throw new Error('boom')
+    })
+
+    await api.request('/boom')
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "level": "error",
+        "method": "GET",
+        "path": "/boom",
+        "route": "/boom",
+        "status": 500,
+      }
+    `)
+  })
+
+  test('parses rate limit state from response headers', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.get('/limited', (c) => {
+      c.header('RateLimit-Limit', '100')
+      c.header('RateLimit-Remaining', '37')
+      c.header('RateLimit-Reset', '1710000000')
+      c.header('RateLimit-Scope', 'data:read')
+      return c.json({ ok: true }, 200)
+    })
+
+    await api.request('/limited')
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "level": "info",
+        "method": "GET",
+        "path": "/limited",
+        "rateLimit": {
+          "limit": 100,
+          "remaining": 37,
+          "reset": 1710000000,
+          "scope": "data:read",
+        },
+        "route": "/limited",
+        "status": 200,
+      }
+    `)
+  })
+
+  test('marks edge-cache hits', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    // Simulate the edge-cache layer answering before routing runs.
+    api.use('*', async (c) => {
+      c.set('edgeCacheStatus', 'hit')
+      return c.json({ cached: true }, 200)
+    })
+
+    await api.request('/anything')
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "cache": "hit",
+        "level": "info",
+        "method": "GET",
+        "path": "/anything",
+        "route": "/*",
+        "status": 200,
+      }
+    `)
+  })
+})
+
+describe('emit', () => {
+  test('routes entries to the level-matched console method', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const base = {
+        duration: 1,
+        method: 'GET',
+        path: '/',
+        requestId: 'req',
+        route: '/',
+      } as const
+
+      Log.emit({ ...base, level: 'info', status: 200 })
+      Log.emit({ ...base, level: 'warn', status: 404 })
+      Log.emit({ ...base, level: 'error', status: 500 })
+
+      expect(log.mock.calls.length).toMatchInlineSnapshot(`1`)
+      expect(warn.mock.calls.length).toMatchInlineSnapshot(`1`)
+      expect(error.mock.calls.length).toMatchInlineSnapshot(`1`)
+      expect(log.mock.calls[0]?.[0]).toMatchObject({ level: 'info', status: 200 })
+    } finally {
+      error.mockRestore()
+      log.mockRestore()
+      warn.mockRestore()
+    }
+  })
+})

package/src/internal/Log.ts

@@ -0,0 +1,216 @@
+import type { MiddlewareHandler } from 'hono'
+import type { RequestIdVariables } from 'hono/request-id'
+
+import * as ApiKey from '../ApiKey.js'
+import type * as Auth from './Auth.js'
+import type * as EdgeCache from './EdgeCache.js'
+import type * as Timing from './Timing.js'
+
+/** Hono variables read by the request logger and written by other layers. */
+export type Variables = {
+  /** Stable error code recorded by `Response.error` for the request log entry. */
+  errorCode?: string | undefined
+}
+
+/** Hono environment shape used by the request logger. */
+export type Environment = {
+  Variables: Variables &
+    EdgeCache.Variables &
+    RequestIdVariables &
+    Timing.Variables & {
+      /** Authenticated or anonymous caller, set by auth middleware. */
+      principal?: Auth.Principal | undefined
+    }
+}
+
+/** Log level, derived from the response status. */
+export type Level = 'error' | 'info' | 'warn'
+
+/** 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
+  /** Stable error code when the response is a JSON error envelope (e.g. `not_found`, `api_key_invalid`). */
+  errorCode?: string | undefined
+  /** Log level derived from the response status: 5xx `error`, 4xx `warn`, else `info`. */
+  level: Level
+  /** Request method. */
+  method: string
+  /** Request pathname. */
+  path: string
+  /** MPP payment reason when the request was paid per call. */
+  payment?: Auth.Payment['reason'] | undefined
+  /** Caller identity. Raw API-key tokens are never logged. */
+  principal?:
+    | {
+        /** Key environment for API-key callers. */
+        environment?: ApiKey.ApiKey['environment'] | undefined
+        /** Principal id: the API key id, or the public quota identity. */
+        id: string
+        /** Owning organization id for API-key callers. */
+        orgId?: string | undefined
+        /** Principal kind. */
+        type: 'api_key' | 'public'
+      }
+    | undefined
+  /** Raw query string (no leading `?`) with API-key tokens redacted, when present. */
+  query?: string | undefined
+  /** Rate limit state from the `RateLimit-*` response headers, when enforced. */
+  rateLimit?:
+    | {
+        /** Quota for the current window. */
+        limit: number
+        /** Requests remaining in the current window. */
+        remaining: number
+        /** Reset timestamp in Unix seconds. */
+        reset?: number | undefined
+        /** Quota bucket scope, when available. */
+        scope?: string | undefined
+      }
+    | undefined
+  /** Request id, also echoed in the `tempo-request-id` response header. */
+  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. */
+  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
+}
+
+/** Sink receiving one {@link Entry} per request. */
+export type Emit = (entry: Entry) => Promise<void> | void
+
+/**
+ * Emits one canonical structured log entry per request, after the response is
+ * written. Register after `requestId()` and before the timing and edge-cache
+ * layers so the entry covers edge-cache hits and includes the Server-Timing
+ * metrics collected inside the request.
+ *
+ * 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.
+ */
+export function middleware<environment extends Environment = Environment>(
+  options: middleware.Options = {},
+): MiddlewareHandler<environment> {
+  const fn = options.emit ?? emit
+  return async (c, next) => {
+    const start = performance.now()
+    await next()
+    const duration = performance.now() - start
+
+    const url = new URL(c.req.url)
+    const status = c.res.status
+    // 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 principal = c.get('principal' as never) as Auth.Principal | undefined
+    const errorCode = c.get('errorCode' as never) as string | undefined
+
+    // 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(
+      (metric) => metric.name !== 'request',
+    )
+    const timings = metrics?.length
+      ? Object.fromEntries(metrics.map((metric) => [metric.name, round(metric.duration)]))
+      : undefined
+
+    const rateLimit = (() => {
+      const limit = c.res.headers.get('RateLimit-Limit')
+      const remaining = c.res.headers.get('RateLimit-Remaining')
+      const reset = c.res.headers.get('RateLimit-Reset')
+      const scope = c.res.headers.get('RateLimit-Scope')
+      if (limit === null || remaining === null) return undefined
+      return {
+        limit: Number(limit),
+        remaining: Number(remaining),
+        ...(reset === null ? {} : { reset: Number(reset) }),
+        ...(scope === null ? {} : { scope }),
+      }
+    })()
+
+    const result = fn({
+      ...(c.get('edgeCacheStatus' as never) === 'hit' ? { cache: 'hit' as const } : {}),
+      duration: round(duration),
+      ...(errorCode === undefined ? {} : { errorCode }),
+      level: status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info',
+      method: c.req.method,
+      path: url.pathname,
+      ...(principal?.payment === undefined ? {} : { payment: principal.payment.reason }),
+      ...(principal === undefined
+        ? {}
+        : {
+            principal: {
+              ...(principal.type === 'api_key' ? { environment: principal.environment } : {}),
+              id: principal.id,
+              ...(principal.type === 'api_key' ? { orgId: principal.orgId } : {}),
+              type: principal.type,
+            },
+          }),
+      // Keys belong in headers, but a confused client may pass one in the
+      // query string; redact defensively before it reaches a log store.
+      ...(url.search.length > 1 ? { query: ApiKey.redact(url.search.slice(1)) } : {}),
+      ...(rateLimit === undefined ? {} : { rateLimit }),
+      requestId: c.get('requestId' as never) as string,
+      route: c.req.routePath,
+      status,
+      ...(timings === undefined ? {} : { timings }),
+    })
+
+    if (result instanceof Promise) {
+      const promise = result.catch((error) => console.error('request log sink failed', error))
+      // Unit tests and non-Worker runtimes do not always provide an execution
+      // context. In Workers, waitUntil keeps async sinks alive without holding
+      // the response open; elsewhere the promise is deliberately fire-and-forget.
+      try {
+        c.executionCtx.waitUntil(promise)
+      } catch {
+        void promise
+      }
+    }
+  }
+}
+
+export declare namespace middleware {
+  /** Options for the request logger middleware. */
+  type Options = {
+    /** Log sink. Defaults to {@link emit}: the level-matched console method, passed the entry as a structured object. */
+    emit?: Emit | undefined
+  }
+}
+
+/**
+ * Default log sink: writes the entry as a structured object through the
+ * console method matching its level. Passing the object (not a pre-serialized
+ * JSON string) lets Cloudflare Workers Logs index the fields for filtering
+ * and querying; Node prints the same object inline on stdout/stderr.
+ */
+export function emit(entry: Entry) {
+  if (entry.level === 'error') console.error(entry)
+  else if (entry.level === 'warn') console.warn(entry)
+  else console.log(entry)
+}
+
+/** Severity ranking used to filter entries below a minimum level. */
+const severity = { error: 2, info: 0, warn: 1 } as const
+
+/**
+ * An {@link Emit} that drops entries below `min` and otherwise delegates to
+ * {@link emit}. `'warn'` keeps warn/error (e.g. production, where the request
+ * metrics sink carries successful-request volume instead of one info log each).
+ */
+export function withMinLevel(min: Level): Emit {
+  return (entry) => {
+    if (severity[entry.level] < severity[min]) return
+    emit(entry)
+  }
+}
+
+function round(value: number) {
+  return Math.round(value * 10) / 10
+}

package/src/internal/MetricSink.ts

@@ -0,0 +1,220 @@
+import type { Metrics } from '../Metrics.js'
+import type * as Webhooks from '../Webhooks.js'
+import type * as Log from './Log.js'
+
+/** Webhook event type, including the synthetic `ping` carried on test envelopes. */
+export type EventType = Webhooks.Envelope['type']
+
+/** Where a delivery attempt originated. */
+export type Trigger = 'manual_retry' | 'ping' | 'queue'
+
+/** Context for one poller tick that the {@link Webhooks.createPoller.Result} omits. */
+export type TickMeta = {
+  /** Chain polled this tick; used when the tick errored before a result existed. */
+  chainId?: number | undefined
+  /** Wall-clock duration of the tick in ms. */
+  durationMs: number
+  /** Whether the tick completed. */
+  outcome: 'error' | 'ok'
+}
+
+/**
+ * A webhook metric event, recorded by the {@link webhooks} sink. The poller
+ * emits `webhook:tick`/`webhook:enqueue` and the delivery path emits
+ * `webhook:delivery`.
+ */
+export type WebhookEvent =
+  | {
+      meta: TickMeta
+      result: Webhooks.createPoller.Result | undefined
+      type: 'webhook:tick'
+    }
+  | {
+      chainId: number
+      durationMs: number
+      eventType: EventType
+      ok: boolean
+      type: 'webhook:enqueue'
+    }
+  | {
+      envelope: Webhooks.Envelope
+      result: Webhooks.Result
+      subscription: Webhooks.Subscription
+      trigger: Trigger
+      type: 'webhook:delivery'
+    }
+
+/** Records request (HTTP) metrics for one request-log entry. Built by {@link requests}. */
+export type RequestSink = (entry: Log.Entry) => void
+
+/** Records webhook reliability metrics. Built by {@link webhooks}. */
+export type WebhookSink = {
+  /** Ships buffered metrics (call once per poller tick / delivery). */
+  flush(): void
+  /** Records one webhook event. */
+  record(event: WebhookEvent): void
+}
+
+/** Low-cardinality tags shared by every HTTP metric, derived from a request log entry. */
+type RouteTags = {
+  cache: 'hit' | 'miss'
+  method: string
+  principal_environment: 'none' | 'production' | 'sandbox'
+  principal_type: 'api_key' | 'public' | 'unknown'
+  route: string
+}
+
+/**
+ * Builds a request (HTTP) metrics sink over `backend`: emits the bounded Worker
+ * metrics derived from one request-log entry, then flushes (one entry == one
+ * request).
+ *
+ * Metric tags deliberately exclude caller ids, organization ids, request ids,
+ * raw paths, and IP-derived identities — those belong in logs or analytics, not
+ * StatsD-style series.
+ */
+export function requests(backend: Metrics): RequestSink {
+  return (entry) => {
+    const tags = routeTags(entry)
+
+    backend.count('http_response_count', 1, {
+      ...tags,
+      ...(entry.errorCode === undefined ? {} : { error_code: entry.errorCode }),
+      ...(entry.payment === undefined ? {} : { payment: entry.payment }),
+      status: entry.status,
+    })
+    backend.histogram('http_response_duration_ms', entry.duration, tags)
+
+    if (entry.status === 429 || entry.errorCode === 'rate_limit_exceeded')
+      backend.count('http_rate_limit_count', 1, {
+        ...tags,
+        rate_limit_scope: entry.rateLimit?.scope ?? 'unknown',
+        status: entry.status,
+      })
+
+    for (const [operation, duration] of Object.entries(entry.timings ?? {}))
+      backend.histogram('upstream_duration_ms', duration, { ...tags, operation })
+
+    backend.flush()
+  }
+}
+
+function routeTags(entry: Log.Entry): RouteTags {
+  return {
+    cache: entry.cache ?? 'miss',
+    method: entry.method,
+    principal_environment: entry.principal?.environment ?? 'none',
+    principal_type: entry.principal?.type ?? 'unknown',
+    route: entry.route,
+  }
+}
+
+/** Bounded attempt-count buckets so the attempt tag never explodes cardinality. */
+type AttemptBucket = '1' | '2' | '3-5' | '6-10' | 'gt10'
+
+/** Low-cardinality delivery destination kind, tagged on `webhook:delivery`. */
+type DestinationType = Webhooks.Subscription['destination']['type']
+
+/** Low-cardinality delivery outcome class derived from an HTTP status / error. */
+type StatusClass = '2xx' | '4xx' | '5xx' | 'network' | 'timeout' | 'unknown' | 'url_rejected'
+
+/**
+ * Builds a webhook delivery-reliability sink over `backend`. Tags stay
+ * low-cardinality (`chain_id`, `event_type`, `destination_type`, `status_class`,
+ * `attempt_bucket`, `outcome`) — never subscription/org/event ids, which belong
+ * in logs or analytics, not StatsD-style series.
+ */
+export function webhooks(backend: Metrics): WebhookSink {
+  return {
+    flush() {
+      backend.flush()
+    },
+    record(event) {
+      switch (event.type) {
+        case 'webhook:tick': {
+          const { meta, result } = event
+          const chain_id = String(result?.chainId ?? meta.chainId ?? 'unknown')
+          backend.count('webhook_poller_tick_count', 1, { chain_id, outcome: meta.outcome })
+          backend.histogram('webhook_poller_tick_duration_ms', meta.durationMs, {
+            chain_id,
+            outcome: meta.outcome,
+          })
+          if (!result) return
+          backend.histogram('webhook_poller_subscription_count', result.subscriptions, { chain_id })
+          backend.count('webhook_poller_scanned_count', result.scanned, { chain_id })
+          backend.gauge('webhook_poller_safe_block', result.safeBlock, { chain_id })
+          backend.count('webhook_poller_dispatch_count', result.dispatched, {
+            chain_id,
+            outcome: 'dispatched',
+          })
+          backend.count('webhook_poller_dispatch_count', result.failed, {
+            chain_id,
+            outcome: 'failed',
+          })
+          return
+        }
+        case 'webhook:enqueue': {
+          const tags = { chain_id: String(event.chainId), event_type: event.eventType }
+          const outcome = event.ok ? 'ok' : 'error'
+          backend.count('webhook_dispatch_enqueue_count', 1, { ...tags, outcome })
+          backend.histogram('webhook_dispatch_enqueue_duration_ms', event.durationMs, {
+            ...tags,
+            outcome,
+          })
+          return
+        }
+        case 'webhook:delivery': {
+          const { envelope, result, subscription } = event
+          const tags = {
+            chain_id: String(envelope.chainId),
+            destination_type: subscription.destination.type satisfies DestinationType,
+            event_type: envelope.type,
+          }
+          const outcome = result.ok ? 'succeeded' : 'failed'
+          backend.count('webhook_delivery_attempt_count', 1, {
+            ...tags,
+            attempt_bucket: attemptBucket(subscription.failureCount + 1),
+            outcome,
+            status_class: statusClass(result),
+            trigger: event.trigger,
+          })
+          if (result.durationMs !== undefined)
+            backend.histogram('webhook_delivery_duration_ms', result.durationMs, {
+              ...tags,
+              outcome,
+            })
+          backend.histogram(
+            'webhook_delivery_queue_latency_ms',
+            Math.max(0, Date.now() - Date.parse(envelope.createdAt)),
+            tags,
+          )
+          return
+        }
+      }
+    },
+  }
+}
+
+/** Buckets a 1-based attempt number into a bounded set of attempt labels. */
+function attemptBucket(attempt: number): AttemptBucket {
+  if (attempt <= 1) return '1'
+  if (attempt === 2) return '2'
+  if (attempt <= 5) return '3-5'
+  if (attempt <= 10) return '6-10'
+  return 'gt10'
+}
+
+/** Maps a delivery result to a low-cardinality status class. */
+function statusClass(result: Webhooks.Result): StatusClass {
+  if (result.ok) return '2xx'
+  const { error, status } = result
+  if (status !== undefined) {
+    if (status >= 300 && status < 400) return 'url_rejected'
+    if (status >= 400 && status < 500) return '4xx'
+    if (status >= 500) return '5xx'
+  }
+  if (error === undefined) return 'unknown'
+  if (/redirect/i.test(error)) return 'url_rejected'
+  if (/timeout|abort/i.test(error)) return 'timeout'
+  return 'network'
+}