@procedures/client 0.43.0 → 0.45.0

package/src/procedures/core/operands.ts

@@ -15,7 +15,7 @@ import {
   type AnyProcedureRef,
   type RefScope,
 } from "../ref.js";
-import { hydrateInput, runControl, runOperand } from "../program.js";
+import { hydrateInput, runControl, runOperand, type RunControlOptions } from "../program.js";
 
 /**
  * The operands of a control-flow procedure arrive raw: the procedure runs them itself. Its logic
@@ -37,10 +37,11 @@ function executorOf(ctx: ProcedureContext): <TIn, TOut>(path: ProcedurePath, inp
 
 /**
  * This function runs a control-flow procedure on the kernel: the runner of its kind runs the
- * operands of the input, in the scope of the caller.
+ * operands of the input, in the scope of the caller. The observer in `options` gets the result of
+ * each step of a chain (`client.trace`).
  */
-export function runControlFlow(name: string, input: unknown, ctx: ProcedureContext): Promise<unknown> {
-  return runControl(name, input, { executor: executorOf(ctx), rawInput: rawRule(ctx), onRef: ctx.onRef, scope: scopeOf(input) });
+export function runControlFlow(name: string, input: unknown, ctx: ProcedureContext, options: Pick<RunControlOptions, "onStep"> = {}): Promise<unknown> {
+  return runControl(name, input, { executor: executorOf(ctx), rawInput: rawRule(ctx), onRef: ctx.onRef, scope: scopeOf(input), onStep: options.onStep });
 }
 
 /**

package/src/procedures/index.ts

@@ -323,6 +323,8 @@ export type {
   RunDocumentOptions,
   RunProgramOptions,
   RunOperandOptions,
+  RunControlOptions,
+  StepObserver,
 } from "./program.js";
 
 // The envelope form of a program (coeval D6, D9 and D10, roadmap item M7)
@@ -337,6 +339,9 @@ export {
   allCoreProcedures,
   allCoreModules,
   chainProcedure,
+  traceProcedure,
+  type TraceRow,
+  type TraceReason,
   parallelProcedure,
   conditionalProcedure,
   andProcedure,

package/src/procedures/program.ts

@@ -995,6 +995,8 @@ export function programMachine(host: ProgramHost): Machine {
       setOwn(names, LAST, result.value);
       passed = result.value;
       results.push(result.value);
+      // The observer of this run (`RunControlOptions.onStep`) gets the result of each step
+      STEP_OBSERVERS.get(input.doc)?.(index, result.value);
     }
     return ok({ results, final: results[results.length - 1] });
   }
@@ -1377,15 +1379,35 @@ export async function runOperand(value: unknown, options: RunOperandOptions): Pr
   return runDocument(doc, { ...options, self: isAnyProcedureRef(value) ? frame : null });
 }
 
+/**
+ * The observer of the steps of one `client.chain` run. It gets the index and the result of each
+ * step that ends without an error, in the order of the steps.
+ */
+export type StepObserver = (index: number, value: unknown) => void;
+
+/** The options of `runControl()`. */
+export interface RunControlOptions extends RunDocumentOptions {
+  /**
+   * The observer of the steps of `client.chain` (`client.trace` uses it). Only the steps of this
+   * chain go to it: a nested chain does not tell it. The other procedures ignore it.
+   */
+  readonly onStep?: StepObserver | undefined;
+}
+
+/** The step observers, by the document of their `client.chain` run (`runControl()`). */
+const STEP_OBSERVERS = new WeakMap<object, StepObserver>();
+
 /**
  * This function runs a control-flow procedure on the kernel: its input becomes a document of its
  * kind, and the runner of the kind runs the operands. The input is raw: its scope (`scopeOf()`)
  * gives the names of the caller.
  */
-export async function runControl(name: string, input: unknown, options: RunDocumentOptions): Promise<unknown> {
+export async function runControl(name: string, input: unknown, options: RunControlOptions): Promise<unknown> {
   const value = desugarControlValue(name, input, { rawInput: options.rawInput, scoped: options.scope !== undefined });
   if (value === undefined) throw new TypeError(`client.${name}: the input does not have the shape of the procedure`);
-  return runDocument(controlDocument(name, value, input, options.scope !== undefined), options);
+  const doc = controlDocument(name, value, input, options.scope !== undefined);
+  if (options.onStep) STEP_OBSERVERS.set(doc, options.onStep);
+  return runDocument(doc, options);
 }
 
 /** The document of the run of a control-flow procedure: its own entry names the runner of the procedure. */

package/src/server/error-policy.ts

@@ -64,8 +64,8 @@ export interface ServerErrorPolicy {
    *   `INTERNAL_ERROR` with the message `"internal error"` and its real retryable flag, with
    *   only the metadata keys of `keepMetadata`. The codes `INTERNAL_ERROR`, `HANDLER_ERROR`, `UNKNOWN`,
    *   `OUTPUT_VALIDATION_ERROR` and `NO_OUTPUT` tell of a failure of the server, not of a
-   *   refusal, so their message is hidden too. The server gives the real error to its `onError`
-   *   logger one time, or to `console.error` without a logger.
+   *   refusal, so their message is hidden too. The server gives the real error one time to its `onError`
+   *   and its `logger`, or to `console.error` without them.
    */
   readonly expose?: "all" | "coded" | undefined;
   /**
@@ -108,7 +108,7 @@ export function markLogged(error: unknown): void {
   if (typeof error === "object" && error !== null) LOGGED.add(error);
 }
 
-/** The logger of the hidden errors: the hook `onError` of the server, or `console.error`. */
+/** The logger of the hidden errors: the hook `onError` and the `logger` of the server, or `console.error`. */
 export type HiddenErrorLog = (error: unknown, request: ServerRequest<unknown> | undefined) => void;
 
 /** This function gives an error to the logger, when the logger did not get it before. */

package/src/server/face-rules.ts

@@ -0,0 +1,115 @@
+/**
+ * The rules of one face of a host (CLI-43, AG1-B): a narrowing and an expose rule for each call of
+ * the face.
+ *
+ * A host can serve one server through more than one face, for example a full face and a read-only
+ * face for a browser. `faceRules()` reads the rules of one face one time, and `apply()` adds them to
+ * each request of that face:
+ *
+ * - The narrowing becomes one more source of the narrowing key (`procedure-narrowing`, CLI-30). Thus
+ *   the server applies the meet of all the sources: the capability of the policy, the request hook
+ *   and the key of the caller. A narrowing can only narrow.
+ * - The expose rule goes to `ServerRequest.expose`. The server meets it with its own rule, for the
+ *   call of the face and for each nested call. An expose rule can only narrow.
+ *
+ * The MCP face of `@procedures/mcp-server` and the HTTP and WebSocket faces of `@procedures/peer`
+ * use this module. It imports no Node code.
+ */
+
+import { NARROWING_METADATA_KEY, addNarrowing, narrowWithin, narrowingOf } from "../procedures/narrowing.js";
+import type { Capability, CapabilityRequest, ProcedurePath } from "../procedures/types.js";
+import { exposePatterns, surfaceRule, type HostPolicy, type ToolSurface } from "./host-policy.js";
+import type { ServerRequest } from "./types.js";
+
+/** The rules of one face, as options of the face. */
+export interface FaceRulesOptions {
+  /**
+   * A narrower capability for each call of the face, for example the read-only mode
+   * `{ effects: { writes: [] } }`. A narrowing that is not valid stops `faceRules()` with an error.
+   */
+  readonly narrowing?: CapabilityRequest<unknown> | readonly CapabilityRequest<unknown>[] | undefined;
+  /**
+   * The procedures that the callers of the face reach: the patterns of `hostPolicy({ expose })`, a
+   * tool surface or a function. The server meets this rule with the rule of the host.
+   */
+  readonly expose?: readonly string[] | ToolSurface | ((path: ProcedurePath) => boolean) | undefined;
+}
+
+/** The rules of one face, read one time. */
+export interface FaceRules {
+  /** The sources of the narrowing as the decoder read them, frozen. The list is empty without a narrowing. */
+  readonly narrowings: readonly CapabilityRequest<unknown>[];
+  /** The expose rule of the face, or undefined without one. */
+  readonly expose: ((path: ProcedurePath) => boolean) | undefined;
+  /**
+   * The capability of the policy, narrowed by the narrowing of the face, without the time. A face
+   * lists its procedures with it: the time limits each call, not the list.
+   */
+  readonly capability: Capability | undefined;
+  /** This function gives the request with the rules of the face. It does not change the request that it gets. */
+  apply<T>(request: ServerRequest<T>): ServerRequest<T>;
+}
+
+/** This function gives the meet of two expose rules: a path passes when it passes each rule. */
+export function meetExpose(
+  first: ((path: ProcedurePath) => boolean) | undefined,
+  second: ((path: ProcedurePath) => boolean) | undefined,
+): ((path: ProcedurePath) => boolean) | undefined {
+  if (!first) return second;
+  if (!second) return first;
+  return (path) => first(path) && second(path);
+}
+
+/** This function gives the rule of the expose option of a face. */
+function exposeRule(expose: NonNullable<FaceRulesOptions["expose"]>): (path: ProcedurePath) => boolean {
+  if (typeof expose === "function") return expose;
+  return Array.isArray(expose) ? exposePatterns(expose as readonly string[]) : surfaceRule(expose as ToolSurface);
+}
+
+/**
+ * This function reads the rules of one face with the decoder and the meet of the wire (CLI-30).
+ * It throws for a part of the narrowing that is not valid, because each call of the face then gets
+ * a refusal. The argument `face` names the face in the message of the error, for example `MCP`.
+ *
+ * @example
+ * ```typescript
+ * const rules = faceRules({ narrowing: { effects: { writes: [] } }, expose: ["graphapi.*"] }, policy, "read");
+ * const handler = { ...inner, handle: (request) => inner.handle(rules.apply(request)) };
+ * ```
+ */
+export function faceRules(
+  options: FaceRulesOptions,
+  policy: Pick<HostPolicy, "capabilityOf" | "clearanceOrder">,
+  face?: string,
+): FaceRules {
+  let narrowings: readonly CapabilityRequest<unknown>[] = [];
+  let capability = policy.capabilityOf?.();
+  if (options.narrowing !== undefined) {
+    const wire = narrowingOf(options.narrowing);
+    // The sources as the decoder read them, frozen: a change of the options or of the metadata of a call does not change them
+    narrowings = Object.freeze(wire.narrowings.map((source) => Object.freeze({ ...source })));
+    const untimed = narrowings.map((source): CapabilityRequest<unknown> => ({
+      ...(source.clearance !== undefined ? { clearance: source.clearance } : {}),
+      ...(source.effects !== undefined ? { effects: source.effects } : {}),
+    }));
+    const listed = narrowWithin(capability, untimed, policy.clearanceOrder);
+    const refusal = [...wire.notes, ...listed.notes].find((note) => note.kind === "refused");
+    if (refusal) throw new Error(`The narrowing of ${face === undefined ? "the face" : `the ${face} face`} is not valid: ${refusal.message}`);
+    capability = listed.capability;
+  }
+  const expose = options.expose !== undefined ? exposeRule(options.expose) : undefined;
+  const sources = narrowings;
+  return {
+    narrowings,
+    expose,
+    capability,
+    apply: (request) => {
+      if (sources.length === 0 && !expose) return request;
+      return {
+        ...request,
+        ...(sources.length > 0 ? { metadata: { ...request.metadata, [NARROWING_METADATA_KEY]: addNarrowing(request.metadata[NARROWING_METADATA_KEY], sources) } } : {}),
+        ...(expose ? { expose: meetExpose(request.expose, expose) } : {}),
+      };
+    },
+  };
+}

package/src/server/procedure-server.ts

@@ -10,7 +10,7 @@ import { errorResponse } from "./error-response.js";
 
 export { errorResponse };
 import type { Admission, AmbientCredentials, Credentials, Method, Principal, PrincipalOf, RequestIdentity, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
-import { methodToPath, pathToMethod } from "./method.js";
+import { methodName, methodToPath, pathToMethod } from "./method.js";
 import { isLocalCredentials } from "./request-auth.js";
 import { STREAM_METADATA_KEY } from "./stream-metadata.js";
 import type {
@@ -39,6 +39,8 @@ import type { NarrowingNote } from "../procedures/narrowing.js";
 import type { ServerDebugReport } from "./types.js";
 import type { KeyedLimiter, LimiterStore } from "@mark1russell7/service/limiter";
 import { callLimiter, limitedCall, rateLimitedResponse, type CallLimit, type CallLimiter } from "./limits.js";
+import { writeLog } from "../logger.js";
+import { meetExpose } from "./face-rules.js";
 
 // =============================================================================
 // Types
@@ -195,9 +197,10 @@ export interface ProcedureServerOptions extends ServerOptions {
   events?: EventPublisherOptions | EventPublisher | undefined;
 
   /**
-   * The debug reports of the server. `true` writes each report with `console.debug`, and a
-   * function gets each report. The server reports each part of the narrowing of a call that has
-   * no effect (CLI-30). Such a part asks for more than the call holds, or it is not valid. The
+   * The debug reports of the server. `true` writes each report to the `logger` at the level `debug`,
+   * or with `console.debug` without a logger (CLI-87). A function gets each report.
+   *
+   * The server reports each part of the narrowing of a call that has no effect (CLI-30). Such a part asks for more than the call holds, or it is not valid. The
    * call goes on without that part. The server also reports a source that refuses the call.
    * @default false
    */
@@ -492,7 +495,15 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       typeof options.debug === "function"
         ? options.debug
         : options.debug === true
-          ? (report) => console.debug(`[ProcedureServer] ${report.topic} of ${report.requestId}: ${report.message}`)
+          ? (report) =>
+              // The logger of the server gets the report at the level debug (CLI-87)
+              writeLog(
+                options.logger,
+                "debug",
+                report.message,
+                { topic: report.topic, requestId: report.requestId, procedure: methodName(report.method), ...(report.detail ? { detail: report.detail } : {}) },
+                `[ProcedureServer] ${report.topic} of ${report.requestId}: ${report.message}`,
+              )
           : undefined;
     // The limits of the calls: one keyed limiter for each limit, on the clock of the server (CLI-40)
     this.callLimits = options.limits && options.limits.length > 0 ? callLimiter(options.limits, { clock: this.clock, stores: options.limitStores }) : undefined;
@@ -808,8 +819,16 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
   /**
    * The handlers that `register()` added come first (exact or pattern matches). Then the server
    * looks up the procedure of the method.
+   *
+   * The expose rule of the face of the request (`request.expose`, AG1-B) comes before both. A path
+   * outside it has no handler, also a handler of `register()` and an `alwaysOn` pin. A rule that is
+   * not a function admits no path, so a face that sets a wrong value does not open the server.
    */
-  protected override findHandler(method: Method): ServerHandler | null {
+  protected override findHandler(method: Method, request?: ServerRequest<unknown>): ServerHandler | null {
+    if (request?.expose !== undefined) {
+      const rule: unknown = request.expose;
+      if (typeof rule !== "function" || rule(methodToPath(method)) !== true) return null;
+    }
     const handler = super.findHandler(method);
     if (handler) return handler;
     const procedure = this.resolveProcedure(method);
@@ -1105,7 +1124,8 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
         ...(request.elicit ? { elicit: request.elicit } : {}),
         ...(request.progress ? { progress: request.progress } : {}),
         repository,
-        expose: this.expose,
+        // The rule of the face of the request meets the rule of the server, also for each nested call (AG1-B)
+        expose: request.expose !== undefined ? meetExpose(this.expose, request.expose) : this.expose,
         strictCalls: this.strictCalls,
         interceptors: this.interceptors,
         capability,

package/src/server/server.ts

@@ -19,6 +19,8 @@ import { HandlerNotFoundError, ServerError } from "./types.js";
 import { compose } from "../middleware/index.js";
 import { callOf, exposeError, exposedResponse, markLogged, policyActs, type ExposedError, type HiddenErrorLog, type ServerErrorPolicy } from "./error-policy.js";
 import { withRealError } from "./error-response.js";
+import { CONSOLE_LOGGER, type LogFields, type Logger } from "../logger.js";
+import { methodName } from "./method.js";
 
 /**
  * Server configuration options.
@@ -34,9 +36,17 @@ export interface ServerOptions {
    * Global error handler.
    * Called when a handler throws an error. The error policy (`errors`) also gives it each hidden
    * error one time. A last-resort error of a face that failed before it knew the call comes with
-   * `UNKNOWN_REQUEST`: a request with the id `"unknown"`.
+   * `UNKNOWN_REQUEST`: a request with the id `"unknown"`. The third argument gives the logger of
+   * the server: the option `logger`, or `CONSOLE_LOGGER` without it (CLI-87).
    */
-  onError?: (error: Error, request: ServerRequest) => void;
+  onError?: (error: Error, request: ServerRequest, context: ServerErrorContext) => void;
+
+  /**
+   * The logger of the server and of its faces (CLI-87). The server writes its log lines and its
+   * errors to it, also when `onError` gets them. A face that has no logger of its own uses this
+   * logger. Without it, each line goes to the console as before.
+   */
+  logger?: Logger | undefined;
 
   /**
    * Request logger.
@@ -57,7 +67,7 @@ export interface ServerOptions {
    * - `expose: "coded"`: an error with a known code (`isKnownErrorCode`) goes to the caller as it
    *   is, and so does an error with a code of `codes`. Each other error goes as `INTERNAL_ERROR`
    *   with the message `"internal error"` and its real retryable flag. The server gives the real
-   *   error to `onError` one time, or to `console.error` without `onError`.
+   *   error one time to `onError` and to the `logger`, or to `console.error` without them.
    * - `map` runs first, with the real error of its own class. Its result goes to the caller as it
    *   is, with its `retryAfterMs`. `undefined` gives the error to `expose`.
    * - The last-resort catch of each face applies the same policy (`exposeError`).
@@ -76,6 +86,12 @@ export interface ServerOptions {
   errors?: ServerErrorPolicy | undefined;
 }
 
+/** The third argument of the hook `onError` of a server (CLI-87). */
+export interface ServerErrorContext {
+  /** The logger of the server: the option `logger`, or `CONSOLE_LOGGER` without it. */
+  readonly logger: Logger;
+}
+
 /**
  * Method matcher for handler registration.
  * Can match exact methods or patterns.
@@ -97,6 +113,17 @@ interface HandlerEntry {
 /** The request that `onError` gets for an error of a face that failed before it knew the call (CLI-80). */
 const UNKNOWN_REQUEST: ServerRequest = { id: "unknown", method: { service: "", operation: "" }, payload: undefined, metadata: {} };
 
+/** The fields of the log line of an error: the request id, the procedure, the transport and the error (CLI-87). */
+function errorFields(request: ServerRequest | undefined, error: unknown): LogFields {
+  if (!request) return { error };
+  return {
+    requestId: request.id,
+    procedure: methodName(request.method),
+    ...(request.transport !== undefined ? { transport: request.transport } : {}),
+    error,
+  };
+}
+
 /**
  * Universal RPC server.
  *
@@ -247,13 +274,28 @@ export class Server {
     return exposeError(this.options.errors, error, callOf(request), (real) => this.hiddenErrorLog(real, request), raw);
   }
 
-  /** The logger of the errors that the error policy hides: `onError`, or `console.error`. */
+  /**
+   * The logger of the server and of its faces: the option `logger`, or undefined without it. A face
+   * writes to the console when it is undefined (CLI-87).
+   */
+  get logger(): Logger | undefined {
+    return this.options.logger;
+  }
+
+  /** The third argument of `onError`: the logger of the server, or the console adapter without it. */
+  private errorContext(): ServerErrorContext {
+    return { logger: this.options.logger ?? CONSOLE_LOGGER };
+  }
+
+  /** The logger of the errors that the error policy hides: `onError` and the logger, or `console.error` without them. */
   private readonly hiddenErrorLog: HiddenErrorLog = (error, request) => {
     const real = error instanceof Error ? error : new Error(String(error));
+    const { onError, logger } = this.options;
     // A face that failed before it knew the call gives no request: onError gets a request of no call
-    if (this.options.onError) this.options.onError(real, request ?? UNKNOWN_REQUEST);
+    if (onError) onError(real, request ?? UNKNOWN_REQUEST, this.errorContext());
+    if (logger) logger.log("error", "The error policy hid an error", errorFields(request, real));
     // A constant format: the request id comes from the caller (CodeQL js/tainted-format-string)
-    else console.error("[Server] hidden error of %s: %o", request?.id ?? "a request", real);
+    else if (!onError) console.error("[Server] hidden error of %s: %o", request?.id ?? "a request", real);
   };
 
   /** The response of a request, before the error policy. */
@@ -267,7 +309,7 @@ export class Server {
 
     try {
       // Find handler
-      const handler = this.findHandler(request.method);
+      const handler = this.findHandler(request.method, request);
       if (!handler) {
         throw new HandlerNotFoundError(request.method);
       }
@@ -295,12 +337,12 @@ export class Server {
 
       return response;
     } catch (error) {
-      // Log error
-      if (this.options.onError) {
-        this.options.onError(error as Error, request);
-        // The error policy does not log this error again (CLI-80)
-        markLogged(error);
-      }
+      // Log error: to onError and to the logger (CLI-87)
+      const { onError, logger } = this.options;
+      if (onError) onError(error as Error, request, this.errorContext());
+      if (logger) logger.log("error", "A handler failed", errorFields(request, error));
+      // The error policy does not log this error again (CLI-80)
+      if (onError || logger) markLogged(error);
 
       // Convert error to response
       return this.errorToResponse<TRes>(request, error as Error);
@@ -309,9 +351,10 @@ export class Server {
 
   /**
    * Find handler for a method. A subclass can add handlers that it finds at request time
-   * (`ProcedureServer` looks up its registry).
+   * (`ProcedureServer` looks up its registry). The request is absent for a lookup outside a call.
+   * `ProcedureServer` reads the expose rule of its face from it (AG1-B).
    */
-  protected findHandler(method: Method): ServerHandler | null {
+  protected findHandler(method: Method, _request?: ServerRequest<unknown>): ServerHandler | null {
     for (const entry of this.handlers) {
       if (this.matchesMethod(entry.matcher, method)) {
         return entry.handler;

package/src/server/types.ts

@@ -8,8 +8,9 @@
 import type { Elicit } from "../procedures/elicit.js";
 import type { ReportProgress } from "../procedures/progress.js";
 import type { Metadata, Status, Method } from "../client/types.js";
-import type { CapabilityRequest } from "../procedures/types.js";
+import type { CapabilityRequest, ProcedurePath } from "../procedures/types.js";
 import type { ExposedError } from "./error-policy.js";
+import type { Logger } from "../logger.js";
 import { methodName } from "./method.js";
 
 // Re-export Method from client types
@@ -75,6 +76,14 @@ export interface ServerRequest<TReq = unknown> {
    * capability does not become wider.
    */
   narrowing?: CapabilityRequest | undefined;
+
+  /**
+   * The expose rule of the face that took the request (AG1-B), for example a read-only face of a
+   * browser. The face sets it, not the caller: it is a function, so JSON cannot carry it.
+   * `ProcedureServer` meets it with its own expose rule, for the call and for each nested call.
+   * Thus it can only narrow. A path outside it gets `NOT_FOUND`, as a path outside the rule of the server.
+   */
+  expose?: ((path: ProcedurePath) => boolean) | undefined;
 }
 
 /**
@@ -247,6 +256,11 @@ export interface RequestHandler {
    * it. Absent: the handler examines each call, and the face refuses no request before its calls.
    */
   admission?(credentials: Credentials): Promise<Admission>;
+  /**
+   * The logger of the handler (CLI-87). A face writes its log lines to it, unless the options of the
+   * face give a logger. `Server` has it. Absent: the face writes to the console.
+   */
+  readonly logger?: Logger | undefined;
 }
 
 /**