tapimo 0.9.0 → 0.10.0

package/src/internal/MetricSink.ts

@@ -1,6 +1,7 @@
 import type { Metrics } from '../Metrics.js'
 import type * as Webhooks from '../Webhooks.js'
 import type * as Log from './Log.js'
+import * as WebhookDestination from './WebhookDestination.js'
 
 /** Webhook event type, including the synthetic `ping` carried on test envelopes. */
 export type EventType = Webhooks.Envelope['type']
@@ -8,6 +9,12 @@ export type EventType = Webhooks.Envelope['type']
 /** Where a delivery attempt originated. */
 export type Trigger = 'manual_retry' | 'ping' | 'queue'
 
+/** Bounded poller stage names used by `webhook:poll`. */
+export type PollStage = 'cursor_write' | 'enrich' | 'rpc_head' | 'scan' | 'subscription_read'
+
+/** Bounded Durable Object or transport failure classes used by `webhook:poll-failure`. */
+export type PollFailure = 'other' | 'overloaded' | 'remote' | 'retryable'
+
 /** 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. */
@@ -20,11 +27,112 @@ export type TickMeta = {
 
 /**
  * A webhook metric event, recorded by the {@link webhooks} sink. The poller
- * emits `webhook:tick`/`webhook:enqueue` and the delivery path emits
- * `webhook:delivery`.
+ * emits head recovery, poll, tick, and enqueue measurements; the delivery path
+ * emits `webhook:delivery`.
  */
 export type WebhookEvent =
   | {
+      /** Tempo chain whose poll cycle completed. */
+      chainId: number
+      /** Whether the poll cycle completed without scan or dispatch failures. */
+      outcome: 'error' | 'ok'
+      /** Requested boundary movement since the preceding successful poll, in blocks. */
+      requestedBoundaryAdvanceBlocks?: number | undefined
+      /** Execution path that acquired this poll claim. */
+      trigger: 'alarm' | 'cron' | 'direct' | 'queue'
+      /** Identifies a transport-neutral poll-cycle measurement. */
+      type: 'webhook:poll-cycle'
+    }
+  | {
+      /** Tempo chain whose durable progress was read. */
+      chainId: number
+      /** Blocks between the desired and fully drained boundaries. */
+      lagBlocks: number
+      /** Identifies durable coordinator progress. */
+      type: 'webhook:head-progress'
+    }
+  | {
+      /** Tempo chain whose recovery poke was dequeued. */
+      chainId: number
+      /** When the recovery poke was dequeued, as epoch milliseconds. */
+      dequeuedAt: number
+      /** When the recovery poke was enqueued, as epoch milliseconds. */
+      enqueuedAt: number
+      /** Recovery source carried through the Queue handoff. */
+      trigger: 'alarm' | 'queue'
+      /** Identifies recovery Queue latency, not observed head volume. */
+      type: 'webhook:head-recovery'
+    }
+  | {
+      /** Tempo chain whose poll claim was acquired. */
+      chainId: number
+      /** Delay from observing the desired boundary to acquiring the claim. */
+      delayMs?: number | undefined
+      /** Execution path that acquired the claim. */
+      trigger: 'alarm' | 'cron' | 'direct' | 'queue'
+      /** Identifies a poll beginning, before scan work runs. */
+      type: 'webhook:poll-start'
+    }
+  | {
+      /** Tempo chain whose poll failed. */
+      chainId: number
+      /** Bounded class of the thrown failure. */
+      failure: PollFailure
+      /** Operation boundary that rejected the poll. */
+      stage: 'claim' | 'continuation_enqueue' | 'finish' | 'scan'
+      /** Execution path that failed before recovery. */
+      trigger: 'alarm' | 'cron' | 'direct' | 'queue'
+      /** Identifies a transport-neutral poll failure. */
+      type: 'webhook:poll-failure'
+    }
+  | {
+      chainId: number
+      durationMs: number
+      eventType?: EventType | undefined
+      outcome: 'error' | 'ok'
+      stage: PollStage
+      type: 'webhook:poll'
+    }
+  | {
+      /** Tempo chain whose eligible subscription count was read. */
+      chainId: number
+      /** Active, unexpired subscriptions selected for the poll. */
+      count: number
+      /** Identifies a pre-scan subscription eligibility measurement. */
+      type: 'webhook:poll-subscriptions'
+    }
+  | {
+      /** Chain scanned by this poll batch. */
+      chainId: number
+      /** Shared upper bound for concurrent upstream scans. */
+      concurrency: number
+      /** Scan duration, present only after completion. */
+      durationMs?: number | undefined
+      /** Subscription event type scanned by this batch. */
+      eventType: EventType
+      /** Subscriptions whose scan rejected, present only after completion. */
+      failedSubscriptions?: number | undefined
+      /** Matching rows retained by completed pages, present only after completion. */
+      matchedItems?: number | undefined
+      /** Largest block window requested by one subscription. */
+      maxWindowBlocks: number
+      /** Whether the checkpoint precedes allocation or follows scan completion. */
+      phase: 'complete' | 'start'
+      /** Outcome of the completed RPC-backed scan. */
+      outcome?: 'empty' | 'error' | 'missing' | 'ok' | undefined
+      /** JSON-RPC method used by this event type's scanner. */
+      rpcMethod: 'eth_getBlockByNumber' | 'eth_getLogs'
+      /** Subscriptions retained in this scan batch. */
+      subscriptionCount: number
+      /** Maximum subscriptions retained by this event-type batch. */
+      subscriptionLimit: number
+      /** Sum of subscription block windows in this scan batch. */
+      totalWindowBlocks: number
+      /** Identifies a memory-attribution scan boundary. */
+      type: 'webhook:poll-scan'
+    }
+  | {
+      cursorLagBlocks?: number | undefined
       meta: TickMeta
       result: Webhooks.createPoller.Result | undefined
       type: 'webhook:tick'
@@ -38,8 +146,20 @@ export type WebhookEvent =
     }
   | {
       envelope: Webhooks.Envelope
+      /** Cloudflare Queue delivery attempt, absent outside the Queue path. */
+      queueAttempt?: number | undefined
       result: Webhooks.Result
       subscription: Webhooks.Subscription
+      timings?: {
+        deliveryLogMs?: number | undefined
+        envelopeToQueueMs?: number | undefined
+        endToEndMs?: number | undefined
+        eventToEnvelopeMs?: number | undefined
+        processingMs?: number | undefined
+        queueWaitMs?: number | undefined
+        stateWriteMs?: number | undefined
+        subscriptionReadMs?: number | undefined
+      }
       trigger: Trigger
       type: 'webhook:delivery'
     }
@@ -195,7 +315,7 @@ type StatusClass = '2xx' | '4xx' | '5xx' | 'network' | 'timeout' | 'unknown' | '
 /**
  * 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
+ * `attempt_bucket`, `failure`, `queue_attempt_bucket`, `outcome`, `stage`) — never subscription/org/event ids, which belong
  * in logs or analytics, not StatsD-style series.
  */
 export function webhooks(backend: Metrics): WebhookSink {
@@ -205,6 +325,101 @@ export function webhooks(backend: Metrics): WebhookSink {
     },
     record(event) {
       switch (event.type) {
+        case 'webhook:head-recovery': {
+          const tags = { chain_id: String(event.chainId), trigger: event.trigger }
+          backend.count('webhook_head_recovery_queue_count', 1, tags)
+          backend.histogram(
+            'webhook_head_recovery_queue_wait_ms',
+            Math.max(0, event.dequeuedAt - event.enqueuedAt),
+            tags,
+          )
+          return
+        }
+        case 'webhook:head-progress':
+          backend.gauge('webhook_head_progress_lag_blocks', event.lagBlocks, {
+            chain_id: String(event.chainId),
+          })
+          return
+        case 'webhook:poll-failure':
+          backend.count('webhook_poll_failure_count', 1, {
+            chain_id: String(event.chainId),
+            failure: event.failure,
+            stage: event.stage,
+            trigger: event.trigger,
+          })
+          return
+        case 'webhook:poll': {
+          const tags = {
+            chain_id: String(event.chainId),
+            ...(event.eventType === undefined ? {} : { event_type: event.eventType }),
+            outcome: event.outcome,
+            stage: event.stage,
+          }
+          backend.histogram('webhook_poller_stage_duration_ms', event.durationMs, tags)
+          return
+        }
+        case 'webhook:poll-scan': {
+          const tags = {
+            chain_id: String(event.chainId),
+            event_type: event.eventType,
+            phase: event.phase,
+          }
+          backend.count('webhook_poller_scan_checkpoint_count', 1, tags)
+          backend.histogram('webhook_poller_scan_concurrency', event.concurrency, tags)
+          backend.histogram('webhook_poller_scan_subscription_count', event.subscriptionCount, tags)
+          backend.histogram('webhook_poller_scan_subscription_limit', event.subscriptionLimit, tags)
+          backend.histogram('webhook_poller_scan_max_window_blocks', event.maxWindowBlocks, tags)
+          backend.histogram(
+            'webhook_poller_scan_total_window_blocks',
+            event.totalWindowBlocks,
+            tags,
+          )
+          if (event.durationMs !== undefined)
+            backend.histogram('webhook_poller_scan_duration_ms', event.durationMs, tags)
+          if (event.failedSubscriptions !== undefined)
+            backend.count(
+              'webhook_poller_scan_failed_subscription_count',
+              event.failedSubscriptions,
+              tags,
+            )
+          if (event.matchedItems !== undefined)
+            backend.count('webhook_poller_scan_matched_item_count', event.matchedItems, tags)
+          if (event.outcome !== undefined)
+            backend.count('webhook_poller_rpc_scan_count', 1, {
+              chain_id: String(event.chainId),
+              event_type: event.eventType,
+              outcome: event.outcome,
+              rpc_method: event.rpcMethod,
+            })
+          return
+        }
+        case 'webhook:poll-subscriptions':
+          backend.gauge('webhook_poller_active_subscription_count', event.count, {
+            chain_id: String(event.chainId),
+          })
+          return
+        case 'webhook:poll-cycle': {
+          const tags = {
+            chain_id: String(event.chainId),
+            outcome: event.outcome,
+            trigger: event.trigger,
+          }
+          backend.count('webhook_poll_cycle_count', 1, tags)
+          if (event.requestedBoundaryAdvanceBlocks !== undefined)
+            backend.histogram(
+              'webhook_poll_requested_boundary_advance_blocks',
+              event.requestedBoundaryAdvanceBlocks,
+              tags,
+            )
+          return
+        }
+        case 'webhook:poll-start': {
+          const tags = { chain_id: String(event.chainId), trigger: event.trigger }
+          backend.count('webhook_poll_start_count', 1, tags)
+          if (event.delayMs !== undefined)
+            backend.histogram('webhook_poll_start_delay_ms', event.delayMs, tags)
+          return
+        }
         case 'webhook:tick': {
           const { meta, result } = event
           const chain_id = String(result?.chainId ?? meta.chainId ?? 'unknown')
@@ -213,6 +428,10 @@ export function webhooks(backend: Metrics): WebhookSink {
             chain_id,
             outcome: meta.outcome,
           })
+          if (event.cursorLagBlocks !== undefined)
+            backend.gauge('webhook_subscription_cursor_lag_blocks', event.cursorLagBlocks, {
+              chain_id,
+            })
           if (!result) return
           backend.histogram('webhook_poller_subscription_count', result.subscriptions, { chain_id })
           backend.count('webhook_poller_scanned_count', result.scanned, { chain_id })
@@ -238,7 +457,14 @@ export function webhooks(backend: Metrics): WebhookSink {
           return
         }
         case 'webhook:delivery': {
-          const { envelope, result, subscription } = event
+          const { envelope, result, subscription, timings } = event
+          const queueTags =
+            event.queueAttempt === undefined
+              ? {}
+              : {
+                  queue_attempt_bucket: attemptBucket(event.queueAttempt),
+                  queue_disposition: WebhookDestination.isRetryable(result) ? 'retried' : 'acked',
+                }
           const tags = {
             chain_id: String(envelope.chainId),
             destination_type: subscription.destination.type satisfies DestinationType,
@@ -249,6 +475,7 @@ export function webhooks(backend: Metrics): WebhookSink {
             ...tags,
             attempt_bucket: attemptBucket(subscription.failureCount + 1),
             outcome,
+            ...queueTags,
             status_class: statusClass(result),
             trigger: event.trigger,
           })
@@ -257,11 +484,41 @@ export function webhooks(backend: Metrics): WebhookSink {
               ...tags,
               outcome,
             })
-          backend.histogram(
-            'webhook_delivery_queue_latency_ms',
-            Math.max(0, Date.now() - Date.parse(envelope.createdAt)),
-            tags,
-          )
+          if (timings?.deliveryLogMs !== undefined)
+            backend.histogram('webhook_delivery_log_write_ms', timings.deliveryLogMs, tags)
+          if (timings?.envelopeToQueueMs !== undefined)
+            backend.histogram(
+              'webhook_delivery_envelope_to_queue_ms',
+              timings.envelopeToQueueMs,
+              tags,
+            )
+          if (timings?.endToEndMs !== undefined)
+            backend.histogram('webhook_delivery_end_to_end_ms', timings.endToEndMs, {
+              ...tags,
+              outcome,
+            })
+          if (timings?.eventToEnvelopeMs !== undefined)
+            backend.histogram(
+              'webhook_delivery_event_to_envelope_ms',
+              timings.eventToEnvelopeMs,
+              tags,
+            )
+          if (timings?.processingMs !== undefined)
+            backend.histogram('webhook_delivery_processing_ms', timings.processingMs, tags)
+          if (timings?.queueWaitMs !== undefined)
+            backend.histogram('webhook_delivery_queue_wait_ms', timings.queueWaitMs, {
+              ...tags,
+              outcome,
+              ...queueTags,
+            })
+          if (timings?.stateWriteMs !== undefined)
+            backend.histogram('webhook_delivery_state_write_ms', timings.stateWriteMs, tags)
+          if (timings?.subscriptionReadMs !== undefined)
+            backend.histogram(
+              'webhook_delivery_subscription_read_ms',
+              timings.subscriptionReadMs,
+              tags,
+            )
           return
         }
       }

package/src/internal/Schema.ts

@@ -356,7 +356,7 @@ export const Denomination = z
   .check(
     z.describe(
       'Currency to denominate values in (case-insensitive, e.g. `AUD`). ' +
-        'Must be priced by the configured FX oracle. Defaults to `USD`.',
+        'Must be priced by the configured FX oracle.',
     ),
     z.meta({ examples: ['AUD'] }),
   )

package/src/internal/Tidx.test.ts

@@ -330,9 +330,9 @@ describe('resolve', () => {
   test('passes Zone metadata to the resolver', () => {
     expect(
       Tidx.resolve(({ zone }) => ({ baseUrl: zone ? 'http://tidx:8080' : undefined }), {
-        chainId: Zones.zoneE.id,
+        chainId: Zones.zoneModerato.id,
         principal: null,
-        zone: Zones.zoneE,
+        zone: Zones.zoneModerato,
       }),
     ).toMatchInlineSnapshot(`
       {
@@ -469,7 +469,7 @@ describe('getClient', () => {
     )
     try {
       const client = Tidx.getClient({
-        chainId: Zones.zoneE.id,
+        chainId: Zones.zoneModerato.id,
         tidx: {
           baseUrl: 'https://internal.indexer',
           zoneHeaders: {
@@ -477,7 +477,7 @@ describe('getClient', () => {
             'CF-Access-Client-Secret': 'client-secret',
           },
         },
-        zone: Zones.zoneE,
+        zone: Zones.zoneModerato,
       })
       await client.fetch({ query: 'select 1' })
 

package/src/internal/Tidx.ts

@@ -92,9 +92,7 @@ export function getClient(options: getClient.Options): Client {
  * output (`baseUrl` + auth + `chainId`), not the principal, so a resolver
  * `tidx` may branch on any principal field while client cardinality stays
  * bounded by the number of distinct upstreams — callers that resolve to the same
- * upstream share a client. Shared by `data()` (per-request reads) and
- * `Webhooks.createPoller` (the scheduled poller) so the resolver logic lives in
- * one place.
+ * upstream share a client.
  */
 export function createGetClient(options: createGetClient.Options = {}): GetClient {
   const { defaultChainId = Viem.defaultChainId, tidx } = options

package/src/internal/Viem.test.ts

@@ -220,6 +220,14 @@ describe('resolveRpc', () => {
 })
 
 describe('getClient', () => {
+  test('disables multicall for Zones', () => {
+    const l1Client = Viem.getClient({ chainId: 4217 })
+    const zoneClient = Viem.getClient({ chainId: zone.id, zone })
+
+    expect(l1Client.batch?.multicall).toEqual({ deployless: true })
+    expect(zoneClient.batch?.multicall).toBe(false)
+  })
+
   test('sends inferred Bearer auth', async () => {
     const fetch = vi
       .spyOn(globalThis, 'fetch')

package/src/internal/Viem.ts

@@ -163,7 +163,8 @@ export function getClient(options: getClient.Options): getClient.ReturnType {
     // (e.g. `balanceOf` across many tokens) and pay one RPC round-trip.
     // Deployless mode bytecode-injects multicall3 so Tempo, which doesn't
     // configure a deployed multicall3, can still serve the aggregated call.
-    batch: { multicall: { deployless: true } },
+    // Zones disable multicall entirely and issue concurrent direct `eth_call`s instead.
+    batch: { multicall: zone ? false : { deployless: true } },
     chain: { ...tempoMainnet, id: chainId },
     transport: http(rpcUrl, fetchOptions ? { fetchOptions } : {}),
   })

package/src/internal/WebhookDestination.test.ts

@@ -93,6 +93,26 @@ describe('from', () => {
   })
 })
 
+describe('isRetryable', () => {
+  test.each([
+    ['success', { ok: true, status: 204 }, false],
+    ['redirect', { error: 'redirect rejected (302)', ok: false, status: 302 }, false],
+    ['bad request', { error: 'non-2xx response (400)', ok: false, status: 400 }, false],
+    ['request timeout', { error: 'non-2xx response (408)', ok: false, status: 408 }, true],
+    ['rate limited', { error: 'non-2xx response (429)', ok: false, status: 429 }, true],
+    ['server error', { error: 'non-2xx response (503)', ok: false, status: 503 }, true],
+    ['opaque redirect', { error: 'redirect rejected (0)', ok: false }, false],
+    ['timeout', { error: 'timed out after 10000ms', ok: false }, true],
+    ['network error', { error: 'TypeError: fetch failed', ok: false }, true],
+    ['unknown error', { ok: false }, true],
+  ] satisfies readonly [string, WebhookDestination.Result, boolean][])(
+    '%s',
+    (_label, result, retryable) => {
+      expect(WebhookDestination.isRetryable(result)).toBe(retryable)
+    },
+  )
+})
+
 describe('url().deliver', () => {
   test('signs the body and POSTs a 2xx as success', async () => {
     let captured:

package/src/internal/WebhookDestination.ts

@@ -100,6 +100,16 @@ export type Result = {
   status?: number | undefined
 }
 
+/** Returns whether another delivery attempt could plausibly succeed. */
+export function isRetryable(result: Result): boolean {
+  if (result.ok) return false
+  if (result.status !== undefined)
+    return result.status === 408 || result.status === 429 || result.status >= 500
+  // Workers exposes rejected redirects as an opaque response without a status.
+  if (result.error && /redirect/i.test(result.error)) return false
+  return true
+}
+
 /**
  * Canonical constructor: normalizes a value into a validated {@link Instance} by
  * delegating to the matching builder (`url`, `slack`, `betterStack`), each of