@nimbus-sh/loom 0.1.0

package/src/callable.ts

@@ -0,0 +1,76 @@
+/**
+ * callable.ts — the opt-in that makes an actor method reachable over the
+ * connection.
+ *
+ * RPC exposure is allowlist-only: a method a client can invoke by name is a
+ * public surface, and an accidental one is a vulnerability. `callable()`
+ * is the allowlist mark. The mechanism mirrors the Agents SDK exactly
+ * (verified in `agents` 0.20.1 dist, `index.js:54,112-134`): a TC39
+ * standard method decorator whose registry is a module-level
+ * `WeakMap<Function, CallableMetadata>` keyed by the method's function
+ * object. Keying by function makes the mark travel with the method through
+ * inheritance and `this[name]` lookup, and costs nothing at class-definition
+ * time.
+ *
+ * The decorator ignores its context argument, so plain-JS callers (tests,
+ * codebases without decorator syntax) can mark a method directly:
+ * `callable()(MyActor.prototype.greet)`.
+ */
+
+export interface CallableMetadata {
+  /** What the method does, for surface listings. */
+  description?: string;
+  /**
+   * A streaming method receives a {@link import('./rpc.js').StreamingResponse}
+   * as its FIRST argument, ahead of the caller's own, and replies through it.
+   * Its return value is discarded.
+   */
+  streaming?: boolean;
+}
+
+const registry = new WeakMap<object, CallableMetadata>();
+
+/**
+ * Mark a method as callable over the connection. First mark wins; marking
+ * the same function twice keeps the first metadata.
+ */
+export function callable(metadata: CallableMetadata = {}) {
+  return function markCallable<This, Args extends unknown[], Return>(
+    target: (this: This, ...args: Args) => Return,
+    _context?: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
+  ): (this: This, ...args: Args) => Return {
+    if (!registry.has(target)) registry.set(target, metadata);
+    return target;
+  };
+}
+
+/** True when the value is a function carrying the callable mark. */
+export function isCallable(method: unknown): boolean {
+  return typeof method === 'function' && registry.has(method);
+}
+
+/** The mark's metadata, or undefined for an unmarked value. */
+export function callableMetadata(method: unknown): CallableMetadata | undefined {
+  return typeof method === 'function' ? registry.get(method) : undefined;
+}
+
+/**
+ * Every callable method reachable from an instance, by name, walking the
+ * prototype chain. A subclass override without its own mark hides the
+ * marked parent method — the override is what `this[name]` resolves to,
+ * and it is unmarked.
+ */
+export function callableMethods(target: object): Map<string, CallableMetadata> {
+  const found = new Map<string, CallableMetadata>();
+  const shadowed = new Set<string>();
+  for (let proto = Object.getPrototypeOf(target); proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+    for (const name of Object.getOwnPropertyNames(proto)) {
+      if (name === 'constructor' || shadowed.has(name)) continue;
+      // Own descriptors only — reading `instance[name]` would run getters.
+      shadowed.add(name);
+      const metadata = callableMetadata(Object.getOwnPropertyDescriptor(proto, name)?.value);
+      if (metadata !== undefined) found.set(name, metadata);
+    }
+  }
+  return found;
+}

package/src/client.ts

