@mark1russell7/service 0.5.20 → 0.6.0

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();
@@ -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,11 +2,11 @@ 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
7
  import { a as keyedLimiter, i as TakeRequest, n as LimiterStore, o as memoryStore, r as MemoryStore, t as KeyedLimiter } from "./store-D5HLgBnW.js";
8
8
  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";
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-eLs5IruM.js";
10
10
  import { Extent, Quantity } from "@mark1russell7/quantity";
11
11
  import { replay } from "@mark1russell7/algebra/replay";
12
12
  import { Machine } from "@mark1russell7/algebra";
@@ -142,8 +142,9 @@ export declare const compression: (rules: readonly Rule[], bind: Binding, k: num
142
142
  * propagation) and of each dependency (its failover time, the idle close of its server). Thus the
143
143
  * service gives the inequalities, and the scenario gives the values.
144
144
  *
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.
145
+ * A rule about a client applies one time for each dependency. A rule about a server (`@server`)
146
+ * also applies one time for each server transport of the service. A rule about a consumer applies
147
+ * one time for each consumer and each worker. A rule about a limiter applies one time for each limiter.
147
148
  */
148
149
  /** A statistic of a measured distribution. The law binds p99 (`LAW_STATISTIC`). */
149
150
  type Statistic = "p50" | "p90" | "p99" | "p999" | "max";
@@ -181,7 +182,11 @@ interface Scenario {
181
182
  };
182
183
  /** These are the values of each dependency, by its name: failover_time@dependency, server_idle_close@server. */
183
184
  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. */
185
+ /**
186
+ * These are the values of each transport, by its name and by the `symbol@hop` of the law. For a
187
+ * consumer or a worker, they are the values of its source: lease_duration@broker. For a server,
188
+ * they are the values of its clients: request_timeout@client.
189
+ */
185
190
  readonly transports?: Readonly<Record<string, Readonly<Record<string, ScenarioValue>>>> | undefined;
186
191
  /**
187
192
  * These are the values of the callers of each limiter, by its name and by the `symbol@hop` of the
@@ -228,8 +233,28 @@ export declare const serviceBindings: (svc: ServiceDescription, scenario: Scenar
228
233
  };
229
234
  /** This identifier is the rule of the findings about a field that the declaration does not give. */
230
235
  export declare const DECLARATION_RULE = "declaration";
236
+ /** This identifier is the rule of the findings for two parts that have one name in the scopes of a rule. */
237
+ export declare const NAME_RULE = "unique-names";
231
238
  /** This identifier is the rule of the findings about the stall time of a progress check (`Check.marks`). */
232
239
  export declare const PROGRESS_RULE = "progress";
240
+ /** This identifier is the rule of the findings about the bound of a unit against the cap of the `drain` phase. */
241
+ export declare const UNIT_BOUND_RULE = "unit-bound";
242
+ /** This identifier is the rule of the findings about the close bound against the cap of the `close transports` phase. */
243
+ export declare const CLOSE_BOUND_RULE = "close-bound";
244
+ /**
245
+ * These are the rules of the bounds of a loop. Each one applies one time for each consumer and
246
+ * each worker (S6 A10, A11). `lint()` gives them, as it gives `PROGRESS_RULE`.
247
+ * - unit-bound: `unit_processing_time` is less than the cap of the `drain` phase. Otherwise the
248
+ * drain can cut a unit that ends in its bound. A unit without a bound violates the rule.
249
+ * - close-bound: `close_bound` is less than the cap of the `close transports` phase. Otherwise the
250
+ * phase can end before the loop closes.
251
+ *
252
+ * The corpus of the law (R3) does not have these rules, thus they have identifiers of the service,
253
+ * not O-numbers. The symbols `drain_phase_cap@process` and `close_phase_cap@process` are the caps of
254
+ * one phase. `process_drain_time@process` is the sum of the caps of all the phases. A phase that the
255
+ * declaration does not give binds no symbol, thus its finding is `depends`.
256
+ */
257
+ export declare const BOUND_RULES: readonly Rule[];
233
258
  /**
234
259
  * These are the marks of the timers of the platform (E10). Kubernetes takes the probe period, the
235
260
  * preStop sleep and the termination grace in whole seconds, thus each is stepped by 1 s. The
@@ -244,6 +269,7 @@ interface ScopedChange extends Change {
244
269
  * This function tells which findings of `lint` a compression by k changes (E10). It scales the
245
270
  * bindings of each scope by the marks. Thus a harness that runs the service k times faster learns
246
271
  * the orderings that its run breaks. The unmarked symbols are the symbols of the rules with no mark.
272
+ * It reads the rules that `lint` applies with their bindings: the service rules and `BOUND_RULES`.
247
273
  */
