@procedures/client 0.0.0-stage → 0.1.0

package/src/server/host-policy.ts

@@ -0,0 +1,121 @@
+/**
+ * The policy of a host: one place that builds what a server lets its callers do (roadmap 2.3).
+ *
+ * The three hosts (the MCP dev-tools server, the `server` CLI, the warm server of `mark`) each
+ * built their own expose rule, call rule, time limit and token. `hostPolicy()` builds them from
+ * one set of options, and `procedureServerOptions()` gives them to a `ProcedureServer`.
+ *
+ * - `expose`: the procedures that callers reach. Patterns: an exact key (`git.status`), a prefix
+ *   (`git.*`) or `*`. A tool surface: namespaces and the keys to leave out. Without it: every
+ *   procedure.
+ * - `strictCalls`: a procedure of code that declares no `metadata.calls` calls only exposed
+ *   procedures (a host for an outside caller sets it).
+ * - `timeoutMs`: the time limit of each call from a caller (not of its nested calls).
+ * - `token`, `browser`: the checks of the network transports (`client-server` applies them).
+ */
+
+import type { ProcedurePath } from "../procedures/types.js";
+import type { Interceptor } from "../procedures/invoke.js";
+import { timeoutInterceptor } from "../procedures/interceptors.js";
+import type { BrowserGuardOptions } from "./browser-guard.js";
+import type { ProcedureRegistry } from "../procedures/registry.js";
+import type { ProcedureServerOptions } from "./procedure-server.js";
+
+/** The procedures of a host that are tools: namespaces (first path segments), less some keys. */
+export interface ToolSurface {
+  namespaces: readonly string[];
+  exclude?: readonly string[] | undefined;
+}
+
+/** The rule of a list of patterns: an exact key (`git.status`), a prefix (`git.*`) or `*`. */
+export function exposePatterns(patterns: readonly string[]): (path: ProcedurePath) => boolean {
+  const exact = new Set<string>();
+  const prefixes: string[] = [];
+  let all = false;
+  for (const pattern of patterns) {
+    if (pattern === "*") all = true;
+    else if (pattern.endsWith(".*")) prefixes.push(pattern.slice(0, -1));
+    else exact.add(pattern);
+  }
+  return (path) => {
+    if (all) return true;
+    const key = path.join(".");
+    return exact.has(key) || prefixes.some((prefix) => key.startsWith(prefix));
+  };
+}
+
+/** The rule of a tool surface: the namespaces, less the excluded keys. */
+export function surfaceRule(surface: ToolSurface): (path: ProcedurePath) => boolean {
+  const namespaces = new Set(surface.namespaces);
+  const excluded = new Set(surface.exclude ?? []);
+  return (path) => namespaces.has(path[0] ?? "") && !excluded.has(path.join("."));
+}
+
+/** The options of `hostPolicy()`. */
+export interface HostPolicyOptions {
+  /** The procedures that callers reach. Without it: every procedure of the registry. */
+  expose?: readonly string[] | ToolSurface | ((path: ProcedurePath) => boolean) | undefined;
+  /** Keys that callers do not reach, also when `expose` matches them. */
+  exclude?: readonly string[] | undefined;
+  /** A procedure of code with no `metadata.calls` calls only exposed procedures. */
+  strictCalls?: boolean | undefined;
+  /** The time limit of each call from a caller, in milliseconds. 0 or no value: no limit. */
+  timeoutMs?: number | undefined;
+  /** More interceptors, after the policy's own (tracing, metrics). */
+  interceptors?: readonly Interceptor[] | undefined;
+  /** The token that each network request must send (HTTP and WebSocket transports). */
+  token?: string | undefined;
+  /** The browser checks of the network transports (`allowedOrigins`, `allowedHosts`, `allowGet`). */
+  browser?: BrowserGuardOptions | undefined;
+}
+
+/** What a host lets its callers do. */
+export interface HostPolicy {
+  readonly expose: ((path: ProcedurePath) => boolean) | undefined;
+  readonly strictCalls: boolean;
+  readonly interceptors: readonly Interceptor[];
+  readonly token: string | undefined;
+  readonly browser: BrowserGuardOptions;
+}
+
+function exposeOf(options: HostPolicyOptions): ((path: ProcedurePath) => boolean) | undefined {
+  const { expose } = options;
+  const rule =
+    expose === undefined
+      ? undefined
+      : typeof expose === "function"
+        ? expose
+        : Array.isArray(expose)
+          ? exposePatterns(expose as readonly string[])
+          : surfaceRule(expose as ToolSurface);
+  const excluded = new Set(options.exclude ?? []);
+  if (excluded.size === 0) return rule;
+  return (path) => !excluded.has(path.join(".")) && (rule ? rule(path) : true);
+}
+
+/** This function builds the policy of a host from its options. */
+export function hostPolicy(options: HostPolicyOptions = {}): HostPolicy {
+  const interceptors: Interceptor[] = [];
+  if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+    interceptors.push(timeoutInterceptor({ ms: options.timeoutMs }));
+  }
+  interceptors.push(...(options.interceptors ?? []));
+  return {
+    expose: exposeOf(options),
+    strictCalls: options.strictCalls ?? false,
+    interceptors,
+    token: options.token,
+    browser: options.browser ?? {},
+  };
+}
+
+/** The options of a `ProcedureServer` that serves a registry under a policy. */
+export function procedureServerOptions(policy: HostPolicy, registry?: ProcedureRegistry): ProcedureServerOptions {
+  return {
+    autoRegister: true,
+    ...(registry ? { registry } : {}),
+    ...(policy.expose ? { expose: policy.expose } : {}),
+    strictCalls: policy.strictCalls,
+    ...(policy.interceptors.length > 0 ? { interceptors: policy.interceptors } : {}),
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Universal Server
+ *
+ * Protocol-agnostic RPC server architecture.
+ * Mirrors the universal client for symmetrical design.
+ *
+ * Features:
+ * - Protocol-agnostic (HTTP, WebSocket, gRPC via adapters)
+ * - Unified RPC format internally
+ * - Middleware support
+ * - Handler registry with pattern matching
+ * - Graceful shutdown
+ *
+ * @example
+ * ```typescript
+ * import { Server, HttpServerTransport } from "@common/server";
+ *
+ * const server = new Server();
+ *
+ * // Register handlers
+ * server.register(
+ *   { service: "users", operation: "get" },
+ *   async (req) => ({
+ *     id: req.id,
+ *     status: { type: "success", code: 200 },
+ *     payload: { id: req.payload.id, name: "John" },
+ *     metadata: {}
+ *   })
+ * );
+ *
+ * // Add HTTP transport
+ * const httpTransport = new HttpServerTransport(server, { port: 3000 });
+ * await httpTransport.start();
+ * ```
+ */
+
+export { Server } from "./server.js";
+export type { ServerOptions } from "./server.js";
+
+export { ProcedureServer, createProcedureServer } from "./procedure-server.js";
+export type { ProcedureServerOptions, StorageConfig } from "./procedure-server.js";
+export { pathToMethod, methodToPath } from "./method.js";
+export {
+  HandlerNotFoundError,
+  ServerError,
+  type ServerRequest,
+  type ServerResponse,
+  type ServerHandler,
+  type ServerMiddleware,
+  type ServerContext,
+  type ServerRunner,
+  type ServerTransport,
+} from "./types.js";
+
+export {
+  HttpServerTransport,
+  defaultServerUrlStrategy,
+  rpcServerUrlStrategy,
+} from "../adapters/http/server/index.js";
+export type {
+  HttpServerTransportOptions,
+  HttpUrlStrategy,
+} from "../adapters/http/server/index.js";
+export { WebSocketServerTransport } from "../adapters/websocket/server/index.js";
+export type {
+  WebSocketServerTransportOptions,
+  WebSocketAuthHandler,
+  WebSocketConnectionHandler,
+  WebSocketMessage,
+} from "../adapters/websocket/server/index.js";

package/src/server/method.ts

@@ -0,0 +1,33 @@
+/**
+ * The one mapping between a procedure path and a transport method.
+ *
+ * A path `["docker", "compose", "up"]` is the method `{ service: "docker.compose", operation: "up" }`:
+ * the last segment is the operation, and the other segments are the service. Before, some hosts
+ * sent `{ service: "docker", operation: "compose.up" }` and others the form above, and the
+ * server matched methods exactly, so a 3-segment procedure was not found through a warm server
+ * (deep dive architecture review 3.3).
+ *
+ * `methodToPath` splits both the service and the operation on ".", so it reads both forms.
+ */
+
+import type { Method } from "../client/types.js";
+import type { ProcedurePath } from "../procedures/types.js";
+
+/**
+ * This function gives the transport method of a procedure path. A path needs at least two
+ * segments, because a method has a service and an operation.
+ */
+export function pathToMethod(path: readonly string[]): Method {
+  if (path.length < 2) {
+    throw new Error(`Invalid procedure path (it needs two segments or more): ${path.join(".")}`);
+  }
+  return { service: path.slice(0, -1).join("."), operation: path[path.length - 1]! };
+}
+
+/**
+ * This function gives the procedure path of a transport method. It accepts both encodings:
+ * `{ service: "a.b", operation: "c" }` and `{ service: "a", operation: "b.c" }` give `["a", "b", "c"]`.
+ */
+export function methodToPath(method: Pick<Method, "service" | "operation">): ProcedurePath {
+  return [...method.service.split("."), ...method.operation.split(".")].filter((segment) => segment !== "");
+}

package/src/server/procedure-server.ts

@@ -0,0 +1,417 @@
+/**
+ * Procedure Server
+ *
+ * Server implementation with procedure auto-registration and repository pattern.
+ * Integrates with ProcedureRegistry and CollectionStorage backends.
+ */
+
+import { Server, type ServerOptions } from "./server.js";
+import type { Method, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
+import { methodToPath, pathToMethod } from "./method.js";
+import type {
+  AnyProcedure,
+  ProcedurePath,
+  RepositoryProvider,
+  ProcedureModule,
+} from "../procedures/types.js";
+import { pathToKey } from "../procedures/types.js";
+import { ProcedureRegistry, PROCEDURE_REGISTRY } from "../procedures/registry.js";
+import { createCollectionProcedures } from "../procedures/collection/procedures.js";
+import { InvocationError, invokeProcedure, type Interceptor } from "../procedures/invoke.js";
+import type { CollectionStorage } from "../procedures/collection/storage.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Storage configuration for a collection.
+ */
+export interface StorageConfig<T = unknown> {
+  /** Storage backend instance */
+  storage: CollectionStorage<T>;
+  /** Collection name (for mapping) */
+  name: string;
+}
+
+/**
+ * Options for ProcedureServer.
+ */
+export interface ProcedureServerOptions extends ServerOptions {
+  /** Procedure registry to use (defaults to global) */
+  registry?: ProcedureRegistry;
+
+  /** Whether to auto-register all procedures from registry */
+  autoRegister?: boolean;
+
+  /** Collections to configure with storage backends */
+  collections?: Record<string, CollectionStorage<unknown>>;
+
+  /**
+   * The procedures that the callers of this server can reach. `registerFromRegistry()` registers
+   * only these procedures. A data-driven procedure (control flow, `eval`, a procedure that
+   * `procedure.define` made) can call only these procedures too, because its caller chooses
+   * what it calls. A procedure of code calls the procedures of its `metadata.calls`
+   * (`docker.run` declares `shell.run`) and the exposed ones. Without this rule, the server
+   * exposes every procedure. See `procedures/policy.ts` (deep dive MCP-3).
+   */
+  expose?: ((path: ProcedurePath) => boolean) | undefined;
+
+  /**
+   * True: a procedure of code without `metadata.calls` can call only the exposed procedures.
+   * A server for an outside caller (the MCP server of the dev tools) sets it.
+   */
+  strictCalls?: boolean | undefined;
+
+  /**
+   * The interceptors of each request and its nested calls, the outermost first: policy,
+   * tracing, timeouts, metrics (see `procedures/interceptors.ts`).
+   */
+  interceptors?: readonly Interceptor[] | undefined;
+}
+
+/**
+ * The error response of a failed invocation. An invocation error keeps its code
+ * (VALIDATION_ERROR, NOT_EXPOSED, ABORTED and so on). An error of the handler is HANDLER_ERROR.
+ */
+export function errorResponse(id: string, error: unknown): ServerResponse<unknown> {
+  // An error that says it is retryable stays retryable: before, every error lost the flag
+  // (deep dive TRN-7)
+  const retryable = (error as { retryable?: unknown } | undefined)?.retryable;
+  return {
+    id,
+    status: {
+      type: "error",
+      code: error instanceof InvocationError ? error.code : "HANDLER_ERROR",
+      message: error instanceof Error ? error.message : String(error),
+      retryable: typeof retryable === "boolean" ? retryable : false,
+    },
+    metadata: {},
+  };
+}
+
+// =============================================================================
+// Procedure Server
+// =============================================================================
+
+/**
+ * Server with procedure auto-registration and repository pattern.
+ *
+ * Features:
+ * - Auto-registers handlers from procedure definitions
+ * - Repository pattern for storage backend injection
+ * - Collection storage configuration per-collection
+ * - Integrates with ProcedureRegistry
+ *
+ * @example
+ * ```typescript
+ * const server = new ProcedureServer({
+ *   collections: {
+ *     users: new ApiStorage(remoteClient, { service: 'users' }),
+ *     cache: new InMemoryStorage(),
+ *   }
+ * });
+ *
+ * // Register collection procedures
+ * server.registerCollectionProcedures('users');
+ *
+ * // Or auto-register all from registry
+ * server.registerFromRegistry();
+ *
+ * await server.start();
+ * ```
+ */
+export class ProcedureServer extends Server implements RepositoryProvider {
+  private readonly procedureRegistry: ProcedureRegistry;
+  private readonly storages = new Map<string, CollectionStorage<unknown>>();
+  /** The procedures that `registerProcedure` pinned, by key */
+  private readonly pinnedProcedures = new Map<string, AnyProcedure>();
+  /**
+   * True after `registerFromRegistry()`: the server serves each procedure of the registry that
+   * has a handler and passes the expose rule, looked up when the request arrives (deep dive
+   * TRN-13). Before, the server copied the registry at startup: a later registration was not
+   * found, and an override or an unregistration was not seen.
+   */
+  private servesRegistry = false;
+  private readonly expose: ((path: ProcedurePath) => boolean) | undefined;
+  private readonly strictCalls: boolean;
+  private readonly interceptors: readonly Interceptor[];
+
+  constructor(options: ProcedureServerOptions = {}) {
+    super(options);
+
+    this.procedureRegistry = options.registry ?? PROCEDURE_REGISTRY;
+    this.expose = options.expose;
+    this.strictCalls = options.strictCalls ?? false;
+    this.interceptors = options.interceptors ?? [];
+
+    // Configure collections
+    if (options.collections) {
+      for (const [name, storage] of Object.entries(options.collections)) {
+        this.storages.set(name, storage);
+      }
+    }
+
+    // Auto-register if enabled
+    if (options.autoRegister) {
+      this.registerFromRegistry();
+    }
+  }
+
+  // ===========================================================================
+  // RepositoryProvider Implementation
+  // ===========================================================================
+
+  /**
+   * Get storage for a collection.
+   *
+   * @param collection - Collection name
+   * @returns Storage instance
+   * @throws Error if collection not configured
+   */
+  getStorage<T>(collection: string): CollectionStorage<T> {
+    const storage = this.storages.get(collection);
+    if (!storage) {
+      throw new Error(`Collection storage not configured: ${collection}`);
+    }
+    return storage as CollectionStorage<T>;
+  }
+
+  /**
+   * Check if a collection is configured.
+   *
+   * @param collection - Collection name
+   */
+  hasCollection(collection: string): boolean {
+    return this.storages.has(collection);
+  }
+
+  // ===========================================================================
+  // Storage Configuration
+  // ===========================================================================
+
+  /**
+   * Configure storage for a collection.
+   *
+   * @param name - Collection name
+   * @param storage - Storage backend
+   * @returns this (for chaining)
+   */
+  useStorage<T>(name: string, storage: CollectionStorage<T>): this {
+    this.storages.set(name, storage as CollectionStorage<unknown>);
+    return this;
+  }
+
+  /**
+   * Configure multiple storages at once.
+   *
+   * @param storages - Map of collection names to storage backends
+   * @returns this (for chaining)
+   */
+  useStorages(storages: Record<string, CollectionStorage<unknown>>): this {
+    for (const [name, storage] of Object.entries(storages)) {
+      this.storages.set(name, storage);
+    }
+    return this;
+  }
+
+  /**
+   * Get all configured collection names.
+   */
+  getCollectionNames(): string[] {
+    return Array.from(this.storages.keys());
+  }
+
+  // ===========================================================================
+  // Procedure Registration
+  // ===========================================================================
+
+  /**
+   * Register a procedure as a server handler. The server keeps this procedure object. A
+   * procedure of the registry at the same path comes first when the server serves the registry.
+   *
+   * @param procedure - Procedure definition
+   */
+  registerProcedure(procedure: AnyProcedure): void {
+    // Must have a handler
+    if (!procedure.handler) {
+      throw new Error(`Procedure at ${pathToKey(procedure.path)} has no handler`);
+    }
+    // The path must make a method: this throws for a path of one segment
+    pathToMethod(procedure.path);
+    this.pinnedProcedures.set(pathToKey(procedure.path), procedure);
+  }
+
+  /**
+   * Register multiple procedures.
+   *
+   * @param procedures - Array of procedures
+   */
+  registerProcedures(procedures: AnyProcedure[]): void {
+    for (const procedure of procedures) {
+      this.registerProcedure(procedure);
+    }
+  }
+
+  /**
+   * Register a procedure module.
+   *
+   * @param module - Module with procedures array
+   */
+  registerModule(module: ProcedureModule): void {
+    this.registerProcedures(module.procedures);
+  }
+
+  /**
+   * Serve the procedures of the registry. The server looks up each request in the registry when
+   * the request arrives, so a later registration, an override or an unregistration takes effect
+   * at once. A procedure without a handler (a stub synced from storage, BUGS-2026-07 H14/H28) or
+   * outside the expose rule is not served.
+   */
+  registerFromRegistry(): void {
+    this.servesRegistry = true;
+  }
+
+  /**
+   * The procedure that answers a method, or undefined. The registry comes first (when the server
+   * serves it), then the pinned procedures.
+   */
+  private resolveProcedure(method: Method): AnyProcedure | undefined {
+    const path = methodToPath(method);
+    if (this.servesRegistry) {
+      const procedure = this.procedureRegistry.get(path);
+      if (procedure?.handler && (!this.expose || this.expose(procedure.path))) {
+        return procedure;
+      }
+    }
+    return this.pinnedProcedures.get(pathToKey(path));
+  }
+
+  /**
+   * The handlers that `register()` added come first (exact or pattern matches). Then the server
+   * looks up the procedure of the method.
+   */
+  protected override findHandler(method: Method): ServerHandler | null {
+    const handler = super.findHandler(method);
+    if (handler) return handler;
+    const procedure = this.resolveProcedure(method);
+    return procedure ? (request) => this.invoke(procedure, request) : null;
+  }
+
+  /** Run a procedure for a request. */
+  private async invoke(procedure: AnyProcedure, request: ServerRequest<unknown>): Promise<ServerResponse<unknown>> {
+    try {
+      // One invocation path for every host (ARCHITECTURE-PROPOSALS P1): input validation, the
+      // context, the expose rule for nested calls (BUGS-2026-07 H18) and output validation
+      const output = await invokeProcedure(procedure, request.payload, {
+        registry: this.procedureRegistry,
+        metadata: request.metadata,
+        signal: request.signal,
+        repository: this,
+        expose: this.expose,
+        strictCalls: this.strictCalls,
+        interceptors: this.interceptors,
+      });
+      if (output.kind === "stream") {
+        return { id: request.id, status: { type: "success", code: 200 }, stream: output.items, metadata: {} };
+      }
+      return { id: request.id, status: { type: "success", code: 200 }, payload: output.value, metadata: {} };
+    } catch (error) {
+      return errorResponse(request.id, error);
+    }
+  }
+
+  /**
+   * Register collection procedures for a specific collection.
+   * Creates standard CRUD procedures using the configured storage.
+   *
+   * @param collectionName - Collection name
+   */
+  registerCollectionProcedures(collectionName: string): void {
+    // Uses a top-level import; require() is not available in this ESM package and
+    // previously threw "Cannot find module" on every call. See BUGS-2026-07 H13.
+    const procedures = createCollectionProcedures(collectionName);
+
+    // Register with the procedure registry first
+    this.procedureRegistry.registerAll(procedures);
+
+    // Then register as server handlers
+    this.registerProcedures(procedures);
+  }
+
+  // ===========================================================================
+  // Utility Methods
+  // ===========================================================================
+
+  /** The paths that the server serves now. */
+  private servedKeys(): Set<string> {
+    const keys = new Set(this.pinnedProcedures.keys());
+    if (this.servesRegistry) {
+      for (const procedure of this.procedureRegistry.getAll()) {
+        if (procedure.handler && (!this.expose || this.expose(procedure.path))) {
+          keys.add(pathToKey(procedure.path));
+        }
+      }
+    }
+    return keys;
+  }
+
+  /**
+   * Get count of the procedures that the server serves now.
+   */
+  get procedureCount(): number {
+    return this.servedKeys().size;
+  }
+
+  /**
+   * Check if the server serves a procedure now.
+   *
+   * @param path - Procedure path
+   */
+  /**
+   * The registry that this server serves. A face of the server (the MCP transport) lists its
+   * tools from it: with an explicit registry (`createRegistry()`), the global registry is not the
+   * server's.
+   */
+  getRegistry(): ProcedureRegistry {
+    return this.procedureRegistry;
+  }
+
+  hasProcedure(path: ProcedurePath): boolean {
+    return this.resolveProcedure(pathToMethod(path)) !== undefined;
+  }
+
+  /**
+   * Close all storage backends.
+   */
+  async closeStorages(): Promise<void> {
+    const closePromises = Array.from(this.storages.values()).map((s) =>
+      s.close()
+    );
+    await Promise.all(closePromises);
+  }
+
+  /**
+   * Stop server and close storages.
+   */
+  override async stop(): Promise<void> {
+    await super.stop();
+    await this.closeStorages();
+  }
+}
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+/**
+ * Create a procedure server with common configuration.
+ *
+ * @param options - Server options
+ * @returns Configured ProcedureServer
+ */
+export function createProcedureServer(
+  options: ProcedureServerOptions = {}
+): ProcedureServer {
+  return new ProcedureServer(options);
+}