@procedures/client 0.35.0 → 0.36.0

package/src/server/server.ts

@@ -17,6 +17,8 @@ import type {
 } from "./types.js";
 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";
 
 /**
  * Server configuration options.
@@ -30,7 +32,9 @@ export interface ServerOptions {
 
   /**
    * Global error handler.
-   * Called when a handler throws an error.
+   * 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"`.
    */
   onError?: (error: Error, request: ServerRequest) => void;
 
@@ -43,6 +47,33 @@ export interface ServerOptions {
    * Response logger.
    */
   onResponse?: (response: ServerResponse) => void;
+
+  /**
+   * The error policy (roadmap CLI-80): what an error tells the caller when it leaves the server.
+   * `handle()` applies it, so each face (HTTP, WebSocket, MCP, a message port) sends the same
+   * error. A nested call of `ctx.client` keeps the real error.
+   *
+   * - `expose: "all"` (the default): each error goes to the caller as before.
+   * - `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`.
+   * - `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`).
+   *
+   * @example
+   * ```typescript
+   * new ProcedureServer({
+   *   errors: {
+   *     expose: "coded",
+   *     map: (error) => (isDuplicateKey(error) ? new ServerError("The item exists", "CONFLICT") : undefined),
+   *   },
+   *   onError: (error, request) => logger.error({ err: error, id: request.id }),
+   * });
+   * ```
+   */
+  errors?: ServerErrorPolicy | undefined;
 }
 
 /**
@@ -63,6 +94,9 @@ interface HandlerEntry {
   handler: ServerHandler;
 }
 
+/** 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: {} };
+
 /**
  * Universal RPC server.
  *
@@ -196,6 +230,35 @@ export class Server {
    */
   async handle<TReq, TRes>(
     request: ServerRequest<TReq>
+  ): Promise<ServerResponse<TRes>> {
+    const policy = this.options.errors;
+    if (!policyActs(policy)) return this.handleRaw(request);
+    const response = await this.handleRaw<TReq, TRes>(request);
+    return exposedResponse(policy, request, response, this.hiddenErrorLog);
+  }
+
+  /**
+   * The error that the last-resort catch of a face sends (roadmap CLI-80): when `handle()` throws,
+   * or the face fails after it. `raw` is the error that the face sends without a policy. Under the
+   * option `errors`, `map` runs first, and `"coded"` hides the message of `INTERNAL_ERROR`. The
+   * logger gets each hidden error one time. A face calls it through `lastResortError`.
+   */
+  exposeError(error: unknown, request: ServerRequest | undefined, raw: ExposedError): ExposedError {
+    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`. */
+  private readonly hiddenErrorLog: HiddenErrorLog = (error, request) => {
+    const real = error instanceof Error ? error : new Error(String(error));
+    // 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);
+    // 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);
+  };
+
+  /** The response of a request, before the error policy. */
+  private async handleRaw<TReq, TRes>(
+    request: ServerRequest<TReq>
   ): Promise<ServerResponse<TRes>> {
     // Log request
     if (this.options.onRequest) {
@@ -235,10 +298,12 @@ export class Server {
       // 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);
       }
 
       // Convert error to response
-      return this.errorToResponse<TRes>(request.id, error as Error);
+      return this.errorToResponse<TRes>(request, error as Error);
     }
   }
 
@@ -320,7 +385,12 @@ export class Server {
   /**
    * Convert error to response.
    */
-  private errorToResponse<TRes>(id: string, error: Error): ServerResponse<TRes> {
+  private errorToResponse<TRes>(request: ServerRequest<unknown>, error: Error): ServerResponse<TRes> {
+    return withRealError(this.errorToStatus<TRes>(request.id, error), error, request);
+  }
+
+  /** The response of an error, without its record for the error policy. */
+  private errorToStatus<TRes>(id: string, error: Error): ServerResponse<TRes> {
     if (error instanceof HandlerNotFoundError) {
       return {
         id,

package/src/server/types.ts

@@ -9,6 +9,7 @@ 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 { ExposedError } from "./error-policy.js";
 import { methodName } from "./method.js";
 
 // Re-export Method from client types
@@ -47,6 +48,12 @@ export interface ServerRequest<TReq = unknown> {
   /** Abort signal for cancellation */
   signal?: AbortSignal;
 
+  /**
+   * The face that took the request: `"http"`, `"websocket"`, `"port"` or `"mcp"` (roadmap CLI-80). The face
+   * sets it, not the caller. The `map` function of the error policy (`errors`) gets it.
+   */
+  transport?: string | undefined;
+
   /**
    * The credentials of the request (roadmap R18). A network face reads them from the request: the
    * bearer token of an `Authorization` header or of the `token` query of a WebSocket connection,
@@ -213,6 +220,12 @@ export interface ServerDebugReport {
  */
 export interface RequestHandler {
   handle(request: ServerRequest): Promise<ServerResponse>;
+  /**
+   * The error that the last-resort catch of a face sends, when `handle()` throws or the face fails
+   * after it (roadmap CLI-80): `raw` under the error policy of the handler. `Server` has it, and
+   * a face calls it through `lastResortError`. Absent: the face sends `raw`.
+   */
+  exposeError?(error: unknown, request: ServerRequest | undefined, raw: ExposedError): ExposedError;
   /**
    * How the handler can authenticate a network request with ambient credentials: the cookies that
    * a browser sends by itself, also for a request of another site (CSRF). A network face then