@procedures/client 0.2.3 → 0.3.0

package/dist/server/host-procedures.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The procedures of a host (roadmap R19): `host.health`, `host.info` and `host.metrics`.
+ *
+ * Before, a peer gave its health only as an Express route (`/health`), and the counts of
+ * `metricsInterceptor` had no way out. A host pins these procedures on its `ProcedureServer`
+ * (`registerProcedure`), so they do not change the registry that the host serves. A call needs
+ * the token of the host, as each other call does. The `/health` route stays for the checks
+ * that have no token.
+ */
+import type { AnyProcedure } from "../procedures/types.js";
+import type { MetricsInterceptor } from "../procedures/interceptors.js";
+import type { ProcedureServer } from "./procedure-server.js";
+/** What a host tells about itself. */
+export interface HostSource {
+    /** The id of the host (the peer id). */
+    readonly id: string;
+    /** The time at which the host started, from `Date.now()`. */
+    readonly startedAt: number;
+    /** The server of the host. */
+    readonly server: ProcedureServer;
+    /** The endpoints of the host, when it has network transports. */
+    readonly endpoints?: (() => ReadonlyArray<{
+        type: string;
+        address: string;
+    }>) | undefined;
+    /** The metrics interceptor of the host, when it counts its calls. */
+    readonly metrics?: MetricsInterceptor | undefined;
+}
+/** This function gives the procedures of a host: `host.health`, `host.info` and `host.metrics`. */
+export declare function hostProcedures(source: HostSource): AnyProcedure[];
+//# sourceMappingURL=host-procedures.d.ts.map

package/dist/server/host-procedures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-procedures.d.ts","sourceRoot":"","sources":["../../src/server/host-procedures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,GAAG,SAAS,CAAC;IAC1F,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;CACnD;AAkCD,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,EAAE,CAqCjE"}

package/dist/server/host-procedures.js

@@ -0,0 +1,75 @@
+/**
+ * The procedures of a host (roadmap R19): `host.health`, `host.info` and `host.metrics`.
+ *
+ * Before, a peer gave its health only as an Express route (`/health`), and the counts of
+ * `metricsInterceptor` had no way out. A host pins these procedures on its `ProcedureServer`
+ * (`registerProcedure`), so they do not change the registry that the host serves. A call needs
+ * the token of the host, as each other call does. The `/health` route stays for the checks
+ * that have no token.
+ */
+import { z } from "zod";
+import { createProcedure } from "../procedures/define.js";
+import { PURE_EFFECTS } from "../procedures/effects.js";
+const healthOutput = z.object({
+    status: z.enum(["ok", "stopping"]).describe("ok, or stopping while the host waits for its calls in flight"),
+    uptimeMs: z.number().describe("The time since the start of the host, in milliseconds"),
+    procedures: z.number().describe("The number of procedures that the host serves"),
+    callsInFlight: z.number().describe("The calls that run now, streams included"),
+    peerId: z.string().describe("The id of the host"),
+});
+const infoOutput = z.object({
+    peerId: z.string().describe("The id of the host"),
+    startedAt: z.string().describe("The start time of the host (ISO 8601)"),
+    endpoints: z.array(z.object({ type: z.string(), address: z.string() })).describe("The network endpoints of the host"),
+    runtime: z.string().describe("The runtime of the host, for example node 24.1.0"),
+});
+const metricsOutput = z.object({
+    procedures: z
+        .record(z.string(), z.object({ calls: z.number(), errors: z.number(), totalMs: z.number(), maxMs: z.number() }))
+        .describe("The calls, the errors and the time of each procedure since the start, by key"),
+});
+/** The runtime of this process: its name and version. */
+function runtimeOf() {
+    const process = globalThis.process;
+    if (process?.versions?.node)
+        return `node ${process.versions.node}`;
+    const navigator = globalThis.navigator;
+    return navigator?.userAgent ?? "unknown";
+}
+/** This function gives the procedures of a host: `host.health`, `host.info` and `host.metrics`. */
+export function hostProcedures(source) {
+    const health = createProcedure()
+        .path(["host", "health"])
+        .input(z.object({}))
+        .output(healthOutput)
+        .meta({ description: "The health of the host: its state, its uptime and its calls in flight", effects: PURE_EFFECTS })
+        .handler(async () => ({
+        status: source.server.stopping ? "stopping" : "ok",
+        uptimeMs: Date.now() - source.startedAt,
+        procedures: source.server.procedureCount,
+        callsInFlight: source.server.callsInFlight,
+        peerId: source.id,
+    }))
+        .build();
+    const info = createProcedure()
+        .path(["host", "info"])
+        .input(z.object({}))
+        .output(infoOutput)
+        .meta({ description: "The identity of the host: its id, its start time, its endpoints and its runtime", effects: PURE_EFFECTS })
+        .handler(async () => ({
+        peerId: source.id,
+        startedAt: new Date(source.startedAt).toISOString(),
+        endpoints: [...(source.endpoints?.() ?? [])],
+        runtime: runtimeOf(),
+    }))
+        .build();
+    const metrics = createProcedure()
+        .path(["host", "metrics"])
+        .input(z.object({}))
+        .output(metricsOutput)
+        .meta({ description: "The calls, the errors and the time of each procedure since the start of the host", effects: PURE_EFFECTS })
+        .handler(async () => ({ procedures: source.metrics?.snapshot() ?? {} }))
+        .build();
+    return [health, info, metrics];
+}
+//# sourceMappingURL=host-procedures.js.map

