tapimo 0.14.0 → 0.15.1

package/src/apps/data/routes/indexer.ts

@@ -37,54 +37,112 @@ const narrowPassthrough = false as boolean
 /** Zod schemas owned by the indexer passthrough. */
 export namespace schema {
   /** Structured result returned by the indexer `query` endpoint. */
-  export const Response = z
-    .object({
-      ok: z
-        .boolean()
-        .check(
-          z.describe('Whether the SQL query completed successfully.'),
-          z.meta({ examples: [true] }),
-        ),
-      columns: z
-        .array(z.string())
-        .check(z.describe('Column names returned by the query, in row-value order.')),
-      rows: z
-        .array(z.array(z.unknown()))
-        .check(
-          z.describe(
-            'Query results. Each row is an array of values in the same order as `columns`.',
+  export const Response = OpenApi.component(
+    z
+      .object({
+        ok: z
+          .boolean()
+          .check(
+            z.describe('Whether the SQL query completed successfully.'),
+            z.meta({ examples: [true] }),
           ),
-        ),
-      row_count: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Number of rows returned in this response.'),
-          z.meta({ examples: [1] }),
-        ),
-      engine: z
-        .optional(z.enum(['postgres', 'clickhouse', 'tiered']))
-        .check(
-          z.describe('Indexer engine that ran the query.'),
-          z.meta({ examples: ['postgres'] }),
-        ),
-      query_time_ms: z
-        .optional(z.number())
-        .check(
-          z.describe('Server-side query execution time in milliseconds.'),
-          z.meta({ examples: [12] }),
-        ),
-    })
-    .check(z.describe('Structured result from a Tempo indexer SQL query.'))
+        columns: z
+          .array(z.string())
+          .check(
+            z.describe('Column names returned by the query, in row-value order.'),
+            z.meta({ examples: [['num', 'hash', 'timestamp']] }),
+          ),
+        rows: z
+          .array(z.array(z.unknown()))
+          .check(
+            z.describe(
+              'Query results. Each row is an array of values in the same order as `columns`.',
+            ),
+            z.meta({ examples: [[[1_234_567, `0x${'aa'.repeat(32)}`, 1_718_668_800]]] }),
+          ),
+        row_count: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Number of rows returned in this response.'),
+            z.meta({ examples: [1] }),
+          ),
+        engine: z
+          .optional(z.enum(['postgres', 'clickhouse', 'tiered']))
+          .check(
+            z.describe('Indexer engine that ran the query.'),
+            z.meta({ examples: ['postgres'] }),
+          ),
+        query_time_ms: z
+          .optional(z.number())
+          .check(
+            z.describe('Server-side query execution time in milliseconds.'),
+            z.meta({ examples: [12] }),
+          ),
+      })
+      .check(z.describe('Structured result from a Tempo indexer SQL query.')),
+    'IndexerQueryResponse',
+  )
 
   /** Error envelope returned by the upstream indexer. */
