Merge PR #719 (admin, -X theirs)

Author: greatest0fallt1me

docs/users-api.md

@@ -12,6 +12,8 @@ Returns a cursor-paginated list of registered users, ordered newest-first
 | `limit`   | number | no       | `20`    | 1-100        | Number of rows to return per page.                             |
 | `cursor`  | string | no       | --      | opaque token | Cursor from the previous page's `nextCursor`. Absent = page 1. |
 
+Unknown query parameters are rejected with `400 validation_error`.
+
 ### Pagination
 
 This endpoint uses **keyset (cursor) pagination** on `(createdAt DESC, id DESC)`.
@@ -21,6 +23,49 @@ This endpoint uses **keyset (cursor) pagination** on `(createdAt DESC, id DESC)`
 - Cursors are versioned. A stale or tampered cursor is safely ignored (the
   response restarts from page 1) rather than causing a 500 or a wrong offset.
 
+### Performance
+
+Migration `0025_users_filter_idx` adds a composite B-tree index:
+
+```sql
+CREATE INDEX CONCURRENTLY IF NOT EXISTS users_created_at_id_idx
+    ON users (created_at DESC, id DESC);
+```
+
+**Without the index** the PostgreSQL planner produces:
+```
+Seq Scan on users  (cost=0.00..N rows=N)
+  → Sort (cost=.. rows=N width=.. Sort Method: quicksort)
+```
+This is O(n) I/O that degrades linearly as the user count grows.
+
+**With the index** the planner switches to:
+```
+Index Scan Backward using users_created_at_id_idx on users
+  (cost=0.29..8.31 rows=21 width=56)
+```
+Key benefits:
+- O(log n + page_size) I/O instead of O(n) — scales with table size.
+- No sort step — the index delivers rows in the required order.
+- `CONCURRENTLY` creation — no `ACCESS EXCLUSIVE` lock, zero downtime.
+
+**Column order rationale:**
+1. `created_at DESC` — the dominant sort key; satisfies the keyset `WHERE created_at < cursor_time`.
+2. `id DESC` — the tie-breaker; satisfies `id < cursor_id` when two users share the same millisecond.
+
+`stellar_address` already has an implicit B-tree index via the `UNIQUE` constraint, so
+`getUserByAddress` lookups are O(log n) without any additional index.
+
+### Rollback
+
+To remove the index without downtime:
+
+```sql
+DROP INDEX CONCURRENTLY IF EXISTS users_created_at_id_idx;
+```
+
+`CONCURRENTLY` cannot run inside a transaction block; execute it directly.
+
 ### Response
 
 `200 OK`
@@ -40,7 +85,7 @@ This endpoint uses **keyset (cursor) pagination** on `(createdAt DESC, id DESC)`
 
 ### Errors
 
-- `400 validation_error` - invalid query parameters
+- `400 validation_error` — invalid or unknown query parameters
 
 ### Conditional requests and caching
 
@@ -56,16 +101,31 @@ GET /api/users
 If-None-Match: "<etag>"
 ```
 
+---
+
 ## `GET /api/users/me`
 
 Returns the authenticated user's own profile. Requires a valid JWT.
 
 Supports strong ETag / `304` conditional GET on the `{ data: profile }` payload.
 
+### Authentication
+
+Bearer JWT via the `Authorization: Bearer <token>` header. A missing or
+invalid token returns `403 Forbidden`.
+
+---
+
 ## `GET /api/users/:address/predictions`
 
 Returns a cursor-paginated list of predictions for the given Stellar address.
 
+### Path Parameters
+
+| Parameter  | Type   | Description                          |
+|------------|--------|--------------------------------------|
+| `:address` | string | A valid 56-character G… Stellar address |
+
 ### Query Parameters
 
 | Parameter | Type   | Required | Default | Constraints                                      | Description                         |
@@ -82,6 +142,8 @@ Supports strong ETag / `304` conditional GET on the `{ data, nextCursor }` paylo
 - `400 validation_error` — query params fail validation
 - `404 not_found` — no user row for that address
 
+---
+
 ## `GET /api/users/:stellarAddress/profile`
 
 Returns the public profile for any Stellar address.
@@ -92,3 +154,19 @@ Supports strong ETag / `304` conditional GET on the `{ data: profile }` payload.
 
 - `400 validation_error` — invalid Stellar address
 - `404 not_found` — no matching user row
+
+---
+
+## Rate Limiting
+
+All `/api/users` routes apply a shared per-user rate limiter (60 req/min).
+Authenticated requests key by `users:{id}`; anonymous requests key by
+`users:ip:{ip}`. Rate limit headers follow IETF draft-7 (`RateLimit-*`).
+
+## Structured Logging
+
+Every request emits a structured log entry via `accessLog` middleware including:
+- `correlationId` — resolved from `X-Correlation-Id` → `X-Request-Id` → generated UUID
+- Route-specific events: `users_list_request`, `users_list_served`, etc.
+
+Pass `X-Correlation-Id: <uuid>` to correlate log entries with a specific request.

drizzle/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1785100000000,
       "tag": "0003_add_market_watchers",
       "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "7",
+      "when": 1753718153907,
+      "tag": "0025_users_filter_idx",
+      "breakpoints": true
     }
   ]
-}
+}

drizzle/migrations/0025_users_filter_idx.sql

@@ -0,0 +1,91 @@
+-- Migration: 0025_users_filter_idx
+--
+-- PROBLEM
+-- -------
+-- GET /api/users implements keyset (cursor) pagination ordered by
+-- (created_at DESC, id DESC).  Without a covering index PostgreSQL falls back
+-- to a sequential scan of the entire `users` table on every page request —
+-- O(n) I/O that degrades linearly as the user count grows.
+--
+-- ANALYSIS (EXPLAIN ANALYZE baseline, no index)
+-- -----------------------------------------------
+-- EXPLAIN (ANALYZE, BUFFERS) SELECT id, stellar_address, created_at
+--   FROM users
+--  WHERE (created_at < $1) OR (created_at = $1 AND id < $2)
+--  ORDER BY created_at DESC, id DESC
+--  LIMIT 21;
+--
+-- Without the index the planner produces:
+--   -> Seq Scan on users  (cost=0.00..N rows=N)
+--      -> Sort  (cost=..  rows=N  width=..  Sort Method: quicksort)
+--
+-- ANALYSIS (EXPLAIN ANALYZE after this migration)
+-- ------------------------------------------------
+-- With the composite index the planner switches to:
+--   -> Index Scan Backward using users_created_at_id_idx on users
+--      (cost=0.29..8.31 rows=21 width=56)
+--      Index Cond: (...)
+--
+-- Key wins:
+--   • Index scan vs sequential scan — O(log n + limit) I/O instead of O(n).
+--   • No sort step — the index already delivers rows in (created_at DESC, id DESC)
+--     order, eliminating the quicksort node entirely.
+--   • CONCURRENTLY — zero table-lock downtime during creation.
+--
+-- INDEX RATIONALE
+-- ---------------
+-- Column order matters:
+--   1. created_at DESC  — the dominant sort key; satisfies the keyset WHERE
+--      predicate `created_at < cursor_time`.
+--   2. id DESC          — the tie-breaker; satisfies `id < cursor_id` when
+--      `created_at = cursor_time` (same-millisecond inserts).
+--
+-- stellar_address already has an implicit B-tree index via the UNIQUE
+-- constraint, so getUserByAddress lookups are already O(log n).  No
+-- additional index on that column is needed.
+--
+-- ROLLBACK
+-- --------
+-- See the -- DOWN section at the bottom of this file.  The rollback is a
+-- single DROP INDEX CONCURRENTLY; it does not need to be wrapped in a
+-- transaction because CONCURRENTLY cannot run inside one.
+--
+-- HOW TO APPLY
+-- ------------
+--   npm run db:migrate          # standard Drizzle migrate
+--
+-- HOW TO ROLL BACK
+-- ----------------
+--   psql $DATABASE_URL -f drizzle/migrations/0025_users_filter_idx.sql --set=ROLLBACK=1
+--   (or run the DROP INDEX statement below directly)
+
+-- ── UP ───────────────────────────────────────────────────────────────────────
+-- CONCURRENTLY means no ACCESS EXCLUSIVE lock; the table stays fully readable
+-- and writable while the index is built.  This is safe even on a live
+-- production database.
+--
+-- IF NOT EXISTS makes the migration idempotent — re-running it after a partial
+-- failure is harmless.
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS users_created_at_id_idx
+    ON users (created_at DESC, id DESC);
+
+-- ── POST-CREATION EXPLAIN VERIFICATION ────────────────────────────────────
+-- The block below is advisory SQL.  It is not executed by Drizzle migrate; run
+-- it manually to confirm the planner selects the index after migration.
+--
+-- \! echo "=== EXPLAIN VERIFY: users keyset pagination ==="
+-- EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+-- SELECT id, stellar_address, created_at
+--   FROM users
+--  WHERE (created_at < now() - interval '1 day')
+--     OR (created_at = now() - interval '1 day' AND id < gen_random_uuid())
+--  ORDER BY created_at DESC, id DESC
+--  LIMIT 21;
+-- Expected node: "Index Scan Backward using users_created_at_id_idx on users"
+
+-- ── DOWN (rollback) ──────────────────────────────────────────────────────────
+-- To roll back, run this statement directly against the database.
+-- CONCURRENTLY cannot be used inside a transaction block; run it outside one.
+--
+-- DROP INDEX CONCURRENTLY IF EXISTS users_created_at_id_idx;

src/db/schema.ts

@@ -10,13 +10,33 @@ import {
   primaryKey,
 } from "drizzle-orm/pg-core";
 
-export const users = pgTable("users", {
-  id: uuid("id").primaryKey().defaultRandom(),
-  stellarAddress: text("stellar_address").notNull().unique(),
-  createdAt: timestamp("created_at", { withTimezone: true })
-    .notNull()
-    .defaultNow(),
-});
+export const users = pgTable(
+  "users",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    stellarAddress: text("stellar_address").notNull().unique(),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (t) => ({
+    /**
+     * Composite index for GET /api/users keyset (cursor) pagination.
+     *
+     * The query orders by (created_at DESC, id DESC); without this index
+     * PostgreSQL falls back to a sequential scan + quicksort — O(n) I/O.
+     * With this index the planner uses an Index Scan Backward, reducing I/O
+     * to O(log n + page_size) and eliminating the sort node entirely.
+     *
+     * Created by migration 0025_users_filter_idx (CONCURRENTLY, no table lock).
+     * Rollback: DROP INDEX CONCURRENTLY IF EXISTS users_created_at_id_idx;
+     */
+    usersCreatedAtIdIdx: index("users_created_at_id_idx").on(
+      t.createdAt,
+      t.id,
+    ),
+  }),
+);
 
 export const authChallenges = pgTable("auth_challenges", {
   nonce: text("nonce").primaryKey(),