capnweb 0.0.0-bd22055 → 0.0.0-c70bbb7

package/README.md

@@ -776,3 +776,10 @@ let stub: RemoteMainInterface = session.getRemoteMain();
 ```
 
 Note that sessions are entirely symmetric: neither side is defined as the "client" nor the "server". Each side can optionally expose a "main interface" to the other. In typical scenarios with a logical client and server, the server exposes a main interface but the client does not.
+
+By default, `send()` accepts a string, and `receive()` returns a string, with Cap'n Web handling the encoding all the way to and from strings. However, transports that want more control over the serialization can declare the property `encodingLevel` to control how much encoding Cap'n Web does before passing off the message:
+
+* `"string"` (default): Full JSON round-trip. The transport deals in strings only. Cap'n Web handles all encoding/decoding. This is what HTTP batch and WebSocket transports use.
+* `"jsonCompatible"`: The transport works with JavaScript value trees, but they must be JSON-compatible. Cap'n Web still encodes special types, but skips the final `JSON.stringify`. The transport is responsible for serialization (e.g. to CBOR, MessagePack).
+* `"jsonCompatibleWithBytes"`: Like `"jsonCompatible"` except that byte arrays are left as `Uint8Array` instead of base64-encoded, avoiding the ~33% base64 size overhead and the encode/decode CPU cost. Handy for use with serializations like CBOR or MessagePack that support this efficiently.
+* `"structuredClonable"`: Messages are structured-clonable values. Cap'n Web passes through native structured-clone types where possible, while still handling RPC-specific values such as stubs. This is useful when the transport is a `MessagePort` or similar.

package/dist/index-bun.cjs

@@ -963,12 +963,14 @@ const ERROR_TYPES = {
 var Devaluator = class Devaluator {
 	exporter;
 	source;
-	constructor(exporter, source) {
+	encodingLevel;
+	constructor(exporter, source, encodingLevel) {
 		this.exporter = exporter;
 		this.source = source;
+		this.encodingLevel = encodingLevel;
 	}
-	static devaluate(value, parent, exporter = NULL_EXPORTER, source) {
-		let devaluator = new Devaluator(exporter, source);
+	static devaluate(value, parent, exporter = NULL_EXPORTER, source, encodingLevel = "string") {
+		let devaluator = new Devaluator(exporter, source, encodingLevel);
 		try {
 			return devaluator.devaluateImpl(value, parent, 0);
 		} catch (err) {
@@ -991,10 +993,12 @@ var Devaluator = class Devaluator {
 				}
 				throw new TypeError(msg);
 			}
-			case "primitive": if (typeof value === "number" && !isFinite(value)) if (value === Infinity) return ["inf"];
-			else if (value === -Infinity) return ["-inf"];
-			else return ["nan"];
-			else return value;
+			case "primitive": if (typeof value === "number" && !isFinite(value)) {
+				if (this.encodingLevel === "structuredClonable") return value;
+				if (value === Infinity) return ["inf"];
+				else if (value === -Infinity) return ["-inf"];
+				else return ["nan"];
+			} else return value;
 			case "object": {
 				let object = value;
 				let result = {};
@@ -1008,13 +1012,17 @@ var Devaluator = class Devaluator {
 				for (let i = 0; i < len; i++) result[i] = this.devaluateImpl(array[i], array, depth + 1);
 				return [result];
 			}
-			case "bigint": return ["bigint", value.toString()];
+			case "bigint":
+				if (this.encodingLevel === "structuredClonable") return value;
+				return ["bigint", value.toString()];
 			case "date": {
+				if (this.encodingLevel === "structuredClonable") return value;
 				const time = value.getTime();
 				return ["date", Number.isNaN(time) ? null : time];
 			}
 			case "bytes": {
 				let bytes = value;
+				if (this.encodingLevel === "structuredClonable" || this.encodingLevel === "jsonCompatibleWithBytes") return ["bytes", bytes];
 				if (bytes.toBase64) return ["bytes", bytes.toBase64({ omitPadding: true })];
 				let b64;
 				if (typeof Buffer !== "undefined") b64 = (bytes instanceof Buffer ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)).toString("base64");
@@ -1139,7 +1147,9 @@ var Devaluator = class Devaluator {
 				} else if (rewritten && rewritten.stack) result.push(rewritten.stack);
 				return result;
 			}
-			case "undefined": return ["undefined"];
+			case "undefined":
+				if (this.encodingLevel === "structuredClonable") return;
+				return ["undefined"];
 			case "stub":
 			case "rpc-promise": {
 				if (!this.source) throw new Error("Can't serialize RPC stubs in this context.");
@@ -1222,8 +1232,10 @@ function streamToBlobPromise(stream, type) {
 }
 var Evaluator = class Evaluator {
 	importer;
-	constructor(importer) {
+	encodingLevel;
+	constructor(importer, encodingLevel = "string") {
 		this.importer = importer;
+		this.encodingLevel = encodingLevel;
 	}
 	hooks = [];
 	promises = [];
@@ -1241,6 +1253,9 @@ var Evaluator = class Evaluator {
 		return this.evaluate(structuredClone(value));
 	}
 	evaluateImpl(value, parent, property) {
+		if (this.encodingLevel === "structuredClonable") {
+			if (value instanceof Date || typeof value === "bigint") return value;
+		}
 		if (value instanceof Array) {
 			if (value.length == 1 && value[0] instanceof Array) {
 				let result = value[0];
@@ -1255,6 +1270,7 @@ var Evaluator = class Evaluator {
 					if (typeof value[1] == "number") return new Date(value[1]);
 					break;
 				case "bytes":
+					if (value[1] instanceof Uint8Array) return value[1];
 					if (typeof value[1] == "string") if (typeof Buffer !== "undefined") return Buffer.from(value[1], "base64");
 					else if (Uint8Array.fromBase64) return Uint8Array.fromBase64(value[1]);
 					else {
@@ -1455,6 +1471,47 @@ function deserialize(value) {
 
 //#endregion
 //#region src/rpc.ts
+const ESTIMATED_OBJECT_OVERHEAD = 16;
+const ESTIMATED_ENTRY_OVERHEAD = 8;
+const ESTIMATED_BINARY_OVERHEAD = 16;
+const MAX_ESTIMATE_DEPTH = 64;
+function estimateStringSize(value) {
+	return 2 + value.length * 3;
+}
+function estimateEncodedSize(value, seen, depth = 0) {
+	if (depth >= MAX_ESTIMATE_DEPTH) return ESTIMATED_ENTRY_OVERHEAD;
+	switch (typeof value) {
+		case "string": return estimateStringSize(value);
+		case "number": return 16;
+		case "bigint": return 16;
+		case "boolean": return 8;
+		case "undefined": return 16;
+		case "object": {
+			if (value === null) return 8;
+			if (ArrayBuffer.isView(value)) return ESTIMATED_BINARY_OVERHEAD + value.byteLength;
+			if (value instanceof ArrayBuffer) return ESTIMATED_BINARY_OVERHEAD + value.byteLength;
+			if (typeof Blob !== "undefined" && value instanceof Blob) return ESTIMATED_BINARY_OVERHEAD + value.size;
+			if (value instanceof Date) return 16;
+			seen ??= /* @__PURE__ */ new WeakSet();
+			if (seen.has(value)) return ESTIMATED_ENTRY_OVERHEAD;
+			seen.add(value);
+			if (value instanceof Array) {
+				let size = ESTIMATED_OBJECT_OVERHEAD;
+				for (let item of value) size += ESTIMATED_ENTRY_OVERHEAD + estimateEncodedSize(item, seen, depth + 1);
+				return size;
+			}
+			if (value instanceof Error) {
+				let size = ESTIMATED_OBJECT_OVERHEAD + estimateStringSize(value.name) + estimateStringSize(value.message) + estimateStringSize(value.stack ?? "");
+				for (let key of Object.keys(value)) size += ESTIMATED_ENTRY_OVERHEAD + estimateStringSize(key) + estimateEncodedSize(value[key], seen, depth + 1);
+				return size;
+			}
+			let size = ESTIMATED_OBJECT_OVERHEAD;
+			for (let key of Object.keys(value)) size += ESTIMATED_ENTRY_OVERHEAD + estimateStringSize(key) + estimateEncodedSize(value[key], seen, depth + 1);
+			return size;
+		}
+		default: return 16;
+	}
+}
 var ImportTableEntry = class {
 	session;
 	importId;
@@ -1620,9 +1677,19 @@ var RpcSessionImpl = class {
 	onBatchDone;
 	pullCount = 0;
 	onBrokenCallbacks = [];
+	encodingLevel;
 	constructor(transport, mainHook, options) {
 		this.transport = transport;
 		this.options = options;
+		let level = "string";
+		if ("encodingLevel" in transport) {
+			let raw = transport.encodingLevel;
+			if (raw !== void 0) {
+				if (raw !== "string" && raw !== "jsonCompatible" && raw !== "jsonCompatibleWithBytes" && raw !== "structuredClonable") throw new TypeError(`Unknown transport encodingLevel: ${String(raw)}`);
+				level = raw;
+			}
+		}
+		this.encodingLevel = level;
 		this.exports.push({
 			hook: mainHook,
 			refcount: 1
@@ -1703,7 +1770,7 @@ var RpcSessionImpl = class {
 			let autoRelease = exp.autoRelease;
 			++this.pullCount;
 			exp.pull = resolve().then((payload) => {
-				let value = Devaluator.devaluate(payload.value, void 0, this, payload);
+				let value = Devaluator.devaluate(payload.value, void 0, this, payload, this.encodingLevel);
 				this.send([
 					"resolve",
 					exportId,
@@ -1714,7 +1781,7 @@ var RpcSessionImpl = class {
 				this.send([
 					"reject",
 					exportId,
-					Devaluator.devaluate(error, void 0, this)
+					Devaluator.devaluate(error, void 0, this, void 0, this.encodingLevel)
 				]);
 				if (autoRelease) this.releaseExport(exportId, 1);
 			}).catch((error) => {
@@ -1722,7 +1789,7 @@ var RpcSessionImpl = class {
 					this.send([
 						"reject",
 						exportId,
-						Devaluator.devaluate(error, void 0, this)
+						Devaluator.devaluate(error, void 0, this, void 0, this.encodingLevel)
 					]);
 					if (autoRelease) this.releaseExport(exportId, 1);
 				} catch (error2) {
@@ -1778,17 +1845,33 @@ var RpcSessionImpl = class {
 	}
 	send(msg) {
 		if (this.abortReason !== void 0) return 0;
-		let msgText;
-		try {
-			msgText = JSON.stringify(msg);
-		} catch (err) {
+		if (this.encodingLevel === "string") {
+			let msgText;
 			try {
-				this.abort(err);
-			} catch (err2) {}
-			throw err;
+				msgText = JSON.stringify(msg);
+			} catch (err) {
+				try {
+					this.abort(err);
+				} catch (err2) {}
+				throw err;
+			}
+			try {
+				let sent = this.transport.send(msgText);
+				if (sent !== void 0 && typeof sent.catch === "function") sent.catch((err) => this.abort(err, false));
+			} catch (err) {
+				queueMicrotask(() => this.abort(err, false));
+			}
+			return msgText.length;
+		} else try {
+			let size = this.transport.send(msg);
+			if (typeof size === "number") return size;
+			let thenable = size;
+			if (thenable && typeof thenable.then === "function") Promise.resolve(thenable).catch((err) => this.abort(err, false));
+			return;
+		} catch (err) {
+			queueMicrotask(() => this.abort(err, false));
+			return;
 		}
-		this.transport.send(msgText).catch((err) => this.abort(err, false));
-		return msgText.length;
 	}
 	sendCall(id, path, args) {
 		if (this.abortReason) throw this.abortReason;
@@ -1798,7 +1881,7 @@ var RpcSessionImpl = class {
 			path
 		];
 		if (args) {
-			let devalue = Devaluator.devaluate(args.value, void 0, this, args);
+			let devalue = Devaluator.devaluate(args.value, void 0, this, args, this.encodingLevel);
 			value.push(devalue[0]);
 		}
 		this.send(["push", value]);
@@ -1813,9 +1896,11 @@ var RpcSessionImpl = class {
 			id,
 			path
 		];
-		let devalue = Devaluator.devaluate(args.value, void 0, this, args);
+		let devalue = Devaluator.devaluate(args.value, void 0, this, args, this.encodingLevel);
 		value.push(devalue[0]);
-		let size = this.send(["stream", value]);
+		let msg = ["stream", value];
+		let size = this.send(msg);
+		if (size === void 0) size = estimateEncodedSize(msg);
 		let importId = this.imports.length;
 		let entry = new ImportTableEntry(this, importId, true);
 		entry.remoteRefcount = 0;
@@ -1871,7 +1956,14 @@ var RpcSessionImpl = class {
 		this.cancelReadLoop?.(error);
 		this.cancelReadLoop = void 0;
 		if (trySendAbortMessage) try {
-			this.transport.send(JSON.stringify(["abort", Devaluator.devaluate(error, void 0, this)])).catch((err) => {});
+			let abortMsg = ["abort", Devaluator.devaluate(error, void 0, this, void 0, this.encodingLevel)];
+			if (this.encodingLevel === "string") {
+				let sent = this.transport.send(JSON.stringify(abortMsg));
+				if (sent !== void 0 && typeof sent.catch === "function") sent.catch((err) => {});
+			} else {
+				let result = this.transport.send(abortMsg);
+				if (result && typeof result.then === "function") Promise.resolve(result).catch((err) => {});
+			}
 		} catch (err) {}
 		if (error === void 0) error = "undefined";
 		this.abortReason = error;
@@ -1893,18 +1985,18 @@ var RpcSessionImpl = class {
 		while (!this.abortReason) {
 			let readCanceled = Promise.withResolvers();
 			this.cancelReadLoop = readCanceled.reject;
-			let msgText;
+			let raw;
 			try {
-				msgText = await Promise.race([this.transport.receive(), readCanceled.promise]);
+				raw = await Promise.race([this.transport.receive(), readCanceled.promise]);
 			} finally {
 				if (this.cancelReadLoop === readCanceled.reject) this.cancelReadLoop = void 0;
 			}
-			let msg = JSON.parse(msgText);
 			if (this.abortReason) break;
+			let msg = this.encodingLevel === "string" ? JSON.parse(raw) : raw;
 			if (msg instanceof Array) switch (msg[0]) {
 				case "push":
 					if (msg.length > 1) {
-						let hook = new PayloadStubHook(new Evaluator(this).evaluate(msg[1]));
+						let hook = new PayloadStubHook(new Evaluator(this, this.encodingLevel).evaluate(msg[1]));
 						hook.ignoreUnhandledRejections();
 						this.exports.push({
 							hook,
@@ -1915,7 +2007,7 @@ var RpcSessionImpl = class {
 					break;
 				case "stream":
 					if (msg.length > 1) {
-						let hook = new PayloadStubHook(new Evaluator(this).evaluate(msg[1]));
+						let hook = new PayloadStubHook(new Evaluator(this, this.encodingLevel).evaluate(msg[1]));
 						hook.ignoreUnhandledRejections();
 						let exportId = this.exports.length;
 						this.exports.push({
@@ -1950,13 +2042,13 @@ var RpcSessionImpl = class {
 					let importId = msg[1];
 					if (typeof importId == "number" && msg.length > 2) {
 						let imp = this.imports[importId];
-						if (imp) if (msg[0] == "resolve") imp.resolve(new PayloadStubHook(new Evaluator(this).evaluate(msg[2])));
+						if (imp) if (msg[0] == "resolve") imp.resolve(new PayloadStubHook(new Evaluator(this, this.encodingLevel).evaluate(msg[2])));
 						else {
-							let payload = new Evaluator(this).evaluate(msg[2]);
+							let payload = new Evaluator(this, this.encodingLevel).evaluate(msg[2]);
 							payload.dispose();
 							imp.resolve(new ErrorStubHook(payload.value));
 						}
-						else if (msg[0] == "resolve") new Evaluator(this).evaluate(msg[2]).dispose();
+						else if (msg[0] == "resolve") new Evaluator(this, this.encodingLevel).evaluate(msg[2]).dispose();
 						continue;
 					}
 					break;
@@ -1971,7 +2063,7 @@ var RpcSessionImpl = class {
 					break;
 				}
 				case "abort": {
-					let payload = new Evaluator(this).evaluate(msg[1]);
+					let payload = new Evaluator(this, this.encodingLevel).evaluate(msg[1]);
 					payload.dispose();
 					this.abort(payload, false);
 					break;
@@ -2043,9 +2135,14 @@ function newWorkersWebSocketRpcResponse(request, localMain, options) {
 		webSocket: pair[1]
 	});
 }
+/**
+* Generic WebSocket transport. Default `T = string` is backward-compatible and satisfies
+* `RpcTransport`. Use `T = ArrayBuffer` as a building block for binary transports.
+*/
 var WebSocketTransport = class {
 	constructor(webSocket) {
 		this.#webSocket = webSocket;
+		webSocket.binaryType = "arraybuffer";
 		if (webSocket.readyState === WebSocket.CONNECTING) {
 			this.#sendQueue = [];
 			webSocket.addEventListener("open", (event) => {
@@ -2058,12 +2155,12 @@ var WebSocketTransport = class {
 			});
 		}
 		webSocket.addEventListener("message", (event) => {
-			if (this.#error) {} else if (typeof event.data === "string") if (this.#receiveResolver) {
+			if (this.#error) {} else if (typeof event.data === "string" || event.data instanceof ArrayBuffer) if (this.#receiveResolver) {
 				this.#receiveResolver(event.data);
 				this.#receiveResolver = void 0;
 				this.#receiveRejecter = void 0;
 			} else this.#receiveQueue.push(event.data);
-			else this.#receivedError(/* @__PURE__ */ new TypeError("Received non-string message from WebSocket."));
+			else this.#receivedError(/* @__PURE__ */ new TypeError("Received unexpected message type from WebSocket."));
 		});
 		webSocket.addEventListener("close", (event) => {
 			this.#receivedError(/* @__PURE__ */ new Error(`Peer closed WebSocket: ${event.code} ${event.reason}`));
@@ -2078,13 +2175,13 @@ var WebSocketTransport = class {
 	#receiveRejecter;
 	#receiveQueue = [];
 	#error;
-	async send(message) {
+	send(message) {
 		if (this.#sendQueue === void 0) this.#webSocket.send(message);
 		else this.#sendQueue.push(message);
 	}
-	async receive() {
-		if (this.#receiveQueue.length > 0) return this.#receiveQueue.shift();
-		else if (this.#error) throw this.#error;
+	receive() {
+		if (this.#receiveQueue.length > 0) return Promise.resolve(this.#receiveQueue.shift());
+		else if (this.#error) return Promise.reject(this.#error);
 		else return new Promise((resolve, reject) => {
 			this.#receiveResolver = resolve;
 			this.#receiveRejecter = reject;
@@ -2119,7 +2216,7 @@ var BatchClientTransport = class {
 	#aborted;
 	#batchToSend = [];
 	#batchToReceive = null;
-	async send(message) {
+	send(message) {
 		if (this.#batchToSend !== null) this.#batchToSend.push(message);
 	}
 	async receive() {
@@ -2161,7 +2258,7 @@ var BatchServerTransport = class {
 	#batchToSend = [];
 	#batchToReceive;
 	#allReceived = Promise.withResolvers();
-	async send(message) {
+	send(message) {
 		this.#batchToSend.push(message);
 	}
 	async receive() {
@@ -2235,17 +2332,17 @@ function newMessagePortRpcSession$1(port, localMain, options) {
 	return new RpcSession$1(new MessagePortTransport(port), localMain, options).getRemoteMain();
 }
 var MessagePortTransport = class {
+	encodingLevel = "structuredClonable";
 	constructor(port) {
 		this.#port = port;
 		port.start();
 		port.addEventListener("message", (event) => {
 			if (this.#error) {} else if (event.data === null) this.#receivedError(/* @__PURE__ */ new Error("Peer closed MessagePort connection."));
-			else if (typeof event.data === "string") if (this.#receiveResolver) {
+			else if (this.#receiveResolver) {
 				this.#receiveResolver(event.data);
 				this.#receiveResolver = void 0;
 				this.#receiveRejecter = void 0;
 			} else this.#receiveQueue.push(event.data);
-			else this.#receivedError(/* @__PURE__ */ new TypeError("Received non-string message from MessagePort."));
 		});
 		port.addEventListener("messageerror", (event) => {
 			this.#receivedError(/* @__PURE__ */ new Error("MessagePort message error."));
@@ -2256,7 +2353,7 @@ var MessagePortTransport = class {
 	#receiveRejecter;
 	#receiveQueue = [];
 	#error;
-	async send(message) {
+	send(message) {
 		if (this.#error) throw this.#error;
 		this.#port.postMessage(message);
 	}
@@ -2944,6 +3041,7 @@ exports.RpcPromise = RpcPromise;
 exports.RpcSession = RpcSession;
 exports.RpcStub = RpcStub;
 exports.RpcTarget = RpcTarget;
+exports.WebSocketTransport = WebSocketTransport;
 exports.deserialize = deserialize;
 exports.newBunWebSocketRpcHandler = newBunWebSocketRpcHandler;
 exports.newBunWebSocketRpcSession = newBunWebSocketRpcSession;