@procedures/server 0.41.0 → 0.42.0

package/src/host.ts

@@ -21,9 +21,10 @@
 
 import { daemon, localDev, service, type Lifecycle, type Profile, type RunOptions, type ServiceBuilder } from "@mark1russell7/service";
 import { probeServer, type ProbeKind } from "@mark1russell7/service/http";
-import { seconds, type Duration } from "@procedures/client";
+import { hostPolicy, realClock, seconds, type Duration, type HostPolicy, type Interceptor } from "@procedures/client";
 import { LOCAL_LISTENER_KNOBS, createProcedureHost, type ProcedureHost, type ProcedureHostOptions } from "@procedures/peer";
 import { lockfileHandle, type LockfileData } from "@procedures/peer/lockfile";
+import { idleInterceptor, idleTimer, idleTimes, type HostIdle } from "./idle.js";
 
 /** The mode of a run: in the foreground of a terminal, or as the background host of `mark`. */
 export type HostRunMode = "foreground" | "background";
@@ -90,6 +91,16 @@ export interface ProcedureHostRunConfig {
    * The return value has no effect.
    */
   readonly declare?: ((svc: ServiceBuilder, host: ProcedureHost) => void) | undefined;
+  /**
+   * The idle stop (CLI-27): the host stops by itself after this time with no call. Without it, the
+   * host stops only at a signal or a stop request, as before.
+   *
+   * - Each call resets the timer at its start and at its end. An open stream or subscription is a
+   *   call in flight, and the host does not stop while it is open.
+   * - The stop is `life.shutdown()` with the exit code 0. Thus the stop in stages of `run()` applies,
+   *   and the lockfile goes at the end.
+   */
+  readonly idle?: HostIdle | undefined;
 }
 
 /** A host that runs under `run()`: the host, the service of the process and its lifecycle. */
@@ -114,8 +125,25 @@ export async function runProcedureHost(config: ProcedureHostRunConfig): Promise<
   const clock = config.run?.clock;
   // A probe server of its own: the listeners of the host then answer no probes, unless the host options say so (D5)
   const dedicated = config.probes;
+  // The idle stop (CLI-27): an interceptor of the policy tells the timer about each call. The timer
+  // starts after the startup, and it asks the lifecycle for the stop.
+  let life: Lifecycle | undefined;
+  const idle = config.idle
+    ? idleTimer({
+        ...idleTimes(config.idle),
+        clock: clock ?? realClock,
+        inFlight: () => life?.inFlight() ?? 0,
+        stop: (cause) => {
+          if (life?.state !== "running") return;
+          config.log?.(`\nIdle: ${cause}.`);
+          void life.shutdown(cause, { code: 0 });
+        },
+      })
+    : undefined;
+  const policy = idle ? withInterceptor(config.host.policy ?? hostPolicy(), idleInterceptor(idle)) : config.host.policy;
   const host = createProcedureHost({
     ...config.host,
+    ...(policy ? { policy } : {}),
     ...(clock ? { clock } : {}),
     ...(dedicated && config.host.probes === undefined ? { probes: false } : {}),
   });
@@ -145,7 +173,12 @@ export async function runProcedureHost(config: ProcedureHostRunConfig): Promise<
   if (config.lockfile) svc.dependency("lockfile", { system: null, knobs: {}, operations: {} }, lockfileHandle(config.lockfile));
   const log = config.log;
   if (log && profile.phases?.some((phase) => phase.name === "stop intake")) svc.onPhase("stop intake", () => log("\nShutting down..."));
-  const life = await svc.run(config.run);
+  life = await svc.run(config.run);
+  if (idle) {
+    // The timer stops with the lifecycle, also after a stop for another cause
+    void life.done.then(() => idle.cancel());
+    if (life.state === "running") idle.start();
+  }
   const probeBase = (): string[] => {
     const address = probes?.server.address();
     if (typeof address !== "object" || address === null) return [];
@@ -155,3 +188,8 @@ export async function runProcedureHost(config: ProcedureHostRunConfig): Promise<
   };
   return { host, service: svc, life, probes: () => (probes ? probeBase() : host.info.probes()) };
 }
+
+/** This function gives a policy with one more interceptor, after the interceptors of the policy. */
+function withInterceptor(policy: HostPolicy, interceptor: Interceptor): HostPolicy {
+  return { ...policy, interceptors: [...policy.interceptors, interceptor] };
+}

