@mark1russell7/service 0.1.0 → 0.2.0

package/build/builder-BFxOuULH.d.ts

@@ -0,0 +1,607 @@
+import { Extent, Quantity } from "@mark1russell7/quantity";
+//#region src/timing.d.ts
+/**
+ * All policies have the same timing shape. A timing is a count of polls (a debounce) or a
+ * duration (a window), and each converts to the other. A long window is easier to read as a
+ * duration, and that is the only difference between the two.
+ */
+type Timing = {
+  readonly type: "debounce";
+  /** This interval is the time between two polls of the signal. */
+  readonly interval: Quantity;
+  /** This count is the number of failed polls in sequence before the policy fails. */
+  readonly failAfter: number;
+  /** This count is the number of passed polls in sequence before the policy recovers. */
+  readonly recoverAfter: number;
+} | {
+  readonly type: "window";
+  /** This duration is how long the signal fails before the policy fails, on the monotonic clock. */
+  readonly failAfter: Quantity;
+  /** This duration is how long the signal passes before the policy recovers. Without it, the first pass recovers the policy. */
+  readonly recoverAfter?: Quantity | undefined;
+};
+/** A poll has an interval, a jitter as a fraction (±20 % is 0.2) and a timeout. */
+interface Poll {
+  readonly interval: Quantity;
+  readonly jitter: number;
+  readonly timeout: Quantity;
+}
+/** A span is a range of times, from the earliest to the latest. */
+interface Span {
+  readonly min: Quantity;
+  readonly max: Quantity;
+}
+/**
+ * This type tells how a failed step answers a poll.
+ * - An `"error"` step refuses at once.
+ * - A `"timeout"` step (a black hole) answers only when the timeout of the poll ends. Each poll
+ *   makes a new call, and each call ends at its timeout. Thus the step is slower by that timeout,
+ *   at the two ends of the span.
+ * - A `"hang"` step makes a use that does not end. The first poll fails at its timeout. While the
+ *   use stays pending, the runtime does not start the check again, and each later poll fails at
+ *   once. Thus a debounce of two polls or more fails as fast as on an error.
+ */
+type FailsBy = "error" | "timeout" | "hang";
+/**
+ * This function gives the time that a policy takes to fail after its signal becomes bad. A
+ * debounce of N polls takes approximately N intervals, with the jitter. A window takes its
+ * duration, plus one interval at most for the poll that starts its sequence. A step that fails by
+ * a timeout adds the timeout of the poll. At 3 polls of 5 s ± 20 %, the latch fails in 8–18 s on
+ * an error, and in 12–22 s on a 4 s timeout. A step that hangs adds the timeout only where its
+ * first failure ends the sequence: a window, or a debounce of one poll.
+ */
+declare const failSpan: (timing: Timing, poll: Poll, by?: FailsBy) => Span;
+/** This function gives the time that a policy takes to recover after its signal becomes good. */
+declare const recoverSpan: (timing: Timing, poll: Poll) => Span;
+/** This function gives the window that a debounce approximates: N polls of an interval fail after N intervals. */
+declare const asWindow: (timing: Timing) => Timing;
+/** This function gives the debounce that approximates a window on a poll: the polls that fit, rounded up. */
+declare const asDebounce: (timing: Timing, poll: Poll) => Timing;
+//#endregion
+//#region src/operation.d.ts
+/**
+ * This type tells if an operation can go again after a failure. It is a property of the
+ * operation, not of the dependency. One Redis client sends a GET, which is safe to send again. It
+ * also sends an INCR, which counts two times when it goes again after a timeout. Each operation
+ * declares its idempotency:
+ * - `true`: a second issue has the same effect. Examples are an HTTP GET or PUT, a SELECT, a
+ *   Redis GET or SET, and a write that the server removes when it is a copy.
+ * - `false`: the client does not send it again after it can have reached the server.
+ * - keyed: the server keeps a key for a window, as with an `Idempotency-Key` header, and it
+ *   ignores a copy in that window. A copy after the window is a second operation. Thus the
+ *   window is a timer, and it must be longer than all retries of the operation.
+ */
+type Idempotency = boolean | {
+  readonly key: string;
+  readonly window: Extent;
+};
+/** An operation is an endpoint that the service calls or serves, a command, or a query. */
+interface Operation {
+  readonly idempotent: Idempotency;
+}
+/**
+ * This function tells if an operation can go again `since` its first issue. An idempotent
+ * operation can always go again, and other operations cannot. A keyed operation can go again
+ * while the server keeps its key.
+ */
+declare const mayReissue: (operation: Operation, since: Quantity) => boolean;
+//#endregion
+//#region src/description.d.ts
+/**
+ * This is the format of a service as data: what `describe()` exports, and nothing starts. The
+ * timer algebra and the ordering law read it. Each timer has a unit. Each knob comes from the
+ * declaration, because the runtime has no defaults. A bound that nobody gives is "no bound", not
+ * zero.
+ */
+declare const FORMAT = "mark1russell7.service/1";
+/** A step is a step of a connection that a check examines. A check that skips a step cannot see a failure in it. */
+type Step = "dial" | "local-state" | "round-trip" | "checkout" | "progress" | "topology" | "latency";
+/** A gate is the policy that the failures of a check count toward. */
+type Gate = "readiness" | "liveness";
+/** A check is an active check: one signal, for one step of a connection. */
+interface Check {
+  readonly name: string;
+  /** This name is the dependency that it examines, or null when it reads the state of the process. */
+  readonly dependency: string | null;
+  readonly step: Step;
+  /** This flag tells if it uses the connection of the application. A check on its own connection cannot see a failure of that connection. */
+  readonly ownConnection: boolean;
+  /** This gate is the policy that it controls, or null for a check that only reports. It has no default. */
+  readonly gates: Gate | null;
+  readonly poll: Poll;
+}
+/**
+ * A dependency is something that the service uses, with its client. Its knobs have the names that
+ * the ordering law uses: `request_timeout`, `connect_bound`, `driver_writeoff_time`,
+ * `heartbeat_interval`, `client_retry_window`. Thus the law reads them without a translation.
+ */
+interface Dependency {
+  readonly name: string;
+  /** This identifier is the component in the corpus (`systems.component.postgresql`), or null when the corpus does not have it. */
+  readonly system: string | null;
+  readonly knobs: Readonly<Record<string, Extent>>;
+  /**
+   * These are the operations that the service does with it, by name (`GET /v1/forecast`, `INCR`).
+   * Each operation declares if it can go again. A dependency usually has the two kinds, thus a
+   * dependency has no idempotency of its own. An operation without a declaration does not go again.
+   */
+  readonly operations: Readonly<Record<string, Operation>>;
+}
+/**
+ * A transport is something that takes work in: a server, a consumer or a worker. Each is a
+ * component with a state machine. The service is ready only while each transport takes work.
+ */
+interface Transport {
+  readonly name: string;
+  readonly kind: "server" | "consumer" | "worker";
+  /** These are its knobs, with the names of the law where the law has them: the `server_idle_close` of a server. */
+  readonly knobs: Readonly<Record<string, Extent>>;
+}
+/**
+ * A controller is a group of routes. It is ready only while the dependencies that it needs are
+ * ready. Each route declares if its callers can send it again. When the shutdown stops a request,
+ * an idempotent route answers 503, which a caller can retry. Other routes answer 500.
+ */
+interface Controller {
+  readonly name: string;
+  readonly requires: readonly string[];
+  readonly routes: Readonly<Record<string, Operation>>;
+}
+/** A coupling is a declared edge between two policies. The algebra checks its margin. */
+interface Coupling {
+  readonly from: Gate;
+  readonly to: Gate;
+  readonly effect: "fails";
+}
+/** A phase is one step of the shutdown sequence, with a cap. Its owner adds it. */
+interface Phase {
+  readonly name: string;
+  readonly cap: Quantity;
+}
+/** A service description is the whole graph of a service, as data. */
+interface ServiceDescription {
+  readonly format: typeof FORMAT;
+  readonly name: string;
+  /** This flag tells if a part joined after the start. That part starts tripped, and the export is partial. */
+  readonly partial: boolean;
+  readonly transports: readonly Transport[];
+  readonly dependencies: readonly Dependency[];
+  readonly controllers: readonly Controller[];
+  readonly checks: readonly Check[];
+  readonly policies: {
+    readonly readiness: Timing;
+    readonly liveness: Timing;
+    /** This duration is how long the service can take to start. The startup probe must agree with it. */
+    readonly startup: Quantity;
+  };
+  readonly couplings: readonly Coupling[];
+  readonly shutdown: {
+    readonly phases: readonly Phase[];
+    /** This window is how long before the end of the drain the cooperative abort occurs, or no bound. */
+    readonly cooperativeWindow: Extent;
+  };
+}
+//#endregion
+//#region src/clock.d.ts
+/** This function stops a timer that `Clock.after` started. A second use does nothing. */
+type Cancel = () => void;
+/**
+ * A clock gives the monotonic time in milliseconds, and it starts a function after a delay. The
+ * runtime reads time only through a clock. Thus a test can give a fake clock, and the timing of
+ * the runtime is then exact and repeatable.
+ */
+interface Clock {
+  /** This method gives the monotonic time, in milliseconds. A step of the wall clock does not move it. */
+  now(): number;
+  /** This method starts `run` after `ms` milliseconds, and gives the function that stops it. */
+  after(ms: number, run: () => void): Cancel;
+}
+/**
+ * This clock reads `performance.now()` and uses `setTimeout`. Its timers do not keep a Node
+ * process alive, thus a timer that is not stopped cannot stop the exit of the process.
+ */
+declare const realClock: Clock;
+//#endregion
+//#region src/events.d.ts
+/**
+ * A machine name names one machine of the runtime. Each machine has a document in `machines.ts`,
+ * which names the same states and events. The document of a client is with its client, for example
+ * `REDIS_CLIENT_MACHINE`.
+ */
+type MachineName = "gate" | "latch" | "window" | "poller" | "drain" | "exit" | "watchdog" | "client";
+/**
+ * A lifecycle event is one transition of one machine of the runtime, on the monotonic clock. The
+ * runtime stamps each planned event: the gate, each phase of the drain, and the exit. Thus a
+ * window that a measurement times starts at the event.
+ */
+interface LifecycleEvent {
+  /** This time is when the transition occurred, in milliseconds on the monotonic clock. */
+  readonly at: number;
+  readonly machine: MachineName;
+  /** This name identifies one machine among others of its kind: a check, or the service. */
+  readonly instance: string;
+  readonly from: string;
+  readonly to: string;
+  readonly on: string;
+  /** This text gives more about the event, for example the cause of a failure. */
+  readonly detail?: string | undefined;
+}
+/** A recorder receives each lifecycle event. */
+type Recorder = (event: LifecycleEvent) => void;
+//#endregion
+//#region src/latch.d.ts
+/**
+ * An outcome is the result of one poll of a check. Only `"ok"` passes. An `"indeterminate"`
+ * outcome measured nothing: it does not pass, and it does not fail.
+ */
+type Outcome = "ok" | "error" | "indeterminate";
+/** A result is one poll of a check, as the runtime records it. */
+interface Result {
+  readonly outcome: Outcome;
+  /** This time is when the result came, on the monotonic clock, in milliseconds. */
+  readonly at: number;
+  /** This time is how long the poll took, in milliseconds. */
+  readonly took: number;
+  /** This text tells why the poll did not pass, or it is null. */
+  readonly cause: string | null;
+  /** This flag tells if the poll failed at its timeout. */
+  readonly timedOut: boolean;
+  /** This flag tells if the check threw. A throw is an error with a flag. */
+  readonly thrown: boolean;
+  /** This flag tells if the force-fail list made the poll fail. */
+  readonly forced: boolean;
+}
+/**
+ * A trace receives each transition of a machine of the runtime: the state before, the state after,
+ * and the event. The machine documents of the lifecycle name the same states and events, thus a
+ * test can replay a trace against its document.
+ */
+type Trace = (from: string, to: string, on: string) => void;
+//#endregion
+//#region src/poller.d.ts
+/**
+ * A check function measures one step of a connection. It ends with nothing or `"ok"` for a pass,
+ * or with `"error"` or `"indeterminate"`. A throw is an error with a flag. The runtime aborts the
+ * signal at the timeout of the poll.
+ */
+type CheckFn = (signal: AbortSignal) => Outcome | void | Promise<Outcome | void>;
+//#endregion
+//#region src/health.d.ts
+/** These options start the runtime. Without them, it uses the real clock and `Math.random`. */
+interface StartOptions {
+  readonly clock?: Clock | undefined;
+  /** This function gives a number in [0, 1) for the jitter of each poll. */
+  readonly random?: (() => number) | undefined;
+  /** This list names the checks or dependencies whose polls fail at once (a seam for tests). */
+  readonly forceFail?: readonly string[] | undefined;
+  /** This function receives each transition of each machine of the runtime. */
+  readonly record?: Recorder | undefined;
+  /**
+   * This function can replace the function of a check, for example to add a delay to each call
+   * (a seam for tests: a degraded dependency). It gives the function to use.
+   */
+  readonly wrapCheck?: ((check: Check, run: CheckFn) => CheckFn) | undefined;
+}
+/** A check verdict is the cached state of one check, for the probes and the report. */
+interface CheckVerdict {
+  readonly gates: Gate | null;
+  readonly dependency: string | null;
+  /** This flag tells if the latch of the check is tripped, or it is null for a check that only reports. */
+  readonly tripped: boolean | null;
+  readonly streak: number;
+  /** This time is when the latch last changed, in milliseconds on the monotonic clock. */
+  readonly since: number | null;
+  readonly last: Result | null;
+}
+/** A verdict is the state of the service, from its cache. Nothing in it starts a check. */
+interface HealthVerdict {
+  /** This flag becomes true one time, after the warm-up sweep. */
+  readonly started: boolean;
+  readonly draining: boolean;
+  /** This flag tells if the service can take new work: started, not draining, and each readiness latch released. */
+  readonly ready: boolean;
+  /** This flag tells if each liveness latch is released. */
+  readonly alive: boolean;
+  /** These flags tell if each controller can take new work, from the dependencies that it needs. */
+  readonly controllers: Readonly<Record<string, boolean>>;
+  readonly dependencies: Readonly<Record<string, boolean>>;
+  readonly checks: Readonly<Record<string, CheckVerdict>>;
+  readonly startup: {
+    readonly budget: number;
+    readonly elapsed: number;
+    readonly overBudget: boolean;
+  };
+}
+/** A probe kind is the question that a probe asks: the startup, the readiness, the liveness, or the whole report. */
+type ProbeKind = "startup" | "readiness" | "liveness" | "report";
+/** A probe answer is a status and a body, for any HTTP framework or none. */
+interface ProbeAnswer {
+  readonly status: 200 | 503;
+  readonly contentType: "application/health+json";
+  readonly body: {
+    readonly status: "pass" | "fail";
+    readonly service: string;
+    readonly probe: ProbeKind;
+    readonly controller?: string | undefined;
+    readonly verdict?: HealthVerdict | undefined;
+  };
+}
+/** The health runtime of a started service. It reads its timing and its checks from the declaration. */
+interface Health {
+  verdict(): HealthVerdict;
+  /**
+   * This method answers a probe from the cache, in constant time, and it starts no check. A
+   * readiness probe with a controller asks about that controller. The report always answers 200.
+   */
+  probe(kind: ProbeKind, controller?: string): ProbeAnswer;
+  /** This method gives each change of the verdict to `listener`, and gives the function that stops it. */
+  subscribe(listener: (verdict: HealthVerdict) => void): () => void;
+  /** This method adds a name to the force-fail list, or removes it. */
+  forceFail(name: string, on: boolean): void;
+  /** This method fails readiness for good. The drain of the lifecycle starts with it. */
+  drain(): void;
+  /** This method stops each poller and each timer of the runtime. */
+  stop(): void;
+}
+//#endregion
+//#region src/process.d.ts
+/** An exit signal is a signal that asks the process to stop: each one starts the shutdown. */
+type ExitSignal = "SIGINT" | "SIGTERM" | "SIGQUIT";
+/** These are the signals that the runtime handles. */
+declare const EXIT_SIGNALS: readonly ExitSignal[];
+/**
+ * A process port is the part of the process that the runtime uses: its exit signals and its exit.
+ * The runtime owns the handlers, because Node as PID 1 without a handler ignores SIGTERM. Only the
+ * runtime ends the process, and library code does not. A test gives a fake port, sends signals,
+ * and reads the exit code.
+ */
+interface ProcessPort {
+  /** This method adds a handler for a signal, and gives the function that removes it. */
+  on(signal: ExitSignal, handler: () => void): () => void;
+  /** This method ends the process with a code: 0 after a clean shutdown, and 1 after an error. */
+  exit(code: number): void;
+}
+/** This port is the process of Node. */
+declare const nodeProcess: ProcessPort;
+//#endregion
+//#region src/requests.d.ts
+/**
+ * A request outcome is what a request of a controller came to, for any HTTP framework or none:
+ * - `done`: the work gave a value.
+ * - `failed`: the work failed for a cause of its own. The adapter answers it as it answers any
+ *   error of the route.
+ * - `refused`: the service did not admit the request. A refused request did not start, thus its
+ *   caller can send it again: 503, retryable.
+ * - `cut`: the shutdown stopped the request. A route whose callers can send it again answers 503,
+ *   retryable. Each other route answers 500, not retryable, because the work can have had its
+ *   effect.
+ */
+type RequestOutcome<T> = {
+  readonly kind: "done";
+  readonly value: T;
+} | {
+  readonly kind: "failed";
+  readonly error: unknown;
+} | {
+  readonly kind: "refused";
+  readonly status: 503;
+  readonly retryable: true;
+  readonly cause: string;
+} | {
+  readonly kind: "cut";
+  readonly status: 503 | 500;
+  readonly retryable: boolean;
+  readonly cause: string;
+};
+/** A request function does the work of one request. It receives a signal that the shutdown aborts. */
+type RequestFn<T> = (signal: AbortSignal) => Promise<T> | T;
+//#endregion
+//#region src/lifecycle.d.ts
+/**
+ * A transport is a source of work: a server, a consumer or a worker. Each has one contract. It
+ * starts, stops its intake, and drains to a deadline without a throw. It counts its work in flight,
+ * and it closes. A second close has no effect.
+ */
+interface TransportImpl {
+  start(signal: AbortSignal): Promise<void> | void;
+  stopIntake(): Promise<void> | void;
+  /**
+   * This method lets the work in flight end until `deadline` (milliseconds on the monotonic
+   * clock). The signal is the cooperative abort, which comes before the deadline.
+   */
+  drain(deadline: number, signal: AbortSignal): Promise<void> | void;
+  inFlight(): number;
+  close(): Promise<void> | void;
+}
+/** A dependency handle connects to a dependency at the start, and closes the connection at the end. */
+interface DependencyHandle {
+  connect(signal: AbortSignal): Promise<void> | void;
+  close(): Promise<void> | void;
+}
+/**
+ * A health server answers the probes, on its own port. It starts first, thus the probes answer
+ * while the dependencies connect, and it closes last.
+ */
+interface HealthServer {
+  listen(health: Health): Promise<void> | void;
+  close(): Promise<void> | void;
+}
+/** A phase context is what a phase gives its work: its deadline, its signal and the clock. */
+interface PhaseContext {
+  /** This time is the end of the cap of the phase, in milliseconds on the monotonic clock. */
+  readonly deadline: number;
+  /** This signal aborts at the end of the cap of the phase. */
+  readonly signal: AbortSignal;
+  readonly clock: Clock;
+}
+/** A phase work is a step of the shutdown that an owner adds to a phase. */
+type PhaseWork = (context: PhaseContext) => Promise<void> | void;
+/**
+ * These are the stages of the shutdown, in their sequence. A declared phase with one of these
+ * names gets the work of the runtime for its stage. A phase with another name gets only the work of
+ * its owners.
+ * - `fail readiness`: readiness fails at the start of the shutdown. This phase then holds for its
+ *   cap, while the endpoints of the platform remove the service.
+ * - `stop intake`: each transport stops its intake, and new requests get a retryable 503.
+ * - `drain`: the transports and the requests in flight end, until the cap. The cooperative abort
+ *   comes before the end of the cap, by the cooperative window.
+ * - `close transports`: each transport closes.
+ * - `stop the poller`: each check and watchdog stops. Then the signal of the service aborts.
+ * - `tear down dependencies`: each dependency closes, in the reverse sequence of its connection.
+ * - `close the health server`: the probes stop last.
+ */
+declare const STAGES: readonly ["fail readiness", "stop intake", "drain", "close transports", "stop the poller", "tear down dependencies", "close the health server"];
+type Stage = (typeof STAGES)[number];
+/** This function gives the place of a stage in the sequence, or -1 for a phase of another name. */
+declare const stageRank: (name: string) => number;
+/**
+ * This function gives the time of the cooperative abort, in milliseconds after the drain starts. It
+ * is the cap less the cooperative window, and not less than half the cap. A window without a bound
+ * gives half the cap.
+ */
+declare const cooperativeAbortAt: (cap: number, window: Extent) => number;
+/** These options run the lifecycle. Without them, it uses the real clock and the process of Node. */
+interface RunOptions extends StartOptions {
+  readonly process?: ProcessPort | undefined;
+}
+/** A lifecycle state tells where the service is in its life. */
+type LifecycleState = "starting" | "running" | "draining" | "exited";
+/** The lifecycle of a running service. */
+interface Lifecycle {
+  readonly health: Health;
+  readonly state: LifecycleState;
+  /** This code is the exit code, or null before the exit. */
+  readonly exitCode: number | null;
+  /** These texts are the errors that make the exit code 1. */
+  readonly errors: readonly string[];
+  /** This promise ends when the startup ends: the service runs, or its startup failed. */
+  readonly started: Promise<void>;
+  /** This promise gives the exit code when the shutdown ends. */
+  readonly done: Promise<number>;
+  /** This signal aborts after the poller stops: the background work of the service stops with it. */
+  readonly signal: AbortSignal;
+  /** This method asks for the shutdown, as an exit signal does. A second request has no effect. */
+  shutdown(cause?: string): Promise<number>;
+  /**
+   * This method does one request of a controller, on a route that the controller declares. The
+   * service refuses it while it cannot take new work, and the shutdown can cut it.
+   */
+  request<T>(controller: string, route: string, work: RequestFn<T>): Promise<RequestOutcome<T>>;
+  inFlight(controller?: string): number;
+  /**
+   * This method tells if a response can keep its connection open. It is false while the service is
+   * not ready, thus each response then closes its connection.
+   */
+  keepAlive(): boolean;
+}
+//#endregion
+//#region src/watchdog.d.ts
+/**
+ * A watchdog spec declares a watchdog of the event loop. The service declares it as a check whose
+ * function the watchdog gives: the process's own wedge, which a liveness window reads.
+ */
+interface WatchdogSpec {
+  readonly name: string;
+  /** This time is the interval of the tick of the watchdog. */
+  readonly tick: Quantity;
+  /** This time is the most that a tick can be late before the loop counts as blocked. */
+  readonly threshold: Quantity;
+  /** This gate is the policy that the check controls, or null for a check that only reports. */
+  readonly gates: Gate | null;
+  readonly poll: Poll;
+}
+/**
+ * A watchdog measures how late its own tick comes. A blocked event loop delays each timer, thus a
+ * tick that comes later than the threshold shows the block. Its states are `watching`, `blocked`
+ * and `stopped`.
+ */
+interface Watchdog {
+  /** This function is the check: it fails when a tick since the last poll came late, or the loop is still blocked. */
+  readonly check: () => Outcome;
+  /** This time is the most that a tick was late, in milliseconds, since the start. */
+  readonly worst: number;
+  readonly blocked: boolean;
+  stop(): void;
+}
+/** This function starts a watchdog on a clock. */
+declare const watchdog: (clock: Clock, spec: WatchdogSpec, trace?: Trace) => Watchdog;
+//#endregion
+//#region src/builder.d.ts
+/**
+ * A service is composed with plain method uses before it starts. The builder is imperative, and
+ * it holds static knowledge. The service does not use an `init` function that gives registrations.
+ *
+ *     const svc = service("app");
+ *     svc.dependency("weather", {
+ *       system: null,
+ *       knobs: { request_timeout },
+ *       operations: { "GET /v1/forecast": { idempotent: true } },
+ *     });
+ *     svc.controller("forecast").requires("weather").route("GET /api/forecast", { idempotent: true });
+ *     svc.check({ name: "weather.round-trip", dependency: "weather", … }, roundTrip);
+ *     svc.describe(); // the whole graph as data, with nothing started
+ *     const health = await svc.start();
+ *
+ * The graph has one source, thus its parts cannot disagree. A dependency or a check can join
+ * after the start. It starts tripped, and the export is partial. The runtime has no defaults of
+ * its own. Thus `describe()` refuses a service that does not declare a policy, its startup budget
+ * or its shutdown, and it tells which.
+ *
+ * `start()` starts only the health runtime. `run()` starts the whole lifecycle: the startup in its
+ * sequence, the exit signals, the capped phases of the shutdown, and the exit of the process.
+ */
+interface ControllerBuilder {
+  /** This method declares the dependencies that its routes need. The controller is ready only while they are ready. */
+  requires(...dependencies: string[]): ControllerBuilder;
+  /** This method declares a route that the controller serves, and if its callers can send it again. */
+  route(route: string, operation: Operation): ControllerBuilder;
+}
+/** A service builder composes a service, gives it as data, and starts it. */
+interface ServiceBuilder {
+  readonly name: string;
+  /** This method declares a dependency, and the handle that connects to it and closes it, if it has one. */
+  dependency(name: string, spec: Omit<Dependency, "name">, handle?: DependencyHandle): ServiceBuilder;
+  /** This method declares a server, and its implementation. `run()` needs the implementation. */
+  server(name: string, knobs: Readonly<Record<string, Extent>>, impl?: TransportImpl): ServiceBuilder;
+  consumer(name: string, knobs: Readonly<Record<string, Extent>>, impl?: TransportImpl): ServiceBuilder;
+  worker(name: string, knobs: Readonly<Record<string, Extent>>, impl?: TransportImpl): ServiceBuilder;
+  /** This method gives the server of the probes. It starts first and closes last. */
+  healthServer(server: HealthServer): ServiceBuilder;
+  /** This method adds work to a declared phase of the shutdown: the owner of the work registers it. */
+  onPhase(phase: string, work: PhaseWork): ServiceBuilder;
+  /** This method declares a watchdog of the event loop, as a check on the state of the process. */
+  watchdog(spec: WatchdogSpec): ServiceBuilder;
+  controller(name: string): ControllerBuilder;
+  /** This method declares a check, and the function that measures its step. `start()` needs the function. */
+  check(check: Check, run?: CheckFn): ServiceBuilder;
+  readiness(timing: Timing): ServiceBuilder;
+  liveness(timing: Timing): ServiceBuilder;
+  startup(budget: Quantity): ServiceBuilder;
+  couple(coupling: Coupling): ServiceBuilder;
+  phase(name: string, cap: Quantity): ServiceBuilder;
+  cooperativeWindow(window: Extent): ServiceBuilder;
+  /** This method gives the service as data, and it starts nothing. */
+  describe(): ServiceDescription;
+  /**
+   * This method closes the composition, starts the health runtime, and gives it after one warm-up
+   * sweep of each check. A part that joins after it starts tripped, and it makes the export
+   * partial. A second use gives the same runtime.
+   */
+  start(options?: StartOptions): Promise<Health>;
+  /**
+   * This method starts the whole lifecycle and gives it when its startup ends: the service operates,
+   * or its startup failed and it shuts down. It refuses a declaration that it cannot start: a transport
+   * without its implementation, or a stage with work and no declared phase.
+   */
+  run(options?: RunOptions): Promise<Lifecycle>;
+  /**
+   * This value is the health runtime from the time that `start()` begins, or null before. Thus the
+   * probes can answer during the warm-up sweep: the startup probe fails until the sweep ends.
+   */
+  readonly health: Health | null;
+}
+/** This function starts the composition of a service. */
+declare const service: (name: string) => ServiceBuilder;
+//#endregion
+export { FailsBy as $, StartOptions as A, Check as B, ProcessPort as C, HealthVerdict as D, Health as E, MachineName as F, Gate as G, Coupling as H, Recorder as I, Step as J, Phase as K, Cancel as L, Outcome as M, Result as N, ProbeAnswer as O, LifecycleEvent as P, mayReissue as Q, Clock as R, ExitSignal as S, CheckVerdict as T, Dependency as U, Controller as V, FORMAT as W, Idempotency as X, Transport as Y, Operation as Z, cooperativeAbortAt as _, WatchdogSpec as a, failSpan as at, RequestOutcome as b, HealthServer as c, PhaseContext as d, Poll as et, PhaseWork as f, TransportImpl as g, Stage as h, Watchdog as i, asWindow as it, CheckFn as j, ProbeKind as k, Lifecycle as l, STAGES as m, ServiceBuilder as n, Timing as nt, watchdog as o, recoverSpan as ot, RunOptions as p, ServiceDescription as q, service as r, asDebounce as rt, DependencyHandle as s, ControllerBuilder as t, Span as tt, LifecycleState as u, stageRank as v, nodeProcess as w, EXIT_SIGNALS as x, RequestFn as y, realClock as z };
+//# sourceMappingURL=builder-BFxOuULH.d.ts.map