-  export const Error = z
-    .object({
-      ok: z.literal(false).check(z.describe('Always `false` when the indexer returns an error.')),
-      error: z.string().check(z.describe('Human-readable error message from the indexer.')),
-    })
-    .check(z.describe('Error response returned by the upstream Tempo indexer.'))
+  export const Error = OpenApi.component(
+    z
+      .object({
+        ok: z.literal(false).check(z.describe('Always `false` when the indexer returns an error.')),
+        error: z
+          .string()
+          .check(
+            z.describe('Human-readable error message from the indexer.'),
+            z.meta({ examples: ['Only SELECT queries are supported'] }),
+          ),
+      })
+      .check(z.describe('Error response returned by the upstream Tempo indexer.')),
+    'IndexerQueryError',
+  )
+
+  /** Tempo error envelope returned before a query reaches the indexer. */
+  export const RequestError = OpenApi.component(
+    Schema.errorResponse(['api_key_malformed', 'chain_id_invalid', 'chain_id_unsupported']),
+    'IndexerQueryRequestError',
+  )
+
+  /** Either error envelope that a rejected indexer request can return. */
+  export const BadRequest = OpenApi.component(
+    z
+      .union([Error, RequestError])
+      .check(
+        z.describe('An upstream query error or a Tempo authentication or chain-selection error.'),
+      ),
+    'IndexerQueryBadRequest',
+  )
+
+  /** Tempo error envelope returned when the upstream indexer cannot be reached. */
+  export const TempoUpstreamError = OpenApi.component(
+    Schema.errorResponse(['upstream_error']),
+    'IndexerQueryTempoUpstreamError',
+  )
+
+  /** Either error envelope returned when the indexer cannot complete a request. */
+  export const UpstreamFailure = OpenApi.component(
+    z
+      .union([Error, TempoUpstreamError])
+      .check(z.describe('An upstream indexer error or a Tempo upstream error.')),
+    'IndexerQueryUpstreamFailure',
+  )
+
+  /** Server-Sent Event stream returned for live indexer queries. */
+  export const EventStream = OpenApi.component(
+    z.string().check(
+      z.describe('A stream of indexer result, error, and lagged events.'),
+      z.meta({
+        examples: [
+          'event: result\ndata: {"ok":true,"columns":["num"],"rows":[[1234567]],"row_count":1}\n\n',
+        ],
+      }),
+    ),
+    'IndexerQueryEventStream',
+  )
 }
 
 /** Creates the raw indexer (TIDX) passthrough handler. */
@@ -124,8 +182,13 @@ export function indexer() {
           example: 4217,
           in: 'query',
           name: 'chainId',
-          required: true,
-          schema: { minimum: 1, type: 'integer' },
+          required: false,
+          schema: {
+            anyOf: [
+              { enum: ['mainnet', 'testnet'], type: 'string' },
+              { minimum: 1, type: 'integer' },
+            ],
+          },
         },
         {
           description:
@@ -191,31 +254,34 @@ export function indexer() {
             },
             // `live=true` streams Server-Sent Events: `result` events carry this
             // same shape, alongside `error` and `lagged` events.
-            'text/event-stream': { schema: OpenApi.resolver(schema.Response) },
+            'text/event-stream': { schema: OpenApi.resolver(schema.EventStream) },
           },
           description:
             'Structured result from a Tempo indexer SQL query. When `live=true` the response is a `text/event-stream` (SSE) of `result` events with this same shape, interleaved with `error` and `lagged` events, re-run on every new block.',
           headers: OpenApi.successHeaders,
         },
-        // 400 and 422 are the upstream indexer's own error shape (`{ ok: false, error }`),
-        // not the Tempo API JSON error envelope; the auth/rate-limit/proxy errors below are.
+        // 400 covers both the upstream indexer shape and Tempo's error envelope.
+        // 422 remains the upstream indexer shape; the other errors are Tempo envelopes.
         400: {
-          content: { 'application/json': { schema: OpenApi.resolver(schema.Error) } },
+          content: { 'application/json': { schema: OpenApi.resolver(schema.BadRequest) } },
           description:
-            'The query parameters are invalid; this uses the upstream indexer’s error shape.',
+            'The query is invalid, the API key is malformed, or the selected chain is invalid or unsupported. Query errors use the indexer envelope; Tempo errors use the standard API envelope.',
         },
-        401: OpenApi.standardError(401, 'Your API key is missing or invalid.'),
+        401: OpenApi.standardError(401, 'The API key is missing or invalid.'),
+        403: OpenApi.standardError(403, 'The API key cannot query the selected indexer.'),
         422: {
           content: { 'application/json': { schema: OpenApi.resolver(schema.Error) } },
           description:
             'The SQL failed validation or execution; this uses the upstream indexer’s error shape.',
         },
-        429: OpenApi.standardError(429, 'You have exceeded the rate limit.'),
+        429: OpenApi.standardError(429, 'The request exceeded its rate limit.'),
         500: OpenApi.standardError(500, 'The Tempo API encountered an internal server error.'),