package/src/idle.ts

@@ -0,0 +1,119 @@
+/**
+ * The idle stop of a procedures host (CLI-27).
+ *
+ * A host with the option `idle` of `runProcedureHost()` stops by itself after a time with no call.
+ * The background host that `mark` starts after a cold command uses it (`MARK_AUTO_WARM`).
+ *
+ * - `run()` of `@mark1russell7/service` has no idle trigger. The host uses the stop request of the
+ *   lifecycle, `life.shutdown()`, as an exit signal does. Thus the runner keeps the stop in stages
+ *   and the exit, and this file has no signal handler, no listener and no `process.exit`.
+ * - An interceptor of the host policy resets the timer at the start and at the end of each call.
+ * - When the timer fires and a call is in flight (`life.inFlight()`), the host does not stop. An
+ *   open stream or subscription is a call in flight until its last item (decision D4). The timer
+ *   then reads the count again at each poll, and the full time starts again after the last call ends.
+ * - The timer uses the clock of the run, so a test gives a fake clock.
+ */
+
+import { toMs, type Clock, type Duration, type Interceptor } from "@procedures/client";
+
+/** The default time between two reads of the calls in flight while a call is open: 5 s. */
+export const IDLE_POLL_MS = 5_000;
+
+/** The option `idle` of `runProcedureHost()`. */
+export interface HostIdle {
+  /** The time with no call, after which the host stops. */
+  readonly after: Duration;
+  /** The time between two reads of the calls in flight while a call is open. The default is 5 s, or `after` when it is shorter. */
+  readonly poll?: Duration | undefined;
+}
+
+/** The options of `idleTimer()`. */
+export interface IdleTimerOptions {
+  /** The time with no call, in milliseconds. */
+  readonly afterMs: number;
+  /** The time between two reads of the calls in flight while a call is open, in milliseconds. */
+  readonly pollMs: number;
+  readonly clock: Clock;
+  /** This function gives the count of the calls in flight. */
+  readonly inFlight: () => number;
+  /** This function stops the host. The timer calls it one time, with the cause of the stop. */
+  readonly stop: (cause: string) => void;
+}
+
+/** The timer of the idle stop. */
+export interface IdleTimer {
+  /** This method starts the timer. Before the start, `touch()` has no effect. */
+  start(): void;
+  /** This method tells the timer about a call: the full time starts again. */
+  touch(): void;
+  /** This method stops the timer for good. */
+  cancel(): void;
+}
+
+/** This function gives the timer of an idle stop. */
+export function idleTimer(options: IdleTimerOptions): IdleTimer {
+  const { afterMs, pollMs, clock } = options;
+  let started = false;
+  let ended = false;
+  // True when the last fire found a call in flight: the full time starts after that call ends
+  let open = false;
+  let cancelTimer: (() => void) | undefined;
+  const arm = (delay: number): void => {
+    cancelTimer?.();
+    cancelTimer = clock.after(delay, fire);
+  };
+  const fire = (): void => {
+    cancelTimer = undefined;
+    if (ended) return;
+    if (options.inFlight() > 0) {
+      open = true;
+      arm(pollMs);
+      return;
+    }
+    if (open) {
+      open = false;
+      arm(afterMs);
+      return;
+    }
+    ended = true;
+    options.stop(`the host had no call for ${afterMs} ms`);
+  };
+  return {
+    start() {
+      if (started || ended) return;
+      started = true;
+      arm(afterMs);
+    },
+    touch() {
+      if (!started || ended) return;
+      open = false;
+      arm(afterMs);
+    },
+    cancel() {
+      ended = true;
+      cancelTimer?.();
+      cancelTimer = undefined;
+    },
+  };
+}
+
+/** The timer of the option `idle` of a host, in milliseconds. */
+export function idleTimes(idle: HostIdle): { afterMs: number; pollMs: number } {
+  const afterMs = toMs(idle.after, "idle.after");
+  if (!Number.isFinite(afterMs) || afterMs <= 0) throw new RangeError(`idle.after must be more than 0 ms, got ${afterMs} ms`);
+  const pollMs = idle.poll === undefined ? Math.min(IDLE_POLL_MS, afterMs) : toMs(idle.poll, "idle.poll");
+  if (!Number.isFinite(pollMs) || pollMs <= 0) throw new RangeError(`idle.poll must be more than 0 ms, got ${pollMs} ms`);
+  return { afterMs, pollMs };
+}
+
+/** This function gives the interceptor that tells a timer about each call: at its start and at its end. */
+export function idleInterceptor(timer: Pick<IdleTimer, "touch">): Interceptor {
+  return async (_invocation, next) => {
+    timer.touch();
+    try {
+      return await next();
+    } finally {
+      timer.touch();
+    }
+  };
+}

package/src/index.ts

@@ -10,6 +10,8 @@ export { parseConfig, parseTopicPatterns } from "./config.js";
 export { runServer, startServer, loadProcedureModule, type RunningServer, type ServerRunOptions } from "./run.js";
 // The runner entry of the procedures host (CLI-8): the only entry that starts run()
 export { runProcedureHost, HOST_PROFILES, type ProcedureHostRunConfig, type RunningHost, type HostRunMode } from "./host.js";
+// The idle stop of a host (CLI-27): the option `idle` of runProcedureHost()
+export { IDLE_POLL_MS, type HostIdle } from "./idle.js";
 export type {
   ServerConfig,
   TransportConfig,
@@ -25,7 +27,7 @@ export type {
 // server.start, server.stop and server.status (from @procedures/peer). The root registers
 // nothing: import "@procedures/server/register", or give the module to createRegistry().
 export * from "./module.js";
-export { serverStartProcedure } from "./procedures/server.start.js";
+export { serverStartProcedure, spawnMarkServer, type MarkServerSpawn, type ServerSpawner, type SpawnedMarkServer } from "./procedures/server.start.js";
 export { serverStopProcedure } from "./procedures/server.stop.js";
 export { serverStatusProcedure } from "./procedures/server.status.js";
 export {

package/src/procedures/server.start.ts

@@ -9,7 +9,7 @@
  * peer package, because the peer of `mark --server` writes them.
  */
 
-import { spawn, type ChildProcess } from "node:child_process";
+import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
@@ -185,6 +185,116 @@ export function findCliPath(): string {
   return "mark";
 }
 
+/** The function that starts a process. The default is `spawn` of `node:child_process`. The tests give their own. */
+export type ServerSpawner = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+
+const defaultSpawner: ServerSpawner = (command, args, options) => spawn(command, [...args], options);
+
+/** The options of `spawnMarkServer()`. */
+export interface MarkServerSpawn {
+  readonly port: number;
+  /** The address of the listener. */
+  readonly host: string;
+  /** The transport. The default is `http`. */
+  readonly transport?: "http" | "websocket" | "both" | undefined;
+  /** The idle stop of the server, in milliseconds (`--idle-timeout`, CLI-27). Without it, the server has no idle stop. */
+  readonly idleTimeoutMs?: number | undefined;
+  /** The root of the `fs.*` procedures of the server (`--fs-root`). Without it, the server has no root. */
+  readonly fsRoot?: string | undefined;
+  /** The function that starts the process. The default is `spawn`. */
+  readonly spawner?: ServerSpawner | undefined;
+}
+
+/** The process of a server that `spawnMarkServer()` started, and the command line of the process. */
+export interface SpawnedMarkServer {
+  readonly child: ChildProcess;
+  readonly command: string;
+  readonly args: readonly string[];
+  /** The log file of the server: its standard output and its standard error. */
+  readonly logFile: string;
+}
+
+/**
+ * This function starts `mark --server` as a detached background process in the current folder,
+ * and gives the process at once. It does not wait for the readiness. `server.start` and the
+ * auto-warm of `mark` (CLI-27) use it.
+ *
+ * - The command line is the command that a user runs: `mark --server --port <port> --host <host>`.
+ * - The output goes to `~/.mark/server.log`. The old log moves to `server.log.1`.
+ * - The process is detached and unref'd, so the caller can exit at once.
+ * - An error of the spawn goes to the event `error` of the process, and it does not throw.
+ *
+ * This function does not use `runCommand()` or `shell.run`. They wait for the end of the process,
+ * and this process must outlive its caller. `SERVER-LAYERS.md` records the exception.
+ */
+export function spawnMarkServer(options: MarkServerSpawn): SpawnedMarkServer {
+  const transport = options.transport ?? "http";
+
+  // Rotate log file
+  rotateLog();
+
+  // Ensure directories exist
+  fs.mkdirSync(SERVERS_DIR, { recursive: true });
+
+  // Open log file for writing
+  const logFd = fs.openSync(LOG_PATH, "a");
+
+  // Find CLI path
+  const cliPath = findCliPath();
+
+  // Build arguments: the root is a global flag, before --server
+  const args = [
+    ...(options.fsRoot !== undefined ? ["--fs-root", options.fsRoot] : []),
+    "--server",
+    "--port",
+    String(options.port),
+    "--host",
+    options.host,
+  ];
+  if (transport !== "http") {
+    args.push("--transport", transport);
+  }
+  if (options.idleTimeoutMs !== undefined) {
+    args.push("--idle-timeout", String(options.idleTimeoutMs));
+  }
+
+  // Determine how to spawn
+  let spawnCmd: string;
+  let spawnArgs: string[];
+
+  if (cliPath === "mark" || cliPath.endsWith(".bin/mark") || cliPath.endsWith(".bin\\mark")) {
+    // Use mark command directly
+    spawnCmd = cliPath;
+    spawnArgs = args;
+  } else {
+    // Use node to run the JS file
+    spawnCmd = process.execPath;
+    spawnArgs = [cliPath, ...args];
+  }
+
+  // Spawn daemon process
+  let child: ChildProcess;
+  try {
+    child = (options.spawner ?? defaultSpawner)(spawnCmd, spawnArgs, {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: { ...process.env },
+      cwd: process.cwd(),
+      // No console window on Windows (deep dive CLI-16)
+      windowsHide: true,
+    });
+  } finally {
+    fs.closeSync(logFd);
+  }
+  // A spawn that fails, for example without `mark` in PATH, emits "error". Without a listener,
+  // the event ends the process of the caller.
+  child.once("error", () => undefined);
+
+  // Unref so parent can exit
+  child.unref();
+  return { child, command: spawnCmd, args: spawnArgs, logFile: LOG_PATH };
+}
+
 /**
  * The rule under a root of the files (roadmap R33, tracker item O36): a root refuses it. It starts
  * a mark server without the root, and it writes the log and the lock files in `~/.mark`.
@@ -227,55 +337,12 @@ export const serverStartProcedure: Procedure<
       };
     }
 
-    // Rotate log file
-    rotateLog();
-
-    // Ensure directories exist
-    fs.mkdirSync(SERVERS_DIR, { recursive: true });
-
-    // Open log file for writing
-    const logFd = fs.openSync(LOG_PATH, "a");
-
-    // Find CLI path
-    const cliPath = findCliPath();
-
-    // Build arguments
-    const args = ["--server", "--port", String(port), "--host", host];
-    if (transport !== "http") {
-      args.push("--transport", transport);
-    }
-
-    // Determine how to spawn
-    let spawnCmd: string;
-    let spawnArgs: string[];
-
-    if (cliPath === "mark" || cliPath.endsWith(".bin/mark") || cliPath.endsWith(".bin\\mark")) {
-      // Use mark command directly
-      spawnCmd = cliPath;
-      spawnArgs = args;
-    } else {
-      // Use node to run the JS file
-      spawnCmd = process.execPath;
-      spawnArgs = [cliPath, ...args];
-    }
-
-    // Spawn daemon process
-    const child = spawn(spawnCmd, spawnArgs, {
-      detached: true,
-      stdio: ["ignore", logFd, logFd],
-      env: { ...process.env },
-      cwd: process.cwd(),
-      // No console window on Windows (deep dive CLI-16)
-      windowsHide: true,
-    });
+    // The detached process of the server, with its log (CLI-27 shares this start with the auto-warm of mark)
+    const { child } = spawnMarkServer({ port, host, transport });
     // The end of the process stops the wait. The listener of "error" also catches a spawn that
     // fails, for example without `mark` in PATH.
     const end = endOf(child);
 
-    // Unref so parent can exit
-    child.unref();
-    fs.closeSync(logFd);
-
     // The wait for the readiness (CLI-9): the readiness probe, and host.info for the identity of the server
     const result = await waitForServer({ url: readinessUrl(host, port), port, before: existing?.peerId, end, timeoutMs });
     if ("ready" in result) {