package/build/clock-DlJFFZlX.js

@@ -0,0 +1,39 @@
+import { compare, convertible } from "@mark1russell7/quantity";
+//#region src/operation.ts
+/**
+* This function tells if an operation can go again `since` its first issue. An idempotent
+* operation can always go again, and other operations cannot. A keyed operation can go again
+* while the server keeps its key.
+*/
+const mayReissue = (operation, since) => {
+	const { idempotent } = operation;
+	if (typeof idempotent === "boolean") return idempotent;
+	return compare(since, idempotent.window) < 0;
+};
+/** This function gives the problems in the declaration of an operation that `describe()` refuses. */
+const operationProblems = (owner, name, operation) => {
+	const { idempotent } = operation;
+	if (typeof idempotent === "boolean") return [];
+	const problems = [];
+	if (idempotent.key.trim().length === 0) problems.push(`${owner}'s ${name} names no key`);
+	if (!convertible(idempotent.window.unit, "s")) problems.push(`${owner}'s ${name} holds its key for a span that is not a time`);
+	return problems;
+};
+//#endregion
+//#region src/clock.ts
+/**
+* This clock reads `performance.now()` and uses `setTimeout`. Its timers do not keep a Node
+* process alive, thus a timer that is not stopped cannot stop the exit of the process.
+*/
+const realClock = {
+	now: () => performance.now(),
+	after(ms, run) {
+		const timer = setTimeout(run, Math.max(0, ms));
+		timer.unref?.();
+		return () => clearTimeout(timer);
+	}
+};
+//#endregion
+export { mayReissue as n, operationProblems as r, realClock as t };
+
+//# sourceMappingURL=clock-DlJFFZlX.js.map

