@mark1russell7/service 0.0.0-stage → 0.2.0

package/build/index.d.ts

@@ -0,0 +1,168 @@
+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";
+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
+ * decisions of the research evaluator. The rules are data, and the caller gives them. Each rule
+ * is one or more linear inequalities over symbols at a hop (`readiness_detection_window@pod`),
+ * with a margin. A binding maps `symbol@hop` to seconds, or to "inf" for a timer that is absent.
+ */
+/** A term is a coefficient times one symbol, at a hop when it has one. */
+interface Term {
+  readonly knob: string;
+  readonly coef: number;
+  readonly at?: string | undefined;
+}
+/** A side is a sum of terms, plus a constant. */
+interface Side {
+  readonly terms: readonly Term[];
+  readonly const?: number | undefined;
+}
+/** An inequality compares two sides, with a margin. */
+interface Inequality {
+  readonly lhs: Side;
+  readonly op: "<" | "<=" | ">" | ">=";
+  readonly rhs: Side;
+  /** The margin is in seconds, or it is words for a margin that no binding gives ("a factor of several"). Words count as 0. */
+  readonly margin?: number | string | undefined;
+}
+/** A rule is one or more inequalities, with their statement in words. */
+interface Rule {
+  readonly id: string;
+  /** This text is the rule in words. */
+  readonly rule: string;
+  /** This text is the window that a violation opens. */
+  readonly window?: string | undefined;
+  readonly expr: Inequality;
+  readonly expr_more?: readonly Inequality[] | undefined;
+}
+/** A bound is in seconds, or it is "inf" for an absent timer, or "off" for a disabled feature. The last two have no limit. */
+type Bound = number | "inf" | "off";
+/**
+ * A binding maps `symbol@hop` to its bound. Its "margin" replaces the margin of each inequality.
+ * Its "margins" replace them one by one, in sequence, as the binding of a chain can.
+ */
+type Binding = Readonly<Record<string, Bound | readonly number[] | undefined>> & {
+  readonly margin?: number | undefined;
+  readonly margins?: readonly number[] | undefined;
+};
+/** A verdict is "holds", "violated", "unbounded" (it holds only because a timer is absent) or "depends" (nothing is bound). */
+type Verdict = "holds" | "violated" | "unbounded" | "depends";
+/** An evaluation is the value of each side of one inequality, its margin, and if it holds. */
+interface Evaluated {
+  readonly lhs: number | null;
+  readonly rhs: number | null;
+  readonly margin: number;
+  readonly holds: boolean | null;
+}
+/** This function gives the inequalities of a rule: its expr, then the others. */
+export declare const inequalities: (rule: Rule) => readonly Inequality[];
+/** This function gives the symbols that a rule reads, as `symbol@hop`. */
+export declare const symbolsOf: (rule: Rule) => string[];
+/**
+ * This function evaluates each inequality on one binding. "<" holds when lhs + margin < rhs, and
+ * ">" holds when lhs > rhs + margin. Only the inequalities with all their symbols bound apply.
+ * The others are null.
+ */
+export declare const evaluate: (rule: Rule, bind: Binding) => Evaluated[];
+/**
+ * This function gives the verdict of an evaluation. When an applicable inequality fails, the
+ * verdict is "violated". When all hold only because a timer is absent, the verdict is "unbounded",
+ * because nothing then limits the window. Otherwise the verdict is "holds". When no inequality
+ * applies, the arithmetic cannot decide, and the verdict is "depends".
+ */
+export declare const verdictOf: (rule: Rule, bind: Binding, evaluated: readonly Evaluated[]) => Verdict;
+//#endregion
+//#region src/lint.d.ts
+/**
+ * This module applies the ordering law to a declaration. The declaration binds the symbols of the
+ * service, from its primitives: the polls of its checks, the windows of its policies, its drain.
+ * The scenario binds the symbols of the platform (preStop, grace, the probes of the kubelet,
+ * propagation) and of each dependency (its failover time, the idle close of its server). Thus the
+ * service gives the inequalities, and the scenario gives the values. A rule about a client
+ * applies one time for each dependency.
+ */
+/** A scenario gives the values of the platform and of each dependency, by the `symbol@hop` of the law. */
+interface Scenario {
+  /** These are the values of the platform: prestop_sleep@pod, termination_grace@pod, probe_period@pod, propagation_bound@cluster. */
+  readonly platform: Readonly<Record<string, Extent>>;
+  /**
+   * These are the probe windows of the kubelet, period × failure threshold. They add to the
+   * windows of the declaration. A probe reads the cached verdict, thus detection is the latch,
+   * then the probe.
+   */
+  readonly probes: {
+    readonly readiness: Quantity;
+    readonly liveness: Quantity;
+  };
+  /** These are the values of each dependency, by its name: failover_time@dependency, server_idle_close@server. */
+  readonly dependencies?: Readonly<Record<string, Readonly<Record<string, Extent>>>> | undefined;
+}
+/** A finding is the verdict of one rule for one scope: the service, or the client of a dependency. */
+interface Finding {
+  readonly rule: string;
+  readonly scope: string;
+  readonly verdict: Verdict;
+  readonly statement: string;
+  readonly window?: string | undefined;
+  readonly evaluated: readonly Evaluated[];
+  /** These are the symbols that have no bound. A "depends" verdict waits for them. */
+  readonly unbound: readonly string[];
+}
+/** These are the identifiers of the rules that each declaration gets. */
+export declare const SERVICE_RULES: readonly string[];
+/** This function gives what the declaration tells about the service, as symbols of the law, and the source of each. */
+export declare const serviceBindings: (svc: ServiceDescription, scenario: Scenario) => {
+  readonly bind: Record<string, Bound>;
+  readonly from: Record<string, string>;
+};
+/** 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
+//#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