@mark1russell7/service 0.5.15 → 0.5.16

package/README.md

@@ -17,6 +17,7 @@ This release has the declaration, its export, the law, the health runtime, the l
 - **The linter.** `lint(description, scenario, rules)` applies the service rules (`SERVICE_RULES`) to a declaration. The declaration binds the symbols of the service: the polls of its checks, the windows of its policies, its drain. The scenario binds the symbols of the platform and of each dependency. A `depends` finding names the symbols that have no bound.
 - **The claims of a scenario.** A default is true only for a version: the keep-alive of Node is 5 s, but 65 s on main. Thus a value of the scenario can be a claim that names its epoch: `{ epoch: "node@22", value }`. Each finding then gives the epoch of each value that its rule reads (`epochs`).
 - **A measured value.** A claim can give a distribution by its statistics: `{ epoch, distribution: { p50, p99 } }`. The law binds the p99. A distribution without a p99 binds nothing, thus each rule that reads it depends.
+- **The four ways that a pod stops.** `STOPS` gives the steps of each way. A deletion and a liveness restart have the preStop hook and the drain. A crash and an OOM stop have neither. `lintStop(description, scenario, rules, way)` applies only the rules of the drain that guard that way: O04 for a deletion, O09 for a liveness restart. For a crash or an OOM stop, a finding of `STOP_RULE` depends on the time until the kubelet finds the exit.
 - **The scopes of a rule.** A rule about a client applies one time for each dependency. A rule about a consumer, for example O20, applies one time for each consumer and each worker.
 - **The loops of a progress check.** A check of the step `progress` can name the loops that mark it, with its stall time: `marks: { loops, stall }`. Each loop is a check or a worker of the service.
 - **The stall time.** `lint()` compares the stall time with the longest gap between two marks of the slowest loop (`PROGRESS_RULE`). A loop marks at the end of each turn, also a turn that fails. The gap of a check is `interval × (1 + jitter) + timeout`. The gap of a worker is its sleep or its longest backoff, the longer one, plus `unit_processing_time`. At 300 s ± 20 % and a timeout of 10 s, a poll gives 370 s.

package/build/index.d.ts

@@ -257,6 +257,52 @@ export declare const compressionOf: (svc: ServiceDescription, scenario: Scenario
  */
 export declare const lint: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[]) => Finding[];
 //#endregion
+//#region src/stops.d.ts
+/**
+ * This module keeps apart the four ways that a pod stops (B11). Each way runs a different part of
+ * the shutdown, thus a different set of the rules of the drain guards it.
+ */
+/** A way that a pod stops: a deletion, a liveness restart, a crash, or a stop for lack of memory (OOM). */
+type StopWay = "deletion" | "liveness-restart" | "crash" | "oom";
+/** What a way of stopping runs, and the rules of the drain that guard it. */
+interface Stop {
+  readonly way: StopWay;
+  /** This is the signal that the process gets first, or null when the process exits by itself. */
+  readonly signal: "SIGTERM" | "SIGKILL" | null;
+  /** This flag tells if the kubelet runs the preStop hook. */
+  readonly preStop: boolean;
+  /** This flag tells if the process runs its shutdown phases. */
+  readonly drain: boolean;
+  /**
+   * This is how the pod leaves its endpoints: by its deletion, when its readiness fails, or when
+   * the kubelet finds that the container exited.
+   */
+  readonly leaves: "deletion" | "readiness" | "exit";
+  /** These are the identifiers of the rules of the drain that guard this way. */
+  readonly rules: readonly string[];
+}
+/** These are the rules of the drain. Each way of stopping applies only its own rules of this set. */
+export declare const DRAIN_RULE_IDS: readonly string[];
+/**
+ * These are the four ways that a pod stops.
+ * - A deletion runs the preStop hook, then SIGTERM. The endpoints drop the pod at its deletion,
+ *   thus the preStop sleep and the hold must cover the propagation (O04).
+ * - A liveness restart also runs the preStop hook and SIGTERM, with the grace. The pod stays in its
+ *   endpoints until its readiness fails, thus readiness must fail first (O09).
+ * - A crash and an OOM stop run no hook and no drain. The kubelet finds the exit at its relist, and
+ *   no rule bounds that time. A client that can reissue a request is the only guard.
+ */
+export declare const STOPS: Readonly<Record<StopWay, Stop>>;
+/** The identifier of the finding of a way of stopping that runs no drain. */
+export declare const STOP_RULE = "stop";
+/**
+ * This function applies the rules to a declaration for one way of stopping. A rule of the drain
+ * applies only when it guards that way. The other rules apply as `lint()` applies them. A way with
+ * no drain also gets a finding of `STOP_RULE` that depends. No rule bounds the time until the
+ * kubelet finds the exit, and the work in flight is lost.
+ */
+export declare const lintStop: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[], way: StopWay) => Finding[];
+//#endregion
 //#region src/worker.d.ts
 /**
  * These are the knobs of a worker loop, by the names of the ordering law where the law has them.
@@ -386,5 +432,5 @@ 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>>;
 //#endregion
-export { type Allowed, type Backoff, type Binding, type Bound, type Cancel, type Change, type Check, type CheckFn, type CheckMetrics, type CheckVerdict, type Claim, type Clock, type Compressed, type Compression, type Controller, type ControllerBuilder, type CooperativeFloor, type Coupling, DURATION_FRACTIONS, type Decision, type DelayBand, type Dependency, type DependencyHandle, type DurationHistogram, EPISODES_KEPT, EXIT_SIGNALS, type EmbeddedProcess, type Episode, type Epochs, type Evaluated, type ExitCodes, type ExitSignal, type ExitTrigger, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthMetrics, type HealthServer, type HealthVerdict, type Heartbeat, type HeartbeatOptions, type HostStream, type Idempotency, type Inequality, type IterationContext, type Jitter, type JobAction, type JobContext, type JobFailure, type JobSettle, type JobSource, type KeyState, type KeyedLimiter, type Lifecycle, type LifecycleEvent, type LifecycleState, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterState, type LimiterStore, type LimiterStoreSpec, type MachineName, type MemoryStore, type MessageShape, type MessageTrigger, type Operation, type OperationOf, type Outcome, PROCESS_TRIGGERS, type Phase, type PhaseContext, type PhaseWork, type PlatformClockOptions, type PodTiming, type Poll, type ProbeAnswer, type ProbeKind, type ProcessHost, type ProcessPort, type ProcessTrigger, type Profile, type ProgressMarks, type QueueDrain, type QueueDrainOptions, type QueueKnobs, type Recorder, type RedeliveryPolicy, type RefusalCause, type Refused, type RepeatSignal, type RequestEnd, type RequestEvent, type RequestFn, type RequestOptions, type RequestStream, type RequestWork, type RequeueCause, type Result, type RoutePattern, type RouteRequest, type Rule, type RunOptions, SLIDING_WINDOW_MACHINE, STAGES, type Scenario, type ScenarioValue, type ScopedChange, type ServiceBuilder, type ServiceDescription, type ShutdownOptions, type Side, type SlidingWindow, type Span, type Stage, type StartOptions, type Statistic, type Step, type StoreFailure, TOKEN_BUCKET_MACHINE, type TakeRequest, type TakeStep, type Term, type TimerMark, type TimerMarks, type Timing, type TokenBucket, type Transport, type TransportImpl, type UnitRequest, type Verdict, type Watchdog, type WatchdogSpec, type WorkerKnobs, type WorkerLoop, type WorkerLoopOptions, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, cooperativeAbortAt, daemon, decide, detectionTime, embeddedProcess, ephemeral, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, localDev, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, stageRank, watchdog };
+export { type Allowed, type Backoff, type Binding, type Bound, type Cancel, type Change, type Check, type CheckFn, type CheckMetrics, type CheckVerdict, type Claim, type Clock, type Compressed, type Compression, type Controller, type ControllerBuilder, type CooperativeFloor, type Coupling, DURATION_FRACTIONS, type Decision, type DelayBand, type Dependency, type DependencyHandle, type DurationHistogram, EPISODES_KEPT, EXIT_SIGNALS, type EmbeddedProcess, type Episode, type Epochs, type Evaluated, type ExitCodes, type ExitSignal, type ExitTrigger, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthMetrics, type HealthServer, type HealthVerdict, type Heartbeat, type HeartbeatOptions, type HostStream, type Idempotency, type Inequality, type IterationContext, type Jitter, type JobAction, type JobContext, type JobFailure, type JobSettle, type JobSource, type KeyState, type KeyedLimiter, type Lifecycle, type LifecycleEvent, type LifecycleState, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterState, type LimiterStore, type LimiterStoreSpec, type MachineName, type MemoryStore, type MessageShape, type MessageTrigger, type Operation, type OperationOf, type Outcome, PROCESS_TRIGGERS, type Phase, type PhaseContext, type PhaseWork, type PlatformClockOptions, type PodTiming, type Poll, type ProbeAnswer, type ProbeKind, type ProcessHost, type ProcessPort, type ProcessTrigger, type Profile, type ProgressMarks, type QueueDrain, type QueueDrainOptions, type QueueKnobs, type Recorder, type RedeliveryPolicy, type RefusalCause, type Refused, type RepeatSignal, type RequestEnd, type RequestEvent, type RequestFn, type RequestOptions, type RequestStream, type RequestWork, type RequeueCause, type Result, type RoutePattern, type RouteRequest, type Rule, type RunOptions, SLIDING_WINDOW_MACHINE, STAGES, type Scenario, type ScenarioValue, type ScopedChange, type ServiceBuilder, type ServiceDescription, type ShutdownOptions, type Side, type SlidingWindow, type Span, type Stage, type StartOptions, type Statistic, type Step, type Stop, type StopWay, type StoreFailure, TOKEN_BUCKET_MACHINE, type TakeRequest, type TakeStep, type Term, type TimerMark, type TimerMarks, type Timing, type TokenBucket, type Transport, type TransportImpl, type UnitRequest, type Verdict, type Watchdog, type WatchdogSpec, type WorkerKnobs, type WorkerLoop, type WorkerLoopOptions, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, cooperativeAbortAt, daemon, decide, detectionTime, embeddedProcess, ephemeral, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, localDev, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, stageRank, watchdog };
 //# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -2858,6 +2858,89 @@ const lint = (svc, scenario, rules) => {
 	return findings;
 };
 //#endregion
+//#region src/stops.ts
+/** These are the rules of the drain. Each way of stopping applies only its own rules of this set. */
+const DRAIN_RULE_IDS = [
+	"O04",
+	"O09",
+	"O10",
+	"O16"
+];
+/**
+* These are the four ways that a pod stops.
+* - A deletion runs the preStop hook, then SIGTERM. The endpoints drop the pod at its deletion,
+*   thus the preStop sleep and the hold must cover the propagation (O04).
+* - A liveness restart also runs the preStop hook and SIGTERM, with the grace. The pod stays in its
+*   endpoints until its readiness fails, thus readiness must fail first (O09).
+* - A crash and an OOM stop run no hook and no drain. The kubelet finds the exit at its relist, and
+*   no rule bounds that time. A client that can reissue a request is the only guard.
+*/
+const STOPS = {
+	deletion: {
+		way: "deletion",
+		signal: "SIGTERM",
+		preStop: true,
+		drain: true,
+		leaves: "deletion",
+		rules: [
+			"O04",
+			"O10",
+			"O16"
+		]
+	},
+	"liveness-restart": {
+		way: "liveness-restart",
+		signal: "SIGTERM",
+		preStop: true,
+		drain: true,
+		leaves: "readiness",
+		rules: [
+			"O09",
+			"O10",
+			"O16"
+		]
+	},
+	crash: {
+		way: "crash",
+		signal: null,
+		preStop: false,
+		drain: false,
+		leaves: "exit",
+		rules: []
+	},
+	oom: {
+		way: "oom",
+		signal: "SIGKILL",
+		preStop: false,
+		drain: false,
+		leaves: "exit",
+		rules: []
+	}
+};
+/** The identifier of the finding of a way of stopping that runs no drain. */
+const STOP_RULE = "stop";
+/**
+* This function applies the rules to a declaration for one way of stopping. A rule of the drain
+* applies only when it guards that way. The other rules apply as `lint()` applies them. A way with
+* no drain also gets a finding of `STOP_RULE` that depends. No rule bounds the time until the
+* kubelet finds the exit, and the work in flight is lost.
+*/
+const lintStop = (svc, scenario, rules, way) => {
+	const stop = STOPS[way];
+	const applies = rules.filter((rule) => !DRAIN_RULE_IDS.includes(rule.id) || stop.rules.includes(rule.id));
+	const findings = lint(svc, scenario, applies);
+	if (stop.drain) return findings;
+	return [...findings, {
+		rule: STOP_RULE,
+		scope: svc.name,
+		verdict: "depends",
+		statement: `a ${way} runs no preStop hook and no drain, and no rule bounds the time until the kubelet finds the exit`,
+		window: "the work in flight is lost, and the endpoints keep the pod until the kubelet finds the exit",
+		evaluated: [],
+		unbound: ["exit_detection@pod"]
+	}];
+};
+//#endregion
 //#region src/profiles.ts
 const s = (value) => ({
 	value,
@@ -3844,6 +3927,6 @@ const MACHINES = {
 	watchdog: WATCHDOG_MACHINE
 };
 //#endregion
-export { DECLARATION_RULE, DURATION_FRACTIONS, EPISODES_KEPT, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, LAW_STATISTIC, LIMITER_RULES, MACHINES, PLATFORM_MARKS, POLLER_MACHINE, PROCESS_TRIGGERS, PROGRESS_RULE, SERVICE_RULES, SLIDING_WINDOW_MACHINE, STAGES, TOKEN_BUCKET_MACHINE, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, capKnob, compress, compression, compressionOf, cooperativeAbortAt, daemon, decide, detectionTime, drainMachine, embeddedProcess, ephemeral, evaluate, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, inequalities, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, lint, localDev, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog, workerLoop };
+export { DECLARATION_RULE, DRAIN_RULE_IDS, DURATION_FRACTIONS, EPISODES_KEPT, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, LAW_STATISTIC, LIMITER_RULES, MACHINES, PLATFORM_MARKS, POLLER_MACHINE, PROCESS_TRIGGERS, PROGRESS_RULE, SERVICE_RULES, SLIDING_WINDOW_MACHINE, STAGES, STOPS, STOP_RULE, TOKEN_BUCKET_MACHINE, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, capKnob, compress, compression, compressionOf, cooperativeAbortAt, daemon, decide, detectionTime, drainMachine, embeddedProcess, ephemeral, evaluate, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, inequalities, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, lint, lintStop, localDev, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog, workerLoop };
 
 //# sourceMappingURL=index.js.map