feat(indexer): expose piece metadata endpoint

Add a read-only /index/v0 endpoint that returns the indexed piece metadata field with bounded ID validation and safe error responses.

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

Author: Kubuxu

apps/ponder/ponder.schema.ts

@@ -1,4 +1,4 @@
-import { tableNames } from '@filoz/repair-db'
+import { type JsonRecord, tableNames } from '@filoz/repair-db'
 import { index, onchainTable, primaryKey } from 'ponder'
 
 export const providers = onchainTable(
@@ -27,7 +27,7 @@ export const dataSets = onchainTable(
     providerId: t.int8({ mode: 'bigint' }).notNull(),
     payer: t.text().notNull(),
     source: t.text(),
-    metadata: t.jsonb(),
+    metadata: t.jsonb().$type<JsonRecord | null>(),
     withCdn: t.boolean().notNull(),
     withIpfsIndexing: t.boolean().notNull(),
     pdpEndEpoch: t.int8({ mode: 'bigint' }),
@@ -47,7 +47,7 @@ export const pieces = onchainTable(
     pieceId: t.int8({ mode: 'bigint' }).notNull(),
     cid: t.text().notNull(),
     rawSize: t.int8({ mode: 'bigint' }).notNull(),
-    metadata: t.jsonb(),
+    metadata: t.jsonb().$type<JsonRecord | null>(),
     removed: t.boolean().notNull(),
     addedAtBlock: t.int8({ mode: 'bigint' }).notNull(),
     removedAtBlock: t.int8({ mode: 'bigint' }),

apps/ponder/src/api/index-api.ts

@@ -0,0 +1,43 @@
+import { Hono } from 'hono'
+
+export type FindPieceMetadata = (
+  dataSetId: bigint,
+  pieceId: bigint
+) => Promise<Record<string, string> | null | undefined>
+
+const unsignedInt8 = /^(0|[1-9]\d{0,18})$/
+const maxPostgresBigint = (1n << 63n) - 1n
+
+function parseId(value: string): bigint | undefined {
+  if (!unsignedInt8.test(value)) return undefined
+
+  const id = BigInt(value)
+  return id <= maxPostgresBigint ? id : undefined
+}
+
+export function createIndexApi(findPieceMetadata: FindPieceMetadata) {
+  const app = new Hono()
+
+  app.onError((error, c) => {
+    console.error('Failed to serve piece metadata', error)
+    return c.json({ error: 'Internal server error' }, 500)
+  })
+
+  app.get('/index/v0/datasets/:dataSetId/pieces/:pieceId/metadata', async (c) => {
+    const dataSetId = parseId(c.req.param('dataSetId'))
+    const pieceId = parseId(c.req.param('pieceId'))
+
+    if (dataSetId === undefined || pieceId === undefined) {
+      return c.json({ error: 'dataSetId and pieceId must be unsigned int8 values' }, 400)
+    }
+
+    const metadata = await findPieceMetadata(dataSetId, pieceId)
+    if (metadata === undefined) {
+      return c.json({ error: 'Piece not found' }, 404)
+    }
+
+    return c.json(metadata)
+  })
+
+  return app
+}

apps/ponder/src/api/index.ts

@@ -1,5 +1,16 @@
-import { Hono } from 'hono'
+import { db } from 'ponder:api'
+import { pieces } from 'ponder:schema'
+import { and, eq } from 'ponder'
+import { createIndexApi } from './index-api.ts'
 
-const app = new Hono()
+const app = createIndexApi(async (dataSetId, pieceId) => {
+  const [piece] = await db
+    .select({ metadata: pieces.metadata })
+    .from(pieces)
+    .where(and(eq(pieces.dataSetId, dataSetId), eq(pieces.pieceId, pieceId)))
+    .limit(1)
+
+  return piece?.metadata
+})
 
 export default app

apps/ponder/src/provider-status.ts

@@ -1,7 +1,7 @@
 import type { Context } from 'ponder:registry'
 import { ponder } from 'ponder:registry'
 import { providers } from 'ponder:schema'
-import { and, eq, inArray, notInArray } from 'drizzle-orm'
+import { and, eq, inArray, notInArray } from 'ponder'
 import { ProviderIdSetAbi } from './abis.ts'
 import { NETWORKS } from './networks.ts'
 

apps/ponder/test/index-api.test.ts

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { createIndexApi } from '../src/api/index-api.ts'
+
+test('metadata endpoint returns the metadata field as the response body', async () => {
+  const app = createIndexApi(async (dataSetId, pieceId) => {
+    assert.equal(dataSetId, 123n)
+    assert.equal(pieceId, 42n)
+    return { name: 'example', type: 'application/octet-stream' }
+  })
+
+  const response = await app.request('/index/v0/datasets/123/pieces/42/metadata')
+
+  assert.equal(response.status, 200)
+  assert.deepEqual(await response.json(), { name: 'example', type: 'application/octet-stream' })
+})
+
+test('metadata endpoint distinguishes absent metadata from an unknown piece', async () => {
+  const withoutMetadata = createIndexApi(async () => null)
+  const missingPiece = createIndexApi(async () => undefined)
+
+  const withoutMetadataResponse = await withoutMetadata.request('/index/v0/datasets/123/pieces/42/metadata')
+  const missingPieceResponse = await missingPiece.request('/index/v0/datasets/123/pieces/42/metadata')
+
+  assert.equal(withoutMetadataResponse.status, 200)
+  assert.equal(await withoutMetadataResponse.json(), null)
+  assert.equal(missingPieceResponse.status, 404)
+  assert.deepEqual(await missingPieceResponse.json(), { error: 'Piece not found' })
+})
+
+test('metadata endpoint rejects non-canonical unsigned IDs before querying', async () => {
+  let queryCount = 0
+  const app = createIndexApi(async () => {
+    queryCount++
+    return null
+  })
+
+  for (const path of [
+    '/index/v0/datasets/-1/pieces/42/metadata',
+    '/index/v0/datasets/01/pieces/42/metadata',
+    '/index/v0/datasets/123/pieces/not-a-number/metadata',
+    '/index/v0/datasets/9223372036854775808/pieces/42/metadata',
+    `/index/v0/datasets/${'9'.repeat(1_000)}/pieces/42/metadata`,
+  ]) {
+    const response = await app.request(path)
+    assert.equal(response.status, 400)
+    assert.deepEqual(await response.json(), { error: 'dataSetId and pieceId must be unsigned int8 values' })
+  }
+
+  assert.equal(queryCount, 0)
+})
+
+test('metadata endpoint does not disclose query errors', async () => {
+  const app = createIndexApi(async () => {
+    throw new Error('database connection string leaked')
+  })
+  const consoleError = console.error
+  console.error = () => undefined
+
+  try {
+    const response = await app.request('/index/v0/datasets/123/pieces/42/metadata')
+
+    assert.equal(response.status, 500)
+    assert.deepEqual(await response.json(), { error: 'Internal server error' })
+  } finally {
+    console.error = consoleError
+  }
+})