248
274
  export declare const compressionOf: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[], k: number, marks: TimerMarks) => {
249
275
  readonly changed: readonly ScopedChange[];
@@ -251,9 +277,11 @@ export declare const compressionOf: (svc: ServiceDescription, scenario: Scenario
251
277
  };
252
278
  /**
253
279
  * 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`).
280
+ * for the service, for each client, for each consumer and worker, or for each limiter. It also
281
+ * gives a finding for each necessary field that the description does not give (`DECLARATION_RULE`).
282
+ * It gives a finding for each name that two parts share in the scopes of a rule (`NAME_RULE`). Each progress check
283
+ * that names its loops also gets its findings (`PROGRESS_RULE`). The findings of the bounds of each
284
+ * consumer and each worker come last (`BOUND_RULES`).
257
285
  */
258
286
  export declare const lint: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[]) => Finding[];
259
287
  //#endregion
@@ -299,7 +327,8 @@ export declare const STOP_RULE = "stop";
299
327
  * This function applies the rules to a declaration for one way of stopping. A rule of the drain
300
328
  * applies only when it guards that way. The other rules apply as `lint()` applies them. A way with
301
329
  * 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.
330
+ * kubelet finds the exit, and the work in flight is lost. Such a way starts no phase, thus it gets no
331
+ * finding of `BOUND_RULES`.
303
332
  */
304
333
  export declare const lintStop: (svc: ServiceDescription, scenario: Scenario, rules: readonly Rule[], way: StopWay) => Finding[];
305
334
  //#endregion
@@ -377,7 +406,7 @@ interface WorkerLoop extends TransportImpl {
377
406
  * not end a backoff. It gives false after the intake stops.
378
407
  */
379
408
  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. */
409
+ /** 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
410
  problems(description: ServiceDescription): string[];
382
411
  }
383
412
  /**
package/build/index.js CHANGED
@@ -1193,23 +1193,13 @@ const retryOf = (knobs, owner) => {
1193
1193
  return backoff;
1194
1194
  };
1195
1195
  /**
1196
- * This function gives the problems of the bounds of a loop in a declaration. The close bound fits
1197
- * in the cap of `close transports`. The bound of a unit fits in the cap of `drain`, or the drain can cut a unit (S6 A10).
1196
+ * This function gives the problems of a loop in a declaration: each phase that the loop needs and
1197
+ * that the declaration does not give. A loop closes in `close transports`, and it ends its units in
1198
+ * `drain`. `lint()` compares the bounds with the caps of the phases (`BOUND_RULES`, S6 A10).
1198
1199
  */
1199
- const boundProblems = (owner, closeBound, unitBound, description) => {
1200
- const capOf = (name) => {
1201
- const phase = description.shutdown.phases.find((each) => each.name === name);
1202
- return phase === void 0 ? void 0 : valueIn(phase.cap, "ms");
1203
- };
1204
- const found = [];
1205
- const close = capOf("close transports");
1206
- if (close === void 0) found.push(`${owner} needs the phase "close transports" to close`);
1207
- else if (closeBound >= close) found.push(`the close_bound of ${owner}, ${closeBound} ms, does not fit in the cap of "close transports", ${close} ms`);
1208
- const drain = capOf("drain");
1209
- if (drain === void 0) found.push(`${owner} needs the phase "drain" to end its units`);
1210
- else if (!Number.isFinite(unitBound)) found.push(`the unit_processing_time of ${owner} has no bound, thus the drain can cut a unit at its cap of ${drain} ms`);
1211
- else if (unitBound >= drain) found.push(`the unit_processing_time of ${owner}, ${unitBound} ms, does not fit in the cap of "drain", ${drain} ms`);
1212
- return found;
1200
+ const boundProblems = (owner, description) => {
1201
+ const has = (name) => description.shutdown.phases.some((each) => each.name === name);
1202
+ return [...has("close transports") ? [] : [`${owner} needs the phase "close transports" to close`], ...has("drain") ? [] : [`${owner} needs the phase "drain" to end its units`]];
1213
1203
  };
1214
1204
  //#endregion
1215
1205
  //#region src/requests.ts
@@ -2694,6 +2684,12 @@ const serviceBindings = (svc, scenario) => {
2694
2684
  set("cooperative_window@process", boundOf(svc.shutdown.cooperativeWindow), "the declared cooperative window");
2695
2685
  const hold = svc.shutdown.phases.find((phase) => phase.name === "fail readiness");
2696
2686
  set("readiness_hold@process", hold === void 0 ? 0 : secondsOf(hold.cap), hold === void 0 ? "no fail readiness phase: the intake stops at once after the signal" : "the cap of the fail readiness phase, which holds while the endpoints update");
2687
+ const capOf = (name) => {
2688
+ const phase = svc.shutdown.phases.find((each) => each.name === name);
2689
+ return phase === void 0 ? void 0 : secondsOf(phase.cap);
2690
+ };
2691
+ set("drain_phase_cap@process", capOf("drain"), "the cap of the drain phase alone");
2692
+ set("close_phase_cap@process", capOf("close transports"), "the cap of the close transports phase alone");
2697
2693
  bindScenario(scenario.platform, (symbol) => symbol, bind, epochs);
2698
2694
  for (const [symbol, epoch] of Object.entries(epochs)) if (bind[symbol] === void 0) delete from[symbol];
2699
2695
  else from[symbol] = epoch === null ? "the scenario" : `the scenario, for ${epoch}`;
@@ -2716,16 +2712,19 @@ const dependencyBindings = (dependency, scenario) => {
2716
2712
  };
2717
2713
  /**
2718
2714
  * These are the hops of the law at which the knobs of a transport bind, by its kind. A worker does
2719
- * its units as a consumer does, thus both bind at `consumer` (O20). A server binds at no hop yet.
2715
+ * its units as a consumer does, thus both bind at `consumer` (O20). A server binds at `server`, in a
2716
+ * scope of its own. In the scope of a dependency, `@server` is the server of that dependency. Thus
2717
+ * the knobs of a server of the service do not bind there, or O19 pairs the wrong two sides.
2720
2718
  */
2721
2719
  const TRANSPORT_HOPS = {
2722
- server: null,
2720
+ server: "server",
2723
2721
  consumer: "consumer",
2724
2722
  worker: "consumer"
2725
2723
  };
2726
2724
  /**
2727
2725
  * This function gives the time knobs of a transport at the hop of its kind, and the values of the
2728
- * scenario for its source. A knob with a hop in its name binds at that hop. A count binds no symbol.
2726
+ * scenario for the transport. These values are of the source of a consumer, or of the clients of a
2727
+ * server. A knob with a hop in its name binds at that hop. A count binds no symbol.
2729
2728
  */
2730
2729
  const transportBindings = (transport, hop, scenario) => {
2731
2730
  const bind = {};
@@ -2760,6 +2759,7 @@ const limiterBindings = (limiter, scenario) => {
2760
2759
  };
2761
2760
  };
2762
2761
  const SCOPED = /@(client|dependency|server)$/;
2762
+ const SERVER_SCOPED = /@server$/;
2763
2763
  const TRANSPORT_SCOPED = /@consumer$/;
2764
2764
  const LIMITER_SCOPED = /@(limiter|caller)$/;
2765
2765
  /** This identifier is the rule of the findings about a field that the declaration does not give. */
@@ -2778,6 +2778,29 @@ const declarationFindings = (svc) => svc.shutdown.onRepeatSignal === void 0 ? [{
2778
2778
  evaluated: [],
2779
2779
  unbound: ["shutdown.onRepeatSignal"]
2780
2780
  }] : [];
2781
+ /** This identifier is the rule of the findings for two parts that have one name in the scopes of a rule. */
2782
+ const NAME_RULE = "unique-names";
2783
+ /**
2784
+ * This function gives a finding for each name that two parts share in one set of scopes. A rule
2785
+ * about a client applies to each dependency and each server transport. A rule about a consumer
2786
+ * applies to each consumer and each worker, and a rule about a limiter to each limiter. Two parts
2787
+ * with one name in a set give findings with one scope, thus a reader cannot tell them apart.
2788
+ */
2789
+ const nameFindings = (svc) => {
2790
+ return [
2791
+ ["the dependencies and the server transports", [...svc.dependencies.map((each) => each.name), ...svc.transports.filter((each) => each.kind === "server").map((each) => each.name)]],
2792
+ ["the consumers and the workers", svc.transports.filter((each) => each.kind !== "server").map((each) => each.name)],
2793
+ ["the limiters", (svc.limiters ?? []).map((each) => each.name)]
2794
+ ].flatMap(([set, names]) => [...new Set(names.filter((name, index) => names.indexOf(name) !== index))].map((name) => ({
2795
+ rule: NAME_RULE,
2796
+ scope: name,
2797
+ verdict: "violated",
2798
+ statement: `each of ${set} has a name of its own`,
2799
+ window: `two parts have the name ${name}, thus their findings have one scope`,
2800
+ evaluated: [],
2801
+ unbound: []
2802
+ })));
2803
+ };
2781
2804
  /** This identifier is the rule of the findings about the stall time of a progress check (`Check.marks`). */
2782
2805
  const PROGRESS_RULE = "progress";
2783
2806
  /**
@@ -2907,7 +2930,65 @@ const progressFindings = (svc) => {
2907
2930
  }
2908
2931
  return findings;
2909
2932
  };
2910
- /** This function gives the scopes of a rule that reads these symbols: the service, each client, each consumer and worker, or each limiter. */
2933
+ /** This identifier is the rule of the findings about the bound of a unit against the cap of the `drain` phase. */
2934
+ const UNIT_BOUND_RULE = "unit-bound";
2935
+ /** This identifier is the rule of the findings about the close bound against the cap of the `close transports` phase. */
2936
+ const CLOSE_BOUND_RULE = "close-bound";
2937
+ /**
2938
+ * These are the rules of the bounds of a loop. Each one applies one time for each consumer and
2939
+ * each worker (S6 A10, A11). `lint()` gives them, as it gives `PROGRESS_RULE`.
2940
+ * - unit-bound: `unit_processing_time` is less than the cap of the `drain` phase. Otherwise the
2941
+ * drain can cut a unit that ends in its bound. A unit without a bound violates the rule.
2942
+ * - close-bound: `close_bound` is less than the cap of the `close transports` phase. Otherwise the
2943
+ * phase can end before the loop closes.
2944
+ *
2945
+ * The corpus of the law (R3) does not have these rules, thus they have identifiers of the service,
2946
+ * not O-numbers. The symbols `drain_phase_cap@process` and `close_phase_cap@process` are the caps of
2947
+ * one phase. `process_drain_time@process` is the sum of the caps of all the phases. A phase that the
2948
+ * declaration does not give binds no symbol, thus its finding is `depends`.
2949
+ */
2950
+ const BOUND_RULES = [{
2951
+ id: UNIT_BOUND_RULE,
2952
+ rule: "the bound of one unit of a consumer or a worker is less than the cap of the drain phase",
2953
+ window: "the drain can cut a unit that ends in its bound",
2954
+ expr: {
2955
+ lhs: { terms: [{
2956
+ knob: "unit_processing_time",
2957
+ coef: 1,
2958
+ at: "consumer"
2959
+ }] },
2960
+ op: "<",
2961
+ rhs: { terms: [{
2962
+ knob: "drain_phase_cap",
2963
+ coef: 1,
2964
+ at: "process"
2965
+ }] },
2966
+ margin: 0
2967
+ }
2968
+ }, {
2969
+ id: CLOSE_BOUND_RULE,
2970
+ rule: "the close bound of a consumer or a worker is less than the cap of the close transports phase",
2971
+ window: "the phase can end before the loop closes",
2972
+ expr: {
2973
+ lhs: { terms: [{
2974
+ knob: "close_bound",
2975
+ coef: 1,
2976
+ at: "consumer"
2977
+ }] },
2978
+ op: "<",
2979
+ rhs: { terms: [{
2980
+ knob: "close_phase_cap",
2981
+ coef: 1,
2982
+ at: "process"
2983
+ }] },
2984
+ margin: 0
2985
+ }
2986
+ }];
2987
+ /**
2988
+ * This function gives the scopes of a rule that reads these symbols: the service, each client, each
2989
+ * consumer and worker, or each limiter. A rule that reads a symbol at `server` applies to each client
2990
+ * and to each server transport. In the scope of a server, the scenario gives the client side.
2991
+ */
2911
2992
  const scopesOf = (svc, scenario, service, symbols) => {
2912
2993
  const within = (name, scoped) => {
2913
2994
  const bind = {
@@ -2924,10 +3005,8 @@ const scopesOf = (svc, scenario, service, symbols) => {
2924
3005
  }
2925
3006
  ];
2926
3007
  };
2927
- return symbols.some((symbol) => LIMITER_SCOPED.test(symbol)) ? (svc.limiters ?? []).map((limiter) => within(limiter.name, limiterBindings(limiter, scenario))) : symbols.some((symbol) => TRANSPORT_SCOPED.test(symbol)) ? svc.transports.flatMap((transport) => {
2928
- const hop = TRANSPORT_HOPS[transport.kind];
2929
- return hop === null ? [] : [within(transport.name, transportBindings(transport, hop, scenario))];
2930
- }) : symbols.some((symbol) => SCOPED.test(symbol)) ? svc.dependencies.map((dependency) => within(dependency.name, dependencyBindings(dependency, scenario))) : [[
3008
+ const transports = (hop) => svc.transports.filter((transport) => TRANSPORT_HOPS[transport.kind] === hop).map((transport) => within(transport.name, transportBindings(transport, hop, scenario)));
3009
+ return symbols.some((symbol) => LIMITER_SCOPED.test(symbol)) ? (svc.limiters ?? []).map((limiter) => within(limiter.name, limiterBindings(limiter, scenario))) : symbols.some((symbol) => TRANSPORT_SCOPED.test(symbol)) ? transports("consumer") : symbols.some((symbol) => SCOPED.test(symbol)) ? [...svc.dependencies.map((dependency) => within(dependency.name, dependencyBindings(dependency, scenario))), ...symbols.some((symbol) => SERVER_SCOPED.test(symbol)) ? transports("server") : []] : [[
2931
3010
  svc.name,
2932
3011
  service.bind,
2933
3012
  service.epochs
@@ -2959,55 +3038,60 @@ const PLATFORM_MARKS = {
2959
3038
  * This function tells which findings of `lint` a compression by k changes (E10). It scales the
2960
3039
  * bindings of each scope by the marks. Thus a harness that runs the service k times faster learns
2961
3040
  * the orderings that its run breaks. The unmarked symbols are the symbols of the rules with no mark.
3041
+ * It reads the rules that `lint` applies with their bindings: the service rules and `BOUND_RULES`.
2962
3042
  */
2963
3043
  const compressionOf = (svc, scenario, rules, k, marks) => {
2964
3044
  const service = serviceBindings(svc, scenario);
2965
3045
  const changed = [];
2966
3046
  const unmarked = /* @__PURE__ */ new Set();
2967
- for (const rule of rules) {
2968
- if (!SERVICE_RULES.includes(rule.id)) continue;
2969
- for (const [scope, bind] of scopesOf(svc, scenario, service, symbolsOf(rule))) {
2970
- const result = compression([rule], bind, k, marks);
2971
- for (const change of result.changed) changed.push({
2972
- ...change,
2973
- scope
2974
- });
2975
- for (const symbol of result.unmarked) unmarked.add(symbol);
2976
- }
3047
+ for (const rule of [...rules.filter((each) => SERVICE_RULES.includes(each.id)), ...BOUND_RULES]) for (const [scope, bind] of scopesOf(svc, scenario, service, symbolsOf(rule))) {
3048
+ const result = compression([rule], bind, k, marks);
3049
+ for (const change of result.changed) changed.push({
3050
+ ...change,
3051
+ scope
3052
+ });
3053
+ for (const symbol of result.unmarked) unmarked.add(symbol);
2977
3054
  }
2978
3055
  return {
2979
3056
  changed,
2980
3057
  unmarked: [...unmarked]
2981
3058
  };
2982
3059
  };
3060
+ /** This function gives the findings of one rule, one for each scope of the rule. */
3061
+ const findingsOf = (svc, scenario, service, rule) => {
3062
+ const symbols = symbolsOf(rule);
3063
+ return scopesOf(svc, scenario, service, symbols).map(([scope, bind, all]) => {
3064
+ const evaluated = evaluate(rule, bind);
3065
+ const epochs = epochsOf(symbols, all);
3066
+ return {
3067
+ rule: rule.id,
3068
+ scope,
3069
+ verdict: verdictOf(rule, bind, evaluated),
3070
+ statement: rule.rule,
3071
+ ...rule.window !== void 0 ? { window: rule.window } : {},
3072
+ evaluated,
3073
+ unbound: symbols.filter((symbol) => bind[symbol] === void 0),
3074
+ ...Object.values(epochs).some((epoch) => epoch !== null) ? { epochs } : {}
3075
+ };
3076
+ });
3077
+ };
2983
3078
  /**
2984
3079
  * This function applies each service rule to a declaration and a scenario. A rule applies one time
2985
- * for the service, for each client, for each consumer and worker, or for each limiter. The function
2986
- * also gives a finding for each necessary field that the description does not give (`DECLARATION_RULE`).
2987
- * Each progress check that names its loops also gets its findings (`PROGRESS_RULE`).
3080
+ * for the service, for each client, for each consumer and worker, or for each limiter. It also
3081
+ * gives a finding for each necessary field that the description does not give (`DECLARATION_RULE`).
3082
+ * It gives a finding for each name that two parts share in the scopes of a rule (`NAME_RULE`). Each progress check
3083
+ * that names its loops also gets its findings (`PROGRESS_RULE`). The findings of the bounds of each
3084
+ * consumer and each worker come last (`BOUND_RULES`).
2988
3085
  */
2989
3086
  const lint = (svc, scenario, rules) => {
2990
3087
  const service = serviceBindings(svc, scenario);
2991
- const findings = [...declarationFindings(svc), ...progressFindings(svc)];
2992
- for (const rule of rules) {
2993
- if (!SERVICE_RULES.includes(rule.id)) continue;
2994
- const symbols = symbolsOf(rule);
2995
- for (const [scope, bind, all] of scopesOf(svc, scenario, service, symbols)) {
2996
- const evaluated = evaluate(rule, bind);
2997
- const epochs = epochsOf(symbols, all);
2998
- findings.push({
2999
- rule: rule.id,
3000
- scope,
3001
- verdict: verdictOf(rule, bind, evaluated),
3002
- statement: rule.rule,
3003
- ...rule.window !== void 0 ? { window: rule.window } : {},
3004
- evaluated,
3005
- unbound: symbols.filter((symbol) => bind[symbol] === void 0),
3006
- ...Object.values(epochs).some((epoch) => epoch !== null) ? { epochs } : {}
3007
- });
3008
- }
3009
- }
3010
- return findings;
3088
+ return [
3089
+ ...declarationFindings(svc),
3090
+ ...nameFindings(svc),
3091
+ ...progressFindings(svc),
3092
+ ...rules.filter((rule) => SERVICE_RULES.includes(rule.id)).flatMap((rule) => findingsOf(svc, scenario, service, rule)),
3093
+ ...BOUND_RULES.flatMap((rule) => findingsOf(svc, scenario, service, rule))
3094
+ ];
3011
3095
  };
3012
3096
  //#endregion
3013
3097
  //#region src/stops.ts
@@ -3075,14 +3159,15 @@ const STOP_RULE = "stop";
3075
3159
  * This function applies the rules to a declaration for one way of stopping. A rule of the drain
3076
3160
  * applies only when it guards that way. The other rules apply as `lint()` applies them. A way with
3077
3161
  * no drain also gets a finding of `STOP_RULE` that depends. No rule bounds the time until the
3078
- * kubelet finds the exit, and the work in flight is lost.
3162
+ * kubelet finds the exit, and the work in flight is lost. Such a way starts no phase, thus it gets no
3163
+ * finding of `BOUND_RULES`.
3079
3164
  */
3080
3165
  const lintStop = (svc, scenario, rules, way) => {
3081
3166
  const stop = STOPS[way];
3082
3167
  const applies = rules.filter((rule) => !DRAIN_RULE_IDS.includes(rule.id) || stop.rules.includes(rule.id));
3083
3168
  const findings = lint(svc, scenario, applies);
3084
3169
  if (stop.drain) return findings;
3085
- return [...findings, {
3170
+ return [...findings.filter((finding) => !BOUND_RULES.some((rule) => rule.id === finding.rule)), {
3086
3171
  rule: STOP_RULE,
3087
3172
  scope: svc.name,
3088
3173
  verdict: "depends",
@@ -3352,7 +3437,7 @@ const workerLoop = (knobs, options) => {
3352
3437
  return closing;
3353
3438
  },
3354
3439
  problems(description) {
3355
- return boundProblems(OWNER$1, closeBound, bound, description);
3440
+ return boundProblems(OWNER$1, description);
3356
3441
  }
3357
3442
  };
3358
3443
  };
@@ -3625,7 +3710,7 @@ const queueDrain = (knobs, options) => {
3625
3710
  return closing;
3626
3711
  },
3627
3712
  problems(description) {
3628
- return boundProblems(OWNER, closeBound, bound, description);
3713
+ return boundProblems(OWNER, description);
3629
3714
  }
3630
3715
  };
3631
3716
  };
@@ -4079,6 +4164,6 @@ const MACHINES = {
4079
4164
  watchdog: WATCHDOG_MACHINE
4080
4165
  };
4081
4166
  //#endregion
4082
- export { DECLARATION_RULE, DRAIN_RULE_IDS, DURATION_FRACTIONS, EPISODES_KEPT, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, LAW_STATISTIC, LIMITER_RULES, LOG_LEVELS, 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, atLeast, backoffBand, backoffDelay, backoffProblems, capKnob, compress, compression, compressionOf, consoleLogger, 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, logEvents, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog, workerLoop };
4167
+ export { BOUND_RULES, CLOSE_BOUND_RULE, DECLARATION_RULE, DRAIN_RULE_IDS, DURATION_FRACTIONS, EPISODES_KEPT, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, LAW_STATISTIC, LIMITER_RULES, LOG_LEVELS, MACHINES, NAME_RULE, PLATFORM_MARKS, POLLER_MACHINE, PROCESS_TRIGGERS, PROGRESS_RULE, SERVICE_RULES, SLIDING_WINDOW_MACHINE, STAGES, STOPS, STOP_RULE, TOKEN_BUCKET_MACHINE, UNIT_BOUND_RULE, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, atLeast, backoffBand, backoffDelay, backoffProblems, capKnob, compress, compression, compressionOf, consoleLogger, 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, logEvents, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog, workerLoop };
4083
4168
 
4084
4169
  //# sourceMappingURL=index.js.map