package/dist/server/host-procedures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-procedures.js","sourceRoot":"","sources":["../../src/server/host-procedures.ts"],"names":[],"mappings":"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"}

package/dist/server/index.d.ts

@@ -35,10 +35,10 @@
  */
 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 { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream } from "./procedure-server.js";
+export type { ProcedureServerOptions, StorageConfig, StopOptions, UseStorageOptions } 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 { HandlerNotFoundError, ServerError, type ServerRequest, type ServerResponse, type RequestHandler, type Credentials, type Principal, 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";

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,YAAY,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EACV,0BAA0B,EAC1B,eAAe,GAChB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,YAAY,EACV,+BAA+B,EAC/B,oBAAoB,EACpB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACvH,YAAY,EAAE,sBAAsB,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACnH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EACV,0BAA0B,EAC1B,eAAe,GAChB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,YAAY,EACV,+BAA+B,EAC/B,oBAAoB,EACpB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,uCAAuC,CAAC"}

package/dist/server/index.js

@@ -34,7 +34,7 @@
  * ```
  */
 export { Server } from "./server.js";
-export { ProcedureServer, createProcedureServer } from "./procedure-server.js";
+export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream } from "./procedure-server.js";
 export { pathToMethod, methodToPath } from "./method.js";
 export { HandlerNotFoundError, ServerError, } from "./types.js";
 export { HttpServerTransport, defaultServerUrlStrategy, rpcServerUrlStrategy, } from "../adapters/http/server/index.js";

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE/E,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,oBAAoB,EACpB,WAAW,GAQZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAEvH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,oBAAoB,EACpB,WAAW,GAWZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC"}

package/dist/server/procedure-server.d.ts

@@ -5,11 +5,13 @@
  * Integrates with ProcedureRegistry and CollectionStorage backends.
  */
 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 type { AnyProcedure, ProcedurePath, RepositoryProvider, ProcedureModule } from "../procedures/types.js";
 import { ProcedureRegistry } from "../procedures/registry.js";
 import { type AdmitItem, type Interceptor, type Invocation } from "../procedures/invoke.js";
 import type { Capability, ClearanceOrder, ResourcesOf } from "../procedures/types.js";
+import { type IdempotencyOptions } from "../procedures/idempotency.js";
+import { type Duration } from "../duration.js";
 import type { CollectionStorage } from "../procedures/collection/storage.js";
 /**
  * Storage configuration for a collection.
@@ -20,6 +22,16 @@ export interface StorageConfig<T = unknown> {
     /** Collection name (for mapping) */
     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.
  */
@@ -60,6 +72,48 @@ 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 declare const STREAM_METADATA_KEY = "stream";
+/** True when a stream response can run without an end (roadmap R15). */
+export declare function isUnboundedStream(response: {
+    metadata?: Record<string, unknown> | undefined;
+}): boolean;
+/**
+ * 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 declare function tokenMatches(expected: string, presented: string | undefined): boolean;
+/** 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;
 }
 /**
  * The error response of a failed invocation. An invocation error keeps its code
@@ -110,6 +164,22 @@ export declare class ProcedureServer extends Server implements RepositoryProvide
     private readonly interceptors;
     /** The capability options of the requests (CAPABILITIES-2026-10). */
     private readonly capabilityOptions;
+    /** The results of keyed calls, or undefined when the option turns them off (R1). */
+    private readonly idempotency;
+    /**
+     * 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;
+    /** True while `stop()` waits for the calls in flight: a new call gets UNAVAILABLE */
+    private draining;
+    /** The calls in flight, a stream until its end */
+    private inFlight;
+    /** The token of the server, and its authenticate function (R18) */
+    private readonly token;
+    private readonly authenticate;
+    /** The functions that `stop()` waits on: each one runs when no call is in flight */
+    private idleWaiters;
     constructor(options?: ProcedureServerOptions);
     /**
      * Get storage for a collection.
@@ -128,11 +198,24 @@ export declare class ProcedureServer extends Server implements RepositoryProvide
     /**
      * 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;
+    useStorage<T>(name: string, storage: CollectionStorage<T>, options: UseStorageOptions): Promise<this>;
+    /** The change of `useStorage` with options: flush the old storage, change, close the old one. */
+    private replaceStorage;
     /**
      * Configure multiple storages at once.
      *
@@ -180,8 +263,31 @@ export declare class ProcedureServer extends Server implements RepositoryProvide
      * looks up the procedure of the method.
      */
     protected findHandler(method: Method): ServerHandler | 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 invoke;
+    /**
+     * 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 admit;
+    /** One call in flight ended: `stop()` can go on when it was the last one. */
+    private callEnded;
+    /** The number of calls in flight, streams included. */
+    get callsInFlight(): number;
+    /** True while `stop()` waits for the calls in flight: the server refuses new calls. */
+    get stopping(): boolean;
+    /**
+     * 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 runKeyed;
+    /** Run a procedure for a request with a signal. */
+    private run;
     /**
      * Register collection procedures for a specific collection.
      * Creates standard CRUD procedures using the configured storage.
@@ -214,7 +320,7 @@ export declare class ProcedureServer extends Server implements RepositoryProvide
     /**
      * Stop server and close storages.
      */
-    stop(): Promise<void>;
+    stop(options?: StopOptions): Promise<void>;
 }
 /**
  * Create a procedure server with common configuration.

package/dist/server/procedure-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"procedure-server.d.ts","sourceRoot":"","sources":["../../src/server/procedure-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"procedure-server.d.ts","sourceRoot":"","sources":["../../src/server/procedure-server.ts"],"names":[],"mappings":"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"}