@procedures/peer 0.13.2 → 0.14.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/peer",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "description": "Serve procedures: createProcedureHost() gives the parts of a service, with HTTP, WebSocket and MCP faces on one listener. Also peers, server.create, server.call and server.connections, and manifests.",
   "keywords": [
     "server",
@@ -67,7 +67,10 @@
     "provenance": true
   },
   "devDependencies": {
-    "@procedures/fs": "0.13.2",
+    "@procedures/better-auth": "0.14.1",
+    "@procedures/fs": "0.14.1",
+    "@procedures/mcp-server": "0.14.1",
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "typescript": "^7.0.2",
     "@types/node": "^22.0.0",
     "@mark1russell7/cue": "^1.0.0",
@@ -78,7 +81,7 @@
   },
   "dependencies": {
     "@mark1russell7/service": "^0.5.2",
-    "@procedures/client": "0.13.2",
+    "@procedures/client": "0.14.1",
     "zod": "^4.6.5"
   },
   "scripts": {

package/src/host/faces.ts

@@ -12,15 +12,17 @@
  *
  * `httpFace()` and `wsFace()` are the faces of this package, on `procedureHandler` and
  * `upgradeHandler` of `@procedures/client/node`. `mcpFace()` of `@procedures/mcp-server` is the
- * MCP face. A face of another package has the same shape, so the host needs no change for it.
+ * MCP face, and `betterAuthFace()` of `@procedures/better-auth` is the face of the auth routes. A
+ * face of another package has the same shape, so the host needs no change for it. A face of
+ * requests that are not procedure calls tracks them with `track` (CLI-54).
  */
 
 import type { IncomingMessage, ServerResponse as NodeResponse } from "node:http";
 import type { Duplex } from "node:stream";
 import type { TransportImpl } from "@mark1russell7/service";
-import { Client, requestCredentials, type BrowserGuardOptions, type Clock, type HostPolicy, type ProcedureRegistry, type ProcedureServer } from "@procedures/client";
+import { Client, realClock, requestCredentials, type BrowserGuardOptions, type Clock, type HostPolicy, type ProcedureRegistry, type ProcedureServer } from "@procedures/client";
 import { procedureHandler, upgradeHandler, type ProcedureHandlerOptions, type UpgradeHandlerOptions } from "@procedures/client/node";
-import type { FaceHandler } from "./tracking.js";
+import type { FaceHandler, HttpTracker } from "./tracking.js";
 
 /** What the host gives a face. */
 export interface HostFaceContext {
@@ -33,6 +35,12 @@ export interface HostFaceContext {
   readonly policy: HostPolicy;
   /** The clock of the host: the clock of the lifecycle. */
   readonly clock: Clock;
+  /**
+   * The request tracking of the HTTP requests of the face that are not procedure calls, for example
+   * the auth routes (CLI-54). Each request goes through `life.request` on the route `<face> <key>`
+   * of the controller of the host. The host always gives it.
+   */
+  readonly track?: HttpTracker | undefined;
 }
 
 /** The upgrade handler of a face, and the path or the function that tells which upgrades it takes. */
@@ -66,6 +74,9 @@ export interface HostFace {
 /** A face factory: the host calls it one time, with the context of the face. */
 export type HostFaceFactory = (context: HostFaceContext) => HostFace;
 
+/** The longest delay of a Node timer. A wait with this delay ends at its event, or at the close of its face. */
+const UNTIL_CLOSE_MS = 2_147_483_647;
+
 /** The browser checks of the policy, as options of a face. The options of the face win over them. */
 function browserOptions(browser: BrowserGuardOptions, http: boolean): BrowserGuardOptions {
   return {
@@ -98,6 +109,8 @@ export function httpFace(options: ProcedureHandlerOptions = {}): HostFaceFactory
  *   upgrade (`ProcedureServer.admits`). Thus no idle connection without credentials stays open.
  * - The stop parts refuse new calls at the stop of the intake. In the drain, each connection
  *   closes when its calls end, so the drain of the listener does not wait for an idle connection.
+ * - After the cooperative abort, the connections stay open until each cut call ends in-band with
+ *   `UNAVAILABLE` (CLI-48). Before, the connections closed at the abort, and a cut stream lost its end.
  */
 export function wsFace(options: UpgradeHandlerOptions = {}): HostFaceFactory {
   return (context) => {
@@ -113,7 +126,17 @@ export function wsFace(options: UpgradeHandlerOptions = {}): HostFaceFactory {
         stopIntake: () => upgrade.stopIntake(),
         drain: async (deadline, signal) => {
           await upgrade.drain(deadline, signal);
-          // The calls ended, or the cooperative abort came: the connections end in their protocol
+          if (signal?.aborted) {
+            // After the cooperative abort, the service cuts each call, at the latest at the deadline,
+            // and each cut call ends in-band. The connections stay open until those calls end
+            // (CLI-48). This wait has no timer of its own: the cap of the phase limits it.
+            await upgrade.drain(realClock.now() + UNTIL_CLOSE_MS);
+            // The close starts here. The stage "close transports" waits for the close handshakes,
+            // so a cut at the deadline does not make the drain late.
+            upgrade.close().catch(() => undefined);
+            return;
+          }
+          // The calls ended: the connections end in their protocol
           await upgrade.close();
         },
         inFlight: () => upgrade.inFlight(),

package/src/host/index.ts

@@ -11,7 +11,8 @@
  *   faces mount on its mount list, so they share one port. Without a listener, the app mounts
  *   `host.handler` and `host.upgrade` on its own listener.
  * - The request tracking: one route pattern for each face, and a function of the idempotency of
- *   each call (decision D3). Each call is a stream (decision D4).
+ *   each call (decision D3). Each call is a stream (decision D4). A face of requests that are not
+ *   procedure calls, for example the auth routes, tracks them with `track` (CLI-54).
  * - The collections: the option `collections` gives the storages, and the host serves
  *   `collections.<name>.*`. Each storage is a dependency of the service. The expose rule applies
  *   to the collection procedures. Only `host.*` and `events.subscribe` are always on (CLI-47).
@@ -44,7 +45,7 @@ import {
 } from "@procedures/client";
 import type { ProcedureHandlerOptions, UpgradeHandlerOptions } from "@procedures/client/node";
 import { httpFace, wsFace, type HostFace, type HostFaceFactory } from "./faces.js";
-import { callOperations, faceHandler, operationOfCall } from "./tracking.js";
+import { callOperations, faceHandler, httpTracker, operationOfCall } from "./tracking.js";
 
 /** The knobs of a transport of the service, by the names of the ordering law. */
 export type HostKnobs = Parameters<ServiceBuilder["server"]>[1];
@@ -307,10 +308,15 @@ export function createProcedureHost(options: ProcedureHostOptions = {}): Procedu
     const factory = factoryOf(faceName, value);
     if (!factory) continue;
     const handler = faceHandler({ server, controller: name, face: faceName, life: () => life, keyed: keyedWindowMs !== undefined });
-    faces.set(faceName, factory({ name: faceName, handler, server, registry, policy, clock }));
+    // The tracking of the requests of the face that are not procedure calls, on the same route pattern (CLI-54)
+    const track = httpTracker({ controller: name, face: faceName, life: () => life });
+    faces.set(faceName, factory({ name: faceName, handler, server, registry, policy, clock, track }));
   }
 
-  // The listeners that the host owns, each one with the faces of its mount list
+  // The listeners that the host owns, each one with the faces of its mount list. The responses
+  // and the upgraded sockets of each listener go into one record, so the close of a face or of a
+  // listener first lets each answer go out (CLI-48).
+  const outgoing = outgoingAnswers();
   const listeners = options.listen ?? [];
   const onListener = new Set<string>();
   const endpoints: Array<() => HostEndpoint[]> = [];
@@ -324,11 +330,16 @@ export function createProcedureHost(options: ProcedureHostOptions = {}): Procedu
       onListener.add(faceName);
       if (face.handler) {
         const handle = face.handler;
-        transport.mount((req, res) => handle(req, res));
+        transport.mount((req, res) => {
+          const taken = handle(req, res);
+          if (taken) outgoing.response(res);
+          return taken;
+        });
       }
       if (face.upgrade) {
         const upgrade = face.upgrade;
         transport.upgrade(upgrade.match, (req, socket, head) => {
+          outgoing.socket(socket as Duplex);
           upgrade.handler(req, socket as Duplex, head as Buffer);
         });
       }
@@ -353,7 +364,11 @@ export function createProcedureHost(options: ProcedureHostOptions = {}): Procedu
       stopIntake: () => transport.stopIntake(),
       drain: (deadline, signal) => transport.drain(deadline, signal),
       inFlight: () => transport.inFlight(),
-      close: () => transport.close(),
+      // The close destroys each connection: first each answer that a face ended goes out (CLI-48)
+      close: async () => {
+        await outgoing.flushed();
+        await transport.close();
+      },
     };
     return { name: `${name}.listen.${listenerName}`, knobs: transport.knobs, impl };
   });
@@ -391,7 +406,22 @@ export function createProcedureHost(options: ProcedureHostOptions = {}): Procedu
       close: () => server.close(),
     },
   };
-  const faceParts: HostPart[] = [...faces.entries()].flatMap(([faceName, face]) => (face.parts ? [{ name: `${name}.${faceName}`, knobs: {}, impl: face.parts }] : []));
+  // The close of a face (the sessions of MCP, the connections of WebSocket) also lets each answer go out first (CLI-48)
+  const faceParts: HostPart[] = [...faces.entries()].flatMap(([faceName, face]) => {
+    const impl = face.parts;
+    if (!impl) return [];
+    const part: TransportImpl = {
+      start: (signal, lifecycle) => impl.start(signal, lifecycle),
+      stopIntake: () => impl.stopIntake(),
+      drain: (deadline, signal) => impl.drain(deadline, signal),
+      inFlight: () => impl.inFlight(),
+      close: async () => {
+        await outgoing.flushed();
+        await impl.close();
+      },
+    };
+    return [{ name: `${name}.${faceName}`, knobs: {}, impl: part }];
+  });
   const parts: HostPart[] = [serverPart, ...faceParts, ...listenerParts];
 
   const dependencies: HostDependency[] = server.storageHandles().map((handle) => ({
@@ -453,7 +483,64 @@ export function createProcedureHost(options: ProcedureHostOptions = {}): Procedu
   };
 }
 
+/** The answers that go out on the listeners of a host: each response of a face, and each upgraded socket. */
+interface OutgoingAnswers {
+  /** This method records a response of a face until its end. */
+  response(res: NodeResponse): void;
+  /** This method records an upgraded socket until its close. */
+  socket(socket: Duplex): void;
+  /**
+   * This method waits until each answer that a face wrote has gone out to the socket. It first gives
+   * one turn of the event loop, so each chain of promises that writes an answer ends (the MCP SDK).
+   * Then it waits for the event `finish` of each response that is ended, and for the write callback
+   * of each socket that has bytes to write. An open stream that is not ended does not hold it.
+   */
+  flushed(): Promise<void>;
+}
+
+/** An empty write: its callback comes after each write before it. */
+const FLUSH = Buffer.alloc(0);
+
+/** This function makes the record of the answers that go out on the listeners of a host (CLI-48). */
+function outgoingAnswers(): OutgoingAnswers {
+  const responses = new Set<NodeResponse>();
+  const sockets = new Set<Duplex>();
+  return {
+    response(res) {
+      if (responses.has(res)) return;
+      responses.add(res);
+      const done = (): void => {
+        responses.delete(res);
+      };
+      res.once("finish", done);
+      res.once("close", done);
+    },
+    socket(socket) {
+      sockets.add(socket);
+      socket.once("close", () => sockets.delete(socket));
+    },
+    async flushed() {
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      const waits: Array<Promise<void>> = [];
+      for (const res of responses) {
+        if (!res.writableEnded || res.writableFinished || res.destroyed) continue;
+        waits.push(
+          new Promise<void>((resolve) => {
+            res.once("finish", () => resolve());
+            res.once("close", () => resolve());
+          }),
+        );
+      }
+      for (const socket of sockets) {
+        if (socket.destroyed || !socket.writable || socket.writableLength === 0) continue;
+        waits.push(new Promise<void>((resolve) => socket.write(FLUSH, () => resolve())));
+      }
+      await Promise.all(waits);
+    },
+  };
+}
+
 export { httpFace, wsFace } from "./faces.js";
 export type { HostFace, HostFaceContext, HostFaceEndpoint, HostFaceFactory, HostFaceUpgrade } from "./faces.js";
-export { callOperations, faceHandler, operationOfCall } from "./tracking.js";
-export type { CallDetail, CallOperation, FaceHandler, FaceHandlerOptions } from "./tracking.js";
+export { callOperations, faceHandler, httpTracker, operationOfCall } from "./tracking.js";
+export type { CallDetail, CallOperation, FaceHandler, FaceHandlerOptions, HttpTracker, HttpTrackerOptions } from "./tracking.js";

package/src/host/tracking.ts

@@ -11,8 +11,11 @@
  *   repeatable procedure, a call with an idempotency key, or a call that runs one time.
  * - Each call is a stream (D4). A unary call is a stream of one. A stream call stays in flight
  *   until its last item, and a cut after the first item ends the stream in-band, with an error.
+ *   Each cut has the code `UNAVAILABLE`, before and after the first item. Its flag `retryable` tells
+ *   if a retry is safe (CLI-48).
  */
 
+import type { IncomingMessage, ServerResponse as NodeResponse } from "node:http";
 import type { Lifecycle, Operation, OperationOf, RequestEnd, RequestEvent, RouteRequest } from "@mark1russell7/service";
 import {
   IDEMPOTENCY_KEY_METADATA,
@@ -33,7 +36,8 @@ import {
  * The operation of a call, which gives its idempotency (D3):
  * - `repeatable`: the effects of the procedure permit a second run (no writes, or idempotent writes).
  * - `keyed`: the call has an idempotency key, and the server keeps its result for the window.
- * - `once`: each other call. A cut of it before its first item answers 500, because it can have had its effect.
+ * - `once`: each other call. A cut of it is `UNAVAILABLE` and not retryable, because it can have had its effect.
+ *   Before its first item, the HTTP face answers 500 for it.
  */
 export type CallOperation = "repeatable" | "keyed" | "once";
 
@@ -93,17 +97,20 @@ function messageOf(error: unknown): string {
 }
 
 /**
- * The response of an end before the first item. A refusal and a retryable cut are `UNAVAILABLE`
- * (503, with `Retry-After` from the transport). Another cut and a failure are `INTERNAL_ERROR` (500).
+ * The response of an end before the first item. A refusal and each cut are `UNAVAILABLE`, because
+ * the server stopped (CLI-48). The flag `retryable` tells if a retry is safe:
+ * - A refusal and a retryable cut are retryable. The HTTP face answers 503, with `Retry-After` from the transport.
+ * - A cut of a call that can have had its effect is not retryable. The HTTP face answers 500, as the runner does.
+ * A failure is `INTERNAL_ERROR` (500).
  */
 function endResponse(id: string, end: RequestEnd): ServerResponse {
   switch (end.kind) {
     case "refused":
       return failure(id, "UNAVAILABLE", `The host does not take the call now: ${end.cause}`, true);
     case "cut":
-      return end.status === 503
+      return end.retryable
         ? failure(id, "UNAVAILABLE", `The host stopped the call: ${end.cause}`, true)
-        : failure(id, "INTERNAL_ERROR", `The host stopped the call, and the call can have had its effect: ${end.cause}`, false);
+        : failure(id, "UNAVAILABLE", `The host stopped the call, and the call can have had its effect: ${end.cause}`, false);
     case "failed":
       return failure(id, "INTERNAL_ERROR", messageOf(end.error), false);
     case "done":
@@ -114,11 +121,15 @@ function endResponse(id: string, end: RequestEnd): ServerResponse {
 /**
  * The error of an end after the first item: the stream ends in-band, with an error line. The count
  * of the items of the stream goes in the message. The head of the response is not an item.
+ *
+ * The code is always `UNAVAILABLE`, because the server stopped the stream. A cut is not a failure
+ * of the server. The flag `retryable` tells if a retry is safe (CLI-48). Before, a cut that is not
+ * retryable had the code `INTERNAL_ERROR`, before and after the first item.
  */
 function inBandEnd(end: Extract<RequestEnd, { kind: "refused" | "cut" }>): Error {
   const delivered = Math.max(0, end.delivered - 1);
   return Object.assign(new Error(`The host stopped the stream after ${delivered} items: ${end.cause}`), {
-    code: end.retryable ? "UNAVAILABLE" : "INTERNAL_ERROR",
+    code: "UNAVAILABLE",
     retryable: end.retryable,
     delivered,
   });
@@ -215,3 +226,85 @@ export function faceHandler(options: FaceHandlerOptions): FaceHandler {
     },
   };
 }
+
+/**
+ * The request tracking of a face whose requests are not procedure calls, for example the auth
+ * routes of an app (CLI-54). The function does the work of one HTTP request through `life.request`,
+ * on the route `<face> <key>` of the controller of the host. Thus the request gets the readiness
+ * of the controller, the refusal after the stop of the intake, and the drain.
+ *
+ * - `serve` writes the response. The request stays in flight until the response closes.
+ * - The operation of the request gives its idempotency. The default: `repeatable` for `GET` and
+ *   `HEAD`, `once` for another method.
+ * - A refusal, a cut before the response starts and an error get a JSON error of wire v1:
+ *   `UNAVAILABLE` (503, retryable) or `INTERNAL_ERROR` (500).
+ * - Without a service, `serve` starts at once.
+ */
+export type HttpTracker = (
+  req: IncomingMessage,
+  res: NodeResponse,
+  key: string,
+  serve: (signal: AbortSignal) => Promise<void> | void,
+  operation?: CallOperation,
+) => Promise<void>;
+
+/** The options of `httpTracker()`. */
+export interface HttpTrackerOptions {
+  /** The controller of the calls in the declaration of the service. */
+  readonly controller: string;
+  /** The name of the face: the first part of the route of each request. */
+  readonly face: string;
+  /** This function gives the lifecycle of the service, or null. Without a lifecycle, each request starts directly. */
+  readonly life: () => Lifecycle | null;
+}
+
+/** This function writes the JSON error of an end of a request, when its response did not start. */
+function writeEnd(res: NodeResponse, end: RequestEnd): void {
+  if (end.kind === "done") return;
+  if (res.headersSent || res.writableEnded) {
+    // The response started: only a close of the connection tells the caller
+    if (!res.writableEnded) res.destroy();
+    return;
+  }
+  const { status } = endResponse("", end);
+  if (status.type !== "error") return;
+  res.statusCode = status.code === "UNAVAILABLE" ? 503 : 500;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ error: status.message, code: status.code, retryable: status.retryable }));
+}
+
+/** This function gives the request tracking of one face (CLI-54). */
+export function httpTracker(options: HttpTrackerOptions): HttpTracker {
+  return async (req, res, key, serve, operation) => {
+    // The work ends when the response closes: a handler can end before its body is out
+    const work = (signal: AbortSignal): Promise<true> =>
+      new Promise<true>((resolve, reject) => {
+        if (res.writableFinished || res.destroyed) {
+          resolve(true);
+          return;
+        }
+        res.once("close", () => resolve(true));
+        Promise.resolve()
+          .then(() => serve(signal))
+          .catch(reject);
+      });
+    const life = options.life();
+    if (!life) {
+      try {
+        await work(new AbortController().signal);
+      } catch (error) {
+        writeEnd(res, { kind: "failed", error, delivered: 0 });
+      }
+      return;
+    }
+    const method = (req.method ?? "GET").toUpperCase();
+    const detail: CallDetail = { face: options.face, key, operation: operation ?? (method === "GET" || method === "HEAD" ? "repeatable" : "once") };
+    let end: RequestEnd;
+    try {
+      end = (await life.request<true>(options.controller, `${options.face} ${key}`, work, { detail }).collect()).end;
+    } catch (error) {
+      end = { kind: "failed", error: new Error(`The service of the host has no route for this request: ${messageOf(error)}`), delivered: 0 };
+    }
+    writeEnd(res, end);
+  };
+}

package/src/index.ts

@@ -34,6 +34,7 @@ export {
   LOCAL_LISTENER_KNOBS,
   callOperations,
   faceHandler,
+  httpTracker,
   operationOfCall,
 } from "./host/index.js";
 export type {
@@ -61,6 +62,8 @@ export type {
   CallOperation,
   FaceHandler,
   FaceHandlerOptions,
+  HttpTracker,
+  HttpTrackerOptions,
 } from "./host/index.js";
 
 // Peer: a procedures host with a service of its own, for a process that has no service