@procedures/peer 0.2.3 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/peer",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Serve procedures: HTTP and WebSocket peers with token authentication, browser checks, an expose list, server.create, status and stop, and manifests.",
   "keywords": [
     "server",
@@ -77,7 +77,7 @@
     "procedures": "./dist/register.js"
   },
   "dependencies": {
-    "@procedures/client": "0.2.3",
+    "@procedures/client": "0.3.0",
     "zod": "^4.6.5"
   },
   "optionalDependencies": {

package/src/connection/index.ts

@@ -19,6 +19,7 @@ import type {
   ProcedureInfo,
   ProcedureAnnounceMessage,
 } from "../types.js";
+import { ms, type Duration } from "@procedures/client";
 
 // =============================================================================
 // Types
@@ -29,8 +30,8 @@ export interface ConnectOptions {
   address: string;
   /** Transport type (auto-detected from URL if not specified) */
   transport?: TransportType;
-  /** Connection timeout in ms */
-  timeout?: number;
+  /** The time limit of the connection, for example `seconds(10)` */
+  timeout?: Duration;
   /** Local peer ID to identify ourselves */
   localPeerId?: string;
 }
@@ -143,7 +144,7 @@ function detectTransport(address: string): TransportType {
 function createClient(
   address: string,
   transport: TransportType,
-  timeout?: number
+  timeout?: Duration
 ): Client {
   switch (transport) {
     case "http": {
@@ -164,7 +165,7 @@ function createClient(
       return new Client({
         transport: new WebSocketTransport({
           url: address,
-          connectionTimeout: timeout ?? 10000,
+          connectionTimeout: timeout ?? ms(10000),
           reconnect: {
             enabled: true,
             maxAttempts: 3,

package/src/discovery/index.ts

@@ -14,6 +14,10 @@ import {
   type ProcedureRegistryLike,
   PROCEDURE_REGISTRY,
   REGISTRY_READ_EFFECTS,
+  describeRegistry,
+  type AnyProcedure,
+  type ProcedureEntry,
+  type ProcedurePath,
 } from "@procedures/client";
 import { schema } from "../schema.js";
 import type {
@@ -55,27 +59,14 @@ export const discoveryAnnounceProcedure: Procedure<
     effects: REGISTRY_READ_EFFECTS,
   })
   .handler(async (_input: DiscoveryAnnounceInput, ctx?: ProcedureContext) => {
-    // The procedures of the registry that serves this call (the peer's registry)
-    const procedures = (ctx?.registry ?? PROCEDURE_REGISTRY).getAll();
-
-    // Convert to ProcedureInfo format
-    const procedureInfos: ProcedureInfo[] = procedures
-      .filter((proc) => {
-        // Skip internal procedures in discovery
-        const meta = proc.metadata as { internal?: boolean } | undefined;
-        return !meta?.internal;
-      })
-      .map((proc) => {
-        const meta = proc.metadata as { description?: string } | undefined;
-        const info: ProcedureInfo = {
-          path: proc.path,
-        };
-        if (meta?.description !== undefined) {
-          info.description = meta.description;
-        }
-        // TODO: Generate JSON schema from input/output schemas
-        return info;
-      });
+    // The one manifest of the core (roadmap R17): the procedures of the registry that serves this
+    // call and that the host exposes, with their JSON Schemas, without the internal ones.
+    // Before, the announce gave no schemas and listed the procedures that the host hides.
+    const manifest = describeRegistry(ctx?.registry ?? PROCEDURE_REGISTRY, {
+      ...(ctx?.expose ? { expose: ctx.expose } : {}),
+      include: (proc: AnyProcedure) => !(proc.metadata as { internal?: boolean } | undefined)?.internal,
+    });
+    const procedureInfos: ProcedureInfo[] = manifest.procedures.map(infoOf);
 
     // Generate a peer ID based on process (could be configured)
     const peerId = `peer-${process.pid}-${Date.now().toString(36)}`;
@@ -95,21 +86,21 @@ export const discoveryAnnounceProcedure: Procedure<
 /**
  * Get procedure info for all registered procedures of a registry (default: the global registry)
  */
-export function getProcedureInfos(registry: ProcedureRegistryLike = PROCEDURE_REGISTRY): ProcedureInfo[] {
-  const procedures = registry.getAll();
+export function getProcedureInfos(
+  registry: ProcedureRegistryLike = PROCEDURE_REGISTRY,
+  expose?: (path: ProcedurePath) => boolean
+): ProcedureInfo[] {
+  // The one manifest of the core (roadmap R17), without the schemas
+  return describeRegistry(registry, { schemas: false, ...(expose ? { expose } : {}) }).procedures.map(infoOf);
+}
 
-  return procedures
-    .filter((proc) => proc.handler !== undefined)
-    .map((proc) => {
-      const meta = proc.metadata as { description?: string } | undefined;
-      const info: ProcedureInfo = {
-        path: proc.path,
-      };
-      if (meta?.description !== undefined) {
-        info.description = meta.description;
-      }
-      return info;
-    });
+/** The ProcedureInfo of a manifest entry: the form that the peers exchange. */
+export function infoOf(entry: ProcedureEntry): ProcedureInfo {
+  const info: ProcedureInfo = { path: [...entry.path] };
+  if (entry.description !== undefined) info.description = entry.description;
+  if (entry.input) info.inputSchema = entry.input;
+  if (entry.output) info.outputSchema = entry.output;
+  return info;
 }
 
 /**

package/src/peer/index.ts

@@ -14,12 +14,15 @@ import {
   defaultServerUrlStrategy,
   defaultUrlPattern,
   procedureServerOptions,
+  hostProcedures,
+  metricsInterceptor,
+  Client,
   type BrowserGuardOptions,
   type HostPolicy,
   type Method,
 } from "@procedures/client";
 import type { Request } from "express";
-import type { ProcedurePath } from "@procedures/client";
+import type { ProcedurePath, StopOptions } from "@procedures/client";
 import type { HttpTransportConfig, TransportConfig, TransportType, WebSocketTransportConfig } from "../types.js";
 import { bearerToken, hostAllowed, originAllowed, tokenMatches } from "./security.js";
 
@@ -57,6 +60,11 @@ export interface PeerOptions {
   registry?: ProcedureRegistry;
   /** The procedures that the peer serves (see `exposeRule`). Without it, the peer serves every procedure. */
   expose?: ((path: ProcedurePath) => boolean) | undefined;
+  /**
+   * The peer counts the calls of each procedure, and `host.metrics` gives the counts (roadmap
+   * R19). The default is true.
+   */
+  metrics?: boolean | undefined;
   /**
    * The policy of the host (`hostPolicy()` of the core, roadmap 2.3): the expose rule, the call
    * rule, the interceptors (a time limit), the token of each network transport that has none of
@@ -76,11 +84,19 @@ export interface Peer {
   /** Start all transports */
   start(): Promise<void>;
   /** Stop all transports */
-  stop(): Promise<void>;
+  /** Stop the peer. With `grace`, the calls in flight have that time to end (roadmap R14). */
+  stop(options?: StopOptions): Promise<void>;
   /** Get active endpoints */
   getEndpoints(): PeerEndpoint[];
   /** Get underlying server */
   getServer(): ProcedureServer;
+  /** The ids of the WebSocket connections of the clients (roadmap R24). */
+  connections(): string[];
+  /**
+   * A client of one connected client (roadmap R24): its calls go to the procedures that the client
+   * serves (the `serve` option of its WebSocketTransport), over the same WebSocket.
+   */
+  clientFor(connectionId: string): Client;
 }
 
 // =============================================================================
@@ -93,6 +109,10 @@ class PeerImpl implements Peer {
   private transports: TransportConfig[];
   private endpoints: PeerEndpoint[] = [];
   private started = false;
+  /** The WebSocket transports of the peer: the calls to its clients go over them (R24) */
+  private wsTransports: WebSocketServerTransport[] = [];
+  /** The HTTP servers that the peer made for its WebSocket transports: `stop()` closes them */
+  private ownedServers: Array<import("node:http").Server> = [];
   private registry: ProcedureRegistry;
   private startTime: number = Date.now();
 
@@ -111,13 +131,27 @@ class PeerImpl implements Peer {
     this.registry = options.registry ?? PROCEDURE_REGISTRY;
     this.browser = policy?.browser ?? {};
 
-    // Create procedure server
+    // Create procedure server. The metrics interceptor counts each call for host.metrics (R19).
+    const metrics = options.metrics === false ? undefined : metricsInterceptor();
+    const serverOptions = policy ? procedureServerOptions(policy, this.registry) : {};
+    const interceptors = [...(serverOptions.interceptors ?? []), ...(metrics ? [metrics.interceptor] : [])];
     this.server = new ProcedureServer({
-      ...(policy ? procedureServerOptions(policy, this.registry) : {}),
+      ...serverOptions,
+      ...(interceptors.length > 0 ? { interceptors } : {}),
       autoRegister: options.autoRegister ?? true,
       registry: this.registry,
       ...(options.expose ? { expose: options.expose } : {}),
     });
+    // host.health, host.info and host.metrics: pinned on the server, not in the registry (R19)
+    this.server.registerProcedures(
+      hostProcedures({
+        id: this.id,
+        startedAt: this.startTime,
+        server: this.server,
+        endpoints: () => this.getEndpoints(),
+        ...(metrics ? { metrics } : {}),
+      })
+    );
   }
 
   async start(): Promise<void> {
@@ -160,7 +194,9 @@ class PeerImpl implements Peer {
     const express = (await import("express")).default;
 
     const app = express();
-    app.use(express.json());
+    // No body parser here: the transport reads the body itself, with bodyLimit, and accepts each
+    // JSON value (roadmap R5). Before, the strict parser of express refused a bare value (a
+    // number, a string, null) with 400, and its limit of 100 kB replaced bodyLimit.
 
     const port = config.port ?? 3000;
     // Loopback by default so the full procedure registry (incl. shell.run / fs.write) is not
@@ -227,6 +263,7 @@ class PeerImpl implements Peer {
       allowedOrigins: this.browser.allowedOrigins ?? ((origin) => originAllowed(origin, config.corsOrigins)),
       ...(this.browser.allowedHosts ? { allowedHosts: this.browser.allowedHosts } : {}),
       allowGet: this.browser.allowGet ?? config.urlStrategy === "rest",
+      ...(config.bodyLimit !== undefined ? { bodyLimit: config.bodyLimit } : {}),
     });
 
     this.server.addTransport(httpTransport);
@@ -290,6 +327,8 @@ class PeerImpl implements Peer {
       httpServer.close();
       throw error;
     }
+    this.ownedServers.push(httpServer);
+    this.wsTransports.push(wsTransport);
 
     this.endpoints.push({
       type: "websocket",
@@ -297,11 +336,25 @@ class PeerImpl implements Peer {
     });
   }
 
-  async stop(): Promise<void> {
+  async stop(options: StopOptions = {}): Promise<void> {
     if (!this.started) return;
-    await this.server.stop();
+    await this.server.stop(options);
+    // The HTTP servers of the WebSocket transports: before, they stayed open, so the port stayed
+    // bound after stop() (roadmap R5)
+    const owned = this.ownedServers;
+    this.ownedServers = [];
+    await Promise.all(
+      owned.map(
+        (httpServer) =>
+          new Promise<void>((resolve) => {
+            httpServer.close(() => resolve());
+            httpServer.closeAllConnections();
+          }),
+      ),
+    );
     this.started = false;
     this.endpoints = [];
+    this.wsTransports = [];
   }
 
   getEndpoints(): PeerEndpoint[] {
@@ -311,6 +364,16 @@ class PeerImpl implements Peer {
   getServer(): ProcedureServer {
     return this.server;
   }
+
+  connections(): string[] {
+    return this.wsTransports.flatMap((transport) => transport.getTrackedConnections().map((connection) => connection.id));
+  }
+
+  clientFor(connectionId: string): Client {
+    const transport = this.wsTransports.find((ws) => ws.getTrackedConnection(connectionId) !== undefined);
+    if (!transport) throw new Error(`Connection not found: ${connectionId}`);
+    return new Client({ transport: transport.transportFor(connectionId), throwOnError: true });
+  }
 }
 
 // =============================================================================

package/src/procedures/manifest.generate.ts

@@ -3,7 +3,8 @@
  * Generates procedure manifests in various formats
  */
 
-import { createProcedure, jsonSchemaOf, type Effects, type Procedure, type ProcedureContext, PROCEDURE_REGISTRY } from "@procedures/client";
+import { createProcedure, describeRegistry, type AnyProcedure, type Effects, type Procedure, type ProcedureContext, PROCEDURE_REGISTRY } from "@procedures/client";
+import { infoOf } from "../discovery/index.js";
 import { wrapSchema } from "../schema.js";
 import { ManifestGenerateOutputSchema } from "../output-schemas.js";
 import { manifestGenerateInputSchema } from "../input-schemas.js";
@@ -30,39 +31,15 @@ export const manifestGenerateProcedure: Procedure<
     effects: { reads: ["registry"], writes: ["fs"], idempotent: true },
   })
   .handler(async (input: ManifestGenerateInput, ctx?: ProcedureContext) => {
-    // The procedures of the caller's registry
-    const allProcedures = (ctx?.registry ?? PROCEDURE_REGISTRY).getAll();
-
-    // Filter by namespace if specified
-    let procedures = allProcedures;
-    if (input.namespace && input.namespace.length > 0) {
-      procedures = allProcedures.filter((proc) => {
-        // Check if procedure path starts with namespace
-        for (let i = 0; i < input.namespace!.length; i++) {
-          if (proc.path[i] !== input.namespace![i]) {
-            return false;
-          }
-        }
-        return true;
-      });
-    }
-
-    // Convert to ProcedureInfo format
-    const procedureInfos: ProcedureInfo[] = procedures.map((proc) => {
-      const meta = proc.metadata as { description?: string; internal?: boolean } | undefined;
-      const info: ProcedureInfo = {
-        path: proc.path,
-      };
-      if (meta?.description !== undefined) {
-        info.description = meta.description;
-      }
-      // The JSON Schemas of the input and the output, when the schemas can describe themselves
-      const inputSchema = jsonSchemaOf(proc.input, { io: "input" });
-      const outputSchema = jsonSchemaOf(proc.output, { io: "output" });
-      if (inputSchema) info.inputSchema = inputSchema;
-      if (outputSchema) info.outputSchema = outputSchema;
-      return info;
+    // The one manifest of the core (roadmap R17): the procedures that the host exposes, with
+    // their JSON Schemas, under the namespace when the input gives one
+    const namespace = input.namespace ?? [];
+    const manifest = describeRegistry(ctx?.registry ?? PROCEDURE_REGISTRY, {
+      ...(ctx?.expose ? { expose: ctx.expose } : {}),
+      withoutHandler: true,
+      include: (proc: AnyProcedure) => namespace.every((segment, index) => proc.path[index] === segment),
     });
+    const procedureInfos: ProcedureInfo[] = manifest.procedures.map(infoOf);
 
     // Determine formats to generate
     const formats = input.formats ?? ["json"];

package/src/procedures/server.call.ts

@@ -3,7 +3,7 @@
  * Call a procedure on a remote peer through an outbound connection
  */
 
-import { createProcedure, pathToMethod, type Effects, type Procedure } from "@procedures/client";
+import { TIMEOUT_METADATA_KEY, createProcedure, pathToMethod, type Effects, type Procedure, type ProcedureContext } from "@procedures/client";
 import { wrapSchema } from "../schema.js";
 import { ServerCallOutputSchema } from "../output-schemas.js";
 import { serverCallInputSchema } from "../input-schemas.js";
@@ -55,7 +55,7 @@ export const serverCallProcedure: Procedure<
     shorts: { connectionId: "c", address: "a" },
     output: "json",
   })
-  .handler(async (input: ServerCallInput): Promise<ServerCallOutput> => {
+  .handler(async (input: ServerCallInput, ctx?: ProcedureContext): Promise<ServerCallOutput> => {
     // Normalize path: accept dot-separated string or array
     const pathArray = typeof input.path === "string"
       ? input.path.split(".")
@@ -87,7 +87,12 @@ export const serverCallProcedure: Procedure<
     // (deep dive architecture review 3.3)
     const method = pathToMethod(pathArray);
 
-    const result = await client.call(method, input.input ?? {});
+    // The signal and the remaining time of this call go with the relayed call (roadmap R14)
+    const deadline = ctx?.capability?.deadline;
+    const result = await client.call(method, input.input ?? {}, {
+      ...(ctx?.signal ? { signal: ctx.signal } : {}),
+      ...(deadline !== undefined ? { context: { [TIMEOUT_METADATA_KEY]: Math.max(0, deadline - Date.now()) } } : {}),
+    });
 
     return {
       result,

package/src/procedures/server.connect.ts

@@ -9,6 +9,7 @@ import { ServerConnectOutputSchema } from "../output-schemas.js";
 import { serverConnectInputSchema } from "../input-schemas.js";
 import type { ServerConnectInput, ServerConnectOutput } from "../types.js";
 import { connect } from "../connection/index.js";
+import { ms } from "@procedures/client";
 
 // Use pass-through schemas
 const serverConnectOutputSchema = wrapSchema<ServerConnectOutput>(ServerConnectOutputSchema);
@@ -35,7 +36,8 @@ export const serverConnectProcedure: Procedure<
       connectOptions.transport = input.transport;
     }
     if (input.timeout !== undefined) {
-      connectOptions.timeout = input.timeout;
+      // The input is data: a number of milliseconds
+      connectOptions.timeout = ms(input.timeout);
     }
     const connection = await connect(connectOptions);
 

package/src/types.ts

@@ -21,6 +21,8 @@ export interface HttpTransportConfig {
   urlStrategy?: "rest" | "rpc" | undefined;
   /** A secret that every request must send as `Authorization: Bearer <token>` */
   token?: string | undefined;
+  /** The largest request body in bytes. The default is 1 MiB. */
+  bodyLimit?: number | undefined;
 }
 
 export interface WebSocketTransportConfig {