@mark1russell7/service 0.1.0 → 0.2.0

package/build/index.d.ts

@@ -1,231 +1,6 @@
+import { $ as FailsBy, A as StartOptions, B as Check, C as ProcessPort, D as HealthVerdict, E as Health, F as MachineName, G as Gate, H as Coupling, I as Recorder, J as Step, K as Phase, L as Cancel, M as Outcome, N as Result, O as ProbeAnswer, P as LifecycleEvent, Q as mayReissue, R as Clock, S as ExitSignal, T as CheckVerdict, U as Dependency, V as Controller, W as FORMAT, X as Idempotency, Y as Transport, Z as Operation, _ as cooperativeAbortAt, a as WatchdogSpec, at as failSpan, b as RequestOutcome, c as HealthServer, d as PhaseContext, et as Poll, f as PhaseWork, g as TransportImpl, h as Stage, i as Watchdog, it as asWindow, j as CheckFn, k as ProbeKind, l as Lifecycle, m as STAGES, n as ServiceBuilder, nt as Timing, o as watchdog, ot as recoverSpan, p as RunOptions, q as ServiceDescription, r as service, rt as asDebounce, s as DependencyHandle, t as ControllerBuilder, tt as Span, u as LifecycleState, v as stageRank, w as nodeProcess, x as EXIT_SIGNALS, y as RequestFn, z as realClock } from "./builder-BFxOuULH.js";
 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. Thus it is
- * slower by that timeout, at the two ends of the span.
- */
-type FailsBy = "error" | "timeout";
-/**
- * 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.
- */
-export 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. */
-export 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. */
-export declare const asWindow: (timing: Timing) => Timing;
-/** This function gives the debounce that approximates a window on a poll: the polls that fit, rounded up. */
-export 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.
- */
-export 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.
- */
-export 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/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", … });
- *     svc.describe(); // the whole graph as data, with nothing started
- *     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.
- */
-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;
-  dependency(name: string, spec: Omit<Dependency, "name">): ServiceBuilder;
-  server(name: string, knobs: Readonly<Record<string, Extent>>): ServiceBuilder;
-  consumer(name: string, knobs: Readonly<Record<string, Extent>>): ServiceBuilder;
-  worker(name: string, knobs: Readonly<Record<string, Extent>>): ServiceBuilder;
-  controller(name: string): ControllerBuilder;
-  check(check: Check): 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. A part that joins after it starts tripped, and it makes the export partial. */
-  start(): Promise<void>;
-}
-/** This function starts the composition of a service. */
-export declare const service: (name: string) => ServiceBuilder;
-//#endregion
+import { Machine } from "@mark1russell7/algebra";
 //#region src/law.d.ts
 /**
  * This module is the evaluator of the timer-ordering law. Its decisions are the same as the
@@ -345,5 +120,49 @@ export declare const serviceBindings: (svc: ServiceDescription, scenario: Scenar
 /** This function applies each service rule to a declaration and a scenario: one time for the service, and one time for each client. */
 export declare const lint: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[]) => Finding[];
 //#endregion
-export type { Binding, Bound, Check, Controller, ControllerBuilder, Coupling, Dependency, Evaluated, FailsBy, Finding, Gate, Idempotency, Inequality, Operation, Phase, Poll, Rule, Scenario, ServiceBuilder, ServiceDescription, Side, Span, Step, Term, Timing, Transport, Verdict };
+//#region src/machines.d.ts
+/**
+ * The startup gate opens one time. The lifecycle moves it from `closed` to `starting` while its
+ * components start. Then one warm-up sweep of each check opens it. A component that does not start
+ * fails it for good.
+ */
+export declare const GATE_MACHINE: Machine;
+/** A debounce latch counts the polls of its check in sequence. A readiness latch starts tripped. */
+export declare const LATCH_MACHINE: Machine;
+/**
+ * A window latch measures time on the monotonic clock from the first failure of a sequence, and
+ * from the first pass after a trip.
+ */
+export declare const WINDOW_MACHINE: Machine;
+/**
+ * A poller starts one check on a jittered loop with a fixed delay. A call that outlives its timeout
+ * stays pending (`hung`), and the poller does not start the check again until the call settles.
+ */
+export declare const POLLER_MACHINE: Machine;
+/**
+ * The exit manager is the only part that ends the process. The first exit request starts the
+ * shutdown, and a later one has no effect. An error makes the exit code 1.
+ */
+export declare const EXIT_MACHINE: Machine;
+/** A watchdog measures how late its own tick comes, and a late tick shows a blocked event loop. */
+export declare const WATCHDOG_MACHINE: Machine;
+/** This function gives the name of a knob for the cap of a phase: `drain` gives `drain_cap`. */
+export declare const capKnob: (phase: string) => string;
+/**
+ * This function gives the drain of a declaration as a machine. It has one state for each declared
+ * phase, in its sequence, and each state has a timer at its cap. The drain also has the cooperative abort: the
+ * cap of the drain less the cooperative window, and half that cap at the least.
+ */
+export declare const drainMachine: (description: ServiceDescription) => Machine;
+/** These are the static machines of the runtime, by the name that their events carry. */
+export declare const MACHINES: Readonly<Record<Exclude<MachineName, "drain" | "client">, Machine>>;
+/**
+ * This function replays the transitions of one machine of the runtime against its document. Each
+ * instance starts in the state that its first transition leaves. Each transition must leave the
+ * state where the replay is. The document must have a transition from that state, on that event,
+ * to that state. The function gives each disagreement.
+ */
+export declare const replay: (doc: Machine, events: readonly LifecycleEvent[]) => string[];
+//#endregion
+export { type Binding, type Bound, type Cancel, type Check, type CheckFn, type CheckVerdict, type Clock, type Controller, type ControllerBuilder, type Coupling, type Dependency, type DependencyHandle, EXIT_SIGNALS, type Evaluated, type ExitSignal, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthServer, type HealthVerdict, type Idempotency, type Inequality, type Lifecycle, type LifecycleEvent, type LifecycleState, type MachineName, type Operation, type Outcome, type Phase, type PhaseContext, type PhaseWork, type Poll, type ProbeAnswer, type ProbeKind, type ProcessPort, type Recorder, type RequestFn, type RequestOutcome, type Result, type Rule, type RunOptions, STAGES, type Scenario, type ServiceBuilder, type ServiceDescription, type Side, type Span, type Stage, type StartOptions, type Step, type Term, type Timing, type Transport, type TransportImpl, type Verdict, type Watchdog, type WatchdogSpec, asDebounce, asWindow, cooperativeAbortAt, failSpan, mayReissue, nodeProcess, realClock, recoverSpan, service, stageRank, watchdog };
 //# sourceMappingURL=index.d.ts.map