@procedures/client 0.4.0 → 0.5.0

package/src/procedures/collection/procedures.ts

@@ -33,6 +33,7 @@ import {
   deleteBatchInputSchema,
   deleteBatchOutputSchema,
   type GetInput,
+  type GetFoundOutput,
   type SetInput,
   type DeleteInput,
   type HasInput,
@@ -107,7 +108,11 @@ export function createCollectionProcedures(collectionName: string): AnyProcedure
       },
       handler: async (input: GetInput, ctx : ProcedureContext) => {
         const storage = getStorage(ctx);
-        return storage.get(input.id);
+        const value = await storage.get(input.id);
+        if (input.found !== true) return value;
+        // The output with `found` keeps a stored null apart from a missing id, in one call
+        const output: GetFoundOutput = value === undefined ? { found: false } : { found: true, value };
+        return output;
       },
     }),
 

package/src/procedures/collection/schemas.ts

@@ -117,6 +117,12 @@ export const valueSchema : ZodLike<unknown> = createSchema<unknown>((data) => {
  */
 export interface GetInput {
   id: string;
+  /**
+   * True: the output is `{ found, value }` (a `GetFoundOutput`), so a stored `null` and a missing
+   * id give different outputs. Without it, the output is the item, or `null` on the wire for a
+   * missing id. `ApiStorage` of `@procedures/store` sends it.
+   */
+  found?: boolean;
 }
 
 export const getInputSchema : ZodLike<GetInput> = createSchema<GetInput>((data) => {
@@ -138,11 +144,31 @@ export const getInputSchema : ZodLike<GetInput> = createSchema<GetInput>((data)
       },
     };
   }
-  return { success: true, data: { id: data["id"] } };
+  const found = data["found"];
+  if (found !== undefined && typeof found !== "boolean") {
+    return {
+      success: false,
+      error: {
+        message: "found must be a boolean",
+        errors: [{ path: ["found"], message: "found must be a boolean" }],
+      },
+    };
+  }
+  return { success: true, data: found === true ? { id: data["id"], found: true } : { id: data["id"] } };
 });
 
 /**
- * Output for get operation - the item or undefined.
+ * The output of `get` with `found: true` in the input. `found` is true when the collection has
+ * the id. Then `value` is the item, also when the item is `null`.
+ */
+export interface GetFoundOutput {
+  found: boolean;
+  value?: unknown;
+}
+
+/**
+ * Output for get operation: the item, or undefined for a missing id. With `found: true` in the
+ * input, the output is a `GetFoundOutput`.
  */
 export const getOutputSchema : ZodLike<unknown> = createSchema<unknown>((data) => {
   // Accept any value (item) or undefined

package/src/procedures/collection/storage.ts

@@ -9,9 +9,16 @@
  * the collections package (roadmap 3.3).
  *
  * Each method gives a Promise: a caller cannot tell a local storage from a remote one.
+ *
+ * The contract (the suite of `@procedures/collections/testing` tests it for each storage):
+ * - A storage keeps a copy of each value that a write takes, and each read gives a new copy.
+ * - A stored `null` reads back as `null`. A missing id reads back as `undefined`.
+ * - A delta of `getChangesSince` follows the order of the last change of each id.
+ * - After `close()`, each operation rejects with an error whose message says "closed". A second
+ *   `close()` does nothing.
  */
 export interface CollectionStorage<T> {
-  /** The item with this id, or undefined. */
+  /** The item with this id, or undefined. A stored null is null. */
   get(id: string): Promise<T | undefined>;
   /** Every item of the collection. */
   getAll(): Promise<T[]>;
@@ -50,7 +57,10 @@ export interface CollectionStorage<T> {
    * that keeps no writes does not have this method. `ProcedureServer.useStorage` calls it.
    */
   flush?(): Promise<void>;
-  /** Release the resources of the storage. */
+  /**
+   * This method releases the resources of the storage. After it, each operation rejects. A second
+   * `close()` does nothing.
+   */
   close(): Promise<void>;
   /** The kind, the size and the statistics of the storage. */
   getMetadata?(): Promise<StorageMetadata>;
@@ -65,6 +75,8 @@ export interface CollectionStorage<T> {
  *   the first call, a version of an older run, or a change log that dropped old deletes.
  * - When `full` is false, `changed` has the items that changed after the version, and `deleted`
  *   has the ids that were deleted after it.
+ * - The order of a full result is the order of the entries. The order of a delta is the order of
+ *   the last change of each id.
  */
 export interface StorageChanges<T> {
   /** The version of the storage that includes these changes. */

package/src/procedures/invoke.ts

@@ -68,8 +68,10 @@ export type InvocationErrorCode =
  *   of `@procedures/fs`).
  * - `host-not-allowed`: the input has a URL whose host the host does not allow, or a redirect goes
  *   to such a host (`createHttpModule({ allow })` of `@procedures/http`).
+ * - `topic-not-allowed`: the `allow` function of an `EventPublisher` refuses a topic of a
+ *   subscription (`documentation/EVENTS.md`).
  */
-export type ForbiddenReason = CapabilityRefusalReason | "outside-root" | "host-not-allowed";
+export type ForbiddenReason = CapabilityRefusalReason | "outside-root" | "host-not-allowed" | "topic-not-allowed";
 
 /** An error of the invocation itself. An error that the handler throws passes through unchanged. */
 export class InvocationError extends Error {
@@ -79,7 +81,7 @@ export class InvocationError extends Error {
   readonly retryable: boolean = false;
   /**
    * The reason of a `FORBIDDEN` error: `effects-undeclared`, `effects-exceeded`, `clearance`,
-   * `deadline`, `outside-root` or `host-not-allowed`.
+   * `deadline`, `outside-root`, `host-not-allowed` or `topic-not-allowed`.
    */
   readonly reason: ForbiddenReason | undefined;
 

package/src/protocol.ts

@@ -46,7 +46,8 @@ export type ProtocolErrorCode =
   | "TIMEOUT"
   | "UNAVAILABLE"
   | "CONNECTION_CLOSED"
-  | "CONNECTION_NOT_FOUND";
+  | "CONNECTION_NOT_FOUND"
+  | "TOPIC_NOT_FOUND";
 
 /**
  * The error codes of the protocol, on each face (HTTP, WebSocket, MCP, local). An error that a
@@ -76,6 +77,7 @@ export const ERROR_CODES: Readonly<Record<ProtocolErrorCode, ErrorCodeInfo>> = {
   UNAVAILABLE: { http: 503, retryable: true, meaning: "The server cannot take the call now: it stops, or it is busy" },
   CONNECTION_CLOSED: { http: 503, retryable: true, meaning: "The connection closed before the call left" },
   CONNECTION_NOT_FOUND: { http: 404, retryable: false, meaning: "The server has no connection with this id" },
+  TOPIC_NOT_FOUND: { http: 404, retryable: false, meaning: "The topic rule of the host has no topic with this name" },
 };
 
 /** True when a code is an error code of the protocol. */

package/src/server/host-policy.ts

@@ -14,6 +14,8 @@
  * - `token`, `browser`: the checks of the network transports (`client-server` applies them).
  * - `capability`, `readOnly`, `clearanceOrder`, `resources`, `admitItem`: the capability of each
  *   call and what the host gives for it (CAPABILITIES-2026-10).
+ * - `events`: the remote events of the host (`documentation/EVENTS.md`). The server pins
+ *   `events.subscribe` with this topic rule, and its procedures get the bus as `ctx.bus`.
  */
 
 import type { Capability, ClearanceOrder, ProcedurePath, ResourcesOf } from "../procedures/types.js";
@@ -24,6 +26,7 @@ import { timeoutInterceptor } from "../procedures/interceptors.js";
 import type { BrowserGuardOptions } from "./browser-guard.js";
 import type { ProcedureRegistry } from "../procedures/registry.js";
 import type { ProcedureServerOptions } from "./procedure-server.js";
+import type { EventPublisherOptions } from "../events/publisher.js";
 import { toMs, type Duration } from "../duration.js";
 
 /** The procedures of a host that are tools: namespaces (first path segments), less some keys. */
@@ -86,6 +89,12 @@ export interface HostPolicyOptions {
   resources?: ((invocation: Invocation) => ResourcesOf) | undefined;
   /** The filter of the output that leaves the host. */
   admitItem?: AdmitItem | undefined;
+  /**
+   * The remote events of the host (`documentation/EVENTS.md`): the topic rule, with an optional
+   * bus, `allow` function and buffer. The default bus is the global bus, which is also the default
+   * `ctx.bus`. Without this option, the host does not serve `events.subscribe`.
+   */
+  events?: EventPublisherOptions | undefined;
 }
 
 /** What a host lets its callers do. */
@@ -100,6 +109,8 @@ export interface HostPolicy {
   readonly clearanceOrder: ClearanceOrder | undefined;
   readonly resources: ((invocation: Invocation) => ResourcesOf) | undefined;
   readonly admitItem: AdmitItem | undefined;
+  /** The remote events: each server of the policy makes its own publisher from these options. */
+  readonly events: EventPublisherOptions | undefined;
 }
 
 /** The capability function of a policy: the capability of the options, narrowed by `readOnly`. */
@@ -145,6 +156,7 @@ export function hostPolicy(options: HostPolicyOptions = {}): HostPolicy {
     clearanceOrder: options.clearanceOrder,
     resources: options.resources,
     admitItem: options.admitItem,
+    events: options.events,
   };
 }
 
@@ -162,5 +174,7 @@ export function procedureServerOptions(policy: HostPolicy, registry?: ProcedureR
     ...(policy.clearanceOrder ? { clearanceOrder: policy.clearanceOrder } : {}),
     ...(policy.resources ? { resources: policy.resources } : {}),
     ...(policy.admitItem ? { admitItem: policy.admitItem } : {}),
+    // The remote events: the server makes its publisher and pins events.subscribe (EVENTS.md)
+    ...(policy.events ? { events: policy.events } : {}),
   };
 }

package/src/server/procedure-server.ts

@@ -25,6 +25,8 @@ import { optionalMs, type Duration } from "../duration.js";
 import type { CollectionStorage } from "../procedures/collection/storage.js";
 import { TIMER_DEFAULTS } from "../timers.js";
 import { errorCodeOf } from "../protocol.js";
+import { EventPublisher, type EventPublisherOptions } from "../events/publisher.js";
+import { getGlobalEventBus } from "../events/bus.js";
 
 // =============================================================================
 // Types
@@ -119,6 +121,14 @@ export interface ProcedureServerOptions extends ServerOptions {
    * `request.principal`.
    */
   authenticate?: ((request: ServerRequest<unknown>) => Principal | undefined | Promise<Principal | undefined>) | undefined;
+
+  /**
+   * The remote events of the server (`documentation/EVENTS.md`): a bus and its topic rule, or an
+   * `EventPublisher`. The server pins the procedure `events.subscribe`, outside its registry, so a
+   * peer can subscribe to the topics. The procedures of the server get this bus as `ctx.bus`.
+   * `stop()` ends each subscription first, with `UNAVAILABLE`.
+   */
+  events?: EventPublisherOptions | EventPublisher | undefined;
 }
 
 /**
@@ -288,6 +298,8 @@ export class ProcedureServer extends Server implements RepositoryProvider {
   private readonly authenticate: ProcedureServerOptions["authenticate"];
   /** The functions that `stop()` waits on: each one runs when no call is in flight */
   private idleWaiters: Array<() => void> = [];
+  /** The publisher of the remote events, from the option `events`, or undefined. */
+  readonly publisher: EventPublisher | undefined;
 
   constructor(options: ProcedureServerOptions = {}) {
     super(options);
@@ -305,6 +317,9 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     this.idempotency = options.idempotency === false ? undefined : new IdempotencyCache(options.idempotency ?? {});
     this.token = options.token;
     this.authenticate = options.authenticate;
+    // The remote events: the server pins events.subscribe, as it pins host.health (EVENTS.md)
+    this.publisher = options.events instanceof EventPublisher ? options.events : options.events ? new EventPublisher(options.events) : undefined;
+    if (this.publisher) this.registerProcedure(this.publisher.procedure);
 
     // Configure collections
     if (options.collections) {
@@ -645,6 +660,8 @@ export class ProcedureServer extends Server implements RepositoryProvider {
         clearanceOrder,
         resources,
         admitItem,
+        // The bus of the remote events is the bus of the procedures (EVENTS.md)
+        ...(this.publisher ? { bus: this.publisher.bus } : {}),
       });
       if (output.kind === "stream") {
         // The faces that collect a stream read this mark (roadmap R15)
@@ -723,23 +740,41 @@ export class ProcedureServer extends Server implements RepositoryProvider {
   }
 
   /**
-   * Close all storage backends.
+   * This function publishes an event on the bus of the server: the bus of the option `events`, or
+   * the global bus. Each subscription of the topic gets it (`documentation/EVENTS.md`).
+   *
+   * @param topic - The topic: a channel of the bus
+   * @param data - The data of the event. It crosses the wire as JSON.
+   */
+  publish<T>(topic: string, data: T): void {
+    (this.publisher?.bus ?? getGlobalEventBus()).emit(topic, data);
+  }
+
+  /**
+   * This method closes each storage one time, also a storage of two collections, and removes the
+   * storages from the server. A closed storage rejects each operation, so the server does not keep
+   * it. Before a new `start()`, give the storages again with `useStorage()`.
    */
   async closeStorages(): Promise<void> {
-    const closePromises = Array.from(this.storages.values()).map((s) =>
-      s.close()
-    );
-    await Promise.all(closePromises);
+    const storages = new Set(this.storages.values());
+    this.storages.clear();
+    const results = await Promise.allSettled(Array.from(storages, (storage) => storage.close()));
+    const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+    if (failed) throw failed.reason;
   }
 
   /**
-   * Stop server and close storages.
+   * This method stops the server, then closes the storages and removes them (`closeStorages()`).
+   * The server can start again, with new storages from `useStorage()`. Before, a server that
+   * started again used the closed storages.
    */
   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;
+    // A subscription has no end: it ends now, with a retryable UNAVAILABLE (EVENTS.md)
+    this.publisher?.end();
     if (graceMs > 0 && this.inFlight > 0) {
       await new Promise<void>((resolve) => {
         const timer = setTimeout(resolve, graceMs);