@supalive/core 1.12.0 → 1.13.0

package/dist/src/exports/server.js

@@ -1,13 +1,14 @@
-import { n as getContextRegistry } from "../../router-CiWYeWUR.js";
-import { n as stableStringify, r as supaliveStringify, t as groupByToMap } from "../../helper-wGbzz6zo.js";
-import { r as evaluateCacheFreshness } from "../../overlap-checker-BdNoCPtA.js";
-import { i as AuthenticationError, o as ClientMessageSchema } from "../../types_client_rpc-CIsjQQGG.js";
-import { n as RemoteSubscriptionMessageSchema } from "../../types_server-Dk6o_B7N.js";
-import { n as sleep } from "../../realtime_db-e3TztUUT.js";
-import { C as appInstanceId, D as serializeMapValue, E as logger, S as RetentionWatermark, T as logLevelOf, _ as UnregisterSubscriptionResultSchema, a as bootstrapDbTypes, b as UpdateSubscriptionReadSetResultSchema, c as initCore, d as InvalidateWritesetParamsSchema, f as InvalidateWritesetResultSchema, g as UnregisterSubscriptionParamsSchema, h as RegisterSubscriptionResultSchema, i as DB_QUERY_TIMEOUT_MS, l as initDatabase, m as RegisterSubscriptionParamsSchema, n as SubscriptionWorker, o as createDatabase, p as RegisterSubscriptionBatchResultSchema, r as CORE_VERSION, s as initCacheLayer, t as dispatchWorkerMessage, u as CacheLayer, v as UnregisterSubscriptionsResultSchema, w as isProduction, x as RETENTION_WATERMARK_CHANNEL, y as UpdateSubscriptionReadSetParamsSchema } from "../../sub-worker-dispatch-Cl-XnBwq.js";
+import { n as getContextRegistry, u as primaryOnlyConn } from "../../router-Kgrlci8X.js";
+import { n as stableStringify, r as supaliveStringify, t as groupByToMap } from "../../helper-zdJT5FUc.js";
+import { r as evaluateCacheFreshness } from "../../overlap-checker-Kz7B_jsp.js";
+import { i as AuthenticationError, o as ClientMessageSchema } from "../../types_client_rpc-ByGwoRCL.js";
+import { n as RemoteSubscriptionMessageSchema } from "../../types_server-BhC19R2a.js";
+import { n as sleep } from "../../realtime_db-CVze3gM0.js";
+import { n as resolveReadRouting, t as makeConnRouting } from "../../read-routing-BUcQAwnd.js";
+import { C as appInstanceId, D as serializeMapValue, E as logger, S as RetentionWatermark, T as logLevelOf, _ as UnregisterSubscriptionResultSchema, a as bootstrapDbTypes, b as UpdateSubscriptionReadSetResultSchema, c as initCore, d as InvalidateWritesetParamsSchema, f as InvalidateWritesetResultSchema, g as UnregisterSubscriptionParamsSchema, h as RegisterSubscriptionResultSchema, i as DB_QUERY_TIMEOUT_MS, l as initDatabase, m as RegisterSubscriptionParamsSchema, n as SubscriptionWorker, o as createDatabase, p as RegisterSubscriptionBatchResultSchema, r as CORE_VERSION, s as initCacheLayer, t as dispatchWorkerMessage, u as CacheLayer, v as UnregisterSubscriptionsResultSchema, w as isProduction, x as RETENTION_WATERMARK_CHANNEL, y as UpdateSubscriptionReadSetParamsSchema } from "../../sub-worker-dispatch-DJgWxtSQ.js";
+import { v4 } from "uuid";
 import { createServer } from "http";
 import { WebSocket, WebSocketServer } from "ws";
-import { v4 } from "uuid";
 import { ExponentialBackoff, handleAll, retry } from "cockatiel";
 import { sha1 } from "hash-wasm";
 import { Client, Server } from "rpc-websockets";
