@everystack/api 0.2.9 → 0.2.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.2.9",
+  "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>",

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]) */
@@ -564,9 +580,16 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
           const result = await verifyUserToken(request, options.auth);
           if (result.error) return result.error;
           user = result.user;
-          if (user && options.auth.onAuthenticated) {
-            options.auth.onAuthenticated(user);
-          }
+        } else if (request.headers.get('authorization')) {
+          // Public RPC with token present — verify opportunistically, same
+          // policy as public table routes below. If valid, the request runs
+          // as authenticated (RLS self-visibility, PII self-tiers). If
+          // invalid, ignore and fall through as anonymous.
+          const result = await verifyUserToken(request, options.auth);
+          if (!result.error) user = result.user;
+        }
+        if (user && options.auth.onAuthenticated) {
+          options.auth.onAuthenticated(user);
         }
       }
 
@@ -598,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),
               )
@@ -610,7 +639,14 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
             kind: 'rpc', name: fnName, user, client,
             result: 'allow', requestId, body: body as Record<string, unknown>,
           });
-          return json(result, 200);
+          // Same cache discipline as table GETs: with pgSettings configured the
+          // response can vary by identity (opportunistic auth on public RPCs),
+          // so it must forbid shared caching ITSELF — never rely on the CDN
+          // config (the cache key carries no identity; a consumer overriding
+          // the stock defaultTtl:0 policy would otherwise cache one user's
+          // personalized response and serve it to everyone).
+          const rpcCacheControl = getCacheControl(options);
+          return json(result, 200, rpcCacheControl ? { 'Cache-Control': rpcCacheControl } : undefined);
         } catch (error) {
           const pgCode = (error as any)?.code;
           let status = 500;
@@ -701,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);
@@ -1933,9 +1975,9 @@ function buildAllConditions(table: DrizzleTable, params: URLSearchParams): { con
   return { conditions };
 }
 
-function json(data: unknown, status: number): Response {
+function json(data: unknown, status: number, headers?: Record<string, string>): Response {
   return new Response(JSON.stringify(data), {
     status,
-    headers: { 'Content-Type': 'application/json' },
+    headers: { 'Content-Type': 'application/json', ...headers },
   });
 }