statewire 0.19.4 → 0.21.0

package/dist/host/socket.js

@@ -1,9 +1,10 @@
 import { encodeDocument, reviveDocumentValue } from "../document.js";
+import { COMMAND_CAPACITY_RETRY_MS, MAX_INFLIGHT_COMMANDS_PER_HOST } from "../wire/limits.js";
 import { DEFAULT_PROTOCOL, WIRE_VERSION, negotiateProtocols } from "../wire/protocol.js";
+import { captureContext, contextValue } from "../wire/context.js";
 import { sanitizeValue } from "../wire/ops.js";
 import { StatewireSendError } from "../types.js";
 import { documentIdentity, getCommandsHost, getStateHost } from "./host.js";
-import { COMMAND_CAPACITY_RETRY_MS, MAX_INFLIGHT_COMMANDS_PER_HOST } from "../wire/limits.js";
 import { createMacrotaskPoster } from "../util/macrotask.js";
 import { frames, stream } from "./http.js";
 import { useEffect, useState } from "@assistant-ui/tap/react-shim";
@@ -40,11 +41,11 @@ const parseFrameValue = (frame) => {
 	if (!isPlainObject(frame)) return violation("malformed frame");
 	const keys = Object.keys(frame);
 	if (keys.length === 0) return violation("malformed frame");
-	const unknown = keys.filter((key) => key !== "cmd").sort();
+	const unknown = keys.filter((key) => key !== "cmd" && key !== "ctx").sort();
 	if (unknown.length > 0) return violation(`unknown frame key: '${unknown[0]}'`);
-	const lane = frame["cmd"];
+	const lane = frame["cmd"] ?? [];
 	if (!Array.isArray(lane)) return violation("malformed frame");
-	if (lane.length === 0) return violation("empty lane");
+	if (Object.hasOwn(frame, "cmd") && lane.length === 0) return violation("empty lane");
 	if (lane.length > 256) return violation("too many commands");
 	const prev = /* @__PURE__ */ new Map();
 	const cmd = [];
@@ -65,7 +66,39 @@ const parseFrameValue = (frame) => {
 			...statement["meta"] !== void 0 && { meta: statement["meta"] }
 		});
 	}
-	return { cmd };
+	const contexts = frame["ctx"];
+	const ctx = [];
+	if (contexts !== void 0) {
+		if (!Array.isArray(contexts) || contexts.length === 0) return violation("empty context lane");
+		const seen = /* @__PURE__ */ new Set();
+		for (const entry of contexts) {
+			if (!isPlainObject(entry) || typeof entry["protocol"] !== "string" || !Object.hasOwn(entry, "value") || Object.keys(entry).some((key) => ![
+				"protocol",
+				"value",
+				"meta"
+			].includes(key))) return violation("malformed context");
+			const protocol = entry["protocol"];
+			if (seen.has(protocol)) return violation("duplicate context protocol");
+			seen.add(protocol);
+			if (frameEncoder.encode(JSON.stringify(entry)).byteLength > 65536) return violation("context entry too large");
+			try {
+				ctx.push({
+					protocol,
+					value: contextValue({
+						value: entry["value"],
+						...entry["meta"] !== void 0 && { meta: entry["meta"] }
+					})
+				});
+			} catch (error) {
+				return violation(error instanceof Error ? error.message : "invalid context");
+			}
+		}
+	}
+	if (cmd.length === 0 && ctx.length === 0) return violation("empty frame");
+	return {
+		cmd,
+		...ctx.length > 0 && { ctx }
+	};
 };
 const parseFrame = (raw) => {
 	let frame;
@@ -116,11 +149,13 @@ const cmdOf = (adm, outcome) => {
 				...encodePayload(failure.payload)
 			};
 		}
-		default: return {
-			...at,
-			type: "failed",
-			message: outcome.error instanceof Error ? outcome.error.message : String(outcome.error)
-		};
+		default:
+			console.error("statewire command failed", outcome.error);
+			return {
+				...at,
+				type: "failed",
+				message: "the command failed"
+			};
 	}
 };
 const parseInitialFrame = (raw) => {
@@ -178,6 +213,10 @@ const closeConn = (h, conn, code, reason) => {
 	if (!conn.open) return;
 	conn.open = false;
 	h.conns.delete(conn);
+	if (conn.leaseTimer !== null) {
+		clearTimeout(conn.leaseTimer);
+		conn.leaseTimer = null;
+	}
 	try {
 		conn.socket.close(code, reason);
 	} catch {}
@@ -196,6 +235,35 @@ const sendTo = (h, conn, data) => {
 		closeConn(h, conn);
 	}
 };
+const expiredAt = (h, authorizedAt) => {
+	const now = Date.now();
+	return authorizedAt === void 0 || !Number.isFinite(authorizedAt) || authorizedAt < 0 || authorizedAt > now || h.maxLeaseLifetimeMs !== null && now - authorizedAt >= h.maxLeaseLifetimeMs;
+};
+const leaseExpiredFin = JSON.stringify({ fin: {
+	reason: "reconnect",
+	code: "lease-expired"
+} });
+const expireLease = (h, conn) => {
+	if (!conn.open || expiredAt(h, conn.authorizedAt)) {
+		if (conn.open) {
+			sendTo(h, conn, leaseExpiredFin);
+			closeConn(h, conn, 1e3, "lease-expired");
+		}
+		return true;
+	}
+	return false;
+};
+const armLeaseTimer = (h, conn) => {
+	if (conn.leaseTimer !== null) clearTimeout(conn.leaseTimer);
+	conn.leaseTimer = null;
+	if (h.disposed || h.maxLeaseLifetimeMs === null || expireLease(h, conn)) return;
+	const delay = h.maxLeaseLifetimeMs - (Date.now() - conn.authorizedAt);
+	conn.leaseTimer = setTimeout(() => {
+		conn.leaseTimer = null;
+		if (!expireLease(h, conn)) armLeaseTimer(h, conn);
+	}, Math.min(delay, 2147483647));
+	conn.leaseTimer.unref?.();
+};
 const violate = (h, conn, reason) => {
 	sendTo(h, conn, JSON.stringify({ fin: {
 		reason: "protocol-error",
@@ -293,6 +361,13 @@ const attachOf = (h, conn) => {
 		return entry;
 	};
 	return {
+		get caller() {
+			return callerOf(h, h.clients.get(conn.clientId), conn);
+		},
+		context: (protocol) => {
+			requireSelected(protocol);
+			return captureContext(conn.contexts.get(protocol) ?? {});
+		},
 		document: (protocol, key) => {
 			if (key === void 0 && protocol === h.protocol.name) return h.stateHost.snapshot();
 			const view = viewOf(h, conn);
@@ -537,6 +612,7 @@ const admitCmd = (h, lane, conn, statement) => {
 		clientId: rec.id,
 		caller: callerOf(h, rec, conn),
 		attach: conn.attach,
+		context: captureContext(conn.contexts.get(statement.protocol) ?? {}),
 		onApplied: () => {
 			if (adm.settled || adm.applied) return;
 			adm.applied = true;
@@ -562,7 +638,32 @@ const refusal = (h, conn, retry) => ({
 		...retry !== void 0 && { retry }
 	} }
 });
+const validateContexts = (h, conn, frame) => {
+	for (const statement of frame.cmd) {
+		if (!selects(conn, statement.protocol)) return violation("unsupported protocol");
+		if (conn.selection.protocols.find((p) => p.name === statement.protocol).record === "ephemeral") {
+			const through = watermark(h, conn, statement.protocol);
+			const first = frame.cmd.find((s) => s.protocol === statement.protocol && s.seq > through);
+			if (first && first.seq !== through + 1) return violation("ephemeral lane gap");
+		}
+	}
+	for (const entry of frame.ctx ?? []) {
+		if (!selects(conn, entry.protocol)) return violation("unsupported context protocol");
+		try {
+			h.current?.validateContext?.(entry.protocol, captureContext(entry.value), conn.attach);
+		} catch (error) {
+			return violation(error instanceof Error ? error.message : "invalid context");
+		}
+	}
+};
+const installContexts = (h, conn, frame) => {
+	for (const entry of frame.ctx ?? []) conn.contexts.set(entry.protocol, captureContext(entry.value));
+	for (const entry of frame.ctx ?? []) h.current?.contextChanged?.(entry.protocol, captureContext(entry.value), conn.attach);
+};
 const admitFrame = (h, conn, frame) => {
+	if (expireLease(h, conn)) return { type: "expired" };
+	validateContexts(h, conn, frame);
+	installContexts(h, conn, frame);
 	const rec = h.clients.get(conn.clientId);
 	rec.touched = Date.now();
 	const lanes = new Map(frame.cmd.map((s) => [s.protocol, laneOf(h, conn, s.protocol)]));
@@ -594,6 +695,7 @@ const admitFrame = (h, conn, frame) => {
 			return refusal(h, conn, retry);
 		}
 	}
+	if (expireLease(h, conn)) return { type: "expired" };
 	for (const s of fresh) admitCmd(h, lanes.get(s.protocol), conn, s);
 	for (const [protocol, lane] of lanes) {
 		const last = fresh.findLast((s) => s.protocol === protocol);
@@ -608,7 +710,7 @@ const admitFrame = (h, conn, frame) => {
 	return { type: "ok" };
 };
 const message = (h, conn, data) => {
-	if (!conn.open || h.disposed || h.finished !== null) return;
+	if (!conn.open || h.disposed || h.finished !== null || expireLease(h, conn)) return;
 	if (frameIsOversized(data)) {
 		sendTo(h, conn, JSON.stringify({ fin: {
 			reason: "protocol-error",
@@ -626,7 +728,7 @@ const message = (h, conn, data) => {
 	let admission;
 	try {
 		const frame = first ? parseInitialFrame(data).frame : parseFrame(data);
-		if (frame.cmd.length === 0) return;
+		if (frame.cmd.length === 0 && !frame.ctx?.length) return;
 		admission = admitFrame(h, conn, frame);
 	} catch (error) {
 		const reason = violationReason(error);
@@ -690,7 +792,18 @@ const normalizedHeaders = (headers) => {
 };
 const connectAuthorized = (h, clientId, socket, options) => {
 	const authorize = h.authorize;
-	if (options.authorized === true) return register(h, clientId, socket, options.authorized === true, options.auth, options.selection)?.connection ?? null;
+	if (options.authorized === true) {
+		if (expiredAt(h, options.authorizedAt)) {
+			try {
+				socket.send(leaseExpiredFin);
+			} catch {}
+			try {
+				socket.close(1e3, "lease-expired");
+			} catch {}
+			return null;
+		}
+		return register(h, clientId, socket, options.authorized === true, options.auth, options.selection, void 0, options.authorizedAt)?.connection ?? null;
+	}
 	const refuse = (code, reason) => {
 		try {
 			socket.close(code, reason);
@@ -781,19 +894,20 @@ const connectAuthorized = (h, clientId, socket, options) => {
 			pending.authorizing = true;
 			Promise.resolve().then(() => authorize?.({ headers })).then((auth) => {
 				if (!pending.open || h.disposed || h.finished !== null) return;
+				const authorizedAt = Date.now();
 				const selection = negotiateProtocols(new Headers(headers), h.wireVersion, [h.protocol]);
 				if ("fin" in selection) {
 					sendPending(pending, JSON.stringify(selection));
 					closePending(h, pending, 1008, selection.fin.message);
 					return;
 				}
-				options.onAuthorized?.(auth, selection);
+				options.onAuthorized?.(auth, selection, authorizedAt);
 				pending.open = false;
 				h.pendingConns.delete(pending);
 				if (pending.timer !== null) clearTimeout(pending.timer);
 				let registration;
 				try {
-					registration = register(h, clientId, socket, true, auth, selection, frame);
+					registration = register(h, clientId, socket, true, auth, selection, frame, authorizedAt);
 				} catch (error) {
 					if (violationReason(error) === null) throw error;
 					return;
@@ -837,7 +951,7 @@ const register = (h, clientId, socket, sawFrame = false, auth = void 0, selectio
 		name: h.protocol.name,
 		version: h.protocol.version
 	}]
-}, frame = { cmd: [] }) => {
+}, frame = { cmd: [] }, authorizedAt) => {
 	const refuse = (code, reason) => {
 		try {
 			socket.close(code, reason);
@@ -855,6 +969,12 @@ const register = (h, clientId, socket, sawFrame = false, auth = void 0, selectio
 		return null;
 	}
 	if (atSubscriberLimit(h)) return refuseSubscriberLimit(socket);
+	if (expiredAt(h, authorizedAt)) {
+		try {
+			socket.send(leaseExpiredFin);
+		} catch {}
+		return refuse(1e3, "lease-expired");
+	}
 	const known = h.clients.get(clientId);
 	if (known !== void 0 && !authEquals(known.principal, auth)) {
 		try {
@@ -887,7 +1007,10 @@ const register = (h, clientId, socket, sawFrame = false, auth = void 0, selectio
 		lastSentAt: 0,
 		lease: null,
 		auth,
+		authorizedAt,
+		leaseTimer: null,
 		lanes: /* @__PURE__ */ new Map(),
+		contexts: /* @__PURE__ */ new Map(),
 		documents: /* @__PURE__ */ new Map(),
 		included: /* @__PURE__ */ new Set(),
 		view: /* @__PURE__ */ new Map(),
@@ -899,13 +1022,19 @@ const register = (h, clientId, socket, sawFrame = false, auth = void 0, selectio
 	conn.attach = attachOf(h, conn);
 	h.conns.add(conn);
 	try {
+		validateContexts(h, conn, frame);
+		installContexts(h, conn, frame);
 		h.current?.attaching?.(conn.attach);
 	} catch (error) {
-		closeConn(h, conn, 1011, "attach failed");
+		const reason = violationReason(error);
+		if (reason !== null) violate(h, conn, reason);
+		else closeConn(h, conn, 1011, "attach failed");
 		throw error;
 	}
 	gcClients(h);
 	ensureHeartbeat(h);
+	armLeaseTimer(h, conn);
+	if (!conn.open) return null;
 	const isEphemeral = (s) => selection.protocols.find((p) => p.name === s.protocol)?.record === "ephemeral";
 	const early = frame.cmd.filter(isEphemeral);
 	const late = frame.cmd.filter((s) => !isEphemeral(s));
@@ -923,6 +1052,7 @@ const register = (h, clientId, socket, sawFrame = false, auth = void 0, selectio
 	const earlyAdmission = admit(early);
 	if (early.length > 0) flush(h);
 	notifyClientRecords(h);
+	if (expireLease(h, conn)) return null;
 	const ops = [];
 	if (selects(conn, h.protocol.name)) {
 		const { value, meta } = encodeDocument(h.stateHost.snapshot());
@@ -981,9 +1111,14 @@ const resume = (h) => {
 	h.disposed = false;
 	h.stateHost?.setOnOp((op) => recordOp(h, op));
 	h.stateHost?.setOnDocuments(() => markViews(h));
+	for (const conn of h.conns) armLeaseTimer(h, conn);
 };
 const suspend = (h) => {
 	h.disposed = true;
+	for (const conn of h.conns) {
+		if (conn.leaseTimer !== null) clearTimeout(conn.leaseTimer);
+		conn.leaseTimer = null;
+	}
 	if (h.heartbeatTimer !== null) {
 		clearInterval(h.heartbeatTimer);
 		h.heartbeatTimer = null;
@@ -1017,6 +1152,7 @@ const useSocketHost = (transport, options, persistence) => {
 			key: void 0,
 			wireVersion: { version: WIRE_VERSION },
 			heartbeatMs: 15e3,
+			maxLeaseLifetimeMs: 864e5,
 			wsInitTimeoutMs: 5e3,
 			maxSubscribers: MAX_SUBSCRIBERS,
 			maxInflightCommands: MAX_INFLIGHT_COMMANDS_PER_HOST,
@@ -1054,11 +1190,17 @@ const useSocketHost = (transport, options, persistence) => {
 	});
 	h.protocol = options?.protocol ?? {
 		name: "default",
-		version: "2026-09-13"
+		version: "2026-09-30"
 	};
 	h.key = options?.key;
-	h.wireVersion = options?.wireVersion ?? { version: "2026-09-13" };
+	h.wireVersion = options?.wireVersion ?? { version: "2026-09-30" };
 	setHeartbeatMs(h, options?.heartbeatIntervalMs ?? 15e3);
+	const maxLeaseLifetimeMs = options?.maxLeaseLifetimeMs === void 0 ? 864e5 : options.maxLeaseLifetimeMs;
+	if (maxLeaseLifetimeMs !== null && (!Number.isFinite(maxLeaseLifetimeMs) || maxLeaseLifetimeMs <= 0)) throw new TypeError("maxLeaseLifetimeMs must be finite and positive or null");
+	if (h.maxLeaseLifetimeMs !== maxLeaseLifetimeMs) {
+		h.maxLeaseLifetimeMs = maxLeaseLifetimeMs;
+		for (const conn of [...h.conns]) armLeaseTimer(h, conn);
+	}
 	h.pushback = options?.pushback;
 	h.wsInitTimeoutMs = options?.wsInitTimeoutMs ?? 5e3;
 	const maxSubscribers = options?.maxSubscribers === void 0 ? MAX_SUBSCRIBERS : options.maxSubscribers;
@@ -1117,6 +1259,6 @@ const StatewireSocketHost = (transport, options, persistence) => {
 	};
 };
 //#endregion
-export { CLIENT_ID_RE, PRINCIPAL_MISMATCH_MESSAGE, SUBSCRIBER_LIMIT_MESSAGE, StatewireSocketHost, admitFrame, atSubscriberLimit, authEquals, closeConn, flush, parseFrame, parseFrameValue, register, sendTo };
+export { CLIENT_ID_RE, PRINCIPAL_MISMATCH_MESSAGE, SUBSCRIBER_LIMIT_MESSAGE, StatewireSocketHost, admitFrame, atSubscriberLimit, authEquals, closeConn, expireLease, flush, parseFrame, parseFrameValue, register, sendTo };
 
 //# sourceMappingURL=socket.js.map