@mark1russell7/service 0.5.20 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -19,10 +19,12 @@ This release has the declaration, its export, the law, the health runtime, the l
19
19
  - **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.
20
20
  - **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.
21
21
  - **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.
22
+ - **A name of its own.** Each part in a set of scopes has a name of its own. The sets are the dependencies and the server transports, the consumers and the workers, and the limiters. Two parts with one name in a set give a `violated` finding of `NAME_RULE` (`unique-names`), because their findings have one scope. Give one of the parts a different name.
23
+ - **The scope of a server.** A rule with a symbol at `@server`, for example O19, also applies one time for each server transport. The knobs of the transport bind at `@server`, for example `server_idle_close@server`. `scenario.transports[name]` gives the client side, for example `request_timeout@client`. Without it, the finding is `depends`. In the scope of a dependency, `@server` is the server of the dependency. Thus the knobs of a server of the service do not bind there.
22
24
  - **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.
23
25
  - **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.
24
26
  - **The marks of the timers.** A harness that runs a service k times faster scales its timers. Each timer has a mark: `scalable`, `fixed`, `stepped` (only multiples of a step) or `floored` (a peer sets a floor).
25
- - **The compression of a service.** `compressionOf(description, scenario, rules, k, marks)` gives each rule and scope whose verdict the compression changes. It also names the symbols that have no mark. `PLATFORM_MARKS` marks the timers of Kubernetes. For example, the propagation of the endpoints is `fixed`, thus a compression of the hold of O04 can break O04.
27
+ - **The compression of a service.** `compressionOf(description, scenario, rules, k, marks)` gives each rule and scope whose verdict the compression changes. It also names the symbols that have no mark. It reads the rules that `lint()` applies, with their bindings: the service rules and `BOUND_RULES`. `PLATFORM_MARKS` marks the timers of Kubernetes. For example, the propagation of the endpoints is `fixed`, thus a compression of the hold of O04 can break O04.
26
28
  - **A name that is not a loop.** A name that is not a check or a worker gets a `depends` finding. Without `marks`, a check gets no finding of this rule.
27
29
  - **Keyed limiters.** `svc.limiter(name, spec)` declares a rate limit for each key, as data. `keyedLimiter` makes its runtime on a store ([The keyed limiter](#the-keyed-limiter)).
28
30
  - **The hold.** The cap of the `fail readiness` phase binds `readiness_hold@process`, and a service without that phase holds for zero. The hold keeps the listener open after the signal, as a preStop sleep does. Thus O04 can compare the sum of the two with the propagation of the endpoints.
@@ -174,7 +176,8 @@ The requirements that the lifecycle follows are in [the requirements of S6](http
174
176
  - **The refusals.** While the service refuses its units, the loop and the taker wait their backoff, and each refused job goes back (`"unstarted"`). Thus a worker stops while a dependency of its controller is not ready.
175
177
  - **The clock.** The sleeps, the backoffs and the bounds use the clock of the options. Give the clock of the lifecycle. With the real clock, the timers do not keep a Node process alive (A14). The lifecycle holds the process until its exit, thus a process whose only parts are workers does not end while it waits.
176
178
  - **The law.** `lint()` applies O20 one time for each consumer and each worker. A knob of the transport binds at the hop `consumer`, and a knob with a hop in its name binds at that hop. The scenario gives the lease of each source, for example the visibility timeout of SQS.
177
- - **The problems.** `problems(description)` compares the bounds with the caps. `close_bound` fits in the cap of `close transports`. `unit_processing_time` fits in the cap of `drain`, or the drain can cut a unit.
179
+ - **The bounds.** `lint()` compares the bounds of each consumer and each worker with the caps of two phases (`BOUND_RULES`). `unit_processing_time` is less than the cap of `drain`, or the drain can cut a unit (`unit-bound`). `close_bound` is less than the cap of `close transports` (`close-bound`). A unit without a bound violates `unit-bound`.
180
+ - **The problems.** `problems(description)` gives each phase that the loop needs and that the declaration does not give: `drain` and `close transports`.
178
181
 
179
182
  ```ts
180
183
  import { kubernetes, lint, queueDrain, redeliverOnce, service, workerLoop } from "@mark1russell7/service";
@@ -223,6 +226,7 @@ app.controller("jobs").requires("db").route("RUN", { idempotent: true });
223
226
 
224
227
  // O20: the lease of the queue, 30 s, against a job of 10 s
225
228
  const scenario = { platform: {}, probes: { readiness: s(30), liveness: s(30) }, transports: { jobs: { "lease_duration@broker": s(30) } } };
229
+ // the findings also compare each bound with the cap of its phase (BOUND_RULES)
226
230
  const findings = lint(app.describe(), scenario, rules);
227
231
  const problems = [...heartbeat.problems(app.describe()), ...jobs.problems(app.describe())];
228
232
  const life = await app.run();
@@ -282,6 +286,22 @@ await life.shutdown("the command ended", { code: end.kind === "done" ? items[0]
282
286
  - **The output.** The stage `flush the output` waits for stdout and stderr. Thus the last lines of a command are not cut.
283
287
  - **The dependencies.** The phase `tear down dependencies` caps the close of the dependencies at 2 s.
284
288
 
289
+ ## The drain rules
290
+
291
+ The caller of `lint()` and `lintStop()` gives the rules. `@mark1russell7/service/rules` gives the rules of the drain as data: `O04`, `O09`, `O10`, `O16` and the list `DRAIN_RULES`. The entry loads no module at run time. Thus it loads no Testcontainers, no `node:` module and no zod, and a service can import it in its tests. The root of the package also gives each rule, and `@mark1russell7/kind` gives the same objects.
292
+
293
+ - **O04.** The preStop sleep plus the hold of `fail readiness` is at least the propagation of the endpoints.
294
+ - **O09.** Readiness detection plus the propagation is no longer than liveness detection plus the preStop sleep.
295
+ - **O10.** The preStop sleep plus the drain of the process fits in the grace period.
296
+ - **O16.** The cooperative window is shorter than the drain, and the drain is shorter than the grace less the preStop sleep.
297
+
298
+ ```ts
299
+ import { lint } from "@mark1russell7/service";
300
+ import { DRAIN_RULES } from "@mark1russell7/service/rules";
301
+
302
+ const findings = lint(svc.describe(), scenario, DRAIN_RULES);
303
+ ```
304
+
285
305
  ## The timers
286
306
 
287
307
  The clock, the heartbeat and the backoff have their own entries. Each entry imports no `node:` module, no zod and no other package. Thus a client in a browser can use them. Each entry is less than 1 kB of gzip. The root of the package also gives each function.
@@ -101,7 +101,7 @@ declare const watchdog: (clock: Clock, spec: WatchdogSpec, trace?: Trace) => Wat
101
101
  //#endregion
102
102
  //#region src/builder.d.ts
103
103
  /**
104
- * A service is composed with plain method uses before it starts. The builder is imperative, and
104
+ * The caller composes a service with plain method uses before it starts. The builder is imperative, and
105
105
  * it holds static knowledge. The service does not use an `init` function that gives registrations.
106
106
  *
107
107
  * const svc = service("app");
@@ -208,4 +208,4 @@ interface ServiceBuilder {
208
208
  declare const service: (name: string) => ServiceBuilder;
209
209
  //#endregion
210
210
  export { WatchdogSpec as a, Profile as c, kubernetes as d, localDev as f, Watchdog as i, daemon as l, ServiceBuilder as n, watchdog as o, service as r, PodTiming as s, ControllerBuilder as t, ephemeral as u };
211
- //# sourceMappingURL=builder-CfbN_nDW.d.ts.map
211
+ //# sourceMappingURL=builder-BNAkpeTT.d.ts.map
@@ -1,7 +1,7 @@
1
1
  import { t as Backoff } from "./backoff-B-jGWVDm.js";
2
2
  import { n as Clock } from "./clock-mVqhXD0b.js";
3
3
  import { E as CheckFn, Vt as Operation, X as Check, Y as Recorder, ct as ServiceDescription, et as Dependency, ft as Poll, lt as Step, rt as Gate, t as DependencyHandle } from "./lifecycle-CCDLvXLF.js";
4
- import { n as ServiceBuilder } from "./builder-CfbN_nDW.js";
4
+ import { n as ServiceBuilder } from "./builder-BNAkpeTT.js";
5
5
  import { Extent, Quantity } from "@mark1russell7/quantity";
6
6
  //#region src/client/meets.d.ts
7
7
  /** A situation is what the connection did when the failure started: a command in flight, or idle. */
@@ -230,4 +230,4 @@ declare const retryProblems: (name: string, knobs: RetryKnobs) => string[];
230
230
  declare const STARTING_POLL: Poll;
231
231
  //#endregion
232
232
  export { MANIFESTATIONS as C, firstDetector as D, Situation as E, unwatched as O, Detector as S, Meeting as T, Sent as _, ClientKnobs as a, retryProblems as b, ClientSpec as c, Factory as d, ReadyWait as f, SendOptions as g, STARTING_POLL as h, ClientJoin as i, ClientStep as l, RetrySchedule as m, CheckOptions as n, ClientOptions as o, RetryKnobs as p, Client as r, ClientSocket as s, Attempt as t, DialFn as u, readyWait as v, Manifestation as w, retrySchedule as x, retryBackoff as y };
233
- //# sourceMappingURL=core-C8HD1stw.d.ts.map
233
+ //# sourceMappingURL=core-CWsGgr9J.d.ts.map
@@ -1,4 +1,4 @@
1
- import "./core-C8HD1stw.js";
1
+ import "./core-CWsGgr9J.js";
2
2
  //#region src/client/dial.d.ts
3
3
  /**
4
4
  * A judge reads the bytes that the server sent so far. It gives null for a good answer, an error for
@@ -13,4 +13,4 @@ type Judge = (received: Buffer) => Error | null | "more";
13
13
  declare const statusLineJudge: (accept: (status: number, line: string) => Error | null) => Judge;
14
14
  //#endregion
15
15
  export { statusLineJudge as n, Judge as t };
16
- //# sourceMappingURL=dial-Bqx5jRXQ.d.ts.map
16
+ //# sourceMappingURL=dial-JEJavY0U.d.ts.map
package/build/grpc.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { Vt as Operation, ft as Poll } from "./lifecycle-CCDLvXLF.js";
2
- import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, b as retryProblems, c as ClientSpec, d as Factory, f as ReadyWait, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, p as RetryKnobs, r as Client, s as ClientSocket, t as Attempt, u as DialFn, v as readyWait, w as Manifestation } from "./core-C8HD1stw.js";
3
- import { t as Judge } from "./dial-Bqx5jRXQ.js";
2
+ import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, b as retryProblems, c as ClientSpec, d as Factory, f as ReadyWait, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, p as RetryKnobs, r as Client, s as ClientSocket, t as Attempt, u as DialFn, v as readyWait, w as Manifestation } from "./core-CWsGgr9J.js";
3
+ import { t as Judge } from "./dial-JEJavY0U.js";
4
4
  import { Extent, Quantity } from "@mark1russell7/quantity";
5
5
  import { Machine } from "@mark1russell7/algebra";
6
6
  //#region src/grpc/connection.d.ts
@@ -1,7 +1,7 @@
1
1
  import { n as Clock } from "./clock-mVqhXD0b.js";
2
2
  import { Vt as Operation, ft as Poll } from "./lifecycle-CCDLvXLF.js";
3
- import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, c as ClientSpec, d as Factory, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, r as Client, s as ClientSocket, t as Attempt, u as DialFn, w as Manifestation } from "./core-C8HD1stw.js";
4
- import { t as Judge } from "./dial-Bqx5jRXQ.js";
3
+ import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, c as ClientSpec, d as Factory, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, r as Client, s as ClientSocket, t as Attempt, u as DialFn, w as Manifestation } from "./core-CWsGgr9J.js";
4
+ import { t as Judge } from "./dial-JEJavY0U.js";
5
5
  import { Extent, Quantity } from "@mark1russell7/quantity";
6
6
  import { Machine } from "@mark1russell7/algebra";
7
7
  //#region src/http-client/connection.d.ts
package/build/index.d.ts CHANGED
@@ -2,138 +2,15 @@ import { a as backoffDelay, i as backoffBand, n as DelayBand, o as backoffProble
2
2
  import { a as realClock, i as platformClock, n as Clock, r as PlatformClockOptions, t as Cancel } from "./clock-mVqhXD0b.js";
3
3
  import { S as retryAfterSeconds, _ as freeAt, a as LimitRule, b as limiterProblems, c as LimiterSpec, d as Refused, f as SlidingWindow, g as decide, h as TokenBucket, i as LimitPolicy, l as LimiterStoreSpec, m as TakeStep, n as Decision, o as Limiter, p as StoreFailure, r as KeyState, s as LimiterEviction, t as Allowed, u as RefusalCause, v as idleSpan, x as longestRetryAfter, y as limitRule } from "./policy-G4QJ1ZZq.js";
4
4
  import { $ as Coupling, A as EPISODES_KEPT, At as ProcessHost, B as Logger, Bt as Idempotency, C as ProbeAnswer, Ct as EXIT_SIGNALS, D as CheckMetrics, Dt as HostStream, E as CheckFn, Et as ExitTrigger, F as ConsoleTarget, Ft as isExitSignal, G as Result, H as consoleLogger, Ht as mayReissue, I as LOG_LEVELS, It as isMessageShape, J as MachineName, L as LogEntry, Lt as matchesMessage, M as HealthMetrics, Mt as ProcessTrigger, N as redact, Nt as embeddedProcess, O as DURATION_FRACTIONS, Ot as MessageShape, P as ConsoleLoggerOptions, Pt as isExitCode, Q as CooperativeFloor, R as LogFields, Rt as nodeProcess, S as HealthVerdict, St as RouteRequest, T as StartOptions, Tt as ExitSignal, U as logEvents, V as atLeast, Vt as Operation, W as Outcome, X as Check, Y as Recorder, Z as Controller, _ as RequestOptions, _t as failSpan, a as PhaseContext, at as Phase, b as CheckVerdict, bt as OperationOf, c as STAGES, ct as ServiceDescription, d as TransportImpl, dt as FailsBy, et as Dependency, f as cooperativeAbortAt, ft as Poll, g as RequestFn, gt as asWindow, h as RequestEvent, ht as asDebounce, i as LifecycleState, it as MessageTrigger, j as Episode, jt as ProcessPort, k as DurationHistogram, kt as PROCESS_TRIGGERS, l as ShutdownOptions, lt as Step, m as RequestEnd, mt as Timing, n as HealthServer, nt as FORMAT, o as PhaseWork, ot as ProgressMarks, p as stageRank, pt as Span, q as LifecycleEvent, r as Lifecycle, rt as Gate, s as RunOptions, st as RepeatSignal, t as DependencyHandle, tt as ExitCodes, u as Stage, ut as Transport, v as RequestStream, vt as heartbeatDetection, w as ProbeKind, wt as EmbeddedProcess, x as Health, xt as RoutePattern, y as RequestWork, yt as recoverSpan, z as LogLevel, zt as processPortOf } from "./lifecycle-CCDLvXLF.js";
5
- import { a as WatchdogSpec, c as Profile, d as kubernetes, f as localDev, i as Watchdog, l as daemon, n as ServiceBuilder, o as watchdog, r as service, s as PodTiming, t as ControllerBuilder, u as ephemeral } from "./builder-CfbN_nDW.js";
5
+ import { a as WatchdogSpec, c as Profile, d as kubernetes, f as localDev, i as Watchdog, l as daemon, n as ServiceBuilder, o as watchdog, r as service, s as PodTiming, t as ControllerBuilder, u as ephemeral } from "./builder-BNAkpeTT.js";
6
6
  import { Heartbeat, HeartbeatOptions, detectionTime, heartbeat } from "./heartbeat.js";
7
+ import { C as symbolsOf, S as inequalities, _ as TimerMarks, a as O16, b as compression, c as Change, d as Evaluated, f as Inequality, g as TimerMark, h as Term, i as O10, l as Compressed, m as Side, n as O04, o as Binding, p as Rule, r as O09, s as Bound, t as DRAIN_RULES, u as Compression, v as Verdict, w as verdictOf, x as evaluate, y as compress } from "./rules-BBRopO1e.js";
7
8
  import { a as keyedLimiter, i as TakeRequest, n as LimiterStore, o as memoryStore, r as MemoryStore, t as KeyedLimiter } from "./store-D5HLgBnW.js";
8
9
  import { a as limiterStateOf, i as limiterMachine, n as SLIDING_WINDOW_MACHINE, r as TOKEN_BUCKET_MACHINE, t as LimiterState } from "./limiter-B0849Vhp.js";
9
- import { a as JobSource, c as QueueKnobs, d as queueDrain, f as redeliverOnce, i as JobSettle, l as RedeliveryPolicy, n as JobContext, o as QueueDrain, p as UnitRequest, r as JobFailure, s as QueueDrainOptions, t as JobAction, u as RequeueCause } from "./queue-CQcMTKYX.js";
10
+ import { a as JobSource, c as QueueKnobs, d as queueDrain, f as redeliverOnce, i as JobSettle, l as RedeliveryPolicy, n as JobContext, o as QueueDrain, p as UnitRequest, r as JobFailure, s as QueueDrainOptions, t as JobAction, u as RequeueCause } from "./queue-eLs5IruM.js";
10
11
  import { Extent, Quantity } from "@mark1russell7/quantity";
11
12
  import { replay } from "@mark1russell7/algebra/replay";
12
13
  import { Machine } from "@mark1russell7/algebra";
13
- //#region src/law.d.ts
14
- /**
15
- * This module is the evaluator of the timer-ordering law. Its decisions are the same as the
16
- * decisions of the research evaluator, except when absent timers leave no order (`evaluate`). The
17
- * rules are data, and the caller gives them. Each rule
18
- * is one or more linear inequalities over symbols at a hop (`readiness_detection_window@pod`),
19
- * with a margin. A binding maps `symbol@hop` to seconds, or to "inf" for a timer that is absent.
20
- */
21
- /** A term is a coefficient times one symbol, at a hop when it has one. */
22
- interface Term {
23
- readonly knob: string;
24
- readonly coef: number;
25
- readonly at?: string | undefined;
26
- }
27
- /** A side is a sum of terms, plus a constant. */
28
- interface Side {
29
- readonly terms: readonly Term[];
30
- readonly const?: number | undefined;
31
- }
32
- /** An inequality compares two sides, with a margin. */
33
- interface Inequality {
34
- readonly lhs: Side;
35
- readonly op: "<" | "<=" | ">" | ">=";
36
- readonly rhs: Side;
37
- /** The margin is in seconds, or it is words for a margin that no binding gives ("a factor of several"). Words count as 0. */
38
- readonly margin?: number | string | undefined;
39
- }
40
- /** A rule is one or more inequalities, with their statement in words. */
41
- interface Rule {
42
- readonly id: string;
43
- /** This text is the rule in words. */
44
- readonly rule: string;
45
- /** This text is the window that a violation opens. */
46
- readonly window?: string | undefined;
47
- readonly expr: Inequality;
48
- readonly expr_more?: readonly Inequality[] | undefined;
49
- }
50
- /** 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. */
51
- type Bound = number | "inf" | "off";
52
- /**
53
- * A binding maps `symbol@hop` to its bound. Its "margin" replaces the margin of each inequality.
54
- * Its "margins" replace them one by one, in sequence, as the binding of a chain can.
55
- */
56
- type Binding = Readonly<Record<string, Bound | readonly number[] | undefined>> & {
57
- readonly margin?: number | undefined;
58
- readonly margins?: readonly number[] | undefined;
59
- };
60
- /** A verdict is "holds", "violated", "unbounded" (it holds only because a timer is absent) or "depends" (nothing is bound). */
61
- type Verdict = "holds" | "violated" | "unbounded" | "depends";
62
- /** An evaluation is the value of each side of one inequality, its margin, and if it holds. */
63
- interface Evaluated {
64
- readonly lhs: number | null;
65
- readonly rhs: number | null;
66
- readonly margin: number;
67
- readonly holds: boolean | null;
68
- }
69
- /** This function gives the inequalities of a rule: its expr, then the others. */
70
- export declare const inequalities: (rule: Rule) => readonly Inequality[];
71
- /** This function gives the symbols that a rule reads, as `symbol@hop`. */
72
- export declare const symbolsOf: (rule: Rule) => string[];
73
- /**
74
- * This function evaluates each inequality on one binding. "<" holds when lhs + margin < rhs, and
75
- * ">" holds when lhs > rhs + margin. Only the inequalities with all their symbols bound apply.
76
- * The others are null. Absent timers can leave no order: the same infinity on each side, or both
77
- * signs of infinity on one side. Then the inequality holds only because a timer is absent.
78
- */
79
- export declare const evaluate: (rule: Rule, bind: Binding) => Evaluated[];
80
- /**
81
- * This function gives the verdict of an evaluation. When an applicable inequality fails, the
82
- * verdict is "violated". When all hold only because a timer is absent, the verdict is "unbounded",
83
- * because nothing then limits the window. Otherwise the verdict is "holds". When no inequality
84
- * applies, the arithmetic cannot decide, and the verdict is "depends".
85
- */
86
- export declare const verdictOf: (rule: Rule, bind: Binding, evaluated: readonly Evaluated[]) => Verdict;
87
- /**
88
- * A mark tells how a timer moves when a compression scales time by k (E10). A "scalable" timer
89
- * becomes k times its value. A "fixed" timer keeps its value. A "stepped" timer takes only
90
- * multiples of its step, thus it rounds up. A "floored" timer has a floor that a peer sets, for
91
- * example the minimum retransmission timeout of the kernel. The step and the floor are in seconds.
92
- */
93
- type TimerMark = {
94
- readonly kind: "scalable";
95
- } | {
96
- readonly kind: "fixed";
97
- } | {
98
- readonly kind: "stepped";
99
- readonly step: number;
100
- } | {
101
- readonly kind: "floored";
102
- readonly floor: number;
103
- readonly by: string;
104
- };
105
- /** The marks map `symbol@hop` to a mark. A bare symbol marks the symbol at each hop. */
106
- type TimerMarks = Readonly<Record<string, TimerMark | undefined>>;
107
- /** A compressed binding, and the symbols that have no mark. */
108
- interface Compressed {
109
- readonly bind: Binding;
110
- /** These symbols have no mark. They keep their values, thus the compression proves nothing about them. */
111
- readonly unmarked: readonly string[];
112
- }
113
- /** A change is a rule whose verdict a compression changes. */
114
- interface Change {
115
- readonly rule: string;
116
- readonly before: Verdict;
117
- readonly after: Verdict;
118
- }
119
- /** The result of a compression: the rules whose verdict it changes, and the symbols of the rules that have no mark. */
120
- interface Compression {
121
- readonly changed: readonly Change[];
122
- readonly unmarked: readonly string[];
123
- }
124
- /**
125
- * This function scales each timer of a binding by k, by its mark (E10). An absent timer ("inf" or
126
- * "off") stays absent. A chain scales each value. The margins of the binding and the constants of
127
- * the rules do not scale: they are tolerances, not timers. A symbol with no mark keeps its value.
128
- */
129
- export declare const compress: (bind: Binding, k: number, marks: TimerMarks) => Compressed;
130
- /**
131
- * This function tells which rules a compression by k changes. A compression keeps each ordering
132
- * when no verdict changes. A change in either direction counts: a violation that the compression
133
- * hides is as wrong as one that it makes. The unmarked symbols are the symbols that the rules read.
134
- */
135
- export declare const compression: (rules: readonly Rule[], bind: Binding, k: number, marks: TimerMarks) => Compression;
136
- //#endregion
137
14
  //#region src/lint.d.ts
138
15
  /**
139
16
  * This module applies the ordering law to a declaration. The declaration binds the symbols of the
@@ -142,8 +19,9 @@ export declare const compression: (rules: readonly Rule[], bind: Binding, k: num
142
19
  * propagation) and of each dependency (its failover time, the idle close of its server). Thus the
143
20
  * service gives the inequalities, and the scenario gives the values.
144
21
  *
145
- * A rule about a client applies one time for each dependency. A rule about a consumer applies one
146
- * time for each consumer and each worker. A rule about a limiter applies one time for each limiter.
22
+ * A rule about a client applies one time for each dependency. A rule about a server (`@server`)
23
+ * also applies one time for each server transport of the service. A rule about a consumer applies
24
+ * one time for each consumer and each worker. A rule about a limiter applies one time for each limiter.
147
25
  */
148
26
  /** A statistic of a measured distribution. The law binds p99 (`LAW_STATISTIC`). */
149
27
  type Statistic = "p50" | "p90" | "p99" | "p999" | "max";
@@ -181,7 +59,11 @@ interface Scenario {
181
59
  };
182
60
  /** These are the values of each dependency, by its name: failover_time@dependency, server_idle_close@server. */
183
61
  readonly dependencies?: Readonly<Record<string, Readonly<Record<string, ScenarioValue>>>> | undefined;
184
- /** These are the values of the source of each consumer and worker, by its name and by the `symbol@hop` of the law: lease_duration@broker. */
62
+ /**
63
+ * These are the values of each transport, by its name and by the `symbol@hop` of the law. For a
64
+ * consumer or a worker, they are the values of its source: lease_duration@broker. For a server,
65
+ * they are the values of its clients: request_timeout@client.
66
+ */
185
67
  readonly transports?: Readonly<Record<string, Readonly<Record<string, ScenarioValue>>>> | undefined;
186
68
  /**
187
69
  * These are the values of the callers of each limiter, by its name and by the `symbol@hop` of the
@@ -228,8 +110,28 @@ export declare const serviceBindings: (svc: ServiceDescription, scenario: Scenar
228
110
  };
229
111
  /** This identifier is the rule of the findings about a field that the declaration does not give. */
230
112
  export declare const DECLARATION_RULE = "declaration";
113
+ /** This identifier is the rule of the findings for two parts that have one name in the scopes of a rule. */
114
+ export declare const NAME_RULE = "unique-names";
231
115
  /** This identifier is the rule of the findings about the stall time of a progress check (`Check.marks`). */
232
116
  export declare const PROGRESS_RULE = "progress";
117
+ /** This identifier is the rule of the findings about the bound of a unit against the cap of the `drain` phase. */
118
+ export declare const UNIT_BOUND_RULE = "unit-bound";
119
+ /** This identifier is the rule of the findings about the close bound against the cap of the `close transports` phase. */
120
+ export declare const CLOSE_BOUND_RULE = "close-bound";
121
+ /**
122
+ * These are the rules of the bounds of a loop. Each one applies one time for each consumer and
123
+ * each worker (S6 A10, A11). `lint()` gives them, as it gives `PROGRESS_RULE`.
124
+ * - unit-bound: `unit_processing_time` is less than the cap of the `drain` phase. Otherwise the
125
+ * drain can cut a unit that ends in its bound. A unit without a bound violates the rule.
126
+ * - close-bound: `close_bound` is less than the cap of the `close transports` phase. Otherwise the
127
+ * phase can end before the loop closes.
128
+ *
129
+ * The corpus of the law (R3) does not have these rules, thus they have identifiers of the service,
130
+ * not O-numbers. The symbols `drain_phase_cap@process` and `close_phase_cap@process` are the caps of
131
+ * one phase. `process_drain_time@process` is the sum of the caps of all the phases. A phase that the
132
+ * declaration does not give binds no symbol, thus its finding is `depends`.
133
+ */
134
+ export declare const BOUND_RULES: readonly Rule[];
233
135
  /**
234
136
  * These are the marks of the timers of the platform (E10). Kubernetes takes the probe period, the
235
137
  * preStop sleep and the termination grace in whole seconds, thus each is stepped by 1 s. The
@@ -244,6 +146,7 @@ interface ScopedChange extends Change {
244
146
  * This function tells which findings of `lint` a compression by k changes (E10). It scales the
245
147
  * bindings of each scope by the marks. Thus a harness that runs the service k times faster learns
246
148
  * the orderings that its run breaks. The unmarked symbols are the symbols of the rules with no mark.
149
+ * It reads the rules that `lint` applies with their bindings: the service rules and `BOUND_RULES`.
247
150
  */
248
151
  export declare const compressionOf: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[], k: number, marks: TimerMarks) => {
249
152
  readonly changed: readonly ScopedChange[];
@@ -251,9 +154,11 @@ export declare const compressionOf: (svc: ServiceDescription, scenario: Scenario
251
154
  };
252
155
  /**
253
156
  * This function applies each service rule to a declaration and a scenario. A rule applies one time
254
- * for the service, for each client, for each consumer and worker, or for each limiter. The function
255
- * also gives a finding for each necessary field that the description does not give (`DECLARATION_RULE`).
256
- * Each progress check that names its loops also gets its findings (`PROGRESS_RULE`).
157
+ * for the service, for each client, for each consumer and worker, or for each limiter. It also
158
+ * gives a finding for each necessary field that the description does not give (`DECLARATION_RULE`).
159
+ * It gives a finding for each name that two parts share in the scopes of a rule (`NAME_RULE`). Each progress check
160
+ * that names its loops also gets its findings (`PROGRESS_RULE`). The findings of the bounds of each
161
+ * consumer and each worker come last (`BOUND_RULES`).
257
162
  */
258
163
  export declare const lint: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[]) => Finding[];
259
164
  //#endregion
@@ -281,7 +186,10 @@ interface Stop {
281
186
  /** These are the identifiers of the rules of the drain that guard this way. */
282
187
  readonly rules: readonly string[];
283
188
  }
284
- /** These are the rules of the drain. Each way of stopping applies only its own rules of this set. */
189
+ /**
190
+ * These are the identifiers of the rules of the drain, from the data of the entry `./rules`. Each
191
+ * way that a pod stops applies only its own rules of this set.
192
+ */
285
193
  export declare const DRAIN_RULE_IDS: readonly string[];
286
194
  /**
287
195
  * These are the four ways that a pod stops.
@@ -299,7 +207,8 @@ export declare const STOP_RULE = "stop";
299
207
  * This function applies the rules to a declaration for one way of stopping. A rule of the drain
300
208
  * applies only when it guards that way. The other rules apply as `lint()` applies them. A way with
301
209
  * no drain also gets a finding of `STOP_RULE` that depends. No rule bounds the time until the
302
- * kubelet finds the exit, and the work in flight is lost.
210
+ * kubelet finds the exit, and the work in flight is lost. Such a way starts no phase, thus it gets no
211
+ * finding of `BOUND_RULES`.
303
212
  */
304
213
  export declare const lintStop: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[], way: StopWay) => Finding[];
305
214
  //#endregion
@@ -377,7 +286,7 @@ interface WorkerLoop extends TransportImpl {
377
286
  * not end a backoff. It gives false after the intake stops.
378
287
  */
379
288
  wake(): boolean;
380
- /** This method gives the problems of the knobs in a declaration: the close bound and the bound of an iteration against the caps. */
289
+ /** This method gives the problems of a declaration: each phase that the loop needs and that it does not give. `lint()` compares the bounds with the caps. */
381
290
  problems(description: ServiceDescription): string[];
382
291
  }
383
292
  /**
@@ -432,5 +341,5 @@ export declare const drainMachine: (description: ServiceDescription) => Machine;
432
341
  /** These are the static machines of the runtime, by the name that their events carry. */
433
342
  export declare const MACHINES: Readonly<Record<Exclude<MachineName, "drain" | "client">, Machine>>;
434
343
  //#endregion
435
- 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 ConsoleLoggerOptions, type ConsoleTarget, 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, LOG_LEVELS, type Lifecycle, type LifecycleEvent, type LifecycleState, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterState, type LimiterStore, type LimiterStoreSpec, type LogEntry, type LogFields, type LogLevel, type Logger, 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, atLeast, backoffBand, backoffDelay, backoffProblems, consoleLogger, cooperativeAbortAt, daemon, decide, detectionTime, embeddedProcess, ephemeral, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, localDev, logEvents, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, stageRank, watchdog };
344
+ 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 ConsoleLoggerOptions, type ConsoleTarget, type Controller, type ControllerBuilder, type CooperativeFloor, type Coupling, DRAIN_RULES, 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, LOG_LEVELS, type Lifecycle, type LifecycleEvent, type LifecycleState, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterState, type LimiterStore, type LimiterStoreSpec, type LogEntry, type LogFields, type LogLevel, type Logger, type MachineName, type MemoryStore, type MessageShape, type MessageTrigger, O04, O09, O10, O16, 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, atLeast, backoffBand, backoffDelay, backoffProblems, compress, compression, consoleLogger, cooperativeAbortAt, daemon, decide, detectionTime, embeddedProcess, ephemeral, evaluate, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, inequalities, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, localDev, logEvents, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, stageRank, symbolsOf, verdictOf, watchdog };
436
345
  //# sourceMappingURL=index.d.ts.map