tapimo 0.0.0 → 0.0.2

package/src/apps/indexer.test.ts

@@ -0,0 +1,153 @@
+import { RateLimit, Store } from 'cadent'
+import * as TestApp from '../../test/App.js'
+import * as Mppx from '../../test/Mppx.js'
+import * as Runtime from '../../test/runtime.js'
+import * as Tempo from '../../test/Tempo.js'
+import * as Tidx from '../internal/Tidx.js'
+import * as Indexer from './indexer.js'
+
+const chainId = String(Runtime.get().chainId)
+
+describe('GET /indexer/query', () => {
+  test('proxies a query to the upstream indexer', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.indexer.query.$get(
+      // testClient route inputs are query strings, not numbers.
+      { query: { sql: 'select hash from txs limit 1', chainId } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Indexer.schema.Response)
+
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    expect(response.headers.get('content-type')).toMatchInlineSnapshot(`"application/json"`)
+    // A successful response proves the proxy injected TIDX basic auth upstream.
+    expect(body.ok).toMatchInlineSnapshot(`true`)
+    expect(body.columns).toMatchInlineSnapshot(`
+      [
+        "hash",
+      ]
+    `)
+    expect(body.row_count).toMatchInlineSnapshot(`1`)
+    expect(Array.isArray(body.rows)).toMatchInlineSnapshot(`true`)
+  })
+
+  test('escaped string literals round-trip through the real indexer', async () => {
+    // Pins the upstream's accepted escape form: TIDX's ANSI SQL parser only
+    // accepts quote doubling (`''`) inside string literals and rejects
+    // backslash escaping with a parse error, so this fails if `Tidx.escape`
+    // ever regresses to a form the indexer cannot parse.
+    const client = TestApp.client()
+    const value = "a'b\\c"
+    const response = await client.v1.indexer.query.$get(
+      {
+        query: {
+          sql: `select '${Tidx.escape(value)}' as x`,
+          chainId,
+        },
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Indexer.schema.Response)
+
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    expect(body.ok).toMatchInlineSnapshot(`true`)
+    expect(body.rows[0]?.[0]).toBe(value)
+  })
+
+  test('bounds and caches buffered queries', async () => {
+    // Stub the upstream so the injected execution bounds are observable on the
+    // outgoing request; the auth path is in-memory and never touches fetch.
+    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 = TestApp.client()
+      const response = await client.v1.indexer.query.$get(
+        { query: { sql: 'select 1', chainId } },
+        TestApp.auth,
+      )
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      // Buffered (non-`live`) queries are response-cached on the `feed` tier.
+      expect(response.headers.get('cache-control')).toMatchInlineSnapshot(
+        `"private, max-age=10, stale-while-revalidate=30"`,
+      )
+      // Tempo API enforces the documented execution bounds upstream even when the
+      // caller omits them.
+      const upstream = new URL((fetch.mock.calls[0]![0] as Request).url)
+      expect(upstream.searchParams.get('timeout_ms')).toMatchInlineSnapshot(`"5000"`)
+      expect(upstream.searchParams.get('limit')).toMatchInlineSnapshot(`"10000"`)
+    } finally {
+      fetch.mockRestore()
+    }
+  })
+
+  test('requires authentication', async () => {
+    const client = TestApp.client()
+    const response = await client.v1.indexer.query.$get(
+      { query: { sql: 'select 1' } },
+      { headers: { 'tempo-api-key': 'wrong' } },
+    )
+
+    expect(response.status).toMatchInlineSnapshot(`401`)
+  })
+
+  test('proxies without auth middleware', async () => {
+    const client = TestApp.client({ auth: false })
+    const response = await client.v1.indexer.query.$get({
+      query: { sql: 'select hash from txs limit 1', chainId },
+    })
+    const body = await TestApp.json(response, Indexer.schema.Response)
+
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    expect(body.ok).toMatchInlineSnapshot(`true`)
+  })
+
+  test('completes the MPP payment lifecycle when public quota is exhausted', async () => {
+    const rateLimitStore = Store.memory()
+    const app = TestApp.create({
+      rateLimit: { store: rateLimitStore },
+      mpp: {
+        charge: {
+          chainId: Tempo.chain.id,
+          currency: Tempo.currency,
+          decimals: 6,
+          getClient: () => Tempo.client,
+          recipient: Tempo.accounts[2].address,
+        },
+        secretKey: 'secret_test_key_0123456789abcdef',
+      },
+    })
+    await exhaustQuota(RateLimit.memory({ store: rateLimitStore }), 'public:anonymous', {
+      perMinute: 60,
+    })
+
+    // An unpaid over-quota request is challenged for payment. MPP challenges
+    // and receipts ride on real HTTP headers, so we drive the lifecycle
+    // through `app.fetch` rather than the typed route client.
+    const challenge = await app.fetch(
+      new Request('http://tempo-api.test/v1/indexer/query?sql=select%201'),
+    )
+    expect(challenge.status).toMatchInlineSnapshot(`402`)
+    expect(challenge.headers.get('www-authenticate')?.startsWith('Payment ')).toMatchInlineSnapshot(
+      `true`,
+    )
+
+    // Paying the challenge unlocks a real proxied query and returns a receipt.
+    const sql = encodeURIComponent('select hash from txs limit 1')
+    const paid = await Mppx.createClient(app).fetch(
+      `http://tempo-api.test/v1/indexer/query?sql=${sql}&chainId=${chainId}`,
+    )
+    const body = await TestApp.json(paid, Indexer.schema.Response)
+
+    expect(paid.status).toMatchInlineSnapshot(`200`)
+    expect(paid.headers.has('payment-receipt')).toMatchInlineSnapshot(`true`)
+    expect(body.ok).toMatchInlineSnapshot(`true`)
+  })
+})
+
+async function exhaustQuota(rateLimit: RateLimit.Store, key: string, limit: RateLimit.Limit) {
+  for (let index = 0; index < limit.perMinute; index++) await rateLimit.consume({ key, limit })
+}

