devframe 0.8.2 → 0.9.0-beta.2

package/dist/validation-BiuDXTKW.mjs

@@ -0,0 +1,266 @@
+import { t as diagnostics } from "./diagnostics-hwjXp_UV.mjs";
+import { createHash } from "node:crypto";
+//#region ../../node_modules/.pnpm/ohash@2.0.11/node_modules/ohash/dist/shared/ohash.D__AXeF1.mjs
+function serialize(o) {
+	return typeof o == "string" ? `'${o}'` : new c().serialize(o);
+}
+const c = /*@__PURE__*/ function() {
+	class o {
+		#t = /* @__PURE__ */ new Map();
+		compare(t, r) {
+			const e = typeof t, n = typeof r;
+			return e === "string" && n === "string" ? t.localeCompare(r) : e === "number" && n === "number" ? t - r : String.prototype.localeCompare.call(this.serialize(t, true), this.serialize(r, true));
+		}
+		serialize(t, r) {
+			if (t === null) return "null";
+			switch (typeof t) {
+				case "string": return r ? t : `'${t}'`;
+				case "bigint": return `${t}n`;
+				case "object": return this.$object(t);
+				case "function": return this.$function(t);
+			}
+			return String(t);
+		}
+		serializeObject(t) {
+			const r = Object.prototype.toString.call(t);
+			if (r !== "[object Object]") return this.serializeBuiltInType(r.length < 10 ? `unknown:${r}` : r.slice(8, -1), t);
+			const e = t.constructor, n = e === Object || e === void 0 ? "" : e.name;
+			if (n !== "" && globalThis[n] === e) return this.serializeBuiltInType(n, t);
+			if (typeof t.toJSON == "function") {
+				const i = t.toJSON();
+				return n + (i !== null && typeof i == "object" ? this.$object(i) : `(${this.serialize(i)})`);
+			}
+			return this.serializeObjectEntries(n, Object.entries(t));
+		}
+		serializeBuiltInType(t, r) {
+			const e = this["$" + t];
+			if (e) return e.call(this, r);
+			if (typeof r?.entries == "function") return this.serializeObjectEntries(t, r.entries());
+			throw new Error(`Cannot serialize ${t}`);
+		}
+		serializeObjectEntries(t, r) {
+			const e = Array.from(r).sort((i, a) => this.compare(i[0], a[0]));
+			let n = `${t}{`;
+			for (let i = 0; i < e.length; i++) {
+				const [a, l] = e[i];
+				n += `${this.serialize(a, true)}:${this.serialize(l)}`, i < e.length - 1 && (n += ",");
+			}
+			return n + "}";
+		}
+		$object(t) {
+			let r = this.#t.get(t);
+			return r === void 0 && (this.#t.set(t, `#${this.#t.size}`), r = this.serializeObject(t), this.#t.set(t, r)), r;
+		}
+		$function(t) {
+			const r = Function.prototype.toString.call(t);
+			return r.slice(-15) === "[native code] }" ? `${t.name || ""}()[native]` : `${t.name}(${t.length})${r.replace(/\s*\n\s*/g, "")}`;
+		}
+		$Array(t) {
+			let r = "[";
+			for (let e = 0; e < t.length; e++) r += this.serialize(t[e]), e < t.length - 1 && (r += ",");
+			return r + "]";
+		}
+		$Date(t) {
+			try {
+				return `Date(${t.toISOString()})`;
+			} catch {
+				return "Date(null)";
+			}
+		}
+		$ArrayBuffer(t) {
+			return `ArrayBuffer[${new Uint8Array(t).join(",")}]`;
+		}
+		$Set(t) {
+			return `Set${this.$Array(Array.from(t).sort((r, e) => this.compare(r, e)))}`;
+		}
+		$Map(t) {
+			return this.serializeObjectEntries("Map", t.entries());
+		}
+	}
+	for (const s of [
+		"Error",
+		"RegExp",
+		"URL"
+	]) o.prototype["$" + s] = function(t) {
+		return `${s}(${t})`;
+	};
+	for (const s of [
+		"Int8Array",
+		"Uint8Array",
+		"Uint8ClampedArray",
+		"Int16Array",
+		"Uint16Array",
+		"Int32Array",
+		"Uint32Array",
+		"Float32Array",
+		"Float64Array"
+	]) o.prototype["$" + s] = function(t) {
+		return `${s}[${t.join(",")}]`;
+	};
+	for (const s of ["BigInt64Array", "BigUint64Array"]) o.prototype["$" + s] = function(t) {
+		return `${s}[${t.join("n,")}${t.length > 0 ? "n" : ""}]`;
+	};
+	return o;
+}();
+//#endregion
+//#region ../../node_modules/.pnpm/ohash@2.0.11/node_modules/ohash/dist/crypto/node/index.mjs
+const e = globalThis.process?.getBuiltinModule?.("crypto")?.hash;
+const r = "sha256";
+const s = "base64url";
+function digest(t) {
+	if (e) return e(r, t, s);
+	const o = createHash(r).update(t);
+	return globalThis.process?.versions?.webcontainer ? o.digest().toString(s) : o.digest(s);
+}
+//#endregion
+//#region ../../node_modules/.pnpm/ohash@2.0.11/node_modules/ohash/dist/index.mjs
+function hash$1(input) {
+	return digest(serialize(input));
+}
+//#endregion
+//#region src/utils/hash.ts
+/**
+* Stable, deterministic hash of any structured-cloneable value.
+*/
+function hash(value) {
+	return hash$1(value);
+}
+//#endregion
+//#region src/rpc/validate-io.ts
+/**
+* Run a single [Standard Schema](https://standardschema.dev) validator,
+* awaiting the result when the validator is asynchronous.
+*/
+async function runStandardSchema(schema, value) {
+	const result = schema["~standard"].validate(value);
+	return result instanceof Promise ? await result : result;
+}
+/**
+* Render Standard Schema issues into a single human-readable line for a
+* diagnostic message, prefixing each with its dotted path when present.
+*/
+function formatIssues(issues) {
+	return issues.map((issue) => {
+		const path = issue.path?.map((segment) => typeof segment === "object" ? segment.key : segment).join(".");
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("; ");
+}
+/**
+* Validate positional arguments against their declared schemas. Only
+* indices with a schema are checked; extra arguments pass through
+* untouched. Throws `DF0038` on the first failing argument.
+*
+* Validation guards the payload without rewriting it: the original values
+* are handed to the handler unchanged, so a schema that describes a subset
+* of an object never silently strips the sender's extra fields (and any
+* declared transforms stay a purely type-level concern).
+*
+* @internal
+*/
+async function validateRpcArgs(name, argsSchema, args) {
+	const original = args.slice();
+	if (!argsSchema || argsSchema.length === 0) return original;
+	for (let index = 0; index < argsSchema.length; index++) {
+		const schema = argsSchema[index];
+		if (!schema) continue;
+		const result = await runStandardSchema(schema, args[index]);
+		if (result.issues) throw diagnostics.DF0043({
+			name,
+			index,
+			issues: formatIssues(result.issues)
+		});
+	}
+	return original;
+}
+/**
+* Validate a handler's resolved return value against its declared schema.
+* Throws `DF0039` when the value fails the schema, otherwise returns the
+* original value unchanged (guard-only, never rewriting the payload — see
+* {@link validateRpcArgs}). Passes through when no return schema is set.
+*
+* @internal
+*/
+async function validateRpcReturn(name, returnSchema, value) {
+	if (!returnSchema) return value;
+	const result = await runStandardSchema(returnSchema, value);
+	if (result.issues) throw diagnostics.DF0044({
+		name,
+		issues: formatIssues(result.issues)
+	});
+	return value;
+}
+//#endregion
+//#region src/rpc/handler.ts
+async function getRpcResolvedSetupResult(definition, context) {
+	if (!definition.setup) return {};
+	if (typeof context === "object" && context !== null) {
+		definition.__cache ??= /* @__PURE__ */ new WeakMap();
+		const cache = definition.__cache;
+		let promise = cache.get(context);
+		if (!promise) {
+			promise = Promise.resolve(definition.setup(context));
+			promise.catch(() => {
+				if (cache.get(context) === promise) cache.delete(context);
+			});
+			cache.set(context, promise);
+		}
+		return await promise;
+	}
+	if (!definition.__promise) {
+		const promise = Promise.resolve(definition.setup(context));
+		promise.catch(() => {
+			if (definition.__promise === promise) definition.__promise = void 0;
+		});
+		definition.__promise = promise;
+	}
+	return await definition.__promise;
+}
+async function getRpcHandler(definition, context) {
+	let handler = definition.handler;
+	if (!handler) {
+		const result = await getRpcResolvedSetupResult(definition, context);
+		if (!result.handler) throw diagnostics.DF0024({ name: definition.name });
+		handler = result.handler;
+	}
+	const argsSchema = definition.args;
+	const returnSchema = definition.returns;
+	if (!argsSchema && !returnSchema) return handler;
+	const inner = handler;
+	const validating = async (...args) => {
+		const validatedArgs = await validateRpcArgs(definition.name, argsSchema, args);
+		const output = await inner(...validatedArgs);
+		return await validateRpcReturn(definition.name, returnSchema, output);
+	};
+	return validating;
+}
+//#endregion
+//#region src/rpc/validation.ts
+/**
+* Validates RPC function definitions.
+* Action and event functions cannot have dumps (side effects should not be cached).
+*
+* @throws {Error} If an action or event function has a dump configuration
+*/
+function validateDefinitions(definitions) {
+	for (const definition of definitions) {
+		const type = definition.type || "query";
+		if ((type === "action" || type === "event") && definition.dump) throw diagnostics.DF0027({
+			name: definition.name,
+			type
+		});
+		if (definition.snapshot && type !== "query") throw diagnostics.DF0028({
+			name: definition.name,
+			type
+		});
+	}
+}
+/**
+* Validates a single RPC function definition.
+*
+* @throws {Error} If an action or event function has a dump configuration
+*/
+function validateDefinition(definition) {
+	validateDefinitions([definition]);
+}
+//#endregion
+export { validateRpcArgs as a, getRpcResolvedSetupResult as i, validateDefinitions as n, validateRpcReturn as o, getRpcHandler as r, hash as s, validateDefinition as t };

package/dist/wire-codec-9VhIKnyp.mjs

@@ -0,0 +1,58 @@
+import { n as strictJsonStringify } from "./serialization-BHY8M5NQ.mjs";
+import { n as structuredCloneStringify, t as structuredCloneParse } from "./structured-clone-CbAV5rFI.mjs";
+//#region src/rpc/wire-codec.ts
+const EMPTY_WIRE_DEFS = /* @__PURE__ */ new Map();
+/**
+* Build the per-connection wire codec every live transport (WS server, WS
+* client, SSE server, SSE client) shares: per-method dispatch between strict
+* JSON (methods declared `jsonSerializable: true`) and `s:`-prefixed
+* structured-clone (everything else, including all error envelopes), with a
+* request-id → method map so a response independently picks the same
+* encoder as its request. One codec per connection — request-id spaces
+* don't collide across connections.
+*
+* @internal
+* implementations; not part of the stable public API.
+*/
+function createRpcWireCodec(definitions = EMPTY_WIRE_DEFS) {
+	const pendingRequestMethods = /* @__PURE__ */ new Map();
+	return {
+		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;
+		}
+	};
+}
+/**
+* Peek at a wire frame's birpc envelope without engaging a codec's
+* request-id bookkeeping — used by the SSE transport to route a frame
+* (park a POST for its response / answer with a bare 202) before it is
+* handed to birpc proper.
+*
+* @internal
+* implementations; not part of the stable public API.
+*/
+function peekRpcWireFrame(raw) {
+	try {
+		const msg = raw.startsWith("s:") ? structuredCloneParse(raw.slice(2)) : JSON.parse(raw);
+		return {
+			t: msg?.t,
+			i: msg?.i
+		};
+	} catch {
+		return {};
+	}
+}
+//#endregion
+export { peekRpcWireFrame as n, createRpcWireCodec as t };

package/dist/{ws-client-B6Tnr0ic.d.mts → ws-client-CdNuATYa.d.mts}

@@ -19,7 +19,12 @@ interface WsRpcChannelOptions {
 /**
  * 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.
  */
-declare function createWsRpcChannel(options: WsRpcChannelOptions): ChannelOptions;
+declare function createWsRpcChannel(options: WsRpcChannelOptions): ChannelOptions & {
+  close: () => void;
+};
 //#endregion
 export { createWsRpcChannel as n, WsRpcChannelOptions as t };

package/dist/ws-server-Bk1hOG3X.mjs

@@ -0,0 +1,267 @@
+import "./constants.mjs";
+import { t as createRpcWireCodec } from "./wire-codec-9VhIKnyp.mjs";
+import { n as randomToken, r as timingSafeEqual } from "./crypto-token-XCqTSMg9.mjs";
+import { createServer } from "node:http";
+import { createServer as createServer$1 } from "node:https";
+import crossws from "crossws/adapters/node";
+//#region src/rpc/transports/session.ts
+let sessionId = 0;
+/**
+* Mint the per-connection session meta every transport binding shares —
+* one id space across transports, so session bookkeeping (streaming
+* subscriptions, shared-state sync, auth trust) never collides between a
+* WS peer and an SSE session on the same server.
+*/
+function createRpcSessionMeta() {
+	return {
+		id: sessionId++,
+		subscribedStates: /* @__PURE__ */ new Set()
+	};
+}
+//#endregion
+//#region src/rpc/transports/ws-server.ts
+/**
+* Create a live, token-protected origin allowlist for external browser
+* viewers. Pass it to {@link WsRpcTransportOptions.allowedOrigins}, then use
+* `registerFromUrl()` in the connection metadata handler to authorize a
+* viewer without sharing a mutable array or disabling DNS-rebinding protection.
+*/
+function createWsOriginRegistry(options = {}) {
+	const token = randomToken();
+	const origins = new Set(options.allowedOrigins ?? []);
+	function normalizeOrigin(origin) {
+		if (!origin) return;
+		try {
+			const url = new URL(origin);
+			const normalized = url.origin === "null" ? `${url.protocol}//${url.host}` : url.origin;
+			return origin === normalized ? normalized : void 0;
+		} catch {}
+	}
+	function registerOrigin(origin, candidateToken) {
+		const normalized = normalizeOrigin(origin);
+		if (!normalized || !candidateToken || !timingSafeEqual(token, candidateToken)) return false;
+		if (options.validateOrigin && !options.validateOrigin(normalized)) return false;
+		origins.add(normalized);
+		return true;
+	}
+	return {
+		token,
+		registerFromUrl(url) {
+			let parsed;
+			try {
+				parsed = new URL(url, "http://localhost");
+			} catch {
+				return;
+			}
+			const origin = parsed.searchParams.get("devframe_viewer_origin") ?? void 0;
+			return registerOrigin(origin, parsed.searchParams.get("devframe_viewer_origin_token") ?? void 0) ? origin : void 0;
+		},
+		isAllowed(origin) {
+			return isAllowedOrigin(origin, [...origins]);
+		}
+	};
+}
+const EMPTY_DEFS = /* @__PURE__ */ new Map();
+function NOOP() {}
+function listen(server, port, host) {
+	return new Promise((resolve, reject) => {
+		const onError = (error) => reject(error);
+		server.once("error", onError);
+		try {
+			server.listen(port, host, () => {
+				server.off("error", onError);
+				resolve();
+			});
+		} catch (error) {
+			server.off("error", onError);
+			reject(error);
+		}
+	});
+}
+/** Compare two URL paths ignoring a trailing slash. */
+function pathMatches(a, b) {
+	const strip = (p) => p.length > 1 && p.endsWith("/") ? p.slice(0, -1) : p;
+	return strip(a) === strip(b);
+}
+function isLoopbackHostname(hostname) {
+	const h = hostname.replace(/^\[|\]$/g, "");
+	return h === "localhost" || h === "127.0.0.1" || h === "::1" || h.endsWith(".localhost") || h.startsWith("127.");
+}
+/**
+* Default origin policy for a localhost dev tool: allow requests with no
+* `Origin` header (native, non-browser clients), allow any loopback origin
+* (so cross-port localhost dev setups keep working), and allow explicitly
+* configured origins. Everything else — a real remote page in the dev's
+* browser — is rejected.
+*/
+function isAllowedOrigin(origin, allowedOrigins) {
+	if (!origin) return true;
+	if (allowedOrigins.includes(origin)) return true;
+	try {
+		return isLoopbackHostname(new URL(origin).hostname);
+	} catch {
+		return false;
+	}
+}
+function isWsOriginRegistry(value) {
+	return !!value && !Array.isArray(value);
+}
+/**
+* Build the `upgrade` listener that hands a request to the crossws adapter,
+* optionally filtered to a single `path`. Non-matching requests are left
+* untouched so other upgrade listeners (e.g. a Vite dev server's HMR socket)
+* can claim them, unless `destroyUnmatched` is set.
+*/
+function createUpgradeListener(ws, path, destroyUnmatched, allowedOrigins) {
+	return (req, socket, head) => {
+		socket.on("error", () => {});
+		if (path) {
+			let pathname = req.url ?? "/";
+			try {
+				pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+			} catch {}
+			if (!pathMatches(pathname, path)) {
+				if (destroyUnmatched) {
+					socket.write("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
+					socket.destroy();
+				}
+				return;
+			}
+		}
+		const originAllowed = isWsOriginRegistry(allowedOrigins) ? allowedOrigins.isAllowed(req.headers.origin) : isAllowedOrigin(req.headers.origin, allowedOrigins || []);
+		if (allowedOrigins !== false && !originAllowed) {
+			socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+			socket.destroy();
+			return;
+		}
+		ws.handleUpgrade(req, socket, head);
+	};
+}
+/**
+* The per-peer lifecycle hooks driving a devframe RPC WebSocket, shaped for
+* any [crossws](https://crossws.h3.dev) adapter. {@link attachWsRpcTransport}
+* feeds them to the Node adapter; runtime-specific attachments (e.g. Bun's
+* fetch-upgrade adapter) reuse the same hooks so every transport speaks the
+* identical wire protocol — one birpc channel per peer, per-method
+* `jsonSerializable` dispatch between strict JSON and structured-clone.
+*/
+function createWsRpcPeerHooks(rpcGroup, options = {}) {
+	const { onConnected = NOOP, onDisconnected = NOOP, definitions = EMPTY_DEFS, serialize: serializeOverride, deserialize: deserializeOverride } = options;
+	const states = /* @__PURE__ */ new WeakMap();
+	return {
+		open: (peer) => {
+			const meta = createRpcSessionMeta();
+			meta.peer = peer;
+			const connection = {
+				id: meta.id,
+				transport: "websocket",
+				request: peer.request,
+				send: (data) => peer.send(data),
+				close: (code, reason) => peer.close(code, reason),
+				peer
+			};
+			const codec = createRpcWireCodec(definitions);
+			const state = {
+				meta,
+				connection,
+				channel: void 0
+			};
+			const channel = {
+				post: (data) => {
+					peer.send(data);
+				},
+				on: (fn) => {
+					state.onMessage = fn;
+				},
+				serialize: serializeOverride ?? codec.serialize,
+				deserialize: deserializeOverride ?? codec.deserialize,
+				meta
+			};
+			state.channel = channel;
+			states.set(peer, state);
+			rpcGroup.updateChannels((channels) => {
+				channels.push(channel);
+			});
+			onConnected(connection, meta);
+		},
+		message: (peer, message) => {
+			states.get(peer)?.onMessage?.(message.text());
+		},
+		close: (peer) => {
+			const state = states.get(peer);
+			if (!state) return;
+			states.delete(peer);
+			rpcGroup.updateChannels((channels) => {
+				const index = channels.indexOf(state.channel);
+				if (index >= 0) channels.splice(index, 1);
+			});
+			onDisconnected(state.connection, state.meta);
+		}
+	};
+}
+/**
+* Attach a WebSocket transport to an existing RPC group, powered by
+* [crossws](https://crossws.h3.dev). Either attach to an existing HTTP(S)
+* `server` (sharing its port, optionally scoped to a `path`), or let this
+* helper create a standalone server from `port` / `host` / `https`.
+*
+* Returns the crossws node adapter, standalone-server readiness/address
+* accessors, `detach` (remove the upgrade listener from a shared `server`),
+* and `close` (full deterministic teardown).
+*/
+function attachWsRpcTransport(rpcGroup, options = {}) {
+	const { server, port, host = "localhost", path, destroyUnmatched = false, unbound, https, allowedOrigins } = options;
+	const ws = crossws({ hooks: createWsRpcPeerHooks(rpcGroup, options) });
+	const sharedUpgradeListener = createUpgradeListener(ws, path, destroyUnmatched, allowedOrigins);
+	const ownedUpgradeListener = createUpgradeListener(ws, path, true, allowedOrigins);
+	/** Bind a server's `upgrade` events, tracked so `close()` detaches them. */
+	const attachments = /* @__PURE__ */ new Set();
+	function attachTo(target, listener) {
+		target.on("upgrade", listener);
+		const detachOne = () => {
+			target.off("upgrade", listener);
+			attachments.delete(detachOne);
+		};
+		attachments.add(detachOne);
+		return detachOne;
+	}
+	let ready = Promise.resolve();
+	let ownedServer;
+	if (unbound) {} else if (server) attachTo(server, sharedUpgradeListener);
+	else if (https) {
+		ownedServer = createServer$1(https);
+		attachTo(ownedServer, ownedUpgradeListener);
+		ready = listen(ownedServer, port ?? 0, host);
+	} else {
+		ownedServer = createServer((_req, res) => {
+			res.writeHead(426, { "content-type": "text/plain" });
+			res.end("Upgrade Required");
+		});
+		attachTo(ownedServer, ownedUpgradeListener);
+		ready = listen(ownedServer, port ?? 0, host);
+	}
+	const activeServer = server ?? ownedServer;
+	function detachAll() {
+		for (const detachOne of [...attachments]) detachOne();
+	}
+	return {
+		ws,
+		ready,
+		address: () => activeServer?.address() ?? null,
+		handleUpgrade: sharedUpgradeListener,
+		attach: (target) => attachTo(target, sharedUpgradeListener),
+		detach: detachAll,
+		async close() {
+			detachAll();
+			ws.closeAll(void 0, void 0, true);
+			if (ownedServer) {
+				const srv = ownedServer;
+				await ready.catch(() => {});
+				if (!srv.listening) return;
+				await new Promise((r) => srv.close(() => r()));
+			}
+		}
+	};
+}
+//#endregion
+export { isLoopbackHostname as a, isAllowedOrigin as i, createWsOriginRegistry as n, createRpcSessionMeta as o, createWsRpcPeerHooks as r, attachWsRpcTransport as t };