package/build/clock-DlJFFZlX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock-DlJFFZlX.js","names":[],"sources":["../src/operation.ts","../src/clock.ts"],"sourcesContent":["import type { Extent, Quantity } from \"@mark1russell7/quantity\";\nimport { compare, convertible } from \"@mark1russell7/quantity\";\n\n/**\n * This type tells if an operation can go again after a failure. It is a property of the\n * operation, not of the dependency. One Redis client sends a GET, which is safe to send again. It\n * also sends an INCR, which counts two times when it goes again after a timeout. Each operation\n * declares its idempotency:\n * - `true`: a second issue has the same effect. Examples are an HTTP GET or PUT, a SELECT, a\n *   Redis GET or SET, and a write that the server removes when it is a copy.\n * - `false`: the client does not send it again after it can have reached the server.\n * - keyed: the server keeps a key for a window, as with an `Idempotency-Key` header, and it\n *   ignores a copy in that window. A copy after the window is a second operation. Thus the\n *   window is a timer, and it must be longer than all retries of the operation.\n */\nexport type Idempotency = boolean | { readonly key: string; readonly window: Extent };\n\n/** An operation is an endpoint that the service calls or serves, a command, or a query. */\nexport interface Operation {\n  readonly idempotent: Idempotency;\n}\n\n/**\n * This function tells if an operation can go again `since` its first issue. An idempotent\n * operation can always go again, and other operations cannot. A keyed operation can go again\n * while the server keeps its key.\n */\nexport const mayReissue = (operation: Operation, since: Quantity): boolean => {\n  const { idempotent } = operation;\n  if (typeof idempotent === \"boolean\") return idempotent;\n  return compare(since, idempotent.window) < 0;\n};\n\n/** This function gives the problems in the declaration of an operation that `describe()` refuses. */\nexport const operationProblems = (owner: string, name: string, operation: Operation): string[] => {\n  const { idempotent } = operation;\n  if (typeof idempotent === \"boolean\") return [];\n  const problems: string[] = [];\n  if (idempotent.key.trim().length === 0) problems.push(`${owner}'s ${name} names no key`);\n  if (!convertible(idempotent.window.unit, \"s\"))\n    problems.push(`${owner}'s ${name} holds its key for a span that is not a time`);\n  return problems;\n};\n","/** This function stops a timer that `Clock.after` started. A second use does nothing. */\nexport type Cancel = () => void;\n\n/**\n * A clock gives the monotonic time in milliseconds, and it starts a function after a delay. The\n * runtime reads time only through a clock. Thus a test can give a fake clock, and the timing of\n * the runtime is then exact and repeatable.\n */\nexport interface Clock {\n  /** This method gives the monotonic time, in milliseconds. A step of the wall clock does not move it. */\n  now(): number;\n  /** This method starts `run` after `ms` milliseconds, and gives the function that stops it. */\n  after(ms: number, run: () => void): Cancel;\n}\n\n/**\n * This clock reads `performance.now()` and uses `setTimeout`. Its timers do not keep a Node\n * process alive, thus a timer that is not stopped cannot stop the exit of the process.\n */\nexport const realClock: Clock = {\n  now: () => performance.now(),\n  after(ms, run) {\n    const timer = setTimeout(run, Math.max(0, ms));\n    (timer as { unref?: () => void }).unref?.();\n    return () => clearTimeout(timer);\n  },\n};\n"],"mappings":";;;;;;;AA2BA,MAAa,cAAc,WAAsB,UAA6B;CAC5E,MAAM,EAAE,eAAe;CACvB,IAAI,OAAO,eAAe,WAAW,OAAO;CAC5C,OAAO,QAAQ,OAAO,WAAW,MAAM,IAAI;AAC7C;;AAGA,MAAa,qBAAqB,OAAe,MAAc,cAAmC;CAChG,MAAM,EAAE,eAAe;CACvB,IAAI,OAAO,eAAe,WAAW,OAAO,CAAC;CAC7C,MAAM,WAAqB,CAAC;CAC5B,IAAI,WAAW,IAAI,KAAK,CAAC,CAAC,WAAW,GAAG,SAAS,KAAK,GAAG,MAAM,KAAK,KAAK,cAAc;CACvF,IAAI,CAAC,YAAY,WAAW,OAAO,MAAM,GAAG,GAC1C,SAAS,KAAK,GAAG,MAAM,KAAK,KAAK,6CAA6C;CAChF,OAAO;AACT;;;;;;;ACvBA,MAAa,YAAmB;CAC9B,WAAW,YAAY,IAAI;CAC3B,MAAM,IAAI,KAAK;EACb,MAAM,QAAQ,WAAW,KAAK,KAAK,IAAI,GAAG,EAAE,CAAC;EAC7C,MAAkC,QAAQ;EAC1C,aAAa,aAAa,KAAK;CACjC;AACF"}