@@ -78,43 +79,65 @@ async function generateCacheKey(queryName, input, queryIdentity) {
 *
 * Flow (mirrors `handleSubscribe` / worker `register`):
 *   1. Resolve `queryIdentity` → `cacheKey` (identical segmentation to subs).
-*   2. Freshness check via {@link evaluateCacheFreshness}: cached metadata +
-*      the retention watermark + a between-ts commit-log scan.
-*   3. Fresh  → return the cached data.
-*      Stale/miss → recompute via `queryInternal` and write BOTH the data and
-*      the metadata (readSet + snapshotTs) back, so a later one-shot or a fresh
-*      subscription can reuse it.
+*   2. Pick the read connection ONCE (replica when it's caught up to the client's
+*      `clientMinTs`, else primary) and use it for BOTH the freshness scan and
+*      the row reads, so a cache HIT offloads the primary too — not just a miss.
+*   3. Freshness check via {@link evaluateCacheFreshness} on that connection:
+*      cached metadata + the retention watermark + a between-ts commit-log scan.
+*   4. Fresh  → return the cached data.
+*      Stale/miss → recompute via `queryInternalOn` (on the chosen connection)
+*      and write BOTH the data and the metadata (readSet + snapshotTs) back, so
+*      a later one-shot or a fresh subscription can reuse it.
 *
 * The retention guard is what makes an untracked one-shot safe: nothing holds
 * the prune watermark down for it, so an entry whose snapshot has fallen below
 * the oldest retained commit log is treated as a miss (its freshness scan would
 * be incomplete).
 *
-* `lastSnapshotTs` is the freshness upper bound — the latest snapshot ts as of
-* this call. The caller loads it (via `db.getLatestSnapshotTimestamp()`) and
-* passes it in, exactly like the subscribe path loads it before `register`, so
-* the snapshot read lives at the caller seam rather than being hidden here.
+* `lastSnapshotTs` is the primary freshness upper bound — the latest snapshot ts
+* as of this call. The caller loads it (via `db.getLatestSnapshotTimestamp()`)
+* and passes it in, exactly like the subscribe path loads it before `register`,
+* so the snapshot read lives at the caller seam rather than being hidden here.
+*
+* `clientMinTs` is the caller's read high-water (the largest commit/snapshot ts
+* it has already observed). It gates replica routing: a query only runs on the
+* replica when the replica has applied at least `clientMinTs` — otherwise reads
+* (and the freshness scan) stay on the primary, preserving read-your-writes and
+* monotonic reads. It is clamped to `lastSnapshotTs` here, so a client can at
+* most force the primary (never a value beyond it). Returns the data plus the
+* `ts` the result reflects, which the caller echoes so the client can advance
+* its high-water.
 */
-async function runCachedQuery(deps, procedure, procedureName, input, serverCtx, lastSnapshotTs) {
+async function runCachedQuery(deps, procedure, procedureName, input, serverCtx, lastSnapshotTs, clientMinTs) {
 	const queryIdentity = resolveQueryIdentity(procedure, serverCtx, input, deps.getUserId);
 	const cacheKey = await generateCacheKey(procedureName, stableStringify(input), queryIdentity);
+	const routing = await resolveReadRouting(deps.db, lastSnapshotTs, clientMinTs ?? 0n);
+	const readTs = routing.readTs;
 	const metadata = await deps.cache.getQueryCacheMetaData(cacheKey);
-	if ((await evaluateCacheFreshness(deps.db.impl, metadata, lastSnapshotTs, deps.getMinRetainedTs())).fresh) {
+	if ((await evaluateCacheFreshness(routing.readImpl, metadata, readTs, deps.getMinRetainedTs())).fresh) {
 		const cached = await deps.cache.getQueryCacheFor(cacheKey);
 		if (cached && metadata && cached.version === metadata.version) {
-			if (lastSnapshotTs > metadata.lastSnapshotTs) deps.cache.advanceQueryCacheMetadata(cacheKey, {
-				lastSnapshotTs,
+			if (readTs > metadata.lastSnapshotTs) deps.cache.advanceQueryCacheMetadata(cacheKey, {
+				lastSnapshotTs: readTs,
 				version: metadata.version,
 				readSet: metadata.readSet
 			}).catch((err) => logger.error(err, "one-shot horizon advance failed"));
-			return cached.data;
+			const servedTs = readTs > metadata.lastSnapshotTs ? readTs : metadata.lastSnapshotTs;
+			return {
+				data: cached.data,
+				ts: servedTs
+			};
 		}
 	}
-	const result = await deps.db.queryInternal(async (ctx) => {
+	const result = await deps.db.queryInternalOn({
+		impl: routing.readImpl,
+		beginTs: readTs
+	}, async (ctx) => {
 		const fn = procedure.fn;
 		return fn({
 			db: ctx,
-			serverCtx
+			serverCtx,
+			...makeConnRouting(ctx, routing)
 		}, input);
 	});
 	await deps.cache.setQueryCacheAndMetadataFor(cacheKey, result.data, {
@@ -122,7 +145,10 @@ async function runCachedQuery(deps, procedure, procedureName, input, serverCtx,
 		version: String(result.ts),
 		readSet: result.readSet
 	}).catch((err) => logger.error(err, "one-shot query cache write failed"));
-	return result.data;
+	return {
+		data: result.data,
+		ts: result.ts
+	};
 }
 //#endregion
 //#region src/server/sub-manager-client.ts
@@ -595,11 +621,13 @@ var HttpRpcHandler = class {
 		const rawBody = await readBody(req);
 		let name;
 		let rawInput;
+		let minTs;
 		try {
 			const envelope = rawBody.trim().length > 0 ? JSON.parse(rawBody) : {};
 			if (!envelope || typeof envelope !== "object" || typeof envelope.name !== "string") throw new Error("missing procedure name");
 			name = envelope.name;
 			rawInput = envelope.input ?? {};
+			minTs = typeof envelope.minTs === "string" ? parseMinTs$1(envelope.minTs) : void 0;
 		} catch {
 			return this.send(res, 400, {
 				success: false,
@@ -631,10 +659,11 @@ var HttpRpcHandler = class {
 			});
 		}
 		try {
-			const data = await this.runProcedure(procedure, input, auth.ctx);
+			const { data, ts } = await this.runProcedure(procedure, input, auth.ctx, minTs);
 			return this.send(res, 200, {
 				success: true,
-				data
+				data,
+				ts: ts?.toString()
 			});
 		} catch (err) {
 			logger$3.error(err, `RPC "${name}" failed`);
@@ -645,25 +674,32 @@ var HttpRpcHandler = class {
 			});
 		}
 	}
-	async runProcedure(procedure, input, serverCtx) {
+	async runProcedure(procedure, input, serverCtx, minTs) {
 		if (procedure.type === "query") {
 			const lastSnapshotTs = await this.deps.db.impl.getLatestSnapshotTimestamp();
-			return runCachedQuery(this.deps.oneShotDeps, procedure, procedure.name, input, serverCtx, lastSnapshotTs);
+			return runCachedQuery(this.deps.oneShotDeps, procedure, procedure.name, input, serverCtx, lastSnapshotTs, minTs);
+		}
+		if (procedure.type === "mutation") {
+			const res = await this.deps.db.mutation(async (ctx) => {
+				const fn = procedure.fn;
+				return fn({
+					db: ctx,
+					serverCtx,
+					...primaryOnlyConn
+				}, input);
+			});
+			return {
+				data: res.result,
+				ts: res.commitTs
+			};
 		}
-		if (procedure.type === "mutation") return (await this.deps.db.mutation(async (ctx) => {
-			const fn = procedure.fn;
-			return fn({
-				db: ctx,
-				serverCtx
-			}, input);
-		})).result;
 		const fn = procedure.fn;
-		return fn({
+		return { data: await fn({
 			db: this.deps.db,
 			serverCtx,
 			storage: this.deps.storage,
 			scheduler: this.deps.scheduler
-		}, input);
+		}, input) };
 	}
 	async resolveAuth(req) {
 		const data = (this.rpc.auth ?? defaultHttpAuth)(req);
@@ -711,6 +747,16 @@ var HttpRpcHandler = class {
 		res.end(supaliveStringify(body));
 	}
 };
+/** Parse a wire `minTs` (decimal bigint string) to a bigint, or undefined when
+* absent/malformed — a bad value falls back to primary-safe routing. */
+function parseMinTs$1(minTs) {
+	if (minTs === void 0) return void 0;
+	try {
+		return BigInt(minTs);
+	} catch {
+		return;
+	}
+}
 function normalizeRpcPath(p) {
 	let s = p.startsWith("/") ? p : `/${p}`;
 	if (s.length > 1 && s.endsWith("/")) s = s.slice(0, -1);
@@ -1127,7 +1173,7 @@ var SupaliveWebSocketServer = class {
 				await this.handleAuth(session, msg.data);
 				break;
 			case "call":
-				await this.handleCall(session, msg.id, msg.procedure, msg.input);
+				await this.handleCall(session, msg.id, msg.procedure, msg.input, parseMinTs(msg.minTs));
 				break;
 			case "subscribe":
 				await this.handleSubscribe(session, msg.id, msg.procedure, msg.input);
@@ -1206,7 +1252,8 @@ var SupaliveWebSocketServer = class {
 					const result = await this.db.mutation(async (ctx) => {
 						return fn({
 							db: ctx,
-							serverCtx: session.serverCtx
+							serverCtx: session.serverCtx,
+							...primaryOnlyConn
 						}, op.validatedInput);
 					});
 					op.resolve(result);
@@ -1218,7 +1265,7 @@ var SupaliveWebSocketServer = class {
 			session.mutationInFlight = false;
 		}
 	}
-	async handleCall(session, id, procedureName, input) {
+	async handleCall(session, id, procedureName, input, minTs) {
 		if (!this.router) {
 			this.sendError(session, id, "Router not registered", "SERVER_ERROR");
 			return;
@@ -1232,12 +1279,13 @@ var SupaliveWebSocketServer = class {
 			const validatedInput = procedure.inputSchema.parse(input);
 			if (procedure.type === "query") {
 				const lastSnapshotTs = await this.db.impl.getLatestSnapshotTimestamp();
-				const result = await runCachedQuery(this.oneShotDeps, procedure, procedureName, validatedInput, session.serverCtx, lastSnapshotTs);
+				const { data, ts } = await runCachedQuery(this.oneShotDeps, procedure, procedureName, validatedInput, session.serverCtx, lastSnapshotTs, minTs);
 				this.sendMessage(session, {
 					type: "response",
 					id,
 					success: true,
-					data: result
+					data,
+					ts: ts.toString()
 				});
 			} else if (procedure.type === "mutation") {
 				if (session.mutationQueue.length >= MAX_MUTATION_QUEUE_BUFFER) {
@@ -1249,7 +1297,8 @@ var SupaliveWebSocketServer = class {
 					type: "response",
 					id,
 					success: true,
-					data: mutationResult.result
+					data: mutationResult.result,
+					ts: mutationResult.commitTs.toString()
 				});
 			} else if (procedure.type === "action") {
 				if (session.actionInFlight >= MAX_ACTION_CONCURRENCY) {
@@ -1301,14 +1350,18 @@ var SupaliveWebSocketServer = class {
 			let data;
 			let dataHash;
 			let liveResult = null;
+			let servedTs;
 			session.subIds.add(subId);
 			if (existingServerSub) {
 				existingServerSub.subscribedTimes += 1;
 				const cached = await this.cache.getQueryCacheFor(existingServerSub.cacheKey);
-				if (cached) data = cached.data;
-				else {
+				if (cached) {
+					data = cached.data;
+					servedTs = cached.lastSnapshotTs;
+				} else {
 					liveResult = await this.executeLiveQuery(procedureName, validatedInput, session.serverCtx);
 					data = liveResult.data;
+					servedTs = liveResult.ts;
 				}
 			} else {
 				const lastSnapshotTs = await this.db.impl.getLatestSnapshotTimestamp();
@@ -1321,11 +1374,19 @@ var SupaliveWebSocketServer = class {
 					instanceName: this.instanceId,
 					lastSnapshotTs
 				});
-				const cached = await this.cache.getQueryCacheFor(subManagerResult.cacheKey);
-				if (cached && !subManagerResult.recompute && cached.version === subManagerResult.version) data = cached.data;
-				else {
+				let rebuild = true;
+				if (!subManagerResult.recompute) {
+					const cached = await this.cache.getQueryCacheFor(subManagerResult.cacheKey);
+					if (cached && cached.version === subManagerResult.version) {
+						data = cached.data;
+						servedTs = cached.lastSnapshotTs;
+						rebuild = false;
+					}
+				}
+				if (rebuild) {
 					liveResult = await this.executeLiveQuery(procedureName, validatedInput, session.serverCtx);
 					data = liveResult.data;
+					servedTs = liveResult.ts;
 				}
 				this.serverSubscriptions.set(subId, {
 					subId,
@@ -1341,7 +1402,7 @@ var SupaliveWebSocketServer = class {
 					lastSnapshotTs: liveResult.ts,
 					readSet: liveResult.readSet,
 					instanceName: this.instanceId
-				}), this.cache.setQueryCacheFor(cacheKey, data, String(liveResult.ts))]);
+				}), this.cache.setQueryCacheFor(cacheKey, data, liveResult.ts)]);
 				if (!updateResult.tracked) logger$2.warn(`updateSubscriptionReadSet returned tracked:false immediately after register for ${subId} — possible sub-manager restart mid-subscribe`);
 			}
 			dataHash = await getHashOf(data);
@@ -1355,7 +1416,8 @@ var SupaliveWebSocketServer = class {
 				type: "sub:update",
 				subId,
 				data,
-				dataHash
+				dataHash,
+				ts: servedTs.toString()
 			});
 			logger$2.info(`Subscribed: ${subId} for session ${session.id}`);
 		} catch (err) {
@@ -1588,18 +1650,20 @@ var SupaliveWebSocketServer = class {
 				lastSnapshotTs: liveResult.ts,
 				readSet: liveResult.readSet,
 				instanceName: this.instanceId
-			}), this.cache.setQueryCacheFor(affected.cacheKey, liveResult.data, String(liveResult.ts))]);
+			}), this.cache.setQueryCacheFor(affected.cacheKey, liveResult.data, liveResult.ts)]);
 			if (!updateResult.tracked) {
 				this.dropSubscriptionLocally(affected.subId, "no longer tracked by sub-manager");
 				return;
 			}
+			const ts = liveResult.ts.toString();
 			for (const [, session] of this.sessions) if (session.subIds.has(affected.subId)) this.sendMessage(session, {
 				type: "sub:update",
 				subId: affected.subId,
 				data: liveResult.data,
-				dataHash
+				dataHash,
+				ts
 			});
-			if (affected.notifyInstances.length > 0) await this.publishSubscriptionUpdate(affected.subId, liveResult.data, dataHash, affected.notifyInstances);
+			if (affected.notifyInstances.length > 0) await this.publishSubscriptionUpdate(affected.subId, liveResult.data, dataHash, affected.notifyInstances, ts);
 			logger$2.debug(`Re-executed affected query for subId: ${affected.subId}`);
 		} catch (err) {
 			logger$2.error(err, `Failed to re-execute query for subId ${affected.subId}`);
@@ -1612,7 +1676,8 @@ var SupaliveWebSocketServer = class {
 			const fn = procedure.fn;
 			return fn({
 				db: ctx,
-				serverCtx
+				serverCtx,
+				...primaryOnlyConn
 			}, input);
 		});
 	}
@@ -1724,7 +1789,8 @@ var SupaliveWebSocketServer = class {
 					type: "sub:update",
 					subId: parsed.subId,
 					data: parsed.data,
-					dataHash: parsed.dataHash
+					dataHash: parsed.dataHash,
+					ts: parsed.ts
 				});
 			}
 			return;
@@ -1745,13 +1811,14 @@ var SupaliveWebSocketServer = class {
 			notifyInstances: req.notifyInstances
 		});
 	}
-	async publishSubscriptionUpdate(subId, data, dataHash, notifyInstances) {
+	async publishSubscriptionUpdate(subId, data, dataHash, notifyInstances, ts) {
 		const payload = supaliveStringify({
 			type: "update",
 			subId,
 			data,
 			dataHash,
-			originInstance: this.instanceId
+			originInstance: this.instanceId,
+			ts
 		});
 		const publishPromises = notifyInstances.map(async (instance) => {
 			if (instance === this.instanceId) return;
@@ -1765,6 +1832,16 @@ var SupaliveWebSocketServer = class {
 		await Promise.all(publishPromises);
 	}
 };
+/** Parse a wire `minTs` (decimal bigint string) to a bigint, or undefined when
+* absent/malformed — a bad value simply falls back to primary-safe routing. */
+function parseMinTs(minTs) {
+	if (minTs === void 0) return void 0;
+	try {
+		return BigInt(minTs);
+	} catch {
+		return;
+	}
+}
 /** Normalize a job path to a leading-slash, no-trailing-slash prefix. */
 function normalizeJobPath(p) {
 	let s = p.startsWith("/") ? p : `/${p}`;