package/src/apps/indexer.ts

@@ -0,0 +1,330 @@
+import { Hono, type Context, type TypedResponse } from 'hono'
+import * as z from 'zod/mini'
+
+import type * as App from '../App.js'
+import * as Auth from '../internal/Auth.js'
+import * as Cache from '../internal/Cache.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as Path from '../internal/Path.js'
+import * as Response from '../internal/Response.js'
+import * as Schema from '../internal/Schema.js'
+import * as Tidx from '../internal/Tidx.js'
+
+// Request headers that must not be forwarded upstream: hop-by-hop headers, the
+// inbound host, and any caller auth so the consumer's Tempo API credentials never
+// reach the indexer (the proxy injects its own TIDX basic auth instead).
+const strippedHeaders = new Set([
+  'authorization',
+  'connection',
+  'cookie',
+  'host',
+  'keep-alive',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+  'tempo-api-key',
+])
+
+/** Never reached; carries typed passthrough response variants into Hono client inference. */
+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`.',
+          ),
+        ),
+      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']))
+        .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.'))
+
+  /** 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.'))
+}
+
+/** Creates the raw indexer (TIDX) passthrough handler. */
+export function indexer() {
+  const queryCache = Cache.response<App.Environment>({
+    cacheControl: Cache.policies.feed,
+    name: 'tempo-api:indexer:v1',
+    key: (c) => {
+      const url = new URL(c.req.url)
+      if (!url.searchParams.has('chainId') && !url.searchParams.has('chain_id'))
+        url.searchParams.set('chainId', String(c.get('chainId')))
+      url.searchParams.sort()
+      return url.toString()
+    },
+  })
+
+  return new Hono<App.Environment>().get(
+    '/query',
+    Auth.policy({ apiKey: { scopes: ['indexer:query'] }, mpp: true, public: true }),
+    OpenApi.describeRoute({
+      description:
+        'Runs a read-only SQL-style query against Tempo’s indexed chain data, with optional live streaming as new blocks arrive.',
+      operationId: 'indexerQuery',
+      parameters: [
+        {
+          description:
+            'Read-only SQL query to run against Tempo’s indexed chain data. Use `SELECT` statements only.',
+          example: 'SELECT num, hash, timestamp FROM blocks ORDER BY num DESC LIMIT 10',
+          in: 'query',
+          name: 'sql',
+          required: true,
+          schema: { type: 'string' },
+        },
+        {
+          description:
+            'Which Tempo network to query. Use the alias `mainnet` or `testnet`, or a numeric chain id (mainnet is `4217`).',
+          example: 4217,
+          in: 'query',
+          name: 'chainId',
+          required: true,
+          schema: { minimum: 1, type: 'integer' },
+        },
+        {
+          description:
+            'ABI event signature to expose as a named SQL CTE, so you can query decoded event fields directly. Repeat this parameter to add multiple signatures.',
+          example: 'Transfer(address indexed from, address indexed to, uint256 value)',
+          explode: true,
+          in: 'query',
+          name: 'signature',
+          required: false,
+          schema: { items: { type: 'string' }, type: 'array' },
+          style: 'form',
+        },
+        {
+          description:
+            'Choose the indexer engine yourself. By default the indexer routes automatically; `clickhouse` cannot be used with `live=true`.',
+          example: 'postgres',
+          in: 'query',
+          name: 'engine',
+          required: false,
+          schema: { enum: ['postgres', 'clickhouse'], type: 'string' },
+        },
+        {
+          description:
+            'Stream results as Server-Sent Events and re-run the query on every new block. This cannot be combined with `engine=clickhouse`.',
+          example: false,
+          in: 'query',
+          name: 'live',
+          required: false,
+          schema: { default: false, type: 'boolean' },
+        },
+        {
+          description:
+            'Maximum number of rows to return. The server clamps this to the range 1 through 10,000.',
+          example: 10,
+          in: 'query',
+          name: 'limit',
+          required: false,
+          schema: { default: 10000, maximum: 10000, minimum: 1, type: 'integer' },
+        },
+        {
+          description:
+            'Per-query timeout in milliseconds. The server clamps this to the range 100 through 30,000.',
+          example: 5000,
+          in: 'query',
+          name: 'timeout_ms',
+          required: false,
+          schema: { default: 5000, maximum: 30000, minimum: 100, type: 'integer' },
+        },
+      ],
+      responses: {
+        200: {
+          content: {
+            'application/json': {
+              schema: OpenApi.resolver(schema.Response),
+              example: {
+                ok: true,
+                columns: ['num', 'hash', 'timestamp'],
+                rows: [[1234567, '0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665', 1718668800]], // prettier-ignore
+                row_count: 1,
+                engine: 'postgres',
+                query_time_ms: 12,
+              },
+            },
+            // `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) },
+          },
+          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: {
+          content: { 'application/json': { schema: OpenApi.resolver(schema.Error) } },
+          description:
+            'The query parameters are invalid; this uses the upstream indexer’s error shape.',
+        },
+        401: OpenApi.standardError(401, 'Your API key is missing or invalid.'),
+        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.'),
+        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.',
+        ),
+      },
+      summary: 'Query indexed chain data',
+      tags: ['Indexer'],
+    }),
+    (c, next) => (isLive(c) ? next() : queryCache(c, next)),
+    (c) => {
+      if (Auth.narrowAccess) return Auth.paidAccessError(c)
+      if (narrowPassthrough)
+        return c.json(
+          Response.validated(schema.Response, { columns: [], ok: true, row_count: 0, rows: [] }),
+          200,
+        )
+      if (narrowPassthrough)
+        return c.json(
+          Response.validated(schema.Error, { error: 'Invalid query parameters', ok: false }),
+          400,
+        )
+      if (narrowPassthrough)
+        return c.json(
+          Response.validated(schema.Error, {
+            error: 'SQL validation or query execution error',
+            ok: false,
+          }),
+          422,
+        )
+      return passthrough(c, 'v1')
+    },
+  )
+}
+
+async function passthrough(
+  c: Context<App.Environment>,
+  version: string,
+): Promise<globalThis.Response & TypedResponse<never, never, never>> {
+  const tidx = c.get('tidx')
+
+  // Resolve the upstream base URL per chain so mainnet and testnet
+  // requests reach the correct indexer.
+  const chainIdParam = c.req.query('chainId')
+  const parsed = chainIdParam ? Schema.ChainId.safeParse(chainIdParam) : undefined
+  const chainId = parsed?.success ? parsed.data : c.get('chainId')
+  // Resolve the upstream for this caller. A resolver `tidx` can route by
+  // principal (e.g. anonymous `type: 'public'` callers to a public, no-auth
+  // indexer); a static config ignores the principal.
+  const { baseUrl, basicAuth } = Tidx.resolve(tidx, { chainId, principal: Auth.getPrincipal(c) })
+  // The chain id is syntactically valid but this deployment has no indexer
+  // upstream configured for it (no `tidx` config and no built-in default).
+  if (!baseUrl)
+    return Response.error(c, {
+      code: 'chain_id_unsupported',
+      message: 'Unsupported chain id',
+      status: 400,
+    }) as never
+
+  // Strip the `<basePath>/<version>/indexer` mount prefix to recover the
+  // upstream path.
+  const prefix = Path.join(c.get('basePath'), version, 'indexer')
+  const requestUrl = new URL(c.req.url)
+  const rest = requestUrl.pathname.slice(prefix.length) || '/'
+
+  const upstream = new URL(baseUrl)
+  upstream.pathname = Path.join(upstream.pathname, rest)
+  upstream.search = requestUrl.search
+
+  // Enforce the documented execution bounds server-side: an arbitrary SELECT
+  // from an anonymous caller is always bounded even if the upstream's own
+  // defaulting changes. Caller-supplied values pass through (the upstream
+  // clamps them to its documented ranges).
+  if (!upstream.searchParams.has('timeout_ms')) upstream.searchParams.set('timeout_ms', '5000')
+  if (!upstream.searchParams.has('limit')) upstream.searchParams.set('limit', '10000')
+
+  const headers = new Headers()
+  for (const [name, value] of c.req.raw.headers)
+    if (!strippedHeaders.has(name.toLowerCase())) headers.set(name, value)
+  if (basicAuth) headers.set('authorization', `Basic ${btoa(basicAuth)}`)
+
+  const method = c.req.method
+
+  // `duplex` is required when streaming a request body, but is not yet in
+  // the DOM `RequestInit` type.
+  const init: RequestInit & { duplex?: 'half' } = { headers, method, redirect: 'manual' }
+  const body = method === 'GET' || method === 'HEAD' ? null : c.req.raw.body
+  if (body) {
+    init.body = body
+    init.duplex = 'half'
+  }
+  // Bound buffered queries so a hung upstream connection cannot pin the
+  // request forever: the upstream's own per-query ceiling is 30 s, so 35 s
+  // only fires when the connection itself stalls. The SSE `live` stream is
+  // long-lived by design and gets no timeout.
+  if (!isLive(c)) init.signal = AbortSignal.timeout(35_000)
+
+  try {
+    const response = await fetch(new Request(upstream, init))
+
+    // 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>
+  } catch (cause) {
+    // Timeouts and network failures become the standard 502 envelope instead
+    // of an unhandled 500.
+    return Response.upstream(c, cause) as never
+  }
+}
+
+/**
+ * Whether the request asked for the SSE `live` stream. Anything other than an
+ * explicit falsy value counts as live, so an ambiguous value is never buffered
+ * into the response cache or cut off by the passthrough timeout.
+ */
+function isLive(c: Context<App.Environment>): boolean {
+  const live = c.req.query('live')
+  if (live === undefined) return false
+  return !['', '0', 'false'].includes(live.toLowerCase())
+}