@procedures/client 0.2.2 → 0.3.0

package/src/server/procedure-server.ts

@@ -6,7 +6,7 @@
  */
 
 import { Server, type ServerOptions } from "./server.js";
-import type { Method, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
+import type { Method, Principal, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
 import { methodToPath, pathToMethod } from "./method.js";
 import type {
   AnyProcedure,
@@ -19,8 +19,11 @@ import { ProcedureRegistry, PROCEDURE_REGISTRY } from "../procedures/registry.js
 import { createCollectionProcedures } from "../procedures/collection/procedures.js";
 import { InvocationError, invokeProcedure, type AdmitItem, type Interceptor, type Invocation } from "../procedures/invoke.js";
 import type { Capability, ClearanceOrder, ResourcesOf } from "../procedures/types.js";
-import { TIMEOUT_METADATA_KEY, narrowCapability } from "../procedures/capability.js";
+import { TIMEOUT_METADATA_KEY, effectsOf, narrowCapability } from "../procedures/capability.js";
+import { IdempotencyCache, idempotencyKeyOf, isRepeatable, type IdempotencyOptions } from "../procedures/idempotency.js";
+import { optionalMs, type Duration } from "../duration.js";
 import type { CollectionStorage } from "../procedures/collection/storage.js";
+import { TIMER_DEFAULTS } from "../timers.js";
 
 // =============================================================================
 // Types
@@ -36,6 +39,17 @@ export interface StorageConfig<T = unknown> {
   name: string;
 }
 
+/** How `ProcedureServer.useStorage` puts a new storage in the place of an old one (roadmap R28). */
+export interface UseStorageOptions {
+  /**
+   * True: the server calls `flush()` of the old storage before it changes the storage. When the
+   * flush fails, the old storage stays and `useStorage` throws.
+   */
+  drain?: boolean | undefined;
+  /** True: the server closes the old storage after the change. */
+  close?: boolean | undefined;
+}
+
 /**
  * Options for ProcedureServer.
  */
@@ -82,6 +96,93 @@ export interface ProcedureServerOptions extends ServerOptions {
   resources?: ((invocation: Invocation) => ResourcesOf) | undefined;
   /** The filter of the output that leaves the server. */
   admitItem?: AdmitItem | undefined;
+
+  /**
+   * The results of keyed calls (roadmap R1). A call to a procedure that is not repeatable, with
+   * an idempotency key in its metadata, runs one time: a later try with the same key gets the
+   * same result. `false` turns this off. The default keeps 1000 results for 10 minutes.
+   */
+  idempotency?: IdempotencyOptions | false | undefined;
+
+  /**
+   * The token of the server (roadmap R18). Each request with credentials (a network request)
+   * must present it as its bearer token, or the server answers `UNAUTHORIZED`. Before, only the
+   * Express middleware of the peer examined the token, so a `ProcedureServer` with the HTTP or
+   * WebSocket transport of the core and the token of a host policy accepted each request.
+   */
+  token?: string | undefined;
+
+  /**
+   * This function gives the principal of a request, or undefined to refuse it with
+   * `UNAUTHORIZED`. It runs after the token check. The capability function can read
+   * `request.principal`.
+   */
+  authenticate?: ((request: ServerRequest<unknown>) => Principal | undefined | Promise<Principal | undefined>) | undefined;
+}
+
+/**
+ * The metadata key of a stream response whose procedure declares `stream: { unbounded: true }`.
+ * Its value is "unbounded".
+ */
+export const STREAM_METADATA_KEY = "stream";
+
+/** True when a stream response can run without an end (roadmap R15). */
+export function isUnboundedStream(response: { metadata?: Record<string, unknown> | undefined }): boolean {
+  return response.metadata?.[STREAM_METADATA_KEY] === "unbounded";
+}
+
+/**
+ * True when the presented token is the expected one. The comparison takes the same time for each
+ * presented token of the same length, so the time does not tell the token.
+ */
+export function tokenMatches(expected: string, presented: string | undefined): boolean {
+  if (presented === undefined || presented.length !== expected.length) return false;
+  let difference = 0;
+  for (let index = 0; index < expected.length; index++) difference |= expected.charCodeAt(index) ^ presented.charCodeAt(index);
+  return difference === 0;
+}
+
+/** The options of `ProcedureServer.stop()`. */
+export interface StopOptions {
+  /**
+   * The time for the calls in flight to end (roadmap R14). The server refuses new calls at once
+   * with a retryable `UNAVAILABLE`. When the time ends, the server aborts the calls that still
+   * run. Absent or 0: the server aborts them at once.
+   */
+  grace?: Duration | undefined;
+}
+
+/** A signal that aborts when one of the signals aborts. */
+function joinSignals(first: AbortSignal | undefined, second: AbortSignal): AbortSignal {
+  if (!first) return second;
+  const any = (AbortSignal as { any?: (signals: AbortSignal[]) => AbortSignal }).any;
+  if (any) return any([first, second]);
+  const controller = new AbortController();
+  const abort = (): void => controller.abort();
+  if (first.aborted || second.aborted) controller.abort();
+  first.addEventListener("abort", abort, { once: true });
+  second.addEventListener("abort", abort, { once: true });
+  return controller.signal;
+}
+
+/** This function waits for a promise, or gives undefined when the signal aborts first. */
+function untilAborted<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | undefined> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.resolve(undefined);
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => resolve(undefined);
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
 }
 
 /** The capability of a request with the remaining time of its caller, when it sends one. */
@@ -105,6 +206,10 @@ export function errorResponse(id: string, error: unknown): ServerResponse<unknow
   const retryable = (error as { retryable?: unknown } | undefined)?.retryable;
   // A refusal of the capability says why (CAPABILITIES-2026-10)
   const reason = error instanceof InvocationError ? error.reason : undefined;
+  // An error can ask the client to wait before a retry: retryAfterMs, in milliseconds (R12)
+  const retryAfterMs = (error as { retryAfterMs?: unknown } | undefined)?.retryAfterMs;
+  const metadata: Record<string, unknown> = reason ? { reason } : {};
+  if (typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) metadata["retry-after"] = retryAfterMs;
   return {
     id,
     status: {
@@ -113,7 +218,7 @@ export function errorResponse(id: string, error: unknown): ServerResponse<unknow
       message: error instanceof Error ? error.message : String(error),
       retryable: typeof retryable === "boolean" ? retryable : false,
     },
-    metadata: reason ? { reason } : {},
+    metadata,
   };
 }
 
@@ -165,6 +270,22 @@ export class ProcedureServer extends Server implements RepositoryProvider {
   private readonly interceptors: readonly Interceptor[];
   /** The capability options of the requests (CAPABILITIES-2026-10). */
   private readonly capabilityOptions: Pick<ProcedureServerOptions, "capability" | "clearanceOrder" | "resources" | "admitItem">;
+  /** The results of keyed calls, or undefined when the option turns them off (R1). */
+  private readonly idempotency: IdempotencyCache<ServerResponse<unknown>> | undefined;
+  /**
+   * The signal of the server: `stop()` aborts it. Each call gets it joined with its request
+   * signal (the request and connection scopes) and its deadline (roadmap R14).
+   */
+  private lifetime = new AbortController();
+  /** True while `stop()` waits for the calls in flight: a new call gets UNAVAILABLE */
+  private draining = false;
+  /** The calls in flight, a stream until its end */
+  private inFlight = 0;
+  /** The token of the server, and its authenticate function (R18) */
+  private readonly token: string | undefined;
+  private readonly authenticate: ProcedureServerOptions["authenticate"];
+  /** The functions that `stop()` waits on: each one runs when no call is in flight */
+  private idleWaiters: Array<() => void> = [];
 
   constructor(options: ProcedureServerOptions = {}) {
     super(options);
@@ -179,6 +300,9 @@ export class ProcedureServer extends Server implements RepositoryProvider {
       resources: options.resources,
       admitItem: options.admitItem,
     };
+    this.idempotency = options.idempotency === false ? undefined : new IdempotencyCache(options.idempotency ?? {});
+    this.token = options.token;
+    this.authenticate = options.authenticate;
 
     // Configure collections
     if (options.collections) {
@@ -228,12 +352,41 @@ export class ProcedureServer extends Server implements RepositoryProvider {
   /**
    * Configure storage for a collection.
    *
+   * Without options, the server uses the new storage at once, and the old storage stays as it
+   * is. With options, the change is asynchronous (roadmap R28):
+   *
+   * - `drain`: the server calls `flush()` of the old storage, then it uses the new storage. A
+   *   failed flush keeps the old storage and throws. A call that arrives during the flush goes
+   *   to the old storage.
+   * - `close`: the server closes the old storage after the change. The close of a
+   *   `HybridStorage` sends the writes that arrived during the flush.
+   *
    * @param name - Collection name
    * @param storage - Storage backend
-   * @returns this (for chaining)
+   * @param options - Drain and close the old storage
+   * @returns this (for chaining), or a promise of it when options are given
    */
-  useStorage<T>(name: string, storage: CollectionStorage<T>): this {
-    this.storages.set(name, storage as CollectionStorage<unknown>);
+  useStorage<T>(name: string, storage: CollectionStorage<T>): this;
+  useStorage<T>(name: string, storage: CollectionStorage<T>, options: UseStorageOptions): Promise<this>;
+  useStorage<T>(name: string, storage: CollectionStorage<T>, options?: UseStorageOptions): this | Promise<this> {
+    if (options === undefined) {
+      this.storages.set(name, storage as CollectionStorage<unknown>);
+      return this;
+    }
+    return this.replaceStorage(name, storage as CollectionStorage<unknown>, options);
+  }
+
+  /** The change of `useStorage` with options: flush the old storage, change, close the old one. */
+  private async replaceStorage(name: string, storage: CollectionStorage<unknown>, options: UseStorageOptions): Promise<this> {
+    const old = this.storages.get(name);
+    const other = old !== undefined && old !== storage ? old : undefined;
+    if (other && options.drain) {
+      await other.flush?.();
+    }
+    this.storages.set(name, storage);
+    if (other && options.close) {
+      await other.close();
+    }
     return this;
   }
 
@@ -333,8 +486,145 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     return procedure ? (request) => this.invoke(procedure, request) : null;
   }
 
-  /** Run a procedure for a request. */
+  /**
+   * Run a procedure for a request. A keyed call to a procedure that is not repeatable runs one
+   * time for its key (R1).
+   */
   private async invoke(procedure: AnyProcedure, request: ServerRequest<unknown>): Promise<ServerResponse<unknown>> {
+    if (this.draining) {
+      // The server stops: a client can send the call to another server, or again later (R14)
+      return {
+        id: request.id,
+        status: { type: "error", code: "UNAVAILABLE", message: "The server is stopping", retryable: true },
+        metadata: {},
+      };
+    }
+    const refusal = await this.admit(request);
+    if (refusal) return refusal;
+    this.inFlight++;
+    let response: ServerResponse<unknown> | undefined;
+    try {
+      const key = this.idempotency ? idempotencyKeyOf(request.metadata) : undefined;
+      response =
+        key === undefined || isRepeatable(effectsOf(procedure))
+          ? await this.run(procedure, request, joinSignals(request.signal, this.lifetime.signal))
+          : await this.runKeyed(procedure, request, `${pathToKey(procedure.path)}\u0000${key}`);
+    } finally {
+      // A stream is in flight until its end; another response is done now
+      if (!response?.stream) this.callEnded();
+    }
+    const stream = response.stream;
+    if (stream) {
+      const ended = (): void => this.callEnded();
+      response = {
+        ...response,
+        stream: (async function* () {
+          try {
+            yield* stream;
+          } finally {
+            ended();
+          }
+        })(),
+      };
+    }
+    return response;
+  }
+
+  /**
+   * The token check and the principal of a request (roadmap R18). A network request (with
+   * credentials) must present the token. The authenticate function gives the principal. The
+   * function gives an UNAUTHORIZED response, or undefined when the request passes.
+   */
+  private async admit(request: ServerRequest<unknown>): Promise<ServerResponse<unknown> | undefined> {
+    const unauthorized = (message: string): ServerResponse<unknown> => ({
+      id: request.id,
+      status: { type: "error", code: "UNAUTHORIZED", message, retryable: false },
+      metadata: {},
+    });
+    if (this.token !== undefined && request.credentials !== undefined) {
+      if (!tokenMatches(this.token, request.credentials.bearer)) return unauthorized("Unauthorized: this server requires its token");
+      request.principal = { id: "token", via: "token" };
+    }
+    if (this.authenticate) {
+      let principal: Principal | undefined;
+      try {
+        principal = await this.authenticate(request);
+      } catch {
+        principal = undefined;
+      }
+      if (!principal) return unauthorized("Unauthorized: the server did not accept the credentials");
+      request.principal = principal;
+    }
+    return undefined;
+  }
+
+  /** One call in flight ended: `stop()` can go on when it was the last one. */
+  private callEnded(): void {
+    this.inFlight--;
+    if (this.inFlight === 0) {
+      const waiters = this.idleWaiters;
+      this.idleWaiters = [];
+      for (const waiter of waiters) waiter();
+    }
+  }
+
+  /** The number of calls in flight, streams included. */
+  get callsInFlight(): number {
+    return this.inFlight;
+  }
+
+  /** True while `stop()` waits for the calls in flight: the server refuses new calls. */
+  get stopping(): boolean {
+    return this.draining;
+  }
+
+  /**
+   * Run a keyed call one time. The run continues when its caller goes away, so that the next try
+   * gets its result: only the deadline of the call and the stop of the server end it. A stream
+   * still stops with its caller, because nobody can read it again.
+   */
+  private async runKeyed(procedure: AnyProcedure, request: ServerRequest<unknown>, cacheKey: string): Promise<ServerResponse<unknown>> {
+    const { result, first } = this.idempotency!.run(
+      cacheKey,
+      async () => {
+        const detached = new AbortController();
+        const stopRun = (): void => detached.abort();
+        this.lifetime.signal.addEventListener("abort", stopRun, { once: true });
+        try {
+          const response = await this.run(procedure, request, detached.signal);
+          if (response.stream) {
+            // A stream follows its caller again
+            if (request.signal?.aborted) detached.abort();
+            else request.signal?.addEventListener("abort", stopRun, { once: true });
+          }
+          return response;
+        } finally {
+          this.lifetime.signal.removeEventListener("abort", stopRun);
+        }
+      },
+      // A retryable error lets the next try run again: the handler said that a retry is safe
+      (response) => !(response.status.type === "error" && response.status.retryable),
+    );
+    if (first) return result;
+    const response = await untilAborted(result, request.signal);
+    if (response === undefined) return errorResponse(request.id, new InvocationError("ABORTED", "The request was aborted", procedure.path));
+    if (response.stream) {
+      return {
+        id: request.id,
+        status: {
+          type: "error",
+          code: "DUPLICATE",
+          message: "A call with this idempotency key gave a stream, and a stream cannot be given again",
+          retryable: false,
+        },
+        metadata: {},
+      };
+    }
+    return { ...response, id: request.id };
+  }
+
+  /** Run a procedure for a request with a signal. */
+  private async run(procedure: AnyProcedure, request: ServerRequest<unknown>, signal: AbortSignal | undefined): 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
@@ -342,7 +632,7 @@ export class ProcedureServer extends Server implements RepositoryProvider {
       const output = await invokeProcedure(procedure, request.payload, {
         registry: this.procedureRegistry,
         metadata: request.metadata,
-        signal: request.signal,
+        signal,
         repository: this,
         expose: this.expose,
         strictCalls: this.strictCalls,
@@ -355,7 +645,14 @@ export class ProcedureServer extends Server implements RepositoryProvider {
         admitItem,
       });
       if (output.kind === "stream") {
-        return { id: request.id, status: { type: "success", code: 200 }, stream: output.items, metadata: {} };
+        // The faces that collect a stream read this mark (roadmap R15)
+        const unbounded = (procedure.metadata as { stream?: { unbounded?: boolean } } | undefined)?.stream?.unbounded === true;
+        return {
+          id: request.id,
+          status: { type: "success", code: 200 },
+          stream: output.items,
+          metadata: unbounded ? { [STREAM_METADATA_KEY]: "unbounded" } : {},
+        };
       }
       return { id: request.id, status: { type: "success", code: 200 }, payload: output.value, metadata: {} };
     } catch (error) {
@@ -436,7 +733,24 @@ export class ProcedureServer extends Server implements RepositoryProvider {
   /**
    * Stop server and close storages.
    */
-  override async stop(): Promise<void> {
+  override async stop(options: StopOptions = {}): Promise<void> {
+    const graceMs = optionalMs(options.grace, "grace") ?? TIMER_DEFAULTS.server.stopGraceMs;
+    // A graceful stop: new calls get UNAVAILABLE, and the calls in flight have the grace time
+    // to end (roadmap R14). Before, the transports aborted every call at once.
+    this.draining = true;
+    if (graceMs > 0 && this.inFlight > 0) {
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, graceMs);
+        this.idleWaiters.push(() => {
+          clearTimeout(timer);
+          resolve();
+        });
+      });
+    }
+    this.lifetime.abort();
+    // A server can start again: its next calls get a new signal
+    this.lifetime = new AbortController();
+    this.draining = false;
     await super.stop();
     await this.closeStorages();
   }

package/src/server/request-auth.ts

@@ -0,0 +1,35 @@
+/**
+ * The credentials of a network request (roadmap R18). A server transport reads them into
+ * `ServerRequest.credentials`, and leaves the secret headers out of the metadata, so a handler
+ * and a nested call do not see them. `ProcedureServer` examines them.
+ */
+
+import type { Credentials } from "./types.js";
+
+/** The headers that carry a secret. They do not go into the metadata of a request. */
+const SECRET_HEADERS = new Set(["authorization", "proxy-authorization", "cookie", "x-api-key"]);
+
+/** The headers without the secret ones, and without the headers that are not text. */
+export function withoutSecretHeaders(headers: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (!SECRET_HEADERS.has(key.toLowerCase()) && typeof value === "string") out[key] = value;
+  }
+  return out;
+}
+
+/** The token of an `Authorization: Bearer <token>` header, or undefined. */
+export function bearerOf(header: unknown): string | undefined {
+  return typeof header === "string" && header.startsWith("Bearer ") ? header.slice("Bearer ".length) : undefined;
+}
+
+/**
+ * The credentials of a request or of a WebSocket upgrade: the bearer token of its
+ * `Authorization` header, or else of its `token` query (a browser WebSocket cannot set headers).
+ */
+export function credentialsOf(request: { headers: Record<string, unknown>; url?: string | undefined }): Credentials {
+  const bearer = bearerOf(request.headers["authorization"]);
+  if (bearer !== undefined) return { bearer };
+  const query = new URL(request.url ?? "/", "http://localhost").searchParams.get("token");
+  return query === null ? {} : { bearer: query };
+}

package/src/server/types.ts

@@ -29,6 +29,43 @@ export interface ServerRequest<TReq = unknown> {
 
   /** Abort signal for cancellation */
   signal?: AbortSignal;
+
+  /**
+   * The credentials that a network transport read from the request: the bearer token of an
+   * `Authorization` header, or of the `token` query of a WebSocket connection (roadmap R18). They
+   * are not in the metadata, so a handler and a nested call do not see them. A request without
+   * credentials comes from this process (a direct `handle()`, MCP over stdio).
+   */
+  credentials?: Credentials | undefined;
+
+  /** The principal of the request: who sends it. `ProcedureServer` sets it when it authenticates the request. */
+  principal?: Principal | undefined;
+}
+
+/** The credentials of a request. */
+export interface Credentials {
+  /** The bearer token that the request presents. */
+  readonly bearer?: string | undefined;
+}
+
+/** Who sends a request (roadmap R18). */
+export interface Principal {
+  /** The id of the principal. With the token of a host: "token". */
+  readonly id: string;
+  /** How the server authenticated it: "token", or the name of an authenticate function. */
+  readonly via: string;
+  /** More facts about the principal, from an authenticate function. */
+  readonly claims?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * The contract of a server transport (roadmap R18): a transport turns each protocol request
+ * into a `ServerRequest` (with its signal and its credentials), gives it to `handle()`, and turns
+ * the `ServerResponse` back (a value, a stream or an error). `Server` and `ProcedureServer`
+ * satisfy it, and a test can give a function.
+ */
+export interface RequestHandler {
+  handle(request: ServerRequest): Promise<ServerResponse>;
 }
 
 /**

package/src/timers.ts

@@ -0,0 +1,82 @@
+/**
+ * The timer settings of the core, as data (roadmap R34).
+ *
+ * Each default time of the middleware, the transports and the server comes from this object, so
+ * a tool can read the settings without a call. `@procedures/systems` binds them to the symbols of
+ * the timer law of `systems`, and examines rules such as "the time of one try is less than the
+ * request time of the WebSocket". The values are milliseconds. The options of an application
+ * are Durations (roadmap R11), and they replace these values.
+ */
+
+/** The default times of the core, in milliseconds. */
+export interface TimerDefaults {
+  readonly retry: {
+    /** The tries after the first one. */
+    readonly maxRetries: number;
+    readonly retryDelayMs: number;
+    readonly backoffMultiplier: number;
+    /** The longest backoff. Infinity: no limit. */
+    readonly maxDelayMs: number;
+  };
+  readonly circuitBreaker: {
+    readonly failureWindowMs: number;
+    readonly resetTimeoutMs: number;
+  };
+  readonly cache: {
+    readonly ttlMs: number;
+    readonly statsIntervalMs: number;
+  };
+  readonly rateLimit: {
+    readonly windowMs: number;
+  };
+  readonly webSocketClient: {
+    /** The time of the handshake. */
+    readonly connectionTimeoutMs: number;
+    /** The time until the first frame of a call. */
+    readonly requestTimeoutMs: number;
+    readonly heartbeatIntervalMs: number;
+    readonly heartbeatTimeoutMs: number;
+    /** The pongs that can go missing, one after the other, before the connection closes. */
+    readonly heartbeatMisses: number;
+    readonly reconnectInitialDelayMs: number;
+    readonly reconnectMaxDelayMs: number;
+  };
+  readonly webSocketServer: {
+    readonly heartbeatIntervalMs: number;
+    readonly heartbeatMisses: number;
+    /** The time until the first frame of a call of the server to a client. */
+    readonly reverseRequestTimeoutMs: number;
+  };
+  readonly idempotency: {
+    /** The time that the server keeps the result of a keyed write. */
+    readonly ttlMs: number;
+  };
+  readonly server: {
+    /** The time that `ProcedureServer.stop()` waits for the calls that run. */
+    readonly stopGraceMs: number;
+  };
+}
+
+/** The default times of the core. The middleware, the transports and the server read them. */
+export const TIMER_DEFAULTS: TimerDefaults = Object.freeze({
+  retry: Object.freeze({ maxRetries: 3, retryDelayMs: 1000, backoffMultiplier: 2, maxDelayMs: Number.POSITIVE_INFINITY }),
+  circuitBreaker: Object.freeze({ failureWindowMs: 10_000, resetTimeoutMs: 30_000 }),
+  cache: Object.freeze({ ttlMs: 60_000, statsIntervalMs: 60_000 }),
+  rateLimit: Object.freeze({ windowMs: 60_000 }),
+  webSocketClient: Object.freeze({
+    connectionTimeoutMs: 10_000,
+    requestTimeoutMs: 30_000,
+    // 20 s: with the pong timeout of 5 s, the client finds a dead connection after 25 s, before a
+    // call on it reaches the request time of 30 s. Before, 30 s gave 35 s (the timer law, R34).
+    heartbeatIntervalMs: 20_000,
+    heartbeatTimeoutMs: 5_000,
+    heartbeatMisses: 1,
+    reconnectInitialDelayMs: 1_000,
+    reconnectMaxDelayMs: 30_000,
+  }),
+  // 15 s: with 2 misses, the server finds a dead client after 30 s, not later than a call of the
+  // server to it reaches its request time of 30 s. Before, 30 s gave 60 s (the timer law, R34).
+  webSocketServer: Object.freeze({ heartbeatIntervalMs: 15_000, heartbeatMisses: 2, reverseRequestTimeoutMs: 30_000 }),
+  idempotency: Object.freeze({ ttlMs: 10 * 60_000 }),
+  server: Object.freeze({ stopGraceMs: 0 }),
+});

package/src/tracing/traceparent.ts

@@ -0,0 +1,61 @@
+/**
+ * The W3C trace context (roadmap R16): `traceparent` is `00-<trace id>-<span id>-<flags>`, with a
+ * trace id of 32 hex digits and a span id of 16. The tracing middleware of a client sends it in
+ * the metadata of a call (and HTTP as the `traceparent` header). The tracing interceptor of a
+ * server continues that trace, and gives it to the nested calls, so one trace goes from the
+ * client to the last handler. Before, the client and the server made two traces.
+ */
+
+/** The metadata key of the W3C trace context of a call. */
+export const TRACEPARENT_METADATA_KEY = "traceparent";
+
+const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const ZERO_TRACE = "0".repeat(32);
+const ZERO_SPAN = "0".repeat(16);
+
+/** A trace context: the trace, the span of the caller, and the sampled flag. */
+export interface TraceContext {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly sampled: boolean;
+}
+
+function randomHex(bytes: number): string {
+  const values = new Uint8Array(bytes);
+  const crypto = (globalThis as { crypto?: { getRandomValues?: (array: Uint8Array) => Uint8Array } }).crypto;
+  if (crypto?.getRandomValues) crypto.getRandomValues(values);
+  else for (let index = 0; index < bytes; index++) values[index] = Math.floor(Math.random() * 256);
+  return Array.from(values, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+
+/** This function makes a new trace id: 32 random hex digits. */
+export function newTraceId(): string {
+  const id = randomHex(16);
+  return id === ZERO_TRACE ? newTraceId() : id;
+}
+
+/** This function makes a new span id: 16 random hex digits. */
+export function newSpanId(): string {
+  const id = randomHex(8);
+  return id === ZERO_SPAN ? newSpanId() : id;
+}
+
+/** True when the ids have the W3C form. */
+export function isW3cIds(traceId: string, spanId: string): boolean {
+  return /^[0-9a-f]{32}$/.test(traceId) && /^[0-9a-f]{16}$/.test(spanId) && traceId !== ZERO_TRACE && spanId !== ZERO_SPAN;
+}
+
+/** The `traceparent` of a trace and a span. */
+export function formatTraceparent(traceId: string, spanId: string, sampled = true): string {
+  return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
+}
+
+/** The trace context of a `traceparent` value, or undefined when it is not valid. */
+export function parseTraceparent(value: unknown): TraceContext | undefined {
+  if (typeof value !== "string") return undefined;
+  const match = TRACEPARENT.exec(value.trim().toLowerCase());
+  if (!match) return undefined;
+  const [, traceId, spanId, flags] = match;
+  if (traceId === ZERO_TRACE || spanId === ZERO_SPAN) return undefined;
+  return { traceId: traceId!, spanId: spanId!, sampled: (parseInt(flags!, 16) & 1) === 1 };
+}