feat: Apibara reorg patch

README.md

@@ -93,3 +93,35 @@ PR CI is path-filtered and runs component-specific checks:
 - [Game Docs](https://docs.provable.games/summit)
 - [View & Trade Beasts](https://beast-dex.vercel.app/marketplace)
 - [Collect Beasts in Loot Survivor](https://lootsurvivor.io)
+
+## Resource Metrics from Railway Logs
+
+API and indexer now emit structured metric lines in logs with the prefix:
+
+`METRIC resource_metric_v1 {...}`
+
+Defaults:
+
+- `METRICS_ENABLED=true` in production by default
+- `METRICS_INTERVAL_MS=30000`
+- `DB_METRICS_INTERVAL_MS=60000`
+
+To summarize current RAM/CPU/DB pressure from Railway logs:
+
+```bash
+cd indexer
+pnpm metrics:snapshot -- --minutes 10
+```
+
+JSON output (for agent/tool consumption):
+
+```bash
+pnpm metrics:snapshot -- --minutes 10 --json
+```
+
+Verify duplicated metrics modules are in sync:
+
+```bash
+cd indexer
+pnpm metrics:check-sync
+```

api/.gitignore

@@ -3,6 +3,7 @@ node_modules/
 
 # Build output
 dist/
+.cache/
 
 # Environment files
 .env

api/AGENTS.md

@@ -43,9 +43,9 @@ Read [`../AGENTS.md`](../AGENTS.md) first for shared addresses/mechanics and ind
   - subscribe payload: `{"type":"subscribe","channels":["summit","event"]}`
 
 Query/pagination rules agents usually need:
-- `/beasts/all`: `limit` default `25`, max `100`; `offset`; filters `prefix`, `suffix`, `beast_id`, `name`, `owner`; `sort` in `summit_held_seconds|level`.
-- `/logs`: `limit` default `50`, max `100`; `offset`; `category`, `sub_category` (comma-separated), `player`.
-- `/beasts/stats/top`: `limit` default `25`, max `100`; `offset`.
+- `/beasts/all`: `limit` default `25`, max `100`; `offset`; filters `prefix`, `suffix`, `beast_id`, `name`, `owner`; `sort` in `summit_held_seconds|level`; `include_total` optional (`false` skips `count(*)`).
+- `/logs`: `limit` default `50`, max `100`; `offset`; `category`, `sub_category` (comma-separated), `player`; `include_total` optional (`false` skips `count(*)`).
+- `/beasts/stats/top`: `limit` default `25`, max `100`; `offset`; `include_total` optional (`false` skips `count(*)`).
 - `/diplomacy`: `prefix` and `suffix` required; returns HTTP `400` if missing.
 - Paginated routes return `{ data, pagination: { limit, offset, total, has_more } }`.
 
@@ -64,7 +64,7 @@ Behavior details that affect integration:
   - lowercase
   - 66-char `0x` padded form.
 - No auth layer (public read API).
-- No cache layer (responses are DB-backed).
+- Thin in-memory SWR cache is enabled for high-traffic read endpoints.
 
 ## TypeScript and DB Settings
 - `tsconfig.json`: `strict: true`.
@@ -94,3 +94,5 @@ Behavior details that affect integration:
 - `DB_POOL_MAX` (default `15`)
 - `PORT` (default `3001`)
 - `NODE_ENV` (`production` hides debug entries from `/` response)
+- `API_CACHE_ENABLED` (optional; defaults to enabled in production)
+- `API_CACHE_MAX_ENTRIES` (default `500`)

api/README.md

@@ -24,13 +24,15 @@ For AI-oriented coding guidance and deeper architecture notes, read `AGENTS.md`
 ## Environment
 
 - `DATABASE_URL` (required)
-- `DATABASE_SSL` (`"true"` or `"false"`; required in production)
+- `DATABASE_SSL` (`"true"` or `"false"`; defaults to `"true"` in production with a warning when unset)
 - `DB_POOL_MAX` (default `15`)
 - `PORT` (default `3001`)
 - `NODE_ENV` (`production` hides debug entries from `/` discovery payload)
+- `API_CACHE_ENABLED` (optional; defaults to enabled in production)
+- `API_CACHE_MAX_ENTRIES` (optional; default `500`)
 
 Production note:
-- API startup fails fast when `NODE_ENV=production` and `DATABASE_SSL` is unset.
+- When `NODE_ENV=production` and `DATABASE_SSL` is unset, SSL defaults to enabled and a warning is logged.
 
 ## Quick Start
 
@@ -88,18 +90,23 @@ curl http://localhost:3001/health
 ### Query Parameters and Response Shapes
 
 `GET /beasts/all`
-- params: `limit` (default `25`, max `100`), `offset`, `prefix`, `suffix`, `beast_id`, `name`, `owner`, `sort` (`summit_held_seconds|level`)
+- params: `limit` (default `25`, max `100`), `offset`, `prefix`, `suffix`, `beast_id`, `name`, `owner`, `sort` (`summit_held_seconds|level`), `include_total` (`true|false`, default `true`)
 - returns: `{ data: Beast[], pagination: { limit, offset, total, has_more } }`
 
 `GET /logs`
-- params: `limit` (default `50`, max `100`), `offset`, `category`, `sub_category`, `player`
+- params: `limit` (default `50`, max `100`), `offset`, `category`, `sub_category`, `player`, `include_total` (`true|false`, default `true`)
 - `category`/`sub_category` accept comma-separated values
 - returns: `{ data: LogEntry[], pagination: { limit, offset, total, has_more } }`
 
 `GET /beasts/stats/top`
-- params: `limit` (default `25`, max `100`), `offset`
+- params: `limit` (default `25`, max `100`), `offset`, `include_total` (`true|false`, default `true`)
 - returns: paginated top beasts sorted by summit hold time, bonus XP, death timestamp
 
+`include_total=false` behavior:
+- skips `count(*)` query for lower latency
+- returns `pagination.total = null`
+- computes `has_more` via `limit + 1` fetch strategy
+
 `GET /diplomacy`
 - params: `prefix` (required), `suffix` (required)
 - returns HTTP `400` if either is missing
@@ -155,7 +162,17 @@ Realtime pipeline:
 
 - Address inputs are normalized to lowercase 66-char `0x`-padded form.
 - API is public read-only (no auth layer).
-- No dedicated caching layer is used.
+- A thin in-memory SWR cache is applied to high-traffic read endpoints:
+  - `/beasts/all` (common public list patterns)
+  - `/logs`
+  - `/beasts/stats/counts`
+  - `/beasts/stats/top`
+  - `/diplomacy`
+  - `/diplomacy/all`
+  - `/leaderboard`
+  - `/quest-rewards/total`
+  - `/consumables/supply`
+- Cached responses include `X-Cache` with `HIT`, `MISS`, `STALE`, or `BYPASS`.
 - Graceful shutdown closes WS subscriptions/listeners on `SIGINT`/`SIGTERM`.
 
 ## Deployment Notes

api/package.json

@@ -9,7 +9,8 @@
     "lint:ci": "eslint . --max-warnings=0 --report-unused-inline-configs error",
     "start": "node dist/index.js",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "stress:test": "tsx scripts/stress-test.ts"
   },
   "description": "Summit API server with REST endpoints and WebSocket subscriptions",
   "dependencies": {

api/railway.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "watchPatterns": ["api/**"]
+  }
+}