@everystack/api 0.2.10 → 0.2.12

package/package.json

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

@@ -156,6 +156,23 @@ export interface CacheConfig {
   private?: string;
 }
 
+/** Global post-RPC hook — fired after a SUCCESSFUL RPC dispatch, fire-and-forget.
+ *  The RPC counterpart to the per-table after* hooks (afterCreate/afterUpdate/
+ *  afterDelete). RPCs are function-scoped, not table-scoped, so this is global
+ *  rather than keyed by table. Receives the RPC's return value (the row(s) it
+ *  produced), the function name, the request body, the verified user/client, and
+ *  the trace-id ctx. Errors are swallowed and never affect the response — a
+ *  side-effect failure (cache purge, webhook) must not fail the write. Runs only
+ *  on the success path. See docs/plans/afterrpc-cache-purge.md. */
+export type AfterRpcHook = (
+  result: unknown,
+  fnName: string,
+  body: unknown,
+  user: Record<string, unknown> | null,
+  client: Record<string, unknown> | null,
+  ctx: RequestContext,
+) => Promise<void>;
+
 /** RPC handler — plain function (backward compatible).
  *  Plain handlers dispatch directly: no transaction, no pgSettings — they own
  *  their DB access through whatever they close over, same privilege model as
@@ -177,11 +194,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]) */
@@ -196,6 +229,10 @@ export interface HandlerOptions {
   pgSettings?: (user: Record<string, unknown> | null, client?: Record<string, unknown> | null) => Record<string, string>;
   /** Per-table lifecycle hooks for mutations. */
   hooks?: Record<string, HookConfig>;
+  /** Global hook fired after a successful RPC. Fire-and-forget; errors swallowed.
+   *  RPC writes fire no per-table hooks, so this is the only post-RPC side-effect
+   *  seam (cache purge, webhooks, audit enrichment). See docs/plans/afterrpc-cache-purge.md. */
+  afterRpc?: AfterRpcHook;
   /** API naming convention for query params, request bodies, and responses.
    *  'snake_case': accept snake_case inbound, return snake_case outbound.
    *  Default: use Drizzle property names as-is (typically camelCase). */
@@ -605,9 +642,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),
               )
@@ -617,6 +660,12 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
             kind: 'rpc', name: fnName, user, client,
             result: 'allow', requestId, body: body as Record<string, unknown>,
           });
+          // Global post-RPC hook: fire-and-forget side effects (cache purge,
+          // webhooks). Swallow errors — a side-effect failure must not fail the
+          // write, exactly like the after* REST hooks. Success path only.
+          if (options?.afterRpc) {
+            try { await options.afterRpc(result, fnName, body, user, client, ctx); } catch {}
+          }
           // 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
@@ -715,8 +764,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);