tapimo 0.7.1 → 0.8.0

package/src/internal/Tidx.local.test.ts

@@ -1,13 +1,18 @@
+/** @module-tag localnet */
+
 import * as TestApp from '../../test/App.js'
 import * as Runtime from '../../test/runtime.js'
 import * as Indexer from '../apps/data/routes/indexer.js'
+import type * as Log from './Log.js'
+import * as Tidx from './Tidx.js'
 
 describe('local TIDX runtime', () => {
   test.runIf(Runtime.get().mode === 'localnet')(
-    'proxies queries to a disposable TIDX',
+    'observes queries through a disposable TIDX',
     async () => {
       const runtime = Runtime.get()
-      const client = TestApp.client()
+      const entries: Log.Entry[] = []
+      const client = TestApp.client({ logger: (entry) => void entries.push(entry) })
       const response = await client.v1.indexer.query.$get(
         { query: { chainId: String(runtime.chainId), sql: 'select 1 as value' } },
         TestApp.auth,
@@ -20,7 +25,7 @@ describe('local TIDX runtime', () => {
       [
         "value",
       ]
-    `)
+      `)
       expect(body.rows).toMatchInlineSnapshot(`
       [
         [
@@ -28,6 +33,76 @@ describe('local TIDX runtime', () => {
         ],
       ]
     `)
+      expect(entries[0]?.provider).toBeUndefined()
+      expect(entries[0]?.timings?.['tidx']).toBeGreaterThan(0)
+    },
+  )
+
+  test.runIf(Runtime.get().mode === 'localnet')(
+    'does not record caller query rejections as provider failures',
+    async () => {
+      const runtime = Runtime.get()
+      const entries: Log.Entry[] = []
+      const client = TestApp.client({ logger: (entry) => void entries.push(entry) })
+      const response = await client.v1.indexer.query.$get(
+        {
+          query: {
+            chainId: String(runtime.chainId),
+            sql: 'select * from missing_observability_table',
+          },
+        },
+        TestApp.auth,
+      )
+
+      expect(response.status).toBe(422)
+      expect(entries[0]?.provider).toBeUndefined()
+      expect(entries[0]?.timings?.['tidx']).toBeGreaterThan(0)
+    },
+  )
+
+  test.runIf(Runtime.get().mode === 'localnet')(
+    'clears a handled failure after a successful query',
+    async () => {
+      const runtime = Runtime.get()
+      const failures: (Log.ProviderFailure | undefined)[] = []
+      const timings: number[] = []
+      const client = Tidx.observe(
+        Tidx.getClient({
+          chainId: runtime.chainId,
+          tidx: { baseUrl: runtime.tidxUrl },
+        }),
+        {
+          record: (failure) => void failures.push(failure),
+          time: async (fn) => {
+            const start = performance.now()
+            try {
+              return await fn()
+            } finally {
+              timings.push(performance.now() - start)
+            }
+          },
+        },
+      )
+
+      await expect(
+        client.fetch({
+          chainId: runtime.chainId,
+          query: 'select * from missing_observability_table',
+        }),
+      ).rejects.toThrow()
+      await client.fetch({ chainId: runtime.chainId, query: 'select 1' })
+
+      expect(failures).toEqual([
+        {
+          failure: 'query',
+          id: 'tidx',
+          operation: 'query',
+          status: 422,
+        },
+        undefined,
+      ])
+      expect(timings).toHaveLength(2)
+      expect(timings.every((duration) => duration > 0)).toBe(true)
     },
   )
 })

package/src/internal/Tidx.test.ts

@@ -1,5 +1,6 @@
 import { Tidx as TidxClient } from 'tidx.ts'
 
+import * as Zones from '../apps/Zones.js'
 import type * as Auth from './Auth.js'
 import * as Tidx from './Tidx.js'
 import type * as Viem from './Viem.js'
@@ -25,6 +26,115 @@ function fakeClient(fetch: Tidx.Client['fetch']): Tidx.Client {
   return { fetch } as never
 }
 
+describe('providerFailure', () => {
+  test('classifies failed 200 bodies as payload failures', () => {
+    expect(Tidx.providerFailure(appError('secret upstream detail'))).toEqual({
+      failure: 'payload',
+      id: 'tidx',
+      operation: 'query',
+    })
+  })
+
+  test('classifies query and HTTP failures', () => {
+    expect([
+      Tidx.providerFailure(appError('secret upstream detail', 422)),
+      Tidx.providerFailure(appError('secret upstream detail', 503)),
+    ]).toMatchInlineSnapshot(`
+      [
+        {
+          "failure": "query",
+          "id": "tidx",
+          "operation": "query",
+          "status": 422,
+        },
+        {
+          "failure": "http",
+          "id": "tidx",
+          "operation": "query",
+          "status": 503,
+        },
+      ]
+    `)
+  })
+
+  test('classifies timeout and rate-limit statuses', () => {
+    expect([
+      Tidx.providerFailure(appError('secret upstream detail', 408)),
+      Tidx.providerFailure(appError('secret upstream detail', 429)),
+    ]).toMatchInlineSnapshot(`
+      [
+        {
+          "failure": "timeout",
+          "id": "tidx",
+          "operation": "query",
+          "status": 408,
+        },
+        {
+          "failure": "rate_limit",
+          "id": "tidx",
+          "operation": "query",
+          "status": 429,
+        },
+      ]
+    `)
+  })
+
+  test('classifies transport failures without their messages', () => {
+    expect([
+      Tidx.providerFailure(new DOMException('secret timeout detail', 'TimeoutError')),
+      Tidx.providerFailure(new TypeError('secret network detail')),
+      Tidx.providerFailure(new Error('secret unknown detail')),
+    ]).toMatchInlineSnapshot(`
+      [
+        {
+          "failure": "timeout",
+          "id": "tidx",
+          "operation": "query",
+        },
+        {
+          "failure": "network",
+          "id": "tidx",
+          "operation": "query",
+        },
+        {
+          "failure": "unknown",
+          "id": "tidx",
+          "operation": "query",
+        },
+      ]
+    `)
+  })
+})
+
+describe('responseFailure', () => {
+  test('classifies failed 200 bodies without consuming the response', async () => {
+    const response = Response.json({ error: 'secret upstream detail', ok: false })
+
+    expect(await Tidx.responseFailure(response)).toEqual({
+      failure: 'payload',
+      id: 'tidx',
+      operation: 'query',
+    })
+    expect(await response.json()).toEqual({ error: 'secret upstream detail', ok: false })
+  })
+
+  test('ignores successful 200 bodies', async () => {
+    const response = Response.json({ ok: true })
+
+    expect(await Tidx.responseFailure(response)).toBeUndefined()
+  })
+})
+
+describe('isQueryRejection', () => {
+  test('matches caller-caused query statuses only', () => {
+    expect(
+      [400, 422, 408, 429, 500].map((status) =>
+        Tidx.isQueryRejection(new Response(null, { status })),
+      ),
+    ).toEqual([true, true, false, false, false])
+  })
+})
+
 describe('escape', () => {
   test('doubles quotes for ANSI string literals, leaving backslashes alone', () => {
     expect(Tidx.escape('USD')).toMatchInlineSnapshot(`"USD"`)
@@ -145,6 +255,19 @@ describe('withTransientRetry', () => {
   })
 })
 
+describe('isDeterministicError', () => {
+  test('flags indexer failures a retry cannot fix', () => {
+    // The planner rejects the query shape outright (e.g. 422 `db error`).
+    expect(Tidx.isDeterministicError(appError('db error', 422))).toBe(true)
+    expect(Tidx.isDeterministicError(appError('syntax error near "SELCT"'))).toBe(true)
+    // Transient failures retry instead.
+    expect(Tidx.isDeterministicError(appError('db error'))).toBe(false)
+    expect(Tidx.isDeterministicError(appError('bad gateway', 502))).toBe(false)
+    // Non-indexer errors are not indexer failures at all.
+    expect(Tidx.isDeterministicError(new Error('db error'))).toBe(false)
+  })
+})
+
 describe('resolve', () => {
   test('defaults to the per-chain indexer URL', () => {
     expect(Tidx.resolve(undefined, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
@@ -185,8 +308,42 @@ describe('resolve', () => {
     `)
   })
 
+  test('selects a serialized base URL by chain id', () => {
+    const tidx = {
+      baseUrl: JSON.stringify({ 4217: 'https://mainnet.indexer.test', 42431: 'https://testnet.indexer.test' }), // prettier-ignore
+    }
+
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://mainnet.indexer.test",
+        "basicAuth": undefined,
+      }
+    `)
+    expect(Tidx.resolve(tidx, { chainId: 42431, principal: null })).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://testnet.indexer.test",
+        "basicAuth": undefined,
+      }
+    `)
+  })
+
+  test('passes Zone metadata to the resolver', () => {
+    expect(
+      Tidx.resolve(({ zone }) => ({ baseUrl: zone ? 'http://tidx:8080' : undefined }), {
+        chainId: Zones.zoneE.id,
+        principal: null,
+        zone: Zones.zoneE,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "http://tidx:8080",
+        "basicAuth": undefined,
+      }
+    `)
+  })
+
   test('the static form ignores the principal', () => {
-    const tidx = { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' }
+    const tidx = { auth: 'user:pass', baseUrl: 'https://internal.indexer' }
     expect(Tidx.resolve(tidx, { chainId: 4217, principal: publicPrincipal }))
       .toMatchInlineSnapshot(`
       {
@@ -206,7 +363,7 @@ describe('resolve', () => {
   test('resolves Bearer auth', () => {
     expect(
       Tidx.resolve(
-        { baseUrl: 'https://internal.indexer', bearerAuth: 'zone-secret' },
+        { auth: 'zone-secret', baseUrl: 'https://internal.indexer' },
         { chainId: 4217, principal: apiKeyPrincipal },
       ),
     ).toMatchInlineSnapshot(`
@@ -218,11 +375,36 @@ describe('resolve', () => {
     `)
   })
 
+  test('selects Bearer auth by chain id', () => {
+    const tidx = {
+      auth: { 4217: 'mainnet-secret', 42431: 'testnet-secret' },
+      baseUrl: 'https://internal.indexer',
+    }
+
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: null }).bearerAuth).toBe('mainnet-secret')
+    expect(Tidx.resolve(tidx, { chainId: 42431, principal: null }).bearerAuth).toBe(
+      'testnet-secret',
+    )
+    expect(Tidx.resolve(tidx, { chainId: 421_700_001, principal: null }).bearerAuth).toBeUndefined()
+  })
+
+  test('parses serialized Bearer auth by chain id', () => {
+    const tidx = {
+      auth: JSON.stringify({ 421_700_001: 'zone-secret' }),
+      baseUrl: 'https://internal.indexer',
+    }
+
+    expect(Tidx.resolve(tidx, { chainId: 421_700_001, principal: null }).bearerAuth).toBe(
+      'zone-secret',
+    )
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: null }).bearerAuth).toBeUndefined()
+  })
+
   test('the resolver form routes anonymous callers to a separate upstream', () => {
-    const tidx = ({ principal }: Viem.resolve.Context) =>
+    const tidx = ({ principal }: Viem.resolveRpc.Context) =>
       principal?.type === 'public'
         ? { baseUrl: 'https://indexer.tempo.xyz' }
-        : { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' }
+        : { auth: 'user:pass', baseUrl: 'https://internal.indexer' }
     expect(Tidx.resolve(tidx, { chainId: 4217, principal: publicPrincipal }))
       .toMatchInlineSnapshot(`
       {
@@ -268,7 +450,7 @@ describe('getClient', () => {
     try {
       const client = Tidx.getClient({
         chainId: 4217,
-        tidx: { baseUrl: 'https://internal.indexer', bearerAuth: 'zone-secret' },
+        tidx: { auth: 'zone-secret', baseUrl: 'https://internal.indexer' },
       })
       await client.fetch({ query: 'select 1' })
 
@@ -278,6 +460,34 @@ describe('getClient', () => {
       fetch.mockRestore()
     }
   })
+
+  test('sends Zone headers', async () => {
+    const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(JSON.stringify({ columns: [], ok: true, row_count: 0, rows: [] }), {
+        headers: { 'content-type': 'application/json' },
+      }),
+    )
+    try {
+      const client = Tidx.getClient({
+        chainId: Zones.zoneE.id,
+        tidx: {
+          baseUrl: 'https://internal.indexer',
+          zoneHeaders: {
+            'CF-Access-Client-Id': 'client-id',
+            'CF-Access-Client-Secret': 'client-secret',
+          },
+        },
+        zone: Zones.zoneE,
+      })
+      await client.fetch({ query: 'select 1' })
+
+      const upstream = fetch.mock.calls[0]![0] as Request
+      expect(upstream.headers.get('CF-Access-Client-Id')).toBe('client-id')
+      expect(upstream.headers.get('CF-Access-Client-Secret')).toBe('client-secret')
+    } finally {
+      fetch.mockRestore()
+    }
+  })
 })
 
 describe('createGetClient', () => {
@@ -286,33 +496,45 @@ describe('createGetClient', () => {
       tidx: ({ principal }) =>
         principal?.type === 'public'
           ? { baseUrl: 'https://indexer.tempo.xyz' }
-          : { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' },
+          : { auth: 'user:pass', baseUrl: 'https://internal.indexer' },
     })
     // Callers resolving to the same upstream share a client; distinct upstreams
     // (and chain ids) get distinct clients.
-    expect(getTidx(4217, apiKeyPrincipal)).toBe(getTidx(4217, apiKeyPrincipal))
-    expect(getTidx(4217, publicPrincipal)).toBe(getTidx(4217, publicPrincipal))
-    expect(getTidx(4217, publicPrincipal)).not.toBe(getTidx(4217, apiKeyPrincipal))
-    expect(getTidx(4217, apiKeyPrincipal)).not.toBe(getTidx(42431, apiKeyPrincipal))
+    expect(getTidx(4217, { principal: apiKeyPrincipal })).toBe(
+      getTidx(4217, { principal: apiKeyPrincipal }),
+    )
+    expect(getTidx(4217, { principal: publicPrincipal })).toBe(
+      getTidx(4217, { principal: publicPrincipal }),
+    )
+    expect(getTidx(4217, { principal: publicPrincipal })).not.toBe(
+      getTidx(4217, { principal: apiKeyPrincipal }),
+    )
+    expect(getTidx(4217, { principal: apiKeyPrincipal })).not.toBe(
+      getTidx(42431, { principal: apiKeyPrincipal }),
+    )
   })
 
   test('shares a client across principals when the resolver ignores them', () => {
     const getTidx = Tidx.createGetClient()
     // With no resolver the upstream is identical for every caller, so the key
     // (resolved output) collapses and all principals share one client.
-    expect(getTidx(4217, publicPrincipal)).toBe(getTidx(4217, apiKeyPrincipal))
-    expect(getTidx(4217, null)).toBe(getTidx(4217, publicPrincipal))
+    expect(getTidx(4217, { principal: publicPrincipal })).toBe(
+      getTidx(4217, { principal: apiKeyPrincipal }),
+    )
+    expect(getTidx(4217, { principal: null })).toBe(getTidx(4217, { principal: publicPrincipal }))
   })
 
   test('does not share clients across Bearer credentials', () => {
     const getTidx = Tidx.createGetClient({
       tidx: ({ principal }) => ({
+        auth: principal?.type === 'public' ? 'public-secret' : 'private-secret',
         baseUrl: 'https://internal.indexer',
-        bearerAuth: principal?.type === 'public' ? 'public-secret' : 'private-secret',
       }),
     })
 
-    expect(getTidx(4217, publicPrincipal)).not.toBe(getTidx(4217, apiKeyPrincipal))
+    expect(getTidx(4217, { principal: publicPrincipal })).not.toBe(
+      getTidx(4217, { principal: apiKeyPrincipal }),
+    )
   })
 
   test('consults the resolver on every call but builds one client per upstream', () => {
@@ -322,14 +544,14 @@ describe('createGetClient', () => {
         const config =
           principal?.type === 'public'
             ? { baseUrl: 'https://indexer.tempo.xyz' }
-            : { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' }
+            : { auth: 'user:pass', baseUrl: 'https://internal.indexer' }
         seen.push(principal?.type)
         return config
       },
     })
-    const first = getTidx(4217, apiKeyPrincipal)
-    const second = getTidx(4217, apiKeyPrincipal)
-    getTidx(4217, publicPrincipal)
+    const first = getTidx(4217, { principal: apiKeyPrincipal })
+    const second = getTidx(4217, { principal: apiKeyPrincipal })
+    getTidx(4217, { principal: publicPrincipal })
     // The resolver is consulted on every call (it derives the cache key from its
     // resolved output) — including the repeat that hits the cache — so a
     // per-request principal is always honored.