-        502: OpenApi.standardError(
-          502,
-          'The upstream Tempo indexer could not complete the request.',
-        ),
+        502: {
+          content: { 'application/json': { schema: OpenApi.resolver(schema.UpstreamFailure) } },
+          description:
+            'The indexer could not complete the request. Indexer HTTP errors retain the indexer envelope; network failures use the Tempo envelope.',
+        },
+        504: OpenApi.standardError(504, 'The request timed out before it completed.'),
       },
       summary: 'Query indexed chain data',
       tags: ['Indexer'],
@@ -228,6 +294,23 @@ export function indexer() {
           Response.validated(schema.Response, { columns: [], ok: true, row_count: 0, rows: [] }),
           200,
         )
+      if (narrowPassthrough)
+        return c.text(
+          'event: result\ndata: {"ok":true,"columns":[],"rows":[],"row_count":0}\n\n',
+          200,
+        )
+      if (narrowPassthrough)
+        return Response.error(c, {
+          code: 'chain_id_invalid',
+          message: 'Invalid chain id',
+          status: 400,
+        })
+      if (narrowPassthrough)
+        return Response.error(c, {
+          code: 'chain_id_unsupported',
+          message: 'Unsupported chain id',
+          status: 400,
+        })
       if (narrowPassthrough)
         return c.json(
           Response.validated(schema.Error, { error: 'Invalid query parameters', ok: false }),
@@ -241,6 +324,18 @@ export function indexer() {
           }),
           422,
         )
+      if (narrowPassthrough)
+        return c.json(
+          Response.validated(schema.Error, { error: 'Indexer unavailable', ok: false }),
+          502,
+        )
+      if (narrowPassthrough) return Response.upstream(c, new Error('Indexer passthrough failed'))
+      if (narrowPassthrough)
+        return Response.error(c, {
+          code: 'request_timeout',
+          message: 'Request timed out',
+          status: 504,
+        })
       return passthrough(c, 'v1')
     },
   )
@@ -319,25 +414,26 @@ async function passthrough(
   if (!live) init.signal = AbortSignal.timeout(35_000)
 
   try {
-    const { failure, response } = await Timing.time(c, 'tidx', async () => {
+    const { body, failure, response } = await Timing.time(c, 'tidx', async () => {
       const response = await fetch(new Request(upstream, init))
       // Syntax/validation failures belong to the caller, not the dependency's
       // operational error ratio.
-      const failure = Tidx.isQueryRejection(response)
-        ? undefined
-        : live
-          ? response.ok
-            ? undefined
-            : Tidx.providerFailure(response)
-          : await Tidx.responseFailure(response)
-      return { failure, response }
+      if (Tidx.isQueryRejection(response))
+        return { body: response.body, failure: undefined, response }
+      if (live)
+        return {
+          body: response.body,
+          failure: response.ok ? undefined : Tidx.providerFailure(response),
+          response,
+        }
+      const inspection = await Tidx.inspectResponse(response)
+      return { ...inspection, response }
     })
     c.set('providerFailure', failure ? { ...failure, chainId } : undefined)
 
     // Stream the upstream response back verbatim so both JSON queries and
     // SSE `live` streams pass through untouched.
-    return c.newResponse(response.body, response) as globalThis.Response &
-      TypedResponse<never, never, never>
+    return c.newResponse(body, response) as globalThis.Response & TypedResponse<never, never, never>
   } catch (cause) {
     // Timeouts and network failures become the standard 502 envelope instead
     // of an unhandled 500.

package/src/apps/data/routes/receipts.test.ts

@@ -1,7 +1,7 @@
 /** @module-tag localnet */
 
-import { Schema } from 'tapimo'
 import { FxOracle } from 'tapimo/apps'
+import { Schema } from 'tapimo/server'
 import { Hex, Value as core_Value } from 'ox'
 import { zeroHash } from 'viem'