@@ -0,0 +1,153 @@
+/**
+ * client.ts — the caller's half of callable RPC: a promise per call, and a
+ * typed stub proxy that makes an actor's methods look local.
+ *
+ * Dependency-free and workerd-free on purpose: the socket is anything with
+ * `send` and message listeners — a browser WebSocket, a PartySocket, a
+ * server-side WebSocket from `fetch()` — so this module runs wherever the
+ * connection was made. Frames and defaults follow the Agents SDK client
+ * (verified in `agents` 0.20.1 dist, `client.js:129-151,217-248`): ids are
+ * `crypto.randomUUID()`, plain calls time out at 30 s by default, streamed
+ * calls (an `onChunk` listener) get no timeout unless one is passed.
+ */
+
+import { isRpcResponseFrame, RPC_FRAME_TYPE } from './protocol.js';
+import type { StreamingResponse } from './rpc.js';
+
+/** The connection as the client drives it. A browser WebSocket satisfies it. */
+export interface ActorSocket {
+  send(data: string): void;
+  addEventListener(type: 'message', listener: (event: { data: unknown }) => void): void;
+  removeEventListener(type: 'message', listener: (event: { data: unknown }) => void): void;
+}
+
+export interface ActorCallOptions {
+  /**
+   * Reject the call after this long. Default: 30,000 ms for plain calls;
+   * none for streamed calls.
+   */
+  timeoutMs?: number;
+  /** Receives each `done: false` chunk of a streamed reply. */
+  onChunk?: (chunk: unknown) => void;
+}
+
+/**
+ * The target's async methods, callable as promises. Which of them the actor
+ * actually answers is decided server-side by the `callable()` mark; an
+ * unmarked method rejects with "is not callable".
+ *
+ * A streaming callable's `StreamingResponse` parameter is server-side —
+ * the caller passes the remaining arguments and the promise resolves with
+ * the final chunk, so the stub type strips that first parameter. The
+ * detection is structural: a method whose first parameter merely ACCEPTS a
+ * StreamingResponse (`unknown`, a broad object) is typed as streaming too.
+ */
+export type ActorStub<T> = {
+  [K in keyof T as T[K] extends (...args: never[]) => unknown ? K : never]: T[K] extends (
+    stream: StreamingResponse,
+    ...args: infer StreamArgs
+  ) => unknown
+    ? (...args: StreamArgs) => Promise<unknown>
+    : T[K] extends (...args: infer Args) => infer Return
+      ? (...args: Args) => Promise<Awaited<Return>>
+      : never;
+};
+
+export interface ActorClient {
+  /** Call one callable method by name. */
+  call<T = unknown>(method: string, args?: unknown[], options?: ActorCallOptions): Promise<T>;
+  /** A proxy whose method calls become `call(name, args)`. */
+  stub<T>(options?: ActorCallOptions): ActorStub<T>;
+  /** Detach from the socket and reject every call still pending. */
+  close(): void;
+}
+
+export const DEFAULT_CALL_TIMEOUT_MS = 30_000;
+
+interface PendingCall {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  onChunk?: (chunk: unknown) => void;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+/** Attach an RPC client to a socket. One message listener for all calls. */
+export function actorClient(socket: ActorSocket, defaults: ActorCallOptions = {}): ActorClient {
+  const pending = new Map<string, PendingCall>();
+
+  const onMessage = (event: { data: unknown }): void => {
+    if (typeof event.data !== 'string') return;
+    let frame: unknown;
+    try {
+      frame = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    if (!isRpcResponseFrame(frame)) return;
+    const call = pending.get(frame.id);
+    if (!call) return;
+    if (frame.success === false) {
+      settle(frame.id)?.reject(new Error(frame.error));
+      return;
+    }
+    if (frame.done === false) {
+      call.onChunk?.(frame.result);
+      return;
+    }
+    settle(frame.id)?.resolve(frame.result);
+  };
+
+  const settle = (id: string): PendingCall | undefined => {
+    const call = pending.get(id);
+    if (!call) return undefined;
+    pending.delete(id);
+    if (call.timer !== undefined) clearTimeout(call.timer);
+    return call;
+  };
+
+  socket.addEventListener('message', onMessage);
+
+  const call = <T>(method: string, args: unknown[] = [], options: ActorCallOptions = {}): Promise<T> => {
+    const onChunk = options.onChunk ?? defaults.onChunk;
+    const timeoutMs = options.timeoutMs ?? defaults.timeoutMs ?? (onChunk ? undefined : DEFAULT_CALL_TIMEOUT_MS);
+    const id = crypto.randomUUID();
+    return new Promise<T>((resolve, reject) => {
+      const entry: PendingCall = { resolve: resolve as (value: unknown) => void, reject, onChunk };
+      if (timeoutMs !== undefined) {
+        entry.timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`RPC call '${method}' timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+      pending.set(id, entry);
+      try {
+        socket.send(JSON.stringify({ type: RPC_FRAME_TYPE, id, method, args }));
+      } catch (e) {
+        settle(id);
+        reject(e instanceof Error ? e : new Error(String(e)));
+      }
+    });
+  };
+
+  return {
+    call,
+    stub<T>(options?: ActorCallOptions): ActorStub<T> {
+      return new Proxy({} as ActorStub<T>, {
+        get(_target, name) {
+          if (typeof name !== 'string') return undefined;
+          // `await stub` (or any promise resolution of the stub itself)
+          // probes `.then`; answering with a caller would fire an RPC
+          // literally named "then".
+          if (name === 'then') return undefined;
+          return (...args: unknown[]) => call(name, args, options);
+        },
+      });
+    },
+    close(): void {
+      socket.removeEventListener('message', onMessage);
+      for (const id of [...pending.keys()]) {
+        settle(id)?.reject(new Error('RPC client closed'));
+      }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @nimbus-sh/loom — the actor framework of Nimbus: partyserver's surface on
+ * top, the @nimbus-sh/fabric floor pre-wired underneath.
+ *
+ * The root export pulls `partyserver`, which imports `cloudflare:workers`,
+ * so importing this module outside workerd fails at resolution. Non-workerd
+ * consumers (tests, browser clients) import the subpath modules they need —
+ * `@nimbus-sh/loom/client.js` is workerd-free by design.
+ */
+
+export * from './actor.js';
+export * from './callable.js';
+export * from './client.js';
+export * from './protocol.js';
+export * from './routing.js';
+export * from './rpc.js';
+export * from './schedules.js';
+export { Server } from 'partyserver';
+export type { Connection, ConnectionContext, WSMessage } from 'partyserver';

package/src/protocol.ts

@@ -0,0 +1,84 @@
+/**
+ * protocol.ts — the JSON frames loom speaks over a WebSocket connection.
+ *
+ * The frame shapes and type strings match the Cloudflare Agents SDK
+ * (`agents` 0.20.1, verified in its shipped dist: `types.js:5-15` for the
+ * type strings, `agent-tool-types` d.ts for the request/response shapes).
+ * Matching them is deliberate: a client written for an Agents server — the
+ * SDK's own `AgentClient` included — can drive a loom actor's state sync and
+ * RPC without translation. Only the frames loom implements are declared
+ * here; the Agents-product frames (MCP, identity, sessions) are not.
+ *
+ * A string message that parses as JSON and carries one of these `type`
+ * values is a protocol frame and never reaches the embedder's `onMessage`.
+ * Everything else — binary, non-JSON text, JSON with any other `type` —
+ * passes through untouched.
+ */
+
+/** State sync, both directions: `{ type, state }`. */
+export const STATE_FRAME_TYPE = 'cf_agent_state';
+
+/** Server → client: a client state update was refused. */
+export const STATE_ERROR_FRAME_TYPE = 'cf_agent_state_error';
+
+/** Callable RPC, both directions. */
+export const RPC_FRAME_TYPE = 'rpc';
+
+/** Client → server: replace the actor's state. */
+export interface StateFrame<S = unknown> {
+  type: typeof STATE_FRAME_TYPE;
+  state: S;
+}
+
+/** Server → client: the refusal a rejected state update earns. */
+export interface StateErrorFrame {
+  type: typeof STATE_ERROR_FRAME_TYPE;
+  error: string;
+}
+
+/** Client → server: call one `callable()` method by name. */
+export interface RpcRequestFrame {
+  type: typeof RPC_FRAME_TYPE;
+  /** Correlates the response frames to the call. The client mints it. */
+  id: string;
+  method: string;
+  args: unknown[];
+}
+
+/**
+ * Server → client. A streamed reply is many `done: false` frames and one
+ * `done: true`; a plain reply is a single `done: true` frame. `done` absent
+ * means final (the Agents client treats it so; loom always sets it).
+ */
+export type RpcResponseFrame = { type: typeof RPC_FRAME_TYPE; id: string } & (
+  | { success: true; result: unknown; done?: boolean }
+  | { success: false; error: string }
+);
+
+/** Same guard the Agents server uses: `type` plus a `state` key. */
+export function isStateFrame(value: unknown): value is StateFrame {
+  return (
+    typeof value === 'object' && value !== null
+    && (value as { type?: unknown }).type === STATE_FRAME_TYPE
+    && 'state' in value
+  );
+}
+
+/** Same guard the Agents server uses: all four fields, `args` an array. */
+export function isRpcRequestFrame(value: unknown): value is RpcRequestFrame {
+  if (typeof value !== 'object' || value === null) return false;
+  const frame = value as Partial<RpcRequestFrame>;
+  return (
+    frame.type === RPC_FRAME_TYPE
+    && typeof frame.id === 'string'
+    && typeof frame.method === 'string'
+    && Array.isArray(frame.args)
+  );
+}
+
+/** The client-side guard for response frames. */
+export function isRpcResponseFrame(value: unknown): value is RpcResponseFrame {
+  if (typeof value !== 'object' || value === null) return false;
+  const frame = value as { type?: unknown; id?: unknown; success?: unknown };
+  return frame.type === RPC_FRAME_TYPE && typeof frame.id === 'string' && typeof frame.success === 'boolean';
+}

package/src/routing.ts

@@ -0,0 +1,19 @@
+/**
+ * routing.ts — URL → binding → named actor instance.
+ *
+ * partyserver's router already is the mechanism loom wants: it maps
+ * `/${prefix}/<binding-kebab>/<name>` onto the Durable Object binding, with
+ * `onBeforeConnect`/`onBeforeRequest` gates, CORS, jurisdiction, location
+ * hints, and retry over transient DO routing errors. Wrapping it in a
+ * parallel implementation would be a drift channel, so loom re-exports it
+ * under its own names. The URL convention stays `/parties/...` by default —
+ * it is the wire contract PartySocket-family clients build URLs from.
+ */
+
+export {
+  routePartykitRequest as routeActorRequest,
+  getServerByName as getActorByName,
+  type PartyServerOptions as ActorRoutingOptions,
+  type Lobby,
+  type RoutingRetryOptions,
+} from 'partyserver';

package/src/rpc.ts

@@ -0,0 +1,110 @@
+/**
+ * rpc.ts — the server half of callable RPC: dispatch one request frame to a
+ * marked method and answer over the connection.
+ *
+ * The dispatch contract mirrors the Agents SDK (verified in `agents` 0.20.1
+ * dist, `index.js:883-934`):
+ *   - the method must exist on the target AND carry the `callable()` mark;
+ *     either failure is an error frame, not a crash.
+ *   - a streaming method receives a {@link StreamingResponse} PREPENDED to
+ *     the caller's arguments and owns its own reply frames; if it throws
+ *     with the stream still open, the error closes the stream.
+ *   - a plain method's awaited return value goes back as one
+ *     `{ success: true, done: true }` frame; a throw becomes
+ *     `{ success: false, error }` carrying the message only, never the stack.
+ *
+ * Sends tolerate exactly one failure: workerd throws a TypeError containing
+ * "WebSocket send() after close" when the peer is gone, and a reply that
+ * cannot be delivered has no one waiting for it. Every other send error is
+ * a real bug and propagates.
+ */
+
+import { callableMetadata, isCallable } from './callable.js';
+import { RPC_FRAME_TYPE, type RpcRequestFrame, type RpcResponseFrame } from './protocol.js';
+
+/** The connection as RPC writes to it. partyserver's `Connection` satisfies it. */
+export interface RpcConnection {
+  send(message: string): void;
+}
+
+function sendIfOpen(connection: RpcConnection, frame: RpcResponseFrame): boolean {
+  try {
+    connection.send(JSON.stringify(frame));
+    return true;
+  } catch (e) {
+    if (e instanceof TypeError && e.message.includes('WebSocket send() after close')) return false;
+    throw e;
+  }
+}
+
+/**
+ * The reply channel a streaming callable writes through. One `end()` (or
+ * `error()`) closes it; every later write is a refused no-op that returns
+ * false, matching the Agents SDK's `StreamingResponse` (dist
+ * `index.js:7169-7233`).
+ */
+export class StreamingResponse {
+  #closed = false;
+
+  constructor(
+    private readonly connection: RpcConnection,
+    private readonly id: string,
+  ) {}
+
+  get isClosed(): boolean {
+    return this.#closed;
+  }
+
+  /** One chunk. Returns false when the stream is closed or the peer is gone. */
+  send(chunk: unknown): boolean {
+    if (this.#closed) {
+      console.warn('loom: StreamingResponse.send() after the stream was closed — chunk not sent');
+      return false;
+    }
+    return sendIfOpen(this.connection, { type: RPC_FRAME_TYPE, id: this.id, success: true, result: chunk, done: false });
+  }
+
+  /** Close the stream, with an optional final chunk. */
+  end(finalChunk?: unknown): boolean {
+    if (this.#closed) return false;
+    this.#closed = true;
+    return sendIfOpen(this.connection, { type: RPC_FRAME_TYPE, id: this.id, success: true, result: finalChunk, done: true });
+  }
+
+  /** Close the stream with an error the caller's promise rejects on. */
+  error(message: string): boolean {
+    if (this.#closed) return false;
+    this.#closed = true;
+    return sendIfOpen(this.connection, { type: RPC_FRAME_TYPE, id: this.id, success: false, error: message });
+  }
+}
+
+/** Run one request frame against the target and reply on the connection. */
+export async function dispatchRpc(
+  target: object,
+  connection: RpcConnection,
+  frame: RpcRequestFrame,
+): Promise<void> {
+  const method = (target as Record<string, unknown>)[frame.method];
+  try {
+    if (typeof method !== 'function') throw new Error(`Method ${frame.method} does not exist`);
+    if (!isCallable(method)) throw new Error(`Method ${frame.method} is not callable`);
+    if (callableMetadata(method)?.streaming) {
+      const stream = new StreamingResponse(connection, frame.id);
+      try {
+        await method.apply(target, [stream, ...frame.args]);
+      } catch (e) {
+        if (!stream.isClosed) stream.error(errorMessage(e));
+      }
+      return;
+    }
+    const result: unknown = await method.apply(target, frame.args);
+    sendIfOpen(connection, { type: RPC_FRAME_TYPE, id: frame.id, success: true, result, done: true });
+  } catch (e) {
+    sendIfOpen(connection, { type: RPC_FRAME_TYPE, id: frame.id, success: false, error: errorMessage(e) });
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : 'Unknown error occurred';
+}