@procedures/server 0.17.2 → 0.17.4

package/src/host.ts

@@ -14,11 +14,14 @@
  *   removes it after the listeners close.
  * - The option `declare` gives the builder of the service to the app before `run()`. The app
  *   declares its own parts and dependencies with the vocabulary of the runner (CLI-62).
+ * - The probes of the service answer on each listener of the host under `/_probes`, or on a port
+ *   of their own with the option `probes` (CLI-9, decision D5). The service gives both.
  */
 
 import { daemon, localDev, service, type Lifecycle, type Profile, type RunOptions, type ServiceBuilder } from "@mark1russell7/service";
-import { seconds } from "@procedures/client";
-import { createProcedureHost, type ProcedureHost, type ProcedureHostOptions } from "@procedures/peer";
+import { probeServer, type ProbeKind } from "@mark1russell7/service/http";
+import { seconds, type Duration } from "@procedures/client";
+import { LOCAL_LISTENER_KNOBS, createProcedureHost, type ProcedureHost, type ProcedureHostOptions } from "@procedures/peer";
 import { lockfileHandle, type LockfileData } from "@procedures/peer/lockfile";
 
 /** The mode of a run: in the foreground of a terminal, or as the background host of `mark`. */
@@ -27,6 +30,28 @@ export type HostRunMode = "foreground" | "background";
 /** The profile of each mode, as data: `localDev` in the foreground, and `daemon` in the background. */
 export const HOST_PROFILES: Readonly<Record<HostRunMode, Profile>> = Object.freeze({ foreground: localDev, background: daemon });
 
+/**
+ * A probe server on a port of its own (CLI-9, decision D5): `probeServer()` of
+ * `@mark1russell7/service/http`. It starts first and closes last, thus its probes answer through
+ * the whole drain. By default, it also answers `/report`, with the whole verdict of the service.
+ * The option `kinds` leaves out a kind, for example the report on a port that is not private.
+ */
+export interface HostProbeServer {
+  /** The port of the probes. 0 gives a free port, and `RunningHost.probes()` gives the real one. */
+  readonly port: number;
+  /** The address. The default is `127.0.0.1`. */
+  readonly host?: string | undefined;
+  /** The path before each probe path. The default is none: the port has only the probes. */
+  readonly prefix?: string | undefined;
+  /** The `Retry-After` of each 503 of a probe. The default is the knob `server_retry_after` of `LOCAL_LISTENER_KNOBS`: 1 s. */
+  readonly retryAfter?: Duration | undefined;
+  /**
+   * The probe kinds that the port answers (SYS-30). The default is all four: `startup`, `readiness`,
+   * `liveness` and `report`. The port answers 404 for a kind that is not in the list.
+   */
+  readonly kinds?: readonly ProbeKind[] | undefined;
+}
+
 /** The configuration of `runProcedureHost()`. */
 export interface ProcedureHostRunConfig {
   /** The name of the service of the process. */
@@ -42,6 +67,12 @@ export interface ProcedureHostRunConfig {
   readonly log?: ((line: string) => void) | undefined;
   /** The options of `run()`: a process port and a clock, for a test. The host gets the same clock. */
   readonly run?: RunOptions | undefined;
+  /**
+   * The probe server of the process on a port of its own (CLI-9, decision D5). Without it, each
+   * listener of the host answers the probes under `/_probes` (the option `probes` of the host).
+   * With it, the listeners do not answer them, unless the option `probes` of the host is given.
+   */
+  readonly probes?: HostProbeServer | undefined;
   /**
    * This function declares the parts of the app on the service of the process, before `run()`
    * (CLI-62). It gets the builder of the service and the host.
@@ -66,6 +97,11 @@ export interface RunningHost {
   readonly service: ServiceBuilder;
   /** The lifecycle. Its state is `running` after a startup that ended, and `draining` or `exited` after a startup that failed. */
   readonly life: Lifecycle;
+  /**
+   * The base URL of each place that answers the probes (CLI-9): the probe server, or each listener
+   * of the host, for example `http://127.0.0.1:3000/_probes`. Add `/startup`, `/readiness` or `/liveness`.
+   */
+  probes(): string[];
 }
 
 /**
@@ -75,9 +111,25 @@ export interface RunningHost {
  */
 export async function runProcedureHost(config: ProcedureHostRunConfig): Promise<RunningHost> {
   const clock = config.run?.clock;
-  const host = createProcedureHost({ ...config.host, ...(clock ? { 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;
+  const host = createProcedureHost({
+    ...config.host,
+    ...(clock ? { clock } : {}),
+    ...(dedicated && config.host.probes === undefined ? { probes: false } : {}),
+  });
   const profile = config.profile ?? HOST_PROFILES[config.mode];
   const svc = service(config.name).profile(profile);
+  const probes = dedicated
+    ? probeServer({
+        port: dedicated.port,
+        host: dedicated.host ?? "127.0.0.1",
+        ...(dedicated.prefix !== undefined ? { prefix: dedicated.prefix } : {}),
+        ...(dedicated.kinds !== undefined ? { kinds: dedicated.kinds } : {}),
+        server_retry_after: dedicated.retryAfter ?? LOCAL_LISTENER_KNOBS.server_retry_after,
+      })
+    : undefined;
+  if (probes) svc.healthServer(probes);
   // The profiles of the computer of a developer leave the policies to the service. No check gates them.
   if (!profile.readiness) svc.readiness({ type: "debounce", interval: seconds(5), failAfter: 3, recoverAfter: 1 });
   if (!profile.liveness) svc.liveness({ type: "window", failAfter: seconds(45) });
@@ -93,5 +145,12 @@ export async function runProcedureHost(config: ProcedureHostRunConfig): Promise<
   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);
-  return { host, service: svc, life };
+  const probeBase = (): string[] => {
+    const address = probes?.server.address();
+    if (typeof address !== "object" || address === null) return [];
+    const bound = dedicated?.host ?? "127.0.0.1";
+    const shown = bound === "0.0.0.0" || bound === "::" ? "localhost" : bound;
+    return [`http://${shown}:${address.port}${dedicated?.prefix ?? ""}`];
+  };
+  return { host, service: svc, life, probes: () => (probes ? probeBase() : host.info.probes()) };
 }

package/src/procedures/server.start.ts

@@ -200,7 +200,8 @@ export const serverStartProcedure: Procedure<
       }
     }
 
-    // Timed out waiting for lockfile, but child may still be alive
+    // Timed out waiting for lockfile, but child may still be alive. Deprecated (CLI-9): from the
+    // next MINOR of the client group, this result is `success: false`, with the PID of the child.
     if (child.pid && isProcessAlive(child.pid)) {
       return {
         success: true,

package/src/run.ts

@@ -247,6 +247,11 @@ export async function startServer(
   };
 }
 
+/** The address of the probe server of `--probe-port`: the address of the first network transport, as `--host` gives it. */
+function probeHostOf(config: ServerConfig): string {
+  return config.transports.find((transport) => transport.type !== "local")?.host ?? "127.0.0.1";
+}
+
 /**
  * The `server` CLI: parse the options, start the server under `run()` of `@mark1russell7/service`,
  * and print where it listens. `mark serve` calls it with its own arguments. The runner owns the
@@ -262,11 +267,13 @@ export async function runServer(argv: string[], options: ServerRunOptions = {}):
   }
 
   const { registry, policy, token, generated, confined } = await prepareServer(config, console.log, options);
-  const { host, life } = await runProcedureHost({
+  const { host, life, probes } = await runProcedureHost({
     name: "procedure-server",
     mode: "foreground",
     host: peerHostOptions({ id: newPeerId(), transports: config.transports, registry, policy }, "procedures"),
     log: console.log,
+    // --probe-port: the probes answer on a port of their own, on the address of --host (CLI-9, D5)
+    ...(config.probePort !== undefined ? { probes: { port: config.probePort, host: probeHostOf(config) } } : {}),
     ...(options.run ? { run: options.run } : {}),
   });
   if (life.state !== "running") {
@@ -284,6 +291,9 @@ export async function runServer(argv: string[], options: ServerRunOptions = {}):
   for (const endpoint of host.info.endpoints()) {
     console.log(`  [${endpoint.type}] ${endpoint.address}`);
   }
+  for (const base of probes()) {
+    console.log(`  [probes] ${base}/startup, ${base}/readiness, ${base}/liveness (no token)`);
+  }
   if (token === undefined) {
     console.log("\nNo token: any program on this computer can call the server.");
   } else {

package/src/schemas.ts

@@ -43,7 +43,11 @@ export const serverStatusInputSchema: ZodLikeSchema<ServerStatusInput> = zodAdap
 );
 
 export const ServerStartOutputSchema: z.ZodType<ServerStartOutput> = z.looseObject({
-  success: z.boolean().describe("True when the server started"),
+  success: z
+    .boolean()
+    .describe(
+      "True when the server started. Deprecated (CLI-9): at the timeout, a server that still starts gives true. From the next MINOR, it gives false."
+    ),
   pid: z.number().optional().describe("The process id of the server"),
   port: z.number().optional().describe("The port of the server"),
   endpoint: z.string().optional().describe("The URL of the server"),

package/src/types.ts

@@ -30,6 +30,11 @@ export interface ServerConfig {
   events?: string[] | undefined;
   /** The root of the files (`--fs-root`): each procedure keeps its paths in it, or it is refused. Undefined: no root. */
   fsRoot?: string | undefined;
+  /**
+   * The port of the probe server (`--probe-port`, CLI-9). Undefined: each listener answers the probes
+   * under `/_probes`, and the server has no probe server.
+   */
+  probePort?: number | undefined;
 }
 
 export interface ServerCreateResult {
@@ -52,7 +57,14 @@ export interface ServerStartInput {
 }
 
 export interface ServerStartOutput {
-  /** Whether start succeeded */
+  /**
+   * True when the server started.
+   *
+   * @deprecated Only the value at the timeout is deprecated, not this field (CLI-9). At the
+   * timeout, a server that still starts gives `true` and the message "still loading". From the next
+   * MINOR of the client group, a start that is not ready at the timeout gives `success: false`, with
+   * the PID of the process that still starts. Read the readiness probe or `mark server status` for the state.
+   */
   success: boolean;
   /** Process ID of server */
   pid?: number | undefined;