experimental-a2 0.4.0 → 0.5.0

package/dist/{client-Bt4tAKi9.js → client-BKlyLiOU.js}

@@ -1,7 +1,7 @@
 import { n as validateSync } from "./validate-XKT4FSNn.js";
 import { t as A2Error } from "./errors-BQuJpe82.js";
-import { a as PRESENCE_TIMINGS, c as STREAM_TIMINGS, g as nullProtoRecord } from "./internal-aEotMzu_.js";
-import { a as eventFromWire, c as isWirePresencePatch, d as presencePatchFromWire, l as isWirePresenceSnapshot, n as errorFromWire, p as presenceSnapshotFromWire, s as isWireEvent, u as parseSocketFrame } from "./wire-DCUZBUlT.js";
+import { a as PRESENCE_TIMINGS, c as STREAM_TIMINGS, g as nullProtoRecord } from "./internal-DstsI6Re.js";
+import { c as isWireEvent, d as parseSocketFrame, f as presencePatchFromWire, l as isWirePresencePatch, m as presenceSnapshotFromWire, o as eventFromWire, r as errorFromWire, u as isWirePresenceSnapshot } from "./wire-BFQmSJ-9.js";
 //#region src/client.ts
 /**
 * experimental-a2/client — the framework-agnostic session client.
@@ -19,6 +19,7 @@ import { a as eventFromWire, c as isWirePresencePatch, d as presencePatchFromWir
 */
 const PUSH_ATTEMPTS = 3;
 const DEFAULT_GC_TIME_MS = 3e5;
+const DEFAULT_HISTORY_LIMIT = 50;
 const httpTransport = (routes, fetchImpl, presence) => ({
 	async *connect({ sessionId, startAfter, signal }) {
 		const sep = routes.stream.includes("?") ? "&" : "?";
@@ -86,6 +87,14 @@ const httpTransport = (routes, fetchImpl, presence) => ({
 		}
 		throw errorFromWire(await res.json().catch(() => null)) ?? new A2Error("STORE_UNAVAILABLE", `push failed with ${res.status}`);
 	},
+	async history({ sessionId, gte, lte }) {
+		const sep = routes.stream.includes("?") ? "&" : "?";
+		const res = await fetchImpl(`${routes.stream}${sep}sessionId=${encodeURIComponent(sessionId)}&gte=${gte}&lte=${lte}`, { headers: { accept: "application/json" } });
+		if (!res.ok) throw errorFromWire(await res.json().catch(() => null)) ?? new A2Error("STORE_UNAVAILABLE", `history failed with ${res.status}`);
+		const rows = await res.json();
+		if (!Array.isArray(rows) || !rows.every(isWireEvent)) throw new A2Error("STORE_UNAVAILABLE", "history response was not a list of events");
+		return rows;
+	},
 	sendPresence(envelope) {
 		(async () => {
 			try {
@@ -100,10 +109,25 @@ const httpTransport = (routes, fetchImpl, presence) => ({
 });
 /** `WebSocket.OPEN` — fixed by the spec, identical in every runtime. */
 const WS_OPEN = 1;
+const wakeChannel = (channel) => {
+	channel.wake?.();
+	channel.wake = null;
+};
+const subscribeFrame = (sessions) => {
+	return JSON.stringify({
+		kind: "subscribe",
+		sessions
+	});
+};
 const wsTransport = (url, webSocketImpl, presence) => {
-	const connections = /* @__PURE__ */ new Map();
-	/** Push retries parked in `awaitReady`, flushed on socket open. */
+	const channels = /* @__PURE__ */ new Map();
+	const pending = /* @__PURE__ */ new Map();
+	/** Push retries parked in `awaitReady`, flushed per session on its
+	* subscribe confirmation. */
 	const readyWaiters = /* @__PURE__ */ new Map();
+	let socket = null;
+	let socketOpen = false;
+	let watchdog;
 	let nextReq = 1;
 	const flushReadyWaiters = (sessionId) => {
 		const waiters = readyWaiters.get(sessionId);
@@ -111,7 +135,7 @@ const wsTransport = (url, webSocketImpl, presence) => {
 		readyWaiters.delete(sessionId);
 		for (const waiter of waiters) waiter();
 	};
-	const socketUrl = (sessionId, startAfter) => {
+	const socketUrl = () => {
 		let resolved;
 		if (/^(https?|wss?):\/\//i.test(url)) resolved = new URL(url);
 		else {
@@ -121,117 +145,239 @@ const wsTransport = (url, webSocketImpl, presence) => {
 		}
 		if (resolved.protocol === "http:") resolved.protocol = "ws:";
 		else if (resolved.protocol === "https:") resolved.protocol = "wss:";
-		resolved.searchParams.set("sessionId", sessionId);
-		resolved.searchParams.set("index", String(startAfter));
 		return resolved.href;
 	};
+	const trySend = (data) => {
+		if (socket === null || !socketOpen) return;
+		try {
+			socket.send(data);
+		} catch {}
+	};
+	const deliver = (channel, frame) => {
+		channel.queue.push(frame);
+		wakeChannel(channel);
+	};
+	const settleChannel = (channel, failure) => {
+		if (channel.ended) return;
+		channel.ended = true;
+		channel.failure = failure;
+		wakeChannel(channel);
+	};
+	const releaseSocket = () => {
+		const current = socket;
+		socket = null;
+		socketOpen = false;
+		clearTimeout(watchdog);
+		watchdog = void 0;
+		if (pending.size > 0) {
+			const rejection = new A2Error("STORE_UNAVAILABLE", "socket closed with the ack outstanding");
+			for (const waiter of pending.values()) waiter.reject(rejection);
+			pending.clear();
+		}
+		return current;
+	};
+	const failSocket = (failure) => {
+		const current = releaseSocket();
+		for (const channel of channels.values()) settleChannel(channel, failure);
+		try {
+			current?.close(1e3);
+		} catch {}
+	};
+	const detach = (channel) => {
+		if (channels.get(channel.sessionId) !== channel) return;
+		channels.delete(channel.sessionId);
+		if (!channel.dropped) {
+			const frame = {
+				kind: "unsubscribe",
+				sessions: [channel.sessionId]
+			};
+			trySend(JSON.stringify(frame));
+		}
+		if (channels.size === 0) {
+			const current = releaseSocket();
+			try {
+				current?.close(1e3);
+			} catch {}
+		}
+	};
+	const armWatchdog = (created) => {
+		clearTimeout(watchdog);
+		watchdog = setTimeout(() => {
+			if (socket !== created) return;
+			failSocket(/* @__PURE__ */ new Error(`socket stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`));
+		}, STREAM_TIMINGS.stallTimeoutMs);
+		watchdog.unref?.();
+	};
+	const route = (frame) => {
+		switch (frame.kind) {
+			case "ping":
+				for (const channel of channels.values()) if (channel.live && !channel.ended) deliver(channel, { kind: "ping" });
+				return;
+			case "subscribed": {
+				const channel = channels.get(frame.sessionId);
+				if (channel === void 0 || channel.ended || channel.live) return;
+				channel.live = true;
+				deliver(channel, { kind: "ping" });
+				flushReadyWaiters(frame.sessionId);
+				return;
+			}
+			case "unsubscribed": {
+				const channel = channels.get(frame.sessionId);
+				if (channel === void 0) return;
+				channel.dropped = true;
+				settleChannel(channel, frame.reason === void 0 ? null : new Error(frame.reason));
+				return;
+			}
+			case "ack": {
+				const waiter = pending.get(frame.req);
+				if (waiter === void 0) return;
+				pending.delete(frame.req);
+				if ("events" in frame) waiter.resolve(frame.events);
+				else waiter.reject(frame.error);
+				return;
+			}
+			case "event": {
+				const channel = channels.get(frame.event.sessionId);
+				if (channel !== void 0 && channel.live && !channel.ended) deliver(channel, {
+					kind: "event",
+					event: frame.event
+				});
+				return;
+			}
+			case "presence": {
+				if (!presence || frame.sessionId === void 0) return;
+				const channel = channels.get(frame.sessionId);
+				if (channel !== void 0 && channel.live && !channel.ended) deliver(channel, {
+					kind: "presence",
+					patch: frame.patch
+				});
+				return;
+			}
+			case "presence-snapshot": {
+				if (!presence || frame.sessionId === void 0) return;
+				const channel = channels.get(frame.sessionId);
+				if (channel !== void 0 && channel.live && !channel.ended) deliver(channel, {
+					kind: "presence-snapshot",
+					snapshot: frame.snapshot
+				});
+				return;
+			}
+		}
+	};
+	const ensureSocket = () => {
+		if (socket !== null) return;
+		if (webSocketImpl === void 0) throw new TypeError("no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing");
+		const created = new webSocketImpl(socketUrl());
+		socket = created;
+		socketOpen = false;
+		armWatchdog(created);
+		created.addEventListener("open", () => {
+			if (socket !== created) return;
+			socketOpen = true;
+			armWatchdog(created);
+			const sessions = [...channels.values()].filter((channel) => !channel.ended).map((channel) => ({
+				id: channel.sessionId,
+				index: channel.startAfter
+			}));
+			if (sessions.length > 0) trySend(subscribeFrame(sessions));
+		});
+		created.addEventListener("message", (event) => {
+			if (socket !== created) return;
+			if (typeof event.data !== "string") return;
+			armWatchdog(created);
+			const frame = parseSocketFrame(event.data);
+			if (frame === null) return;
+			route(frame);
+		});
+		created.addEventListener("close", (event) => {
+			if (socket !== created) return;
+			failSocket(event.code === 1e3 ? null : /* @__PURE__ */ new Error(`socket closed (${event.code}${event.reason ? `: ${event.reason}` : ""})`));
+		});
+		created.addEventListener("error", () => {
+			if (socket !== created) return;
+			failSocket(/* @__PURE__ */ new Error("socket error"));
+		});
+	};
 	return {
 		async *connect({ sessionId, startAfter, signal }) {
-			if (webSocketImpl === void 0) throw new TypeError("no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing");
-			const socket = new webSocketImpl(socketUrl(sessionId, startAfter));
-			const connection = {
-				socket,
-				pending: /* @__PURE__ */ new Map()
-			};
-			connections.set(sessionId, connection);
-			const queue = [];
-			let ended = false;
-			let failure = null;
-			let wake = null;
-			const notify = () => {
-				wake?.();
-				wake = null;
-			};
-			const finish = (error) => {
-				if (ended) return;
-				ended = true;
-				failure = error;
-				if (connections.get(sessionId) === connection) connections.delete(sessionId);
-				const rejection = new A2Error("STORE_UNAVAILABLE", "socket closed with the ack outstanding");
-				for (const waiter of connection.pending.values()) waiter.reject(rejection);
-				connection.pending.clear();
-				notify();
+			const channel = {
+				sessionId,
+				startAfter,
+				queue: [],
+				live: false,
+				dropped: false,
+				ended: false,
+				failure: null,
+				wake: null
 			};
-			socket.addEventListener("open", () => {
-				queue.push({ kind: "ping" });
-				notify();
-				flushReadyWaiters(sessionId);
-			});
-			socket.addEventListener("message", (event) => {
-				if (typeof event.data !== "string") return;
-				const frame = parseSocketFrame(event.data);
-				if (frame === null) return;
-				if (frame.kind === "ack") {
-					const waiter = connection.pending.get(frame.req);
-					if (waiter === void 0) return;
-					connection.pending.delete(frame.req);
-					if ("events" in frame) waiter.resolve(frame.events);
-					else waiter.reject(frame.error);
-					return;
-				}
-				if (!presence && frame.kind !== "event" && frame.kind !== "ping") return;
-				queue.push(frame);
-				notify();
-			});
-			socket.addEventListener("close", (event) => {
-				finish(event.code === 1e3 ? null : /* @__PURE__ */ new Error(`socket closed (${event.code}${event.reason ? `: ${event.reason}` : ""})`));
-			});
-			socket.addEventListener("error", () => {
-				finish(/* @__PURE__ */ new Error("socket error"));
-			});
+			channels.set(sessionId, channel);
+			try {
+				ensureSocket();
+				if (socketOpen) trySend(subscribeFrame([{
+					id: sessionId,
+					index: startAfter
+				}]));
+			} catch (error) {
+				if (channels.get(sessionId) === channel) channels.delete(sessionId);
+				throw error;
+			}
 			const onAbort = () => {
-				finish(signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("stream aborted"));
-				try {
-					socket.close(1e3);
-				} catch {}
+				settleChannel(channel, signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("stream aborted"));
+				detach(channel);
 			};
 			if (signal.aborted) onAbort();
 			else signal.addEventListener("abort", onAbort, { once: true });
+			const pendingSubscribe = setTimeout(() => {
+				if (channel.live) return;
+				settleChannel(channel, /* @__PURE__ */ new Error("subscribe not confirmed: is the ws route serving the multiplexed socket (handle with options.upgrade)?"));
+			}, STREAM_TIMINGS.stallTimeoutMs);
+			pendingSubscribe.unref?.();
 			try {
 				for (;;) {
-					while (queue.length > 0) yield queue.shift();
-					if (ended) {
-						if (failure) throw failure;
+					while (channel.queue.length > 0) yield channel.queue.shift();
+					if (channel.ended) {
+						if (channel.failure) throw channel.failure;
 						return;
 					}
 					await new Promise((resolve) => {
-						wake = resolve;
+						channel.wake = resolve;
 					});
 				}
 			} finally {
+				clearTimeout(pendingSubscribe);
 				signal.removeEventListener("abort", onAbort);
-				finish(null);
-				try {
-					socket.close(1e3);
-				} catch {}
+				settleChannel(channel, null);
+				detach(channel);
 			}
 		},
 		async push(body) {
-			const connection = connections.get(body.sessionId);
-			if (connection === void 0 || connection.socket.readyState !== WS_OPEN) throw new A2Error("STORE_UNAVAILABLE", "no open socket for the session");
+			const channel = channels.get(body.sessionId);
+			const target = socket;
+			if (channel === void 0 || !channel.live || channel.ended || target === null || !socketOpen || target.readyState !== WS_OPEN) throw new A2Error("STORE_UNAVAILABLE", "no open socket for the session");
 			const req = nextReq;
 			nextReq += 1;
 			return await new Promise((resolve, reject) => {
-				connection.pending.set(req, {
+				pending.set(req, {
 					resolve,
 					reject
 				});
 				const frame = {
 					kind: "push",
 					req,
+					sessionId: body.sessionId,
 					events: body.events
 				};
 				try {
-					connection.socket.send(JSON.stringify(frame));
+					target.send(JSON.stringify(frame));
 				} catch (cause) {
-					connection.pending.delete(req);
+					pending.delete(req);
 					reject(new A2Error("STORE_UNAVAILABLE", "socket send failed", { cause }));
 				}
 			});
 		},
 		awaitReady(sessionId, maxWaitMs) {
-			const connection = connections.get(sessionId);
-			if (connection && connection.socket.readyState === WS_OPEN) return Promise.resolve();
+			const channel = channels.get(sessionId);
+			if (channel !== void 0 && channel.live && !channel.ended && socketOpen) return Promise.resolve();
 			return new Promise((resolve) => {
 				let waiters = readyWaiters.get(sessionId);
 				if (!waiters) {
@@ -244,6 +390,7 @@ const wsTransport = (url, webSocketImpl, presence) => {
 					settled = true;
 					clearTimeout(timer);
 					waiters.delete(done);
+					if (waiters.size === 0) readyWaiters.delete(sessionId);
 					resolve();
 				};
 				const timer = setTimeout(done, maxWaitMs);
@@ -252,15 +399,14 @@ const wsTransport = (url, webSocketImpl, presence) => {
 			});
 		},
 		sendPresence(envelope) {
-			const connection = connections.get(envelope.sessionId);
-			if (connection === void 0 || connection.socket.readyState !== WS_OPEN) return;
+			const channel = channels.get(envelope.sessionId);
+			if (channel === void 0 || !channel.live || channel.ended) return;
 			const frame = {
 				kind: "presence",
+				sessionId: envelope.sessionId,
 				...envelope.presence
 			};
-			try {
-				connection.socket.send(JSON.stringify(frame));
-			} catch {}
+			trySend(JSON.stringify(frame));
 		}
 	};
 };
@@ -384,6 +530,14 @@ function createClient(options) {
 				};
 			}
 		};
+		const historyState = () => {
+			const oldestLoaded = serverEvents[0]?.index ?? null;
+			return {
+				loading: historyLoads > 0,
+				complete: oldestLoaded === 1 || frontier === 0,
+				oldestLoaded
+			};
+		};
 		const buildSnapshot = () => {
 			const overlay = overlayEvents();
 			let state = foldedState;
@@ -392,6 +546,7 @@ function createClient(options) {
 				state,
 				events: [...serverEvents, ...overlay],
 				index: frontier,
+				history: historyState(),
 				connection: connection(),
 				...declaresPresence ? { presence: presenceState } : {}
 			};
@@ -565,8 +720,7 @@ function createClient(options) {
 				if (lastPushError.code !== "STORE_UNAVAILABLE") throw lastPushError;
 				if (attempt < PUSH_ATTEMPTS) {
 					const sleepMs = 250 * attempt;
-					if (transport.awaitReady) await transport.awaitReady(sessionId, sleepMs + STREAM_TIMINGS.reconnectBaseMs * attempt);
-					else await new Promise((resolve) => setTimeout(resolve, sleepMs));
+					await Promise.all([new Promise((resolve) => setTimeout(resolve, sleepMs)), transport.awaitReady?.(sessionId, sleepMs + STREAM_TIMINGS.reconnectBaseMs * attempt)]);
 				}
 			}
 			throw lastPushError;
@@ -644,6 +798,59 @@ function createClient(options) {
 				}
 			})());
 		};
+		let historyLoads = 0;
+		/** Calls chain per session: each resolves its bounds after the
+		* prior call's merge, so overlapping backscrolls page backward
+		* instead of re-fetching the same range. */
+		let historyTail = Promise.resolve();
+		const eventsBetween = (gte, lte) => serverEvents.filter((event) => event.index >= gte && event.index <= lte);
+		/** The narrowest sub-range of [gte, lte] missing from the feed, or
+		* null when the range is fully loaded (nothing to fetch). */
+		const missingBetween = (gte, lte) => {
+			const present = new Set(eventsBetween(gte, lte).map((e) => e.index));
+			let lo = gte;
+			while (lo <= lte && present.has(lo)) lo += 1;
+			if (lo > lte) return null;
+			let hi = lte;
+			while (hi > lo && present.has(hi)) hi -= 1;
+			return {
+				gte: lo,
+				lte: hi
+			};
+		};
+		const loadHistory = (loadOptions) => {
+			const readHistory = transport.history;
+			if (readHistory === void 0) throw new TypeError("loadHistory requires an http api — the ws transport has no history lane; serve the session over handle() and pass its route url as the string or { type: \"http\" } api");
+			const before = loadOptions?.before;
+			const limit = loadOptions?.limit;
+			if (before !== void 0 && (!Number.isSafeInteger(before) || before < 1)) throw new TypeError("loadHistory before must be a positive safe integer");
+			if (limit !== void 0 && (!Number.isSafeInteger(limit) || limit < 1)) throw new TypeError("loadHistory limit must be a positive safe integer");
+			touch(sessionId);
+			const run = historyTail.then(async () => {
+				const upper = before ?? serverEvents[0]?.index ?? frontier + 1;
+				const lte = Math.min(upper - 1, frontier);
+				const gte = Math.max(1, upper - (limit ?? DEFAULT_HISTORY_LIMIT));
+				if (gte > lte) return [];
+				const missing = missingBetween(gte, lte);
+				if (missing === null) return eventsBetween(gte, lte);
+				historyLoads += 1;
+				notify();
+				try {
+					const rows = await readHistory({
+						sessionId,
+						...missing
+					});
+					mergeServerEvents(rows.map((row) => eventFromWire(row)), frontier);
+					return eventsBetween(gte, lte);
+				} finally {
+					historyLoads -= 1;
+					notify();
+					touch(sessionId);
+				}
+			});
+			historyTail = run.catch(() => {});
+			return run;
+		};
 		let generation = 0;
 		let active = false;
 		let abort = null;
@@ -729,6 +936,7 @@ function createClient(options) {
 				return snapshot;
 			},
 			push,
+			loadHistory,
 			connect() {
 				touch(sessionId);
 				if (active) return;
@@ -776,7 +984,7 @@ function createClient(options) {
 				notifyHydrated();
 			},
 			canEvict() {
-				return listeners.size === 0 && !active && inFlightPushes === 0 && confirmWatchers.length === 0 && presenceTimer === void 0;
+				return listeners.size === 0 && !active && inFlightPushes === 0 && historyLoads === 0 && confirmWatchers.length === 0 && presenceTimer === void 0;
 			}
 		};
 		return runtime;
@@ -796,3 +1004,5 @@ function createClient(options) {
 }
 //#endregion
 export { createClient as t };
+
+//# sourceMappingURL=client-BKlyLiOU.js.map