@everystack/api 0.2.10 → 0.2.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -30,11 +30,6 @@
       "default": "./src/client/index.ts"
     }
   },
-  "scripts": {
-    "test": "jest",
-    "build": "tsc --build",
-    "lint": "tsc --noEmit"
-  },
   "peerDependencies": {
     "drizzle-orm": "0.41.0"
   },
@@ -45,5 +40,10 @@
     "jest": "29.7.0",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3"
+  },
+  "scripts": {
+    "test": "jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
   }
-}
+}

package/src/handler/index.ts

@@ -177,11 +177,27 @@ export interface RpcHandlerWithRole {
    *  connection without the settings, and on a single-connection pool
    *  (Lambda) they deadlock against the open transaction. */
   settings?: boolean;
+  /** Route this RPC's ANONYMOUS calls to `options.readDb` (the read replica)
+   *  when one is configured. Authenticated callers stay on the primary
+   *  (read-your-writes). Only meaningful with `settings: true` — plain RPCs
+   *  own their DB access through what they close over, so there is nothing
+   *  for the handler to route (use createReadDb() in the fn instead). The
+   *  fn must not write: on a real replica a write fails with "cannot
+   *  execute … in a read-only transaction". */
+  readOnly?: boolean;
 }
 
 export interface HandlerOptions {
   auth?: AuthConfig;
   rpc?: Record<string, RpcHandler | RpcHandlerWithRole>;
+  /** Read-replica connection (e.g. createReadDb from @everystack/server/db).
+   *  When provided, ANONYMOUS GET table reads execute against it; writes,
+   *  authenticated requests, and RPCs stay on the primary `db`. RPCs opt in
+   *  per-function with `readOnly: true`. Anonymous-only routing is what makes
+   *  replication lag safe: authenticated users never read the replica, so
+   *  read-your-writes holds trivially. Omitted → behavior identical to a
+   *  single-connection handler. See docs/plans/read-replica-routing.md. */
+  readDb?: DrizzleDb;
   /** Relation definitions for resource embedding: { [sourceTable]: { [relationName]: RelationConfig } } */
   relations?: Record<string, Record<string, RelationConfig>>;
   /** Base path to strip from request URL (e.g., '/api' when mounted at /api/[...path]) */
@@ -605,9 +621,15 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
           // go through a captured db that waits on the connection the
           // transaction holds). Only `settings: true` entries get the
           // transaction, and they receive it as the 4th argument.
+          // Read routing: a readOnly-marked settings RPC serves ANONYMOUS
+          // callers from the replica. Authenticated callers stay on the
+          // primary (read-your-writes).
+          const rpcDb = isObjectForm && entry.readOnly && !user && options?.readDb
+            ? options.readDb
+            : db;
           const result = isObjectForm && entry.settings
             ? await executeWithSettings(
-                db,
+                rpcDb,
                 options?.pgSettings?.(user, client),
                 (tx) => fn(body, user, client, tx, ctx),
               )
@@ -715,8 +737,14 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
       }
     }
 
+    // Read routing: anonymous GETs serve from the replica when one is
+    // configured. `user` is resolved (incl. opportunistic auth) above, so an
+    // authenticated GET stays on the primary — read-your-writes holds because
+    // only anonymous traffic can ever reach the replica. Writes never route.
+    const routedDb = method === 'GET' && !user && options?.readDb ? options.readDb : db;
+
     try {
-      const response = await executeWithSettings(db, settings, async (dbOrTx) => {
+      const response = await executeWithSettings(routedDb, settings, async (dbOrTx) => {
         if (method === 'GET') {
           const cacheControl = getCacheControl(options);
           return handleGet(dbOrTx, schema, table, tableName, url.searchParams, request, options, cacheControl);