diff --git a/README.md b/README.md index c08efaf..ff3fa75 100644 --- a/README.md +++ b/README.md @@ -194,20 +194,22 @@ let userId: number = await authedApi.getUserId(); The following types can be passed over RPC (in arguments or return values), and will be passed "by value", meaning the content is serialized, producing a copy at the receiving end: -* Primitive values: strings, numbers, booleans, null, undefined +* Primitive values: strings, numbers (including `NaN`, `Infinity`, and `-Infinity`), booleans, null, undefined * Plain objects (e.g., from object literals) * Arrays * `bigint` * `Date` * `Uint8Array` -* `Error` and its well-known subclasses - -The following types are not supported as of this writing, but may be added in the future: +* `ArrayBuffer` * `Map` and `Set` -* `ArrayBuffer` and typed arrays other than `Uint8Array` * `RegExp` +* `URL` and `Headers` +* `Error` and its well-known subclasses (with full-fidelity serialization including `cause` chains and custom properties) + +The following types are not supported as of this writing, but may be added in the future: +* Typed arrays other than `Uint8Array` * `ReadableStream` and `WritableStream`, with automatic flow control. -* `Headers`, `Request`, and `Response` +* `Request` and `Response` (require asynchronous body handling) The following are intentionally NOT supported: * Application-defined classes that do not extend `RpcTarget`. @@ -317,7 +319,7 @@ To facilitate interoperability: So basically, it "just works". With that said, as of this writing, the feature set is not exactly the same between the two. We aim to fix this over time, by adding missing features to both sides until they match. In particular, as of this writing: -* Workers RPC supports some types that Cap'n Web does not yet, like `Map`, streams, etc. +* Workers RPC supports some types that Cap'n Web does not yet, like streams. * Workers RPC supports sending values that contain aliases and cycles. This can actually cause problems, so we actually plan to *remove* this feature from Workers RPC (with a compatibility flag, of course). * Workers RPC does not yet support placing an `RpcPromise` into the parameters of a request, to be replaced by its resolution. * Workers RPC does not yet support the magic `.map()` method. diff --git a/__tests__/index.test.ts b/__tests__/index.test.ts index f551d15..714012b 100644 --- a/__tests__/index.test.ts +++ b/__tests__/index.test.ts @@ -26,9 +26,25 @@ let SERIALIZE_TEST_CASES: Record = { '["date",1234]': new Date(1234), '["bytes","aGVsbG8h"]': new TextEncoder().encode("hello!"), '["undefined"]': undefined, - '["error","Error","the message"]': new Error("the message"), - '["error","TypeError","the message"]': new TypeError("the message"), - '["error","RangeError","the message"]': new RangeError("the message"), + '["error",{"name":"Error","message":"the message"}]': (() => { let e = new Error("the message"); delete e.stack; return e; })(), + '["error",{"name":"TypeError","message":"the message"}]': (() => { let e = new TypeError("the message"); delete e.stack; return e; })(), + '["error",{"name":"RangeError","message":"the message"}]': (() => { let e = new RangeError("the message"); delete e.stack; return e; })(), + '["special-number","NaN"]': NaN, + '["special-number","Infinity"]': Infinity, + '["special-number","-Infinity"]': -Infinity, + '["regexp",{"source":"test","flags":"gi"}]': /test/gi, + '["regexp",{"source":"^\\\\d+$","flags":""}]': /^\d+$/, + '["map",[[["foo","bar"]]]]': new Map([["foo", "bar"]]), + '["map",[[["a","b"]],[["c","d"]]]]': new Map([["a", "b"], ["c", "d"]]), + '["set",["foo","bar"]]': new Set(["foo", "bar"]), + '["arraybuffer","aGVsbG8h"]': new TextEncoder().encode("hello!").buffer, + '["url","https://example.com/path?q=1"]': new URL("https://example.com/path?q=1"), + '["headers",[["content-type","application/json"],["x-custom","value"]]]': (() => { + let h = new Headers(); + h.set("Content-Type", "application/json"); + h.set("X-Custom", "value"); + return h; + })(), }; class NotSerializable { @@ -96,6 +112,49 @@ describe("simple serialization", () => { expect(() => deserialize('["date"]')).toThrowError(); // missing timestamp expect(() => deserialize('["error"]')).toThrowError(); // missing type and message }) + + it("supports full fidelity Error serialization", () => { + // Test error with cause and custom properties + let error = new Error("outer error"); + error.name = "CustomError"; + let cause = new TypeError("inner error"); + error.cause = cause; + (error as any).customProp = "custom value"; + (error as any).code = 404; + + let serialized = serialize(error); + let deserialized = deserialize(serialized) as Error; + + expect(deserialized.name).toBe("CustomError"); + expect(deserialized.message).toBe("outer error"); + expect(deserialized.cause).toBeInstanceOf(TypeError); + expect((deserialized.cause as Error).message).toBe("inner error"); + expect((deserialized as any).customProp).toBe("custom value"); + expect((deserialized as any).code).toBe(404); + }) + + it("supports nested Map and Set structures", () => { + // Test Map with complex values + let map = new Map(); + map.set("key1", "value1"); + map.set(123, new Map([["nested", "map"]])); + let serialized = serialize(map); + let deserialized = deserialize(serialized) as Map; + expect(deserialized.get("key1")).toBe("value1"); + expect(deserialized.get(123)).toBeInstanceOf(Map); + expect((deserialized.get(123) as Map).get("nested")).toBe("map"); + + // Test Set with complex values + let set = new Set(); + set.add("item1"); + set.add(new Set(["nested", "set"])); + let serializedSet = serialize(set); + let deserializedSet = deserialize(serializedSet) as Set; + expect(deserializedSet.has("item1")).toBe(true); + let nestedSet = Array.from(deserializedSet).find(item => item instanceof Set) as Set; + expect(nestedSet).toBeInstanceOf(Set); + expect(nestedSet.has("nested")).toBe(true); + }) }); // ======================================================================================= @@ -1187,8 +1246,10 @@ describe("error serialization", () => { // By default, the stack isn't sent. A stack may be added client-side, though. So we // verify that it doesn't contain the function name `throwErrorImpl` nor the file name // `test-util.ts`, which should only appear on the server. - expect((err as Error).stack).not.toContain("throwErrorImpl"); - expect((err as Error).stack).not.toContain("test-util.ts"); + if ((err as Error).stack) { + expect((err as Error).stack).not.toContain("throwErrorImpl"); + expect((err as Error).stack).not.toContain("test-util.ts"); + } return "caught"; }); diff --git a/src/core.ts b/src/core.ts index 81ff88a..4aa0e7b 100644 --- a/src/core.ts +++ b/src/core.ts @@ -25,15 +25,21 @@ export type PropertyPath = (string | number)[]; type TypeForRpc = "unsupported" | "primitive" | "object" | "function" | "array" | "date" | "bigint" | "bytes" | "stub" | "rpc-promise" | "rpc-target" | "rpc-thenable" | "error" | - "undefined"; + "undefined" | "regexp" | "map" | "set" | "arraybuffer" | "url" | "headers" | "special-number"; export function typeForRpc(value: unknown): TypeForRpc { switch (typeof value) { case "boolean": - case "number": case "string": return "primitive"; + case "number": + // Check for special numbers (NaN, Infinity, -Infinity) + if (!isFinite(value)) { + return "special-number"; + } + return "primitive"; + case "undefined": return "undefined"; @@ -74,7 +80,17 @@ export function typeForRpc(value: unknown): TypeForRpc { case Uint8Array.prototype: return "bytes"; - // TODO: All other structured clone types. + case RegExp.prototype: + return "regexp"; + + case Map.prototype: + return "map"; + + case Set.prototype: + return "set"; + + case ArrayBuffer.prototype: + return "arraybuffer"; case RpcStub.prototype: return "stub"; @@ -107,6 +123,14 @@ export function typeForRpc(value: unknown): TypeForRpc { return "error"; } + // Check for URL and Headers (these don't have standard prototypes we can switch on) + if (typeof URL !== "undefined" && value instanceof URL) { + return "url"; + } + if (typeof Headers !== "undefined" && value instanceof Headers) { + return "headers"; + } + return "unsupported"; } } @@ -766,10 +790,36 @@ export class RpcPayload { case "bytes": case "error": case "undefined": + case "special-number": + case "regexp": + case "arraybuffer": + case "url": + case "headers": // immutable, no need to copy // TODO: Should errors be copied if they have own properties? return value; + case "map": { + let map = value as Map; + let result = new Map(); + for (let [key, val] of map) { + result.set( + this.deepCopy(key, map, 0, result, dupStubs, owner), + this.deepCopy(val, map, 1, result, dupStubs, owner) + ); + } + return result; + } + + case "set": { + let set = value as Set; + let result = new Set(); + for (let val of set) { + result.add(this.deepCopy(val, set, 0, result, dupStubs, owner)); + } + return result; + } + case "array": { // We have to construct the new array first, then fill it in, so we can pass it as the // parent. @@ -1034,6 +1084,13 @@ export class RpcPayload { case "date": case "error": case "undefined": + case "special-number": + case "regexp": + case "map": + case "set": + case "arraybuffer": + case "url": + case "headers": return; case "array": { @@ -1120,6 +1177,13 @@ export class RpcPayload { case "date": case "error": case "undefined": + case "special-number": + case "regexp": + case "map": + case "set": + case "arraybuffer": + case "url": + case "headers": case "function": case "rpc-target": return; @@ -1247,7 +1311,18 @@ function followPath(value: unknown, parent: object | undefined, case "bytes": case "date": case "error": - // These have no properties that can be accessed remotely. + case "special-number": + case "regexp": + case "arraybuffer": + case "url": + case "headers": + // These have no properties that can be accessed remotely (or are immutable). + value = undefined; + break; + + case "map": + case "set": + // Map and Set don't support property access via this mechanism value = undefined; break; diff --git a/src/serialize.ts b/src/serialize.ts index 1038378..0506687 100644 --- a/src/serialize.ts +++ b/src/serialize.ts @@ -153,24 +153,132 @@ export class Devaluator { } } + case "special-number": { + let num = value as number; + if (Number.isNaN(num)) { + return ["special-number", "NaN"]; + } else if (num === Infinity) { + return ["special-number", "Infinity"]; + } else if (num === -Infinity) { + return ["special-number", "-Infinity"]; + } + // Should not happen if typeForRpc is correct - fall through to default case + break; + } + + case "regexp": { + let re = value as RegExp; + return ["regexp", { source: re.source, flags: re.flags }]; + } + + case "map": { + let map = value as Map; + let entries: unknown[] = []; + for (let [key, val] of map) { + // Each entry is a [key, val] array, which needs to be wrapped like any array + let keyVal = [ + this.devaluateImpl(key, map, depth + 1), + this.devaluateImpl(val, map, depth + 1) + ]; + entries.push([keyVal]); + } + return ["map", entries]; + } + + case "set": { + let set = value as Set; + let values: unknown[] = []; + for (let val of set) { + let serializedVal = this.devaluateImpl(val, set, depth + 1); + // If the value serialized to an array, it's already wrapped by devaluateImpl + // But for Set, we need to wrap array values one more time + if (serializedVal instanceof Array && !(serializedVal.length > 0 && typeof serializedVal[0] === "string")) { + values.push([serializedVal]); + } else { + values.push(serializedVal); + } + } + return ["set", values]; + } + + case "arraybuffer": { + let buffer = value as ArrayBuffer; + let bytes = new Uint8Array(buffer); + if ((bytes as any).toBase64) { + return ["arraybuffer", (bytes as any).toBase64({omitPadding: true})]; + } else { + // Convert Uint8Array to number array for String.fromCharCode + let bytesArray = new Array(bytes.length); + for (let i = 0; i < bytes.length; i++) { + bytesArray[i] = bytes[i]; + } + return ["arraybuffer", + btoa(String.fromCharCode.apply(null, bytesArray).replace(/=*$/, ""))]; + } + } + + case "url": { + let url = value as URL; + return ["url", url.href]; + } + + case "headers": { + let headers = value as Headers; + let entries: Array<[string, string]> = []; + headers.forEach((value, key) => { + entries.push([key, value]); + }); + return ["headers", entries]; + } + case "error": { let e = value; - // TODO: - // - Determine type by checking prototype rather than `name`, which can be overridden? - // - Serialize cause / suppressed error / etc. - // - Serialize added properties. - let rewritten = this.exporter.onSendError(e); if (rewritten) { e = rewritten; } - let result = ["error", e.name, e.message]; - if (rewritten && rewritten.stack) { - result.push(rewritten.stack); + // Full fidelity error serialization: name, message, stack, cause (recursive), customProps + let errorData: Record = { + name: e.name || "Error", + message: e.message || "" + }; + + // Preserve stack trace only if onSendError returned an Error with stack property + // (same behavior as original implementation) + if (rewritten && rewritten.stack !== undefined) { + errorData.stack = rewritten.stack; } - return result; + + // Preserve cause (recursive - cause can be another Error) + if (e.cause !== undefined) { + errorData.cause = this.devaluateImpl(e.cause, e, depth + 1); + } + + // Capture custom properties (best effort) + // Use getOwnPropertyNames to capture both enumerable and non-enumerable properties + // Standard Error properties: name, message, stack, cause + // Browser-specific properties to exclude: line, column, sourceURL (WebKit), fileName, lineNumber, columnNumber (Firefox) + const browserProps = new Set(["line", "column", "sourceURL", "fileName", "lineNumber", "columnNumber"]); + let customProps: Record = {}; + const allProps = Object.getOwnPropertyNames(e); + for (const key of allProps) { + if (key !== "name" && key !== "message" && key !== "stack" && key !== "cause" && !browserProps.has(key)) { + try { + customProps[key] = this.devaluateImpl(e[key as keyof Error], e, depth + 1); + } catch (err) { + // Skip properties that can't be accessed or serialized + } + } + } + + // Only include customProps if not empty + if (Object.keys(customProps).length > 0) { + errorData.customProps = customProps; + } + + return ["error", errorData]; } case "undefined": @@ -315,6 +423,90 @@ export class Evaluator { return new Date(value[1]); } break; + case "special-number": + if (typeof value[1] == "string") { + if (value[1] == "NaN") { + return NaN; + } else if (value[1] == "Infinity") { + return Infinity; + } else if (value[1] == "-Infinity") { + return -Infinity; + } + } + break; + case "regexp": + if (value[1] && typeof value[1] == "object" && typeof value[1].source == "string") { + return new RegExp(value[1].source, value[1].flags || ""); + } + break; + case "map": + if (value[1] instanceof Array) { + let map = new Map(); + for (let wrappedEntry of value[1]) { + // Each entry is wrapped: [[key, val]] + if (wrappedEntry instanceof Array && wrappedEntry.length == 1 && + wrappedEntry[0] instanceof Array && wrappedEntry[0].length == 2) { + let entry = wrappedEntry[0]; + map.set( + this.evaluateImpl(entry[0], map, 0), + this.evaluateImpl(entry[1], map, 1) + ); + } + } + return map; + } + break; + case "set": + if (value[1] instanceof Array) { + let set = new Set(); + for (let wrappedItem of value[1]) { + // Items in Set may be wrapped if they were arrays: [[value]] + let item = wrappedItem; + if (wrappedItem instanceof Array && wrappedItem.length === 1 && + wrappedItem[0] instanceof Array && !(wrappedItem[0].length > 0 && typeof wrappedItem[0][0] === "string")) { + // It's a wrapped array, unwrap it + item = wrappedItem[0]; + } + set.add(this.evaluateImpl(item, set, 0)); + } + return set; + } + break; + case "arraybuffer": { + let b64 = Uint8Array as any as FromBase64; + if (typeof value[1] == "string") { + if (b64.fromBase64) { + let bytes = b64.fromBase64(value[1]); + return (bytes as any).buffer as ArrayBuffer; + } else { + let bs = atob(value[1]); + let len = bs.length; + let bytes = new Uint8Array(len); + for (let i = 0; i < len; i++) { + bytes[i] = bs.charCodeAt(i); + } + return bytes.buffer; + } + } + break; + } + case "url": + if (typeof value[1] == "string") { + return new URL(value[1]); + } + break; + case "headers": + if (value[1] instanceof Array) { + let headers = new Headers(); + for (let entry of value[1]) { + if (entry instanceof Array && entry.length == 2 && + typeof entry[0] == "string" && typeof entry[1] == "string") { + headers.set(entry[0], entry[1]); + } + } + return headers; + } + break; case "bytes": { let b64 = Uint8Array as FromBase64; if (typeof value[1] == "string") { @@ -333,12 +525,58 @@ export class Evaluator { break; } case "error": + // Support both old format: ["error", name, message, stack?] + // and new format: ["error", {name, message, stack?, cause?, customProps?}] if (value.length >= 3 && typeof value[1] === "string" && typeof value[2] === "string") { + // Old format - backward compatibility let cls = ERROR_TYPES[value[1]] || Error; let result = new cls(value[2]); if (typeof value[3] === "string") { result.stack = value[3]; } + return result; + } else if (value.length >= 2 && value[1] && typeof value[1] === "object") { + // New format with full fidelity + let errorData = value[1] as { + name: string; + message: string; + stack?: string; + cause?: unknown; + customProps?: Record; + }; + let cls = ERROR_TYPES[errorData.name] || Error; + let result = new cls(errorData.message || ""); + + // Always delete auto-generated stack first + delete result.stack; + + // Only set name explicitly if it's not a standard error type or differs from default + // This preserves the correct non-enumerable property for standard errors + if (!ERROR_TYPES[errorData.name] || result.name !== errorData.name) { + // Delete the auto-set name first, then set our own + delete (result as any).name; + Object.defineProperty(result, 'name', { + value: errorData.name, + writable: true, + enumerable: false, + configurable: true + }); + } + + if (errorData.stack !== undefined) { + result.stack = errorData.stack; + } + + if (errorData.cause !== undefined) { + result.cause = this.evaluateImpl(errorData.cause, result, "cause"); + } + + if (errorData.customProps) { + for (let key in errorData.customProps) { + result[key] = this.evaluateImpl(errorData.customProps[key], result, key); + } + } + return result; } break;