devframe 0.8.2 → 0.9.0-beta.2

package/dist/rpc/transports/sse-client.mjs

@@ -0,0 +1,142 @@
+import { DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_SSE_SESSION_HEADER } from "../../constants.mjs";
+import { t as createRpcWireCodec } from "../../wire-codec-9VhIKnyp.mjs";
+//#region src/rpc/transports/sse-client.ts
+function NOOP() {}
+/**
+* Build a birpc `ChannelOptions` object backed by an SSE stream (server →
+* client) and HTTP `POST` (client → server) — the WebSocket-free counterpart
+* to `createWsRpcChannel`, wire-compatible with `attachSseRpcTransport`.
+*
+* The stream is consumed via `fetch` streaming (not `EventSource`), so it
+* works in browsers and server runtimes alike. The server's first frame
+* (`event: session`) carries the session id; every `POST` echoes it in the
+* `x-birpc-session` header. A response to a client-initiated request comes
+* back in the `POST`'s own body and is re-injected into the channel; a
+* dropped stream terminates the channel — there is no reconnect, matching
+* the WS channel's closed-is-done semantics.
+*/
+function createSseRpcChannel(options) {
+	const { onConnected = NOOP, onError = NOOP, onDisconnected = NOOP, definitions, fetch: fetchImpl = globalThis.fetch.bind(globalThis) } = options;
+	let url = options.url;
+	if (options.authToken) url = `${url}${url.includes("?") ? "&" : "?"}${DEVFRAME_AUTH_TOKEN_QUERY_PARAM}=${encodeURIComponent(options.authToken)}`;
+	const codec = createRpcWireCodec(definitions);
+	const abort = new AbortController();
+	let closed = false;
+	let onMessage;
+	let activeReader;
+	let resolveSession;
+	let rejectSession;
+	const sessionReady = new Promise((resolve, reject) => {
+		resolveSession = resolve;
+		rejectSession = reject;
+	});
+	sessionReady.catch(() => {});
+	function fail(error) {
+		if (closed) return;
+		closed = true;
+		rejectSession(error);
+		onError(error);
+		onDisconnected();
+	}
+	function end() {
+		if (closed) return;
+		closed = true;
+		rejectSession(/* @__PURE__ */ new Error("Devframe SSE stream closed"));
+		onDisconnected();
+	}
+	function dispatch(event, data) {
+		if (event === "session") {
+			resolveSession(data);
+			onConnected();
+			return;
+		}
+		onMessage?.(data);
+	}
+	/** Parse the SSE byte stream frame by frame and dispatch each event. */
+	async function consume(stream) {
+		const reader = stream.getReader();
+		activeReader = reader;
+		const decoder = new TextDecoder();
+		let buffer = "";
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			for (;;) {
+				const boundary = buffer.search(/\n\n|\r\n\r\n/);
+				if (boundary < 0) break;
+				const frame = buffer.slice(0, boundary);
+				buffer = buffer.slice(boundary + (buffer[boundary] === "\r" ? 4 : 2));
+				let event = "message";
+				const data = [];
+				for (const rawLine of frame.split(/\r?\n/)) {
+					if (rawLine.startsWith(":")) continue;
+					if (rawLine.startsWith("event:")) event = rawLine.slice(6).trimStart();
+					else if (rawLine.startsWith("data:")) data.push(rawLine.slice(5).replace(/^ /, ""));
+				}
+				if (data.length > 0) dispatch(event, data.join("\n"));
+			}
+		}
+		end();
+	}
+	(async () => {
+		try {
+			const response = await fetchImpl(url, {
+				headers: { accept: "text/event-stream" },
+				signal: abort.signal
+			});
+			if (!response.ok || !response.body) throw new Error(`Devframe SSE stream request failed: ${response.status}`);
+			await consume(response.body);
+		} catch (error) {
+			if (abort.signal.aborted) {
+				end();
+				return;
+			}
+			fail(error instanceof Error ? error : new Error(String(error)));
+		}
+	})();
+	return {
+		close: () => {
+			closed = true;
+			abort.abort();
+			activeReader?.cancel().catch(() => {});
+		},
+		on: (handler) => {
+			onMessage = handler;
+		},
+		post: async (data) => {
+			let sessionId;
+			try {
+				sessionId = await sessionReady;
+			} catch {
+				return;
+			}
+			if (closed) {
+				onError(/* @__PURE__ */ new Error("Devframe SSE channel is closed; message dropped"));
+				return;
+			}
+			try {
+				const response = await fetchImpl(url, {
+					method: "POST",
+					headers: {
+						"content-type": "text/plain; charset=utf-8",
+						[DEVFRAME_SSE_SESSION_HEADER]: sessionId
+					},
+					body: data
+				});
+				if (response.status === 200) {
+					const body = await response.text();
+					if (body) onMessage?.(body);
+					return;
+				}
+				if (!response.ok) throw new Error(`Devframe SSE POST failed: ${response.status}`);
+			} catch (error) {
+				onError(error instanceof Error ? error : new Error(String(error)));
+			}
+		},
+		serialize: codec.serialize,
+		deserialize: codec.deserialize
+	};
+}
+//#endregion
+export { createSseRpcChannel };

package/dist/rpc/transports/sse-server.d.mts

@@ -0,0 +1,61 @@
+import { v as RpcFunctionDefinitionAny } from "../../types-CnJSgRVa.mjs";
+import { d as DevframeRpcConnection, n as WsOriginRegistry, u as DevframeNodeRpcSessionMeta } from "../../ws-server-Ces08fjP.mjs";
+import { BirpcGroup } from "birpc";
+//#region src/rpc/transports/sse-server.d.ts
+interface SseRpcTransportOptions {
+  /**
+   * Same contract as `WsRpcTransportOptions.allowedOrigins`: extra origins
+   * to accept beyond the loopback default, a live origin registry, or
+   * `false` to disable the gate. Applied to the stream `GET`, the RPC
+   * `POST`, and the CORS preflight alike.
+   */
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false;
+  /**
+   * RPC function definitions, used by the per-call wire serializer to
+   * dispatch between strict-JSON and structured-clone encoding based on
+   * each function's `jsonSerializable` flag. When omitted, all messages
+   * fall back to structured-clone — same contract as the WS transport.
+   */
+  definitions?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>;
+  onConnected?: (connection: DevframeRpcConnection, meta: DevframeNodeRpcSessionMeta) => void;
+  onDisconnected?: (connection: DevframeRpcConnection, meta: DevframeNodeRpcSessionMeta) => void;
+  /**
+   * Milliseconds between keep-alive comment frames (`: ping`) written to
+   * every open stream, so intermediaries (reverse proxies, tunnels) don't
+   * drop an idle connection. `0` disables. Default: `30_000`.
+   */
+  keepAliveInterval?: number;
+  /** Mint a session id. Default: `crypto.randomUUID`. */
+  generateSessionId?: () => string;
+}
+interface SseRpcTransport {
+  /**
+   * Web-standard handler for the SSE route: `GET` opens the event stream,
+   * `POST` carries RPC frames (session id in the `x-birpc-session` header),
+   * `OPTIONS` answers the CORS preflight for registered cross-origin
+   * viewers. Mount it on the route the connection meta advertises.
+   */
+  handler: (request: Request) => Promise<Response> | Response;
+  /** Number of currently connected SSE sessions. */
+  sessionCount: () => number;
+  /** Terminate every open stream and detach their birpc channels. */
+  close: () => void;
+}
+/**
+ * Attach an SSE + HTTP POST transport to an existing RPC group — the
+ * WebSocket-free counterpart to `attachWsRpcTransport`, for hosts and
+ * proxies where the upgrade isn't available. Speaks the same birpc wire
+ * protocol (one channel per session, per-method `jsonSerializable`
+ * dispatch) over a half-duplex pair, mirroring birpc's own SSE helpers:
+ *
+ *  - the server mints a session id as the stream's first frame
+ *    (`event: session`);
+ *  - every client `POST` echoes it in the `x-birpc-session` header;
+ *  - a client-initiated request's response comes back in that `POST`'s
+ *    own body (parked until the handler answers);
+ *  - server-initiated calls/events stream down as `event: message`
+ *    frames, and the client's replies up via `POST` get a bare `202`.
+ */
+declare function attachSseRpcTransport<ClientFunctions extends object, ServerFunctions extends object>(rpcGroup: BirpcGroup<ClientFunctions, ServerFunctions, false>, options?: SseRpcTransportOptions): SseRpcTransport;
+//#endregion
+export { SseRpcTransport, SseRpcTransportOptions, attachSseRpcTransport };

package/dist/rpc/transports/sse-server.mjs

@@ -0,0 +1,209 @@
+import { DEVFRAME_SSE_SESSION_HEADER } from "../../constants.mjs";
+import { n as peekRpcWireFrame, t as createRpcWireCodec } from "../../wire-codec-9VhIKnyp.mjs";
+import { i as isAllowedOrigin, o as createRpcSessionMeta } from "../../ws-server-Bk1hOG3X.mjs";
+//#region src/rpc/transports/sse-server.ts
+const SSE_STREAM_HEADERS = {
+	"content-type": "text/event-stream",
+	"cache-control": "no-cache, no-transform",
+	"x-accel-buffering": "no"
+};
+function NOOP() {}
+/**
+* Attach an SSE + HTTP POST transport to an existing RPC group — the
+* WebSocket-free counterpart to `attachWsRpcTransport`, for hosts and
+* proxies where the upgrade isn't available. Speaks the same birpc wire
+* protocol (one channel per session, per-method `jsonSerializable`
+* dispatch) over a half-duplex pair, mirroring birpc's own SSE helpers:
+*
+*  - the server mints a session id as the stream's first frame
+*    (`event: session`);
+*  - every client `POST` echoes it in the `x-birpc-session` header;
+*  - a client-initiated request's response comes back in that `POST`'s
+*    own body (parked until the handler answers);
+*  - server-initiated calls/events stream down as `event: message`
+*    frames, and the client's replies up via `POST` get a bare `202`.
+*/
+function attachSseRpcTransport(rpcGroup, options = {}) {
+	const { allowedOrigins, definitions, onConnected = NOOP, onDisconnected = NOOP, keepAliveInterval = 3e4, generateSessionId = () => crypto.randomUUID() } = options;
+	const sessions = /* @__PURE__ */ new Map();
+	const encoder = new TextEncoder();
+	function originAllowed(request) {
+		if (allowedOrigins === false) return true;
+		const origin = request.headers.get("origin") ?? void 0;
+		return allowedOrigins && !Array.isArray(allowedOrigins) ? allowedOrigins.isAllowed(origin) : isAllowedOrigin(origin, allowedOrigins ?? []);
+	}
+	/**
+	* CORS headers for a browser on another (allowed) origin — the side-car /
+	* registered-viewer case. Same-origin requests carry no `Origin` (or their
+	* own), where these headers are inert.
+	*/
+	function corsHeaders(request) {
+		const origin = request.headers.get("origin");
+		if (!origin) return {};
+		return {
+			"access-control-allow-origin": origin,
+			"vary": "origin"
+		};
+	}
+	function openStream(request) {
+		const meta = createRpcSessionMeta();
+		const id = generateSessionId();
+		const codec = createRpcWireCodec(definitions);
+		let controller;
+		let keepAlive;
+		let closeSession = () => {};
+		function write(text) {
+			try {
+				controller?.enqueue(encoder.encode(text));
+			} catch {
+				closeSession();
+			}
+		}
+		function writeEvent(event, data) {
+			write(`event: ${event}\n${data.split("\n").map((line) => `data: ${line}`).join("\n")}\n\n`);
+		}
+		const session = {
+			id,
+			meta,
+			connection: void 0,
+			channel: void 0,
+			parked: /* @__PURE__ */ new Map(),
+			closed: false,
+			close: () => {
+				if (session.closed) return;
+				session.closed = true;
+				if (keepAlive) clearInterval(keepAlive);
+				sessions.delete(id);
+				for (const resolve of session.parked.values()) resolve(null);
+				session.parked.clear();
+				try {
+					controller?.close();
+				} catch {}
+				rpcGroup.updateChannels((channels) => {
+					const index = channels.indexOf(session.channel);
+					if (index >= 0) channels.splice(index, 1);
+				});
+				onDisconnected(session.connection, meta);
+			}
+		};
+		closeSession = session.close;
+		const connection = {
+			id: meta.id,
+			transport: "sse",
+			request,
+			send: (data) => writeEvent("message", data),
+			close: () => session.close()
+		};
+		session.connection = connection;
+		const channel = {
+			post: (data) => {
+				const { t, i } = peekRpcWireFrame(data);
+				if (t === "s" && i) {
+					const resolve = session.parked.get(i);
+					if (resolve) {
+						session.parked.delete(i);
+						resolve(data);
+						return;
+					}
+				}
+				writeEvent("message", data);
+			},
+			on: (fn) => {
+				session.onMessage = fn;
+			},
+			serialize: codec.serialize,
+			deserialize: codec.deserialize,
+			meta
+		};
+		session.channel = channel;
+		const body = new ReadableStream({
+			start(c) {
+				controller = c;
+				sessions.set(id, session);
+				rpcGroup.updateChannels((channels) => {
+					channels.push(channel);
+				});
+				write(`event: session\ndata: ${id}\n\n`);
+				if (keepAliveInterval > 0) {
+					keepAlive = setInterval(write, keepAliveInterval, ": ping\n\n");
+					keepAlive.unref?.();
+				}
+				onConnected(connection, meta);
+			},
+			cancel() {
+				session.close();
+			}
+		});
+		return new Response(body, {
+			status: 200,
+			headers: {
+				...SSE_STREAM_HEADERS,
+				...corsHeaders(request)
+			}
+		});
+	}
+	async function handlePost(request) {
+		const id = request.headers.get(DEVFRAME_SSE_SESSION_HEADER);
+		const session = id ? sessions.get(id) : void 0;
+		if (!session || session.closed) return new Response("Unknown SSE session", {
+			status: 400,
+			headers: corsHeaders(request)
+		});
+		const frame = await request.text();
+		const { t, i } = peekRpcWireFrame(frame);
+		if (t === "q" && i) {
+			const parked = new Promise((resolve) => {
+				session.parked.set(i, resolve);
+			});
+			session.onMessage?.(frame);
+			const responseBody = await parked;
+			if (responseBody == null) return new Response("SSE session closed before the response settled", {
+				status: 409,
+				headers: corsHeaders(request)
+			});
+			return new Response(responseBody, {
+				status: 200,
+				headers: {
+					"content-type": "text/plain; charset=utf-8",
+					...corsHeaders(request)
+				}
+			});
+		}
+		session.onMessage?.(frame);
+		return new Response(null, {
+			status: 202,
+			headers: corsHeaders(request)
+		});
+	}
+	function handlePreflight(request) {
+		return new Response(null, {
+			status: 204,
+			headers: {
+				"access-control-allow-methods": "GET, POST, OPTIONS",
+				"access-control-allow-headers": `content-type, ${DEVFRAME_SSE_SESSION_HEADER}`,
+				"access-control-max-age": "86400",
+				...corsHeaders(request)
+			}
+		});
+	}
+	return {
+		handler: (request) => {
+			if (!originAllowed(request)) return new Response("Forbidden", { status: 403 });
+			switch (request.method) {
+				case "GET": return openStream(request);
+				case "POST": return handlePost(request);
+				case "OPTIONS": return handlePreflight(request);
+				default: return new Response("Method Not Allowed", {
+					status: 405,
+					headers: { allow: "GET, POST, OPTIONS" }
+				});
+			}
+		},
+		sessionCount: () => sessions.size,
+		close: () => {
+			for (const session of [...sessions.values()]) session.close();
+		}
+	};
+}
+//#endregion
+export { attachSseRpcTransport };

package/dist/rpc/transports/ws-bun.d.mts

@@ -0,0 +1,35 @@
+import { n as WsOriginRegistry } from "../../ws-server-Ces08fjP.mjs";
+import { t as ContextRpcServer } from "../../rpc-core-CGctXToO.mjs";
+//#region src/rpc/transports/ws-bun.d.ts
+interface AttachBunWsTransportOptions {
+  /** Same contract as `WsRpcTransportOptions.allowedOrigins`. */
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false;
+}
+/**
+ * Structural view of the Bun `Bun.serve({ websocket })` handler object the
+ * crossws Bun adapter produces — typed loosely so devframe carries no
+ * dependency on Bun's own types.
+ */
+interface BunWsTierWebSocket {
+  open?: (ws: unknown) => unknown;
+  message: (ws: unknown, message: unknown) => unknown;
+  close?: (ws: unknown, code?: number, reason?: string) => unknown;
+  drain?: (ws: unknown) => unknown;
+}
+interface BunWsTier {
+  /** Complete a WS upgrade request — `Bun.serve`'s server as 2nd argument. */
+  handleUpgrade: (request: Request, server: unknown) => Promise<Response | undefined>;
+  /** The handlers to spread into `Bun.serve({ websocket })`. */
+  websocket: BunWsTierWebSocket;
+  close: () => Promise<void>;
+}
+/**
+ * The Bun fetch-upgrade WebSocket tier for `initDevframe` / `initHub` — the
+ * same RPC peer wiring as `attachWsRpcTransport`, driven by crossws's Bun
+ * adapter so upgrades complete through `handler(request, server)` on the
+ * app's own origin, with no side-car server. Load it dynamically so the Bun
+ * adapter never enters a Node-only bundle path.
+ */
+declare function attachBunWsTransport(core: ContextRpcServer, options?: AttachBunWsTransportOptions): Promise<BunWsTier>;
+//#endregion
+export { AttachBunWsTransportOptions, BunWsTier, BunWsTierWebSocket, attachBunWsTransport };

package/dist/rpc/transports/ws-bun.mjs

@@ -0,0 +1,31 @@
+import { i as isAllowedOrigin, r as createWsRpcPeerHooks } from "../../ws-server-Bk1hOG3X.mjs";
+//#region src/rpc/transports/ws-bun.ts
+/**
+* The Bun fetch-upgrade WebSocket tier for `initDevframe` / `initHub` — the
+* same RPC peer wiring as `attachWsRpcTransport`, driven by crossws's Bun
+* adapter so upgrades complete through `handler(request, server)` on the
+* app's own origin, with no side-car server. Load it dynamically so the Bun
+* adapter never enters a Node-only bundle path.
+*/
+async function attachBunWsTransport(core, options = {}) {
+	const { default: bunAdapter } = await import("crossws/adapters/bun");
+	const { allowedOrigins } = options;
+	const ws = bunAdapter({ hooks: {
+		...createWsRpcPeerHooks(core.rpcGroup, {
+			onConnected: core.onConnected,
+			onDisconnected: core.onDisconnected
+		}),
+		upgrade(request) {
+			const origin = request.headers.get("origin") ?? void 0;
+			const allowed = allowedOrigins && !Array.isArray(allowedOrigins) ? allowedOrigins.isAllowed(origin) : isAllowedOrigin(origin, allowedOrigins || []);
+			if (allowedOrigins !== false && !allowed) return new Response("Forbidden", { status: 403 });
+		}
+	} });
+	return {
+		handleUpgrade: (request, server) => ws.handleUpgrade(request, server),
+		websocket: ws.websocket,
+		close: () => ws.close()
+	};
+}
+//#endregion
+export { attachBunWsTransport };

package/dist/rpc/transports/ws-client.d.mts

@@ -1,2 +1,2 @@
-import { n as createWsRpcChannel, t as WsRpcChannelOptions } from "../../ws-client-B6Tnr0ic.mjs";
+import { n as createWsRpcChannel, t as WsRpcChannelOptions } from "../../ws-client-CdNuATYa.mjs";
 export { WsRpcChannelOptions, createWsRpcChannel };

package/dist/rpc/transports/ws-client.mjs

@@ -1,12 +1,14 @@
 import { DEVFRAME_AUTH_TOKEN_QUERY_PARAM } from "../../constants.mjs";
-import { n as strictJsonStringify } from "../../serialization-C8Mnw9hK.mjs";
-import { n as structuredCloneStringify, t as structuredCloneParse } from "../../structured-clone-CbAV5rFI.mjs";
+import { t as createRpcWireCodec } from "../../wire-codec-9VhIKnyp.mjs";
 //#region src/rpc/transports/ws-client.ts
 function NOOP() {}
 const EMPTY_DEFS = /* @__PURE__ */ new Map();
 /**
 * Build a birpc `ChannelOptions` object backed by a browser `WebSocket`.
 * Pass the result straight to `createRpcClient`'s `channel` option.
+*
+* Also returns `close()`, closing the underlying socket — mirroring the server transport's
+* existing `WsRpcTransport.close()`. `birpc`'s own `ChannelOptions` has no teardown of its own.
 */
 function createWsRpcChannel(options) {
 	let url = options.url;
@@ -23,8 +25,11 @@ function createWsRpcChannel(options) {
 	ws.addEventListener("close", (e) => {
 		onDisconnected(e);
 	});
-	const pendingRequestMethods = /* @__PURE__ */ new Map();
+	const codec = createRpcWireCodec(definitions);
 	return {
+		close: () => {
+			ws.close();
+		},
 		on: (handler) => {
 			ws.addEventListener("message", (e) => {
 				handler(e.data);
@@ -51,21 +56,8 @@ function createWsRpcChannel(options) {
 			}
 			onError(/* @__PURE__ */ new Error("Devframe WebSocket is not open; message dropped"));
 		},
-		serialize: (msg) => {
-			let method;
-			if (msg.t === "q") method = msg.m;
-			else {
-				method = pendingRequestMethods.get(msg.i);
-				pendingRequestMethods.delete(msg.i);
-			}
-			if (!(msg.t === "s" && "e" in msg) && !!method && definitions.get(method)?.jsonSerializable === true) return strictJsonStringify(msg, method ?? "");
-			return `s:${structuredCloneStringify(msg)}`;
-		},
-		deserialize: (raw) => {
-			const msg = raw.startsWith("s:") ? structuredCloneParse(raw.slice(2)) : JSON.parse(raw);
-			if (msg.t === "q" && msg.i && msg.m) pendingRequestMethods.set(msg.i, msg.m);
-			return msg;
-		}
+		serialize: codec.serialize,
+		deserialize: codec.deserialize
 	};
 }
 //#endregion

package/dist/rpc/transports/ws-server.d.mts

@@ -1,2 +1,2 @@
-import { a as WsRpcTransportOptions, c as isAllowedOrigin, i as WsRpcTransport, l as isLoopbackHostname, n as DevframeNodeRpcSessionMeta, o as attachWsRpcTransport, r as WsOriginRegistry, s as createWsOriginRegistry, t as CreateWsOriginRegistryOptions } from "../../ws-server-uKQcClcJ.mjs";
-export { CreateWsOriginRegistryOptions, DevframeNodeRpcSessionMeta, WsOriginRegistry, WsRpcTransport, WsRpcTransportOptions, attachWsRpcTransport, createWsOriginRegistry, isAllowedOrigin, isLoopbackHostname };
+import { a as attachWsRpcTransport, c as isAllowedOrigin, d as DevframeRpcConnection, f as DevframeRpcConnectionRequest, i as WsRpcTransportOptions, l as isLoopbackHostname, n as WsOriginRegistry, o as createWsOriginRegistry, p as DevframeRpcTransportKind, r as WsRpcTransport, s as createWsRpcPeerHooks, t as CreateWsOriginRegistryOptions, u as DevframeNodeRpcSessionMeta } from "../../ws-server-Ces08fjP.mjs";
+export { CreateWsOriginRegistryOptions, type DevframeNodeRpcSessionMeta, type DevframeRpcConnection, type DevframeRpcConnectionRequest, type DevframeRpcTransportKind, WsOriginRegistry, WsRpcTransport, WsRpcTransportOptions, attachWsRpcTransport, createWsOriginRegistry, createWsRpcPeerHooks, isAllowedOrigin, isLoopbackHostname };