tapimo 0.7.1 → 0.8.0

package/src/analytics/Analytics.test.ts

@@ -12,6 +12,7 @@ const entry = {
   requestId: 'req-1',
   route: '/v1/transactions',
   status: 200,
+  timings: { transactions: 42.7, transactions_count: 7.1 },
 } satisfies Log.Entry
 
 const clickHouse = {
@@ -42,6 +43,7 @@ const row = {
   service: 'api',
   status: 200,
   timestamp: '2026-01-01 00:00:00.000',
+  timings: { transactions: 42.7, transactions_count: 7.1 },
 } satisfies Analytics.Event
 
 afterEach(() => vi.unstubAllGlobals())
@@ -160,8 +162,8 @@ describe('clickhouse', () => {
     await Analytics.clickhouse(clickHouse).migrate()
 
     const bodies = fetch.mock.calls.map((call) => String(call[1]?.body))
-    const guarded = Analytics.migrations.find((migration) => migration.guard)!
-    expect(bodies).not.toContain(guarded.sql)
+    for (const migration of Analytics.migrations.filter((migration) => migration.guard))
+      expect(bodies).not.toContain(migration.sql)
   })
 
   test('migrate throws MigrateError on a non-2xx response', async () => {
@@ -180,6 +182,7 @@ describe('migrations', () => {
     // that predate a column (e.g. billing columns for existing production).
     const sql = Analytics.migrations.map((migration) => migration.sql).join('\n')
     for (const column of Object.keys(row)) expect(sql).toContain(column)
+    expect(sql).toContain('timings Map(String, Float64)')
   })
 })
 
@@ -220,6 +223,7 @@ describe('createQueueSink', () => {
       service: row.service,
       status: row.status,
       timestamp: '<timestamp>',
+      timings: row.timings,
     }).toMatchInlineSnapshot(`
       {
         "billing_active": null,
@@ -241,10 +245,23 @@ describe('createQueueSink', () => {
         "service": "api",
         "status": 200,
         "timestamp": "<timestamp>",
+        "timings": {
+          "transactions": 42.7,
+          "transactions_count": 7.1,
+        },
       }
     `)
   })
 
+  test('stores an empty timing map when the request has no operation timings', async () => {
+    const send = vi.fn<(message: Analytics.Event) => Promise<void>>().mockResolvedValue(undefined)
+    const sink = Analytics.createQueueSink({ send })(context)
+
+    await sink({ ...entry, timings: undefined })
+
+    expect(send.mock.calls[0]![0].timings).toMatchInlineSnapshot(`{}`)
+  })
+
   test('retries a failed send once with the same row', async () => {
     const send = vi
       .fn<(message: Analytics.Event) => Promise<void>>()
@@ -369,31 +386,73 @@ describe('handleQueue', () => {
 
   test('inserts the batch and acks each message', async () => {
     const { insert, message, store } = fixture()
+    const onResult = vi.fn()
 
-    const handled = await Analytics.handleQueue(store, {
-      messages: [message],
-      queue: Analytics.queueName,
-    })
+    const handled = await Analytics.handleQueue(
+      store,
+      {
+        messages: [message],
+        queue: Analytics.queueName,
+      },
+      { onResult },
+    )
 
     expect(handled).toBe(true)
     expect(insert).toHaveBeenCalledWith('request_events', [row])
     expect(message.ack).toHaveBeenCalledTimes(1)
     expect(message.retry).not.toHaveBeenCalled()
+    expect(onResult).toHaveBeenCalledWith({ messages: 1, outcome: 'acked' })
   })
 
   test('retries every message when the insert fails', async () => {
     vi.spyOn(console, 'error').mockImplementation(() => {})
     const { insert, message, store } = fixture()
+    const onResult = vi.fn()
     insert.mockRejectedValueOnce(new Error('clickhouse down'))
 
-    const handled = await Analytics.handleQueue(store, {
-      messages: [message],
-      queue: Analytics.queueName,
-    })
+    const handled = await Analytics.handleQueue(
+      store,
+      {
+        messages: [message],
+        queue: Analytics.queueName,
+      },
+      { onResult },
+    )
 
     expect(handled).toBe(true)
     expect(message.ack).not.toHaveBeenCalled()
     expect(message.retry).toHaveBeenCalledTimes(1)
+    expect(onResult).toHaveBeenCalledWith({
+      cause: expect.objectContaining({ message: 'clickhouse down' }),
+      messages: 1,
+      outcome: 'retried',
+    })
+  })
+
+  test('does not retry acknowledged messages when the result callback fails', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { message, store } = fixture()
+
+    const handled = await Analytics.handleQueue(
+      store,
+      {
+        messages: [message],
+        queue: Analytics.queueName,
+      },
+      {
+        onResult() {
+          throw new Error('metrics failed')
+        },
+      },
+    )
+
+    expect(handled).toBe(true)
+    expect(message.ack).toHaveBeenCalledTimes(1)
+    expect(message.retry).not.toHaveBeenCalled()
+    expect(console.error).toHaveBeenCalledWith(
+      'Analytics queue result callback failed',
+      expect.objectContaining({ message: 'metrics failed' }),
+    )
   })
 
   test('resolves factory sources at the leaf', async () => {

package/src/analytics/Analytics.ts

@@ -135,7 +135,8 @@ export const migrations: readonly Migration[] = [
         rpc_error_data_code Nullable(String),
         rpc_error_count UInt16 DEFAULT 0,
         request_id Nullable(String),
-        billing_active Nullable(UInt8)
+        billing_active Nullable(UInt8),
+        timings Map(String, Float64)
       )
       ENGINE = MergeTree
       ORDER BY (timestamp)
@@ -176,6 +177,21 @@ export const migrations: readonly Migration[] = [
         ADD COLUMN IF NOT EXISTS rpc_error_count UInt16 DEFAULT 0
     `,
   },
+  {
+    name: '0004_request_events_timings',
+    // Patches tables created before request timings entered the baseline. Fresh
+    // tables skip this ALTER, allowing scoped preview users to migrate.
+    guard: `
+      SELECT toUInt8(count() = 1) FROM system.columns
+      WHERE database = currentDatabase()
+        AND table = 'request_events'
+        AND name = 'timings'
+    `,
+    sql: `
+      ALTER TABLE request_events
+        ADD COLUMN IF NOT EXISTS timings Map(String, Float64)
+    `,
+  },
 ]
 
 /**
@@ -292,6 +308,7 @@ export async function handleQueue(
   await RequestEvents.insertMessages(
     get(source),
     batch.messages as readonly RequestEvents.insertMessages.Message[],
+    { onResult: options.onResult },
   )
   return true
 }
@@ -299,6 +316,8 @@ export async function handleQueue(
 export declare namespace handleQueue {
   /** Options for {@link handleQueue}. */
   type Options = {
+    /** Receives the final insert disposition for metrics and error reporting. */
+    onResult?: RequestEvents.insertMessages.Options['onResult']
     /** Queue name to match instead of {@link queueName} (e.g. a per-preview queue). */
     queue?: string | undefined
   }
@@ -340,9 +359,13 @@ export class ConfigError extends Error {
 
 /** Failed ClickHouse insert (non-2xx HTTP response). */
 export class InsertError extends Error {
+  /** HTTP response status returned by ClickHouse. */
+  status: number
+
   constructor(status: number, body: string) {
     super(`ClickHouse insert failed with status ${status}: ${body.slice(0, 500)}`)
     this.name = 'Analytics.InsertError'
+    this.status = status
   }
 }
 

package/src/analytics/tables/requestEvents.ts

@@ -46,6 +46,8 @@ export type Table = {
   status: number
   /** UTC request completion timestamp formatted for ClickHouse DateTime64. */
   timestamp: string
+  /** Longest Server-Timing operation duration per metric name. */
+  timings: Record<string, number>
 }
 
 /** One request attribution term for usage reads. */
@@ -214,6 +216,7 @@ export declare namespace createQueueSink {
 export async function insertMessages(
   analytics: Analytics.Analytics,
   messages: readonly insertMessages.Message[],
+  options: insertMessages.Options = {},
 ): Promise<void> {
   if (messages.length === 0) return
 
@@ -223,9 +226,19 @@ export async function insertMessages(
       messages.map((message) => message.body),
     )
     for (const message of messages) message.ack()
+    reportResult({ messages: messages.length, outcome: 'acked' })
   } catch (error) {
     console.error('ClickHouse analytics insert failed', error)
     for (const message of messages) message.retry()
+    reportResult({ cause: error, messages: messages.length, outcome: 'retried' })
+  }
+
+  function reportResult(result: insertMessages.Result) {
+    try {
+      options.onResult?.(result)
+    } catch (error) {
+      console.error('Analytics queue result callback failed', error)
+    }
   }
 }
 
@@ -239,6 +252,29 @@ export declare namespace insertMessages {
     /** Marks the message for redelivery. */
     retry(): void
   }
+
+  /** Queue insert observability options. */
+  type Options = {
+    /** Receives one bounded batch result after messages are acknowledged or retried. */
+    onResult?: ((result: Result) => void) | undefined
+  }
+
+  /** Outcome of one analytics insert batch. */
+  type Result =
+    | {
+        /** Number of messages acknowledged. */
+        messages: number
+        /** Successful queue disposition. */
+        outcome: 'acked'
+      }
+    | {
+        /** Original insert failure. */
+        cause: unknown
+        /** Number of messages marked for retry. */
+        messages: number
+        /** Failed queue disposition. */
+        outcome: 'retried'
+      }
 }
 
 /**
@@ -257,7 +293,7 @@ export async function readLastUsedAt(
         formatDateTime(max(timestamp), '%Y-%m-%dT%H:%i:%S.000Z', 'UTC') AS lastUsedAt
       FROM ${table}
       WHERE principal_type = 'api_key'
-        AND key_id IN (${apiKeyIds.map(literal).join(', ')})
+        AND key_id IN (${apiKeyIds.map(ClickHouseValue.literal).join(', ')})
       GROUP BY key_id
     `,
   )
@@ -347,33 +383,33 @@ export async function readProjectUsage(
   return {
     byKey: byKey.map((row) => ({
       apiKeyId: String(row.key_id),
-      averageDurationMs: number(row.averageDurationMs),
-      errors: number(row.errors),
-      requests: number(row.requests),
+      averageDurationMs: ClickHouseValue.number(row.averageDurationMs),
+      errors: ClickHouseValue.number(row.errors),
+      requests: ClickHouseValue.number(row.requests),
     })),
     byRoute: byRoute.map((row) => ({
-      averageDurationMs: number(row.averageDurationMs),
-      errors: number(row.errors),
-      requests: number(row.requests),
+      averageDurationMs: ClickHouseValue.number(row.averageDurationMs),
+      errors: ClickHouseValue.number(row.errors),
+      requests: ClickHouseValue.number(row.requests),
       route: String(row.route),
     })),
     byStatus: byStatus.map((row) => ({
-      requests: number(row.requests),
-      status: number(row.status),
+      requests: ClickHouseValue.number(row.requests),
+      status: ClickHouseValue.number(row.status),
     })),
     from: options.from,
     interval: options.interval,
     series: series.map((row) => ({
-      errors: number(row.errors),
-      requests: number(row.requests),
+      errors: ClickHouseValue.number(row.errors),
+      requests: ClickHouseValue.number(row.requests),
       time: String(row.time),
     })),
     to: options.to,
     totals: totals[0]
       ? {
-          averageDurationMs: number(totals[0].averageDurationMs),
-          errors: number(totals[0].errors),
-          requests: number(totals[0].requests),
+          averageDurationMs: ClickHouseValue.number(totals[0].averageDurationMs),
+          errors: ClickHouseValue.number(totals[0].errors),
+          requests: ClickHouseValue.number(totals[0].requests),
         }
       : { averageDurationMs: 0, errors: 0, requests: 0 },
   }
@@ -401,7 +437,10 @@ export async function readErrorBreakdown(
       LIMIT 25
     `,
   )
-  return rows.map((row) => ({ code: String(row.code), requests: number(row.requests) }))
+  return rows.map((row) => ({
+    code: String(row.code),
+    requests: ClickHouseValue.number(row.requests),
+  }))
 }
 
 /** One org's deduped billable request count for a single UTC hour. */
@@ -449,16 +488,16 @@ export async function readBillableCounts(
       WHERE principal_type = 'api_key'
         AND org_id IS NOT NULL
         AND request_id IS NOT NULL
-        AND key_environment = ${literal(options.environment)}
+        AND key_environment = ${ClickHouseValue.literal(options.environment)}
         ${sandboxGate}
-        AND timestamp >= parseDateTime64BestEffort(${literal(options.from)}, 3, 'UTC')
-        AND timestamp < parseDateTime64BestEffort(${literal(options.to)}, 3, 'UTC')
+        AND timestamp >= parseDateTime64BestEffort(${ClickHouseValue.literal(options.from)}, 3, 'UTC')
+        AND timestamp < parseDateTime64BestEffort(${ClickHouseValue.literal(options.to)}, 3, 'UTC')
       GROUP BY org_id, toStartOfHour(timestamp)
     `,
   )
   return rows.map((row) => ({
     bucketStart: String(row.bucketStart),
-    count: number(row.count),
+    count: ClickHouseValue.number(row.count),
     orgId: String(row.orgId),
   }))
 }
@@ -535,7 +574,8 @@ function event(entry: Log.Entry, context: Metrics.cloudflare.Context): Table {
     rpc_error_data_code: entry.rpc?.dataCode ?? null,
     service: context.service ?? 'unknown',
     status: entry.status,
-    timestamp: timestamp(),
+    timestamp: ClickHouseValue.timestamp(),
+    timings: entry.timings ?? {},
   }
 }
 
@@ -548,8 +588,8 @@ function usageWhere(options: ProjectUsageOptions) {
   return [
     `principal_type = 'api_key'`,
     `(${attributions})`,
-    `timestamp >= parseDateTime64BestEffort(${literal(options.from)}, 3, 'UTC')`,
-    `timestamp <= parseDateTime64BestEffort(${literal(options.to)}, 3, 'UTC')`,
+    `timestamp >= parseDateTime64BestEffort(${ClickHouseValue.literal(options.from)}, 3, 'UTC')`,
+    `timestamp <= parseDateTime64BestEffort(${ClickHouseValue.literal(options.to)}, 3, 'UTC')`,
   ].join(' AND ')
 }
 
@@ -558,7 +598,7 @@ function attributionWhere(attribution: Attribution, options: ProjectUsageOptions
     if (!attribution.apiKeyIds?.length) return '0'
     return [
       `project_id IS NULL`,
-      `key_id IN (${attribution.apiKeyIds.map(literal).join(', ')})`,
+      `key_id IN (${attribution.apiKeyIds.map(ClickHouseValue.literal).join(', ')})`,
       ...(attribution.environment === undefined
         ? []
         : [keyEnvironmentWhere(attribution.environment, true)]),
@@ -568,10 +608,10 @@ function attributionWhere(attribution: Attribution, options: ProjectUsageOptions
   // Absent `projectId` scopes to the whole organization (any project).
   if (attribution.projectId === undefined) {
     return [
-      `org_id = ${literal(options.orgId)}`,
+      `org_id = ${ClickHouseValue.literal(options.orgId)}`,
       ...(attribution.apiKeyIds === undefined
         ? []
-        : [`key_id IN (${attribution.apiKeyIds.map(literal).join(', ')})`]),
+        : [`key_id IN (${attribution.apiKeyIds.map(ClickHouseValue.literal).join(', ')})`]),
       ...(attribution.environment === undefined
         ? []
         : [keyEnvironmentWhere(attribution.environment, false)]),
@@ -579,11 +619,11 @@ function attributionWhere(attribution: Attribution, options: ProjectUsageOptions
   }
 
   return [
-    `org_id = ${literal(options.orgId)}`,
-    `project_id = ${literal(attribution.projectId)}`,
+    `org_id = ${ClickHouseValue.literal(options.orgId)}`,
+    `project_id = ${ClickHouseValue.literal(attribution.projectId)}`,
     ...(attribution.apiKeyIds === undefined
       ? []
-      : [`key_id IN (${attribution.apiKeyIds.map(literal).join(', ')})`]),
+      : [`key_id IN (${attribution.apiKeyIds.map(ClickHouseValue.literal).join(', ')})`]),
     ...(attribution.environment === undefined
       ? []
       : [keyEnvironmentWhere(attribution.environment, false)]),
@@ -591,19 +631,21 @@ function attributionWhere(attribution: Attribution, options: ProjectUsageOptions
 }
 
 function keyEnvironmentWhere(environment: Environment, allowLegacyNull: boolean) {
-  const exact = `key_environment = ${literal(environment)}`
+  const exact = `key_environment = ${ClickHouseValue.literal(environment)}`
   if (!allowLegacyNull) return exact
   return `(${exact} OR key_environment IS NULL)`
 }
 
-function literal(value: string) {
-  return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`
-}
+namespace ClickHouseValue {
+  export function literal(value: string) {
+    return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`
+  }
 
-function number(value: number | string) {
-  return Number(value)
-}
+  export function number(value: number | string) {
+    return Number(value)
+  }
 
-function timestamp() {
-  return new Date().toISOString().replace('T', ' ').replace('Z', '')
+  export function timestamp() {
+    return new Date().toISOString().replace('T', ' ').replace('Z', '')
+  }
 }

package/src/apps/Zones.test.ts

@@ -0,0 +1,33 @@
+import * as Zones from './Zones.js'
+
+describe('chains', () => {
+  test('defines hosted zones', () => {
+    expect(Zones.chains).toMatchObject([
+      {
+        contracts: {
+          messenger: { address: '0x254356112cCf6f32fAd84F16CC5E0A0cCA17Beb7' },
+          portal: { address: '0x59831A17340EE14FE136d751EfbeA8b630470fD2' },
+        },
+        id: 421_700_001,
+        rpcUrls: {
+          default: { http: ['https://rpc-zone-e.testnet.tempo.xyz'] },
+          internal: { http: ['https://rpc-zone-e.testnet.tempo.xyz'] },
+        },
+        sourceId: 42_431,
+      },
+      {
+        contracts: {
+          messenger: { address: '0x5A4d000000000000000000000000000000000000' },
+          portal: { address: '0x5aD0000000000000000000000000000000000006' },
+        },
+        id: 421_700_006,
+        rpcUrls: {
+          default: { http: ['https://rpc-zone-stable-public.devnet.tempoxyz.dev'] },
+          internal: { http: ['https://rpc-zone-stable.devnet.tempoxyz.dev'] },
+          tidx: { http: ['https://tidx-zone-stable.devnet.tempoxyz.dev'] },
+        },
+        sourceId: 31_318,
+      },
+    ])
+  })
+})

package/src/apps/Zones.ts

@@ -0,0 +1,40 @@
+import { defineChain } from 'viem'
+import { tempoDevnet, tempoTestnet } from 'viem/tempo/chains'
+
+/** Zone E on Tempo testnet. */
+export const zoneE = defineChain({
+  ...tempoTestnet,
+  contracts: {
+    ...tempoTestnet.contracts,
+    messenger: { address: '0x254356112cCf6f32fAd84F16CC5E0A0cCA17Beb7' },
+    portal: { address: '0x59831A17340EE14FE136d751EfbeA8b630470fD2' },
+  },
+  id: 421_700_001,
+  name: 'zone-e',
+  rpcUrls: {
+    default: { http: ['https://rpc-zone-e.testnet.tempo.xyz'] },
+    internal: { http: ['https://rpc-zone-e.testnet.tempo.xyz'] },
+  },
+  sourceId: tempoTestnet.id,
+})
+
+/** Stable hosted Zone on Tempo devnet. */
+export const zoneStable = defineChain({
+  ...tempoDevnet,
+  contracts: {
+    ...tempoDevnet.contracts,
+    messenger: { address: '0x5A4d000000000000000000000000000000000000' },
+    portal: { address: '0x5aD0000000000000000000000000000000000006' },
+  },
+  id: 421_700_006,
+  name: 'zone-stable',
+  rpcUrls: {
+    default: { http: ['https://rpc-zone-stable-public.devnet.tempoxyz.dev'] },
+    internal: { http: ['https://rpc-zone-stable.devnet.tempoxyz.dev'] },
+    tidx: { http: ['https://tidx-zone-stable.devnet.tempoxyz.dev'] },
+  },
+  sourceId: tempoDevnet.id,
+})
+
+/** Hosted Zone chains served by the API and admin. */
+export const chains = [zoneE, zoneStable] as const