feat(capn-web): new package implementing Cap'n Web RPC

packages/capn-web/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@endo/capn-web",
+  "version": "0.1.0",
+  "description": "Cap'n Web RPC for the browser, on top of @endo/eventual-send",
+  "type": "module",
+  "keywords": [
+    "endo",
+    "capnweb",
+    "rpc",
+    "eventual-send",
+    "object-capabilities"
+  ],
+  "author": "Endo contributors",
+  "homepage": "https://github.com/endojs/endo#readme",
+  "license": "Apache-2.0",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./loopback.js": "./src/transports/loopback.js",
+    "./websocket.js": "./src/transports/websocket.js",
+    "./http-batch.js": "./src/transports/http-batch.js",
+    "./message-port.js": "./src/transports/message-port.js",
+    "./package.json": "./package.json"
+  },
+  "module": "src/index.js",
+  "directories": {
+    "src": "src",
+    "test": "test"
+  },
+  "files": [
+    "./*.d.ts",
+    "./*.js",
+    "./*.map",
+    "LICENSE*",
+    "SECURITY*",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endojs/endo.git",
+    "directory": "packages/capn-web"
+  },
+  "scripts": {
+    "build": "exit 0",
+    "prepack": "git clean -fX -e node_modules/ && tsc --build tsconfig.build.json",
+    "postpack": "git clean -fX -e node_modules/",
+    "test": "ses-ava",
+    "test:xs": "exit 0",
+    "lint-fix": "yarn lint:eslint --fix && yarn lint:types",
+    "lint": "yarn lint:eslint && yarn lint:types",
+    "lint:eslint": "eslint '**/*.js'",
+    "lint:types": "tsc"
+  },
+  "devDependencies": {
+    "@endo/init": "workspace:^",
+    "@endo/ses-ava": "workspace:^",
+    "ava": "catalog:dev",
+    "c8": "catalog:dev",
+    "capnweb": "^0.6.1",
+    "eslint": "catalog:dev",
+    "ses": "workspace:^",
+    "typescript": "catalog:dev"
+  },
+  "dependencies": {
+    "@endo/errors": "workspace:^",
+    "@endo/eventual-send": "workspace:^",
+    "@endo/exo": "workspace:^",
+    "@endo/harden": "workspace:^",
+    "@endo/pass-style": "workspace:^",
+    "@endo/promise-kit": "workspace:^"
+  },
+  "bugs": {
+    "url": "https://github.com/endojs/endo/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sesAvaConfigs": {
+    "lockdown": "../../ava-endo-lockdown.config.mjs",
+    "unsafe": "../../ava-endo-lockdown-unsafe.config.mjs",
+    "endo": "../../ava-endo-shims-only.config.mjs"
+  },
+  "eslintConfig": {
+    "extends": [
+      "plugin:@endo/internal"
+    ]
+  },
+  "typeCoverage": {
+    "atLeast": 0
+  }
+}

packages/capn-web/src/devaluate.js

@@ -0,0 +1,226 @@
+/* global globalThis */
+// Devaluator: turn a live JS value into a Cap'n Web wire expression.
+//
+// The output is a JSON-serialisable structure whose semantics are described
+// in https://github.com/cloudflare/capnweb/blob/main/protocol.md
+//
+// Notably:
+//   - Arrays are wrapped in another array as [[...]] (escape) to disambiguate
+//     them from instruction arrays.
+//   - Capabilities are encoded as ["export", -id] / ["promise", -id] (when
+//     freshly introduced) or ["import", id] (when round-tripping a remote
+//     reference).
+//   - Special atomic values (undefined, BigInt, Date, etc.) get tagged forms.
+//
+// Classification dispatches in this order:
+//   1. atomic specials (undefined / nan / inf / bigint / Date / Uint8Array
+//      / Error) via tryEncodeSpecial
+//   2. JSON-safe primitives (null, string, boolean, finite number)
+//   3. host objects with explicit wire forms (Headers / Request / Response,
+//      WritableStream / ReadableStream)
+//   4. round-trip identity for stubs we already imported
+//   5. `passStyleOf` leaf classification — used to recognise remotables
+//      (Far / makeExo) and bare promises in a way that respects endo's
+//      pass-style discipline.  We do NOT pass the whole value tree through
+//      passStyleOf, because that's recursive and would reject any nested
+//      non-passable host (Date, Uint8Array, …) that we already handle
+//      ourselves.
+//   6. plain arrays and records — recursed locally
+//   7. anything else → "cannot serialize" error.
+
+import harden from '@endo/harden';
+import { passStyleOf } from '@endo/pass-style';
+
+import { tryEncodeSpecial } from './special-values.js';
+import {
+  isHeaders,
+  isRequest,
+  isResponse,
+  encodeHeaders,
+  encodeRequest,
+  encodeResponse,
+} from './fetch-codec.js';
+import { exportWritableStream, exportReadableStream } from './streams.js';
+import { isForbiddenKey } from './path-keys.js';
+
+const G = /** @type {any} */ (globalThis);
+
+const isPlainObject = v => {
+  if (v === null || typeof v !== 'object') return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+
+/**
+ * Try `passStyleOf` on a single value but don't let it raise — we only
+ * use it for leaf classification (remotable / promise / error).  Returns
+ * undefined if the value isn't passable on its own terms.
+ *
+ * @param {unknown} value
+ */
+const passStyleOfOrUndefined = value => {
+  try {
+    return passStyleOf(/** @type {any} */ (value));
+  } catch (_e) {
+    return undefined;
+  }
+};
+
+/**
+ * @typedef {object} DevaluatorContext
+ * @property {(value: object) => number | undefined} importIdOf
+ *   If `value` is a remote stub (presence or promise) from this session's
+ *   imports, returns its allocator-side id; otherwise undefined.
+ * @property {(value: unknown, isPromise: boolean) => number} exportValue
+ *   Allocate (or reuse) a negative export id and register `value` as our
+ *   export.  Returns the id.
+ * @property {(readable: ReadableStream) => number} [sendPipe]
+ *   Open a capnweb-compatible `["pipe"]` channel for `readable` and
+ *   return the new positive import id.  When omitted (e.g. devaluating
+ *   outside a session context), `ReadableStream` values fall back to
+ *   the legacy Far'd readable stub form.
+ */
+
+/**
+ * @param {DevaluatorContext} ctx
+ */
+export const makeDevaluator = ctx => {
+  /**
+   * @param {unknown} value
+   * @param {WeakSet<object>} seen  Tracks containers currently on the
+   *   recursion stack to detect cycles.
+   * @returns {unknown}
+   */
+  const devaluateInner = (value, seen) => {
+    // 1. Atomic specials.
+    const special = tryEncodeSpecial(value);
+    if (special !== undefined) return special;
+
+    // 2. JSON-safe primitives.
+    if (value === null) return null;
+    if (typeof value === 'string') return value;
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'number') return value;
+
+    // 3. Host objects with explicit wire forms.
+    if (isHeaders(value)) return encodeHeaders(/** @type {Headers} */ (value));
+    if (isRequest(value)) {
+      return encodeRequest(/** @type {Request} */ (value), v =>
+        devaluateInner(v, seen),
+      );
+    }
+    if (isResponse(value)) {
+      return encodeResponse(/** @type {Response} */ (value), v =>
+        devaluateInner(v, seen),
+      );
+    }
+    if (G.WritableStream && value instanceof G.WritableStream) {
+      const writer = exportWritableStream(
+        /** @type {WritableStream} */ (value),
+      );
+      const id = ctx.exportValue(writer, false);
+      return ['writable', id];
+    }
+    if (G.ReadableStream && value instanceof G.ReadableStream) {
+      // Capnweb-compatible: send `["pipe"]` and reference the new pipe
+      // import id via `["readable", +id]`.  The framework pumps the
+      // user's readable into a synthetic writable that issues per-chunk
+      // method calls on the import.  Falls back to the legacy Far'd
+      // readable stub form (`["readable", -id]`) if `sendPipe` isn't
+      // configured (e.g. no `TransformStream` available, or the
+      // devaluator was constructed in a non-session context).
+      if (ctx.sendPipe) {
+        const id = ctx.sendPipe(/** @type {ReadableStream} */ (value));
+        return ['readable', id];
+      }
+      const reader = exportReadableStream(
+        /** @type {ReadableStream} */ (value),
+      );
+      const id = ctx.exportValue(reader, false);
+      return ['readable', id];
+    }
+
+    // 4. Round-trip identity.
+    if (
+      value !== null &&
+      (typeof value === 'object' || typeof value === 'function')
+    ) {
+      const importId = ctx.importIdOf(/** @type {object} */ (value));
+      if (importId !== undefined) {
+        const isPromiseStub =
+          typeof (/** @type {any} */ (value).then) === 'function';
+        return [isPromiseStub ? 'pipeline' : 'import', importId];
+      }
+    }
+
+    // 5. Pass-style leaf classification — remotable / promise / error.
+    const style = passStyleOfOrUndefined(value);
+    if (style === 'remotable') {
+      const id = ctx.exportValue(value, false);
+      return ['export', id];
+    }
+    if (style === 'promise') {
+      const id = ctx.exportValue(value, true);
+      return ['promise', id];
+    }
+    if (style === 'error') {
+      return [
+        'error',
+        /** @type {any} */ (value).name || 'Error',
+        /** @type {any} */ (value).message || '',
+      ];
+    }
+
+    // 6. Plain shapes — locally recursed.  Detect cycles up-front: a
+    //    structure that contains itself can't be serialised, and a naive
+    //    recursion would never return.
+    if (Array.isArray(value)) {
+      if (seen.has(/** @type {object} */ (value))) {
+        throw new TypeError('Cannot serialize circular reference');
+      }
+      seen.add(/** @type {object} */ (value));
+      try {
+        return [value.map(v => devaluateInner(v, seen))];
+      } finally {
+        seen.delete(/** @type {object} */ (value));
+      }
+    }
+    if (isPlainObject(value)) {
+      if (seen.has(/** @type {object} */ (value))) {
+        throw new TypeError('Cannot serialize circular reference');
+      }
+      seen.add(/** @type {object} */ (value));
+      try {
+        /** @type {Record<string, unknown>} */
+        const out = {};
+        for (const [k, v] of Object.entries(/** @type {object} */ (value))) {
+          if (!isForbiddenKey(k)) {
+            out[k] = devaluateInner(v, seen);
+          }
+        }
+        return out;
+      } finally {
+        seen.delete(/** @type {object} */ (value));
+      }
+    }
+
+    // 7. Functions that aren't marked as remotables, exotic class
+    //    instances, etc.  Reject with a clear message.
+    if (typeof value === 'function') {
+      throw new TypeError(
+        `Cannot serialize bare function; wrap with Far / makeExo to expose it as a remotable.`,
+      );
+    }
+    throw new TypeError(
+      `Cannot serialize value of type ${Object.prototype.toString.call(value)}`,
+    );
+  };
+
+  /**
+   * @param {unknown} value
+   * @returns {unknown} a JSON-serialisable expression
+   */
+  const devaluate = value => devaluateInner(value, new WeakSet());
+
+  return harden({ devaluate });
+};