@mark1russell7/service 0.6.0 → 0.6.2

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.
Files changed (48) hide show
  1. package/README.md +42 -3
  2. package/build/{builder-BNAkpeTT.d.ts → builder-0OlfomVU.d.ts} +2 -2
  3. package/build/{core-CWsGgr9J.d.ts → core-Iy9rIXOT.d.ts} +3 -3
  4. package/build/{dial-JEJavY0U.d.ts → dial-DLT7bTlA.d.ts} +2 -2
  5. package/build/grpc.d.ts +3 -3
  6. package/build/grpc.js +1 -1
  7. package/build/http-client.d.ts +3 -3
  8. package/build/http-client.js +1 -1
  9. package/build/http.d.ts +17 -3
  10. package/build/http.js +53 -10
  11. package/build/http.js.map +1 -1
  12. package/build/index.d.ts +48 -131
  13. package/build/index.js +98 -13
  14. package/build/index.js.map +1 -1
  15. package/build/{lifecycle-CCDLvXLF.d.ts → lifecycle-DXK880vG.d.ts} +44 -3
  16. package/build/{limiter-B0849Vhp.d.ts → limiter-BoZkXIxk.d.ts} +2 -2
  17. package/build/{limiter-pkBZUp-t.js → limiter-CmC4vCjk.js} +21 -13
  18. package/build/limiter-CmC4vCjk.js.map +1 -0
  19. package/build/limiter.d.ts +3 -3
  20. package/build/limiter.js +1 -1
  21. package/build/{machine-DZMb_QEU.js → machine-Dq2OlzCG.js} +7 -20
  22. package/build/machine-Dq2OlzCG.js.map +1 -0
  23. package/build/mongodb.d.ts +3 -3
  24. package/build/mongodb.js +1 -1
  25. package/build/pg.d.ts +2 -2
  26. package/build/pg.js +1 -1
  27. package/build/{queue-eLs5IruM.d.ts → queue-CvBNNZZJ.d.ts} +2 -2
  28. package/build/rabbitmq.d.ts +4 -4
  29. package/build/rabbitmq.js +1 -1
  30. package/build/redis.d.ts +3 -3
  31. package/build/redis.js +1 -1
  32. package/build/retrier-CRda6z9G.js +73 -0
  33. package/build/retrier-CRda6z9G.js.map +1 -0
  34. package/build/rules-BBRopO1e.d.ts +145 -0
  35. package/build/rules.d.ts +2 -0
  36. package/build/rules.js +128 -0
  37. package/build/rules.js.map +1 -0
  38. package/build/{store-D5HLgBnW.d.ts → store-Cwuepb-z.d.ts} +14 -3
  39. package/build/testing.d.ts +4 -2
  40. package/build/testing.js +12 -1
  41. package/build/testing.js.map +1 -1
  42. package/build/websocket.d.ts +3 -3
  43. package/build/websocket.js +1 -1
  44. package/package.json +7 -3
  45. package/build/limiter-pkBZUp-t.js.map +0 -1
  46. package/build/machine-DZMb_QEU.js.map +0 -1
  47. package/build/operation-DL5RxFds.js +0 -25
  48. package/build/operation-DL5RxFds.js.map +0 -1
@@ -0,0 +1,73 @@
1
+ import { realClock } from "./clock.js";
2
+ import { backoffDelay, backoffProblems } from "./backoff.js";
3
+ import { compare, convertible } from "@mark1russell7/quantity";
4
+ //#region src/operation.ts
5
+ /**
6
+ * This function tells if an operation can go again `since` its first issue. An idempotent
7
+ * operation can always go again, and other operations cannot. A keyed operation can go again
8
+ * while the server keeps its key.
9
+ */
10
+ const mayReissue = (operation, since) => {
11
+ const { idempotent } = operation;
12
+ if (typeof idempotent === "boolean") return idempotent;
13
+ return compare(since, idempotent.window) < 0;
14
+ };
15
+ /** This function gives the problems in the declaration of an operation that `describe()` refuses. */
16
+ const operationProblems = (owner, name, operation) => {
17
+ const { idempotent } = operation;
18
+ if (typeof idempotent === "boolean") return [];
19
+ const problems = [];
20
+ if (idempotent.key.trim().length === 0) problems.push(`${owner}'s ${name} names no key`);
21
+ if (!convertible(idempotent.window.unit, "s")) problems.push(`${owner}'s ${name} holds its key for a span that is not a time`);
22
+ return problems;
23
+ };
24
+ //#endregion
25
+ //#region src/retrier.ts
26
+ /** This function makes a retrier with no check of its policy. A client of the package uses it with its own knobs. */
27
+ const retrierOn = (clock, backoff, random, signal) => {
28
+ let tries = 0;
29
+ let timer = null;
30
+ const cancel = () => {
31
+ timer?.();
32
+ timer = null;
33
+ };
34
+ signal?.addEventListener("abort", cancel, { once: true });
35
+ return {
36
+ get attempts() {
37
+ return tries;
38
+ },
39
+ get pending() {
40
+ return timer !== null;
41
+ },
42
+ schedule(run) {
43
+ if (signal?.aborted === true) return null;
44
+ tries += 1;
45
+ const delay = Math.round(backoffDelay(backoff, tries, random));
46
+ timer?.();
47
+ timer = clock.after(delay, () => {
48
+ timer = null;
49
+ run();
50
+ });
51
+ return delay;
52
+ },
53
+ cancel,
54
+ reset() {
55
+ tries = 0;
56
+ }
57
+ };
58
+ };
59
+ /**
60
+ * This function makes a retrier over `backoffDelay`. The first try waits `base`, and each try after
61
+ * it waits `factor` times more, to the `cap`, with the jitter of the policy. It refuses a policy
62
+ * with a problem of `backoffProblems`.
63
+ */
64
+ const retrier = (options) => {
65
+ const { clock = realClock, random = Math.random, signal, ...backoff } = options;
66
+ const problems = backoffProblems(backoff);
67
+ if (problems.length > 0) throw new Error(`the retrier has a bad backoff: ${problems.join("; ")}`);
68
+ return retrierOn(clock, backoff, random, signal);
69
+ };
70
+ //#endregion
71
+ export { operationProblems as i, retrierOn as n, mayReissue as r, retrier as t };
72
+
73
+ //# sourceMappingURL=retrier-CRda6z9G.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"retrier-CRda6z9G.js","names":[],"sources":["../src/operation.ts","../src/retrier.ts"],"sourcesContent":["import type { Extent, Quantity } from \"@mark1russell7/quantity\";\nimport { compare, convertible } from \"@mark1russell7/quantity\";\n\n/**\n * This type tells if an operation can go again after a failure. It is a property of the\n * operation, not of the dependency. One Redis client sends a GET, which is safe to send again. It\n * also sends an INCR, which counts two times when it goes again after a timeout. Each operation\n * declares its idempotency:\n * - `true`: a second issue has the same effect. Examples are an HTTP GET or PUT, a SELECT, a\n * Redis GET or SET, and a write that the server removes when it is a copy.\n * - `false`: the client does not send it again after it can have reached the server.\n * - keyed: the server keeps a key for a window, as with an `Idempotency-Key` header, and it\n * ignores a copy in that window. A copy after the window is a second operation. Thus the\n * window is a timer, and it must be longer than all retries of the operation.\n */\nexport type Idempotency = boolean | { readonly key: string; readonly window: Extent };\n\n/** An operation is an endpoint that the service calls or serves, a command, or a query. */\nexport interface Operation {\n readonly idempotent: Idempotency;\n}\n\n/**\n * This function tells if an operation can go again `since` its first issue. An idempotent\n * operation can always go again, and other operations cannot. A keyed operation can go again\n * while the server keeps its key.\n */\nexport const mayReissue = (operation: Operation, since: Quantity): boolean => {\n const { idempotent } = operation;\n if (typeof idempotent === \"boolean\") return idempotent;\n return compare(since, idempotent.window) < 0;\n};\n\n/** This function gives the problems in the declaration of an operation that `describe()` refuses. */\nexport const operationProblems = (owner: string, name: string, operation: Operation): string[] => {\n const { idempotent } = operation;\n if (typeof idempotent === \"boolean\") return [];\n const problems: string[] = [];\n if (idempotent.key.trim().length === 0) problems.push(`${owner}'s ${name} names no key`);\n if (!convertible(idempotent.window.unit, \"s\"))\n problems.push(`${owner}'s ${name} holds its key for a span that is not a time`);\n return problems;\n};\n","import type { Backoff } from \"./backoff.ts\";\nimport { backoffDelay, backoffProblems } from \"./backoff.ts\";\nimport type { Cancel, Clock } from \"./clock.ts\";\nimport { realClock } from \"./clock.ts\";\n\n/** These options make a retrier: a backoff policy, the clock of its timers, and the signal that cancels it. */\nexport interface RetrierOptions extends Backoff {\n /** This clock starts each retry. The default is the real clock. A test gives a fake clock. */\n readonly clock?: Clock | undefined;\n /** This function gives a number in [0, 1) for the jitter of each delay. The default is `Math.random`. */\n readonly random?: (() => number) | undefined;\n /**\n * This signal cancels the retrier when it aborts, for example the `signal` of the lifecycle, which\n * aborts in the drain. After the abort, `schedule` starts nothing.\n */\n readonly signal?: AbortSignal | undefined;\n}\n\n/** A retrier starts a function again after the backoff of each try, on its clock. */\nexport interface Retrier {\n /** This count is the number of tries since the last reset. */\n readonly attempts: number;\n /** This flag tells if a retry waits for its timer. */\n readonly pending: boolean;\n /**\n * This method counts one more try, and starts `run` after the backoff delay of that try. It gives\n * the delay in milliseconds. A retry that waits stops, thus one retry at most waits. After the\n * abort of the signal, it starts nothing and gives null. The function catches its own errors.\n */\n schedule(run: () => void): number | null;\n /** This method sets the count of tries to 0, for example after a start that succeeded. A retry that waits stays. */\n reset(): void;\n /** This method stops the retry that waits. The count of tries stays. */\n cancel(): void;\n}\n\n/** This function makes a retrier with no check of its policy. A client of the package uses it with its own knobs. */\nexport const retrierOn = (clock: Clock, backoff: Backoff, random: () => number, signal?: AbortSignal): Retrier => {\n let tries = 0;\n let timer: Cancel | null = null;\n const cancel = (): void => {\n timer?.();\n timer = null;\n };\n signal?.addEventListener(\"abort\", cancel, { once: true });\n return {\n get attempts() {\n return tries;\n },\n get pending() {\n return timer !== null;\n },\n schedule(run) {\n if (signal?.aborted === true) return null;\n tries += 1;\n const delay = Math.round(backoffDelay(backoff, tries, random));\n timer?.();\n timer = clock.after(delay, () => {\n timer = null;\n run();\n });\n return delay;\n },\n cancel,\n reset() {\n tries = 0;\n },\n };\n};\n\n/**\n * This function makes a retrier over `backoffDelay`. The first try waits `base`, and each try after\n * it waits `factor` times more, to the `cap`, with the jitter of the policy. It refuses a policy\n * with a problem of `backoffProblems`.\n */\nexport const retrier = (options: RetrierOptions): Retrier => {\n const { clock = realClock, random = Math.random, signal, ...backoff } = options;\n const problems = backoffProblems(backoff);\n if (problems.length > 0) throw new Error(`the retrier has a bad backoff: ${problems.join(\"; \")}`);\n return retrierOn(clock, backoff, random, signal);\n};\n"],"mappings":";;;;;;;;;AA2BA,MAAa,cAAc,WAAsB,UAA6B;CAC5E,MAAM,EAAE,eAAe;CACvB,IAAI,OAAO,eAAe,WAAW,OAAO;CAC5C,OAAO,QAAQ,OAAO,WAAW,MAAM,IAAI;AAC7C;;AAGA,MAAa,qBAAqB,OAAe,MAAc,cAAmC;CAChG,MAAM,EAAE,eAAe;CACvB,IAAI,OAAO,eAAe,WAAW,OAAO,CAAC;CAC7C,MAAM,WAAqB,CAAC;CAC5B,IAAI,WAAW,IAAI,KAAK,CAAC,CAAC,WAAW,GAAG,SAAS,KAAK,GAAG,MAAM,KAAK,KAAK,cAAc;CACvF,IAAI,CAAC,YAAY,WAAW,OAAO,MAAM,GAAG,GAC1C,SAAS,KAAK,GAAG,MAAM,KAAK,KAAK,6CAA6C;CAChF,OAAO;AACT;;;;ACLA,MAAa,aAAa,OAAc,SAAkB,QAAsB,WAAkC;CAChH,IAAI,QAAQ;CACZ,IAAI,QAAuB;CAC3B,MAAM,eAAqB;EACzB,QAAQ;EACR,QAAQ;CACV;CACA,QAAQ,iBAAiB,SAAS,QAAQ,EAAE,MAAM,KAAK,CAAC;CACxD,OAAO;EACL,IAAI,WAAW;GACb,OAAO;EACT;EACA,IAAI,UAAU;GACZ,OAAO,UAAU;EACnB;EACA,SAAS,KAAK;GACZ,IAAI,QAAQ,YAAY,MAAM,OAAO;GACrC,SAAS;GACT,MAAM,QAAQ,KAAK,MAAM,aAAa,SAAS,OAAO,MAAM,CAAC;GAC7D,QAAQ;GACR,QAAQ,MAAM,MAAM,aAAa;IAC/B,QAAQ;IACR,IAAI;GACN,CAAC;GACD,OAAO;EACT;EACA;EACA,QAAQ;GACN,QAAQ;EACV;CACF;AACF;;;;;;AAOA,MAAa,WAAW,YAAqC;CAC3D,MAAM,EAAE,QAAQ,WAAW,SAAS,KAAK,QAAQ,QAAQ,GAAG,YAAY;CACxE,MAAM,WAAW,gBAAgB,OAAO;CACxC,IAAI,SAAS,SAAS,GAAG,MAAM,IAAI,MAAM,kCAAkC,SAAS,KAAK,IAAI,GAAG;CAChG,OAAO,UAAU,OAAO,SAAS,QAAQ,MAAM;AACjD"}
@@ -0,0 +1,145 @@
1
+ //#region src/law.d.ts
2
+ /**
3
+ * This module is the evaluator of the timer-ordering law. Its decisions are the same as the
4
+ * decisions of the research evaluator, except when absent timers leave no order (`evaluate`). The
5
+ * rules are data, and the caller gives them. Each rule
6
+ * is one or more linear inequalities over symbols at a hop (`readiness_detection_window@pod`),
7
+ * with a margin. A binding maps `symbol@hop` to seconds, or to "inf" for a timer that is absent.
8
+ */
9
+ /** A term is a coefficient times one symbol, at a hop when it has one. */
10
+ interface Term {
11
+ readonly knob: string;
12
+ readonly coef: number;
13
+ readonly at?: string | undefined;
14
+ }
15
+ /** A side is a sum of terms, plus a constant. */
16
+ interface Side {
17
+ readonly terms: readonly Term[];
18
+ readonly const?: number | undefined;
19
+ }
20
+ /** An inequality compares two sides, with a margin. */
21
+ interface Inequality {
22
+ readonly lhs: Side;
23
+ readonly op: "<" | "<=" | ">" | ">=";
24
+ readonly rhs: Side;
25
+ /** The margin is in seconds, or it is words for a margin that no binding gives ("a factor of several"). Words count as 0. */
26
+ readonly margin?: number | string | undefined;
27
+ }
28
+ /** A rule is one or more inequalities, with their statement in words. */
29
+ interface Rule {
30
+ readonly id: string;
31
+ /** This text is the rule in words. */
32
+ readonly rule: string;
33
+ /** This text is the window that a violation opens. */
34
+ readonly window?: string | undefined;
35
+ readonly expr: Inequality;
36
+ readonly expr_more?: readonly Inequality[] | undefined;
37
+ }
38
+ /** 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. */
39
+ type Bound = number | "inf" | "off";
40
+ /**
41
+ * A binding maps `symbol@hop` to its bound. Its "margin" replaces the margin of each inequality.
42
+ * Its "margins" replace them one by one, in sequence, as the binding of a chain can.
43
+ */
44
+ type Binding = Readonly<Record<string, Bound | readonly number[] | undefined>> & {
45
+ readonly margin?: number | undefined;
46
+ readonly margins?: readonly number[] | undefined;
47
+ };
48
+ /** A verdict is "holds", "violated", "unbounded" (it holds only because a timer is absent) or "depends" (nothing is bound). */
49
+ type Verdict = "holds" | "violated" | "unbounded" | "depends";
50
+ /** An evaluation is the value of each side of one inequality, its margin, and if it holds. */
51
+ interface Evaluated {
52
+ readonly lhs: number | null;
53
+ readonly rhs: number | null;
54
+ readonly margin: number;
55
+ readonly holds: boolean | null;
56
+ }
57
+ /** This function gives the inequalities of a rule: its expr, then the others. */
58
+ declare const inequalities: (rule: Rule) => readonly Inequality[];
59
+ /** This function gives the symbols that a rule reads, as `symbol@hop`. */
60
+ declare const symbolsOf: (rule: Rule) => string[];
61
+ /**
62
+ * This function evaluates each inequality on one binding. "<" holds when lhs + margin < rhs, and
63
+ * ">" holds when lhs > rhs + margin. Only the inequalities with all their symbols bound apply.
64
+ * The others are null. Absent timers can leave no order: the same infinity on each side, or both
65
+ * signs of infinity on one side. Then the inequality holds only because a timer is absent.
66
+ */
67
+ declare const evaluate: (rule: Rule, bind: Binding) => Evaluated[];
68
+ /**
69
+ * This function gives the verdict of an evaluation. When an applicable inequality fails, the
70
+ * verdict is "violated". When all hold only because a timer is absent, the verdict is "unbounded",
71
+ * because nothing then limits the window. Otherwise the verdict is "holds". When no inequality
72
+ * applies, the arithmetic cannot decide, and the verdict is "depends".
73
+ */
74
+ declare const verdictOf: (rule: Rule, bind: Binding, evaluated: readonly Evaluated[]) => Verdict;
75
+ /**
76
+ * A mark tells how a timer moves when a compression scales time by k (E10). A "scalable" timer
77
+ * becomes k times its value. A "fixed" timer keeps its value. A "stepped" timer takes only
78
+ * multiples of its step, thus it rounds up. A "floored" timer has a floor that a peer sets, for
79
+ * example the minimum retransmission timeout of the kernel. The step and the floor are in seconds.
80
+ */
81
+ type TimerMark = {
82
+ readonly kind: "scalable";
83
+ } | {
84
+ readonly kind: "fixed";
85
+ } | {
86
+ readonly kind: "stepped";
87
+ readonly step: number;
88
+ } | {
89
+ readonly kind: "floored";
90
+ readonly floor: number;
91
+ readonly by: string;
92
+ };
93
+ /** The marks map `symbol@hop` to a mark. A bare symbol marks the symbol at each hop. */
94
+ type TimerMarks = Readonly<Record<string, TimerMark | undefined>>;
95
+ /** A compressed binding, and the symbols that have no mark. */
96
+ interface Compressed {
97
+ readonly bind: Binding;
98
+ /** These symbols have no mark. They keep their values, thus the compression proves nothing about them. */
99
+ readonly unmarked: readonly string[];
100
+ }
101
+ /** A change is a rule whose verdict a compression changes. */
102
+ interface Change {
103
+ readonly rule: string;
104
+ readonly before: Verdict;
105
+ readonly after: Verdict;
106
+ }
107
+ /** The result of a compression: the rules whose verdict it changes, and the symbols of the rules that have no mark. */
108
+ interface Compression {
109
+ readonly changed: readonly Change[];
110
+ readonly unmarked: readonly string[];
111
+ }
112
+ /**
113
+ * This function scales each timer of a binding by k, by its mark (E10). An absent timer ("inf" or
114
+ * "off") stays absent. A chain scales each value. The margins of the binding and the constants of
115
+ * the rules do not scale: they are tolerances, not timers. A symbol with no mark keeps its value.
116
+ */
117
+ declare const compress: (bind: Binding, k: number, marks: TimerMarks) => Compressed;
118
+ /**
119
+ * This function tells which rules a compression by k changes. A compression keeps each ordering
120
+ * when no verdict changes. A change in either direction counts: a violation that the compression
121
+ * hides is as wrong as one that it makes. The unmarked symbols are the symbols that the rules read.
122
+ */
123
+ declare const compression: (rules: readonly Rule[], bind: Binding, k: number, marks: TimerMarks) => Compression;
124
+ //#endregion
125
+ //#region src/rules.d.ts
126
+ /**
127
+ * O04 with the hold of the service. The listener of a pod stays open through the preStop sleep and
128
+ * then through the hold of `fail readiness`. Thus the sum of the two must cover the propagation of
129
+ * the endpoints. The rule of the research is the case without a hold.
130
+ */
131
+ declare const O04: Rule;
132
+ /** O09 is W8: readiness detection plus propagation is no longer than liveness detection plus the preStop sleep. */
133
+ declare const O09: Rule;
134
+ /** O10: the preStop sleep plus the drain of the process fits in the grace period. */
135
+ declare const O10: Rule;
136
+ /** O16: the cooperative window is shorter than the drain, which is shorter than the grace less the preStop sleep. */
137
+ declare const O16: Rule;
138
+ /**
139
+ * These are the rules of the drain. For each way that a pod stops, `lintStop()` applies only the
140
+ * rules of this set that guard that way. `DRAIN_RULE_IDS` gives their identifiers.
141
+ */
142
+ declare const DRAIN_RULES: readonly Rule[];
143
+ //#endregion
144
+ export { symbolsOf as C, inequalities as S, TimerMarks as _, O16 as a, compression as b, Change as c, Evaluated as d, Inequality as f, TimerMark as g, Term as h, O10 as i, Compressed as l, Side as m, O04 as n, Binding as o, Rule as p, O09 as r, Bound as s, DRAIN_RULES as t, Compression as u, Verdict as v, verdictOf as w, evaluate as x, compress as y };
145
+ //# sourceMappingURL=rules-BBRopO1e.d.ts.map
@@ -0,0 +1,2 @@
1
+ import { a as O16, i as O10, n as O04, p as Rule, r as O09, t as DRAIN_RULES } from "./rules-BBRopO1e.js";
2
+ export { DRAIN_RULES, O04, O09, O10, O16, type Rule };
package/build/rules.js ADDED
@@ -0,0 +1,128 @@
1
+ //#region src/rules.ts
2
+ /**
3
+ * O04 with the hold of the service. The listener of a pod stays open through the preStop sleep and
4
+ * then through the hold of `fail readiness`. Thus the sum of the two must cover the propagation of
5
+ * the endpoints. The rule of the research is the case without a hold.
6
+ */
7
+ const O04 = {
8
+ id: "O04",
9
+ rule: "the preStop sleep plus the hold of fail readiness is at least the endpoint propagation",
10
+ window: "new connections reach a pod whose listener is closed",
11
+ expr: {
12
+ lhs: { terms: [{
13
+ knob: "prestop_sleep",
14
+ coef: 1,
15
+ at: "pod"
16
+ }, {
17
+ knob: "readiness_hold",
18
+ coef: 1,
19
+ at: "process"
20
+ }] },
21
+ op: ">=",
22
+ rhs: { terms: [{
23
+ knob: "propagation_bound",
24
+ coef: 1,
25
+ at: "cluster"
26
+ }] }
27
+ }
28
+ };
29
+ /** O09 is W8: readiness detection plus propagation is no longer than liveness detection plus the preStop sleep. */
30
+ const O09 = {
31
+ id: "O09",
32
+ rule: "readiness detection plus endpoint propagation is no longer than liveness detection plus the preStop sleep",
33
+ window: "traffic reaches a container that its liveness probe kills",
34
+ expr: {
35
+ lhs: { terms: [{
36
+ knob: "readiness_detection_window",
37
+ coef: 1,
38
+ at: "pod"
39
+ }, {
40
+ knob: "propagation_bound",
41
+ coef: 1,
42
+ at: "cluster"
43
+ }] },
44
+ op: "<=",
45
+ rhs: { terms: [{
46
+ knob: "liveness_detection_window",
47
+ coef: 1,
48
+ at: "pod"
49
+ }, {
50
+ knob: "prestop_sleep",
51
+ coef: 1,
52
+ at: "pod"
53
+ }] }
54
+ }
55
+ };
56
+ /** O10: the preStop sleep plus the drain of the process fits in the grace period. */
57
+ const O10 = {
58
+ id: "O10",
59
+ rule: "the preStop sleep plus the shutdown of the process fits in the grace period",
60
+ window: "work in flight at SIGKILL is cut, and each connection closes at once",
61
+ expr: {
62
+ lhs: { terms: [{
63
+ knob: "prestop_sleep",
64
+ coef: 1,
65
+ at: "pod"
66
+ }, {
67
+ knob: "process_drain_time",
68
+ coef: 1,
69
+ at: "process"
70
+ }] },
71
+ op: "<=",
72
+ rhs: { terms: [{
73
+ knob: "termination_grace",
74
+ coef: 1,
75
+ at: "pod"
76
+ }] }
77
+ }
78
+ };
79
+ /** O16: the cooperative window is shorter than the drain, which is shorter than the grace less the preStop sleep. */
80
+ const O16 = {
81
+ id: "O16",
82
+ rule: "the cooperative window is shorter than the drain, which is shorter than the grace less the preStop sleep",
83
+ window: "handlers are cut before they answer, or the drain itself gets SIGKILL",
84
+ expr: {
85
+ lhs: { terms: [{
86
+ knob: "cooperative_window",
87
+ coef: 1,
88
+ at: "process"
89
+ }] },
90
+ op: "<",
91
+ rhs: { terms: [{
92
+ knob: "process_drain_time",
93
+ coef: 1,
94
+ at: "process"
95
+ }] }
96
+ },
97
+ expr_more: [{
98
+ lhs: { terms: [{
99
+ knob: "process_drain_time",
100
+ coef: 1,
101
+ at: "process"
102
+ }] },
103
+ op: "<",
104
+ rhs: { terms: [{
105
+ knob: "termination_grace",
106
+ coef: 1,
107
+ at: "pod"
108
+ }, {
109
+ knob: "prestop_sleep",
110
+ coef: -1,
111
+ at: "pod"
112
+ }] }
113
+ }]
114
+ };
115
+ /**
116
+ * These are the rules of the drain. For each way that a pod stops, `lintStop()` applies only the
117
+ * rules of this set that guard that way. `DRAIN_RULE_IDS` gives their identifiers.
118
+ */
119
+ const DRAIN_RULES = [
120
+ O04,
121
+ O09,
122
+ O10,
123
+ O16
124
+ ];
125
+ //#endregion
126
+ export { DRAIN_RULES, O04, O09, O10, O16 };
127
+
128
+ //# sourceMappingURL=rules.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rules.js","names":[],"sources":["../src/rules.ts"],"sourcesContent":["// @mark1russell7/service/rules: the rules of the ordering law that a drain in Kubernetes meets, as\n// data (SYS-32). The caller of `lint()` gives the rules. This entry gives the drain rules from one\n// source, thus a service does not copy them into its tests. It loads no module at run time: only the\n// type of a rule comes from the law. Thus it loads no Testcontainers, no `node:` module and no zod.\n\nimport type { Rule } from \"./law.ts\";\n\nexport type { Rule } from \"./law.ts\";\n\n/**\n * O04 with the hold of the service. The listener of a pod stays open through the preStop sleep and\n * then through the hold of `fail readiness`. Thus the sum of the two must cover the propagation of\n * the endpoints. The rule of the research is the case without a hold.\n */\nexport const O04: Rule = {\n id: \"O04\",\n rule: \"the preStop sleep plus the hold of fail readiness is at least the endpoint propagation\",\n window: \"new connections reach a pod whose listener is closed\",\n expr: {\n lhs: {\n terms: [\n { knob: \"prestop_sleep\", coef: 1, at: \"pod\" },\n { knob: \"readiness_hold\", coef: 1, at: \"process\" },\n ],\n },\n op: \">=\",\n rhs: { terms: [{ knob: \"propagation_bound\", coef: 1, at: \"cluster\" }] },\n },\n};\n\n/** O09 is W8: readiness detection plus propagation is no longer than liveness detection plus the preStop sleep. */\nexport const O09: Rule = {\n id: \"O09\",\n rule: \"readiness detection plus endpoint propagation is no longer than liveness detection plus the preStop sleep\",\n window: \"traffic reaches a container that its liveness probe kills\",\n expr: {\n lhs: {\n terms: [\n { knob: \"readiness_detection_window\", coef: 1, at: \"pod\" },\n { knob: \"propagation_bound\", coef: 1, at: \"cluster\" },\n ],\n },\n op: \"<=\",\n rhs: {\n terms: [\n { knob: \"liveness_detection_window\", coef: 1, at: \"pod\" },\n { knob: \"prestop_sleep\", coef: 1, at: \"pod\" },\n ],\n },\n },\n};\n\n/** O10: the preStop sleep plus the drain of the process fits in the grace period. */\nexport const O10: Rule = {\n id: \"O10\",\n rule: \"the preStop sleep plus the shutdown of the process fits in the grace period\",\n window: \"work in flight at SIGKILL is cut, and each connection closes at once\",\n expr: {\n lhs: {\n terms: [\n { knob: \"prestop_sleep\", coef: 1, at: \"pod\" },\n { knob: \"process_drain_time\", coef: 1, at: \"process\" },\n ],\n },\n op: \"<=\",\n rhs: { terms: [{ knob: \"termination_grace\", coef: 1, at: \"pod\" }] },\n },\n};\n\n/** O16: the cooperative window is shorter than the drain, which is shorter than the grace less the preStop sleep. */\nexport const O16: Rule = {\n id: \"O16\",\n rule: \"the cooperative window is shorter than the drain, which is shorter than the grace less the preStop sleep\",\n window: \"handlers are cut before they answer, or the drain itself gets SIGKILL\",\n expr: {\n lhs: { terms: [{ knob: \"cooperative_window\", coef: 1, at: \"process\" }] },\n op: \"<\",\n rhs: { terms: [{ knob: \"process_drain_time\", coef: 1, at: \"process\" }] },\n },\n expr_more: [\n {\n lhs: { terms: [{ knob: \"process_drain_time\", coef: 1, at: \"process\" }] },\n op: \"<\",\n rhs: {\n terms: [\n { knob: \"termination_grace\", coef: 1, at: \"pod\" },\n { knob: \"prestop_sleep\", coef: -1, at: \"pod\" },\n ],\n },\n },\n ],\n};\n\n/**\n * These are the rules of the drain. For each way that a pod stops, `lintStop()` applies only the\n * rules of this set that guard that way. `DRAIN_RULE_IDS` gives their identifiers.\n */\nexport const DRAIN_RULES: readonly Rule[] = [O04, O09, O10, O16];\n"],"mappings":";;;;;;AAcA,MAAa,MAAY;CACvB,IAAI;CACJ,MAAM;CACN,QAAQ;CACR,MAAM;EACJ,KAAK,EACH,OAAO,CACL;GAAE,MAAM;GAAiB,MAAM;GAAG,IAAI;EAAM,GAC5C;GAAE,MAAM;GAAkB,MAAM;GAAG,IAAI;EAAU,CACnD,EACF;EACA,IAAI;EACJ,KAAK,EAAE,OAAO,CAAC;GAAE,MAAM;GAAqB,MAAM;GAAG,IAAI;EAAU,CAAC,EAAE;CACxE;AACF;;AAGA,MAAa,MAAY;CACvB,IAAI;CACJ,MAAM;CACN,QAAQ;CACR,MAAM;EACJ,KAAK,EACH,OAAO,CACL;GAAE,MAAM;GAA8B,MAAM;GAAG,IAAI;EAAM,GACzD;GAAE,MAAM;GAAqB,MAAM;GAAG,IAAI;EAAU,CACtD,EACF;EACA,IAAI;EACJ,KAAK,EACH,OAAO,CACL;GAAE,MAAM;GAA6B,MAAM;GAAG,IAAI;EAAM,GACxD;GAAE,MAAM;GAAiB,MAAM;GAAG,IAAI;EAAM,CAC9C,EACF;CACF;AACF;;AAGA,MAAa,MAAY;CACvB,IAAI;CACJ,MAAM;CACN,QAAQ;CACR,MAAM;EACJ,KAAK,EACH,OAAO,CACL;GAAE,MAAM;GAAiB,MAAM;GAAG,IAAI;EAAM,GAC5C;GAAE,MAAM;GAAsB,MAAM;GAAG,IAAI;EAAU,CACvD,EACF;EACA,IAAI;EACJ,KAAK,EAAE,OAAO,CAAC;GAAE,MAAM;GAAqB,MAAM;GAAG,IAAI;EAAM,CAAC,EAAE;CACpE;AACF;;AAGA,MAAa,MAAY;CACvB,IAAI;CACJ,MAAM;CACN,QAAQ;CACR,MAAM;EACJ,KAAK,EAAE,OAAO,CAAC;GAAE,MAAM;GAAsB,MAAM;GAAG,IAAI;EAAU,CAAC,EAAE;EACvE,IAAI;EACJ,KAAK,EAAE,OAAO,CAAC;GAAE,MAAM;GAAsB,MAAM;GAAG,IAAI;EAAU,CAAC,EAAE;CACzE;CACA,WAAW,CACT;EACE,KAAK,EAAE,OAAO,CAAC;GAAE,MAAM;GAAsB,MAAM;GAAG,IAAI;EAAU,CAAC,EAAE;EACvE,IAAI;EACJ,KAAK,EACH,OAAO,CACL;GAAE,MAAM;GAAqB,MAAM;GAAG,IAAI;EAAM,GAChD;GAAE,MAAM;GAAiB,MAAM;GAAI,IAAI;EAAM,CAC/C,EACF;CACF,CACF;AACF;;;;;AAMA,MAAa,cAA+B;CAAC;CAAK;CAAK;CAAK;AAAG"}
@@ -56,6 +56,15 @@ interface KeyedLimiter {
56
56
  * fails, it gives the decision of `onStoreFailure`, with the failure as text.
57
57
  */
58
58
  take(key: string): Promise<Decision>;
59
+ /**
60
+ * This method takes one unit for a key, and gives the decision at once, with no promise. Only a
61
+ * local store whose take gives its decision at once permits it, for example `memoryStore`. A shared store throws.
62
+ */
63
+ tryTakeSync?(key: string): Decision;
64
+ }
65
+ /** A local limiter is a keyed limiter on a memory store: its take can give the decision at once. */
66
+ interface LocalLimiter extends KeyedLimiter {
67
+ tryTakeSync(key: string): Decision;
59
68
  }
60
69
  /**
61
70
  * This function makes the runtime of a limiter from its spec and its store. It refuses a spec with a
@@ -65,8 +74,10 @@ interface KeyedLimiter {
65
74
  * permitted with `remaining` 0. With `closed`, it is refused with the cause `store`.
66
75
  * - The `retryAfter` of the cause `store` is the longest `retryAfter` of the policy.
67
76
  * - A failure of a local store rejects the take, because a local store has no `onStoreFailure`.
77
+ * - `tryTakeSync` gives the decision at once. A shared store throws, and so does a local store that gives a promise.
68
78
  */
69
- declare const keyedLimiter: (name: string, spec: LimiterSpec, store: LimiterStore) => KeyedLimiter;
79
+ declare function keyedLimiter(name: string, spec: LimiterSpec, store: MemoryStore): LocalLimiter;
80
+ declare function keyedLimiter(name: string, spec: LimiterSpec, store: LimiterStore): KeyedLimiter;
70
81
  //#endregion
71
- export { keyedLimiter as a, TakeRequest as i, LimiterStore as n, memoryStore as o, MemoryStore as r, KeyedLimiter as t };
72
- //# sourceMappingURL=store-D5HLgBnW.d.ts.map
82
+ export { TakeRequest as a, MemoryStore as i, LimiterStore as n, keyedLimiter as o, LocalLimiter as r, memoryStore as s, KeyedLimiter as t };
83
+ //# sourceMappingURL=store-Cwuepb-z.d.ts.map
@@ -1,6 +1,6 @@
1
1
  import { n as Clock } from "./clock-mVqhXD0b.js";
2
- import { B as Logger, E as CheckFn, Et as ExitTrigger, L as LogEntry, Tt as ExitSignal, W as Outcome, d as TransportImpl, jt as ProcessPort, r as Lifecycle, z as LogLevel } from "./lifecycle-CCDLvXLF.js";
3
- import { n as ServiceBuilder } from "./builder-BNAkpeTT.js";
2
+ import { D as CheckFn, Dt as ExitSignal, H as Logger, It as UncaughtOrigin, K as Outcome, Nt as ProcessPort, Ot as ExitTrigger, R as LogEntry, V as LogLevel, d as TransportImpl, r as Lifecycle } from "./lifecycle-DXK880vG.js";
3
+ import { n as ServiceBuilder } from "./builder-0OlfomVU.js";
4
4
  //#region src/fakes.d.ts
5
5
  /** A fake clock moves only when a test tells it to. */
6
6
  interface FakeClock extends Clock {
@@ -24,6 +24,8 @@ interface FakeProcess extends ProcessPort {
24
24
  trigger(name: ExitTrigger): void;
25
25
  /** This method sends a message of the IPC channel to each handler of the trigger `ipc-message`. */
26
26
  message(value: unknown): void;
27
+ /** This method sends an error that no code caught to each handler of `onUncaught`. The default origin is `uncaughtException`. */
28
+ uncaught(error: unknown, origin?: UncaughtOrigin): void;
27
29
  /** These are the exit codes, in sequence. A correct runtime exits one time. */
28
30
  readonly exits: readonly number[];
29
31
  /** This count is the number of handlers that are registered. */
package/build/testing.js CHANGED
@@ -57,6 +57,7 @@ const fakeClock = (start = 0) => {
57
57
  /** This function makes a fake process. */
58
58
  const fakeProcess = (options = {}) => {
59
59
  const handlers = /* @__PURE__ */ new Map();
60
+ const uncaughtHandlers = /* @__PURE__ */ new Set();
60
61
  const exits = [];
61
62
  const log = [];
62
63
  let flushes = 0;
@@ -77,6 +78,13 @@ const fakeProcess = (options = {}) => {
77
78
  set.delete(handler);
78
79
  };
79
80
  },
81
+ onUncaught(handler) {
82
+ const own = (error, origin) => handler(error, origin);
83
+ uncaughtHandlers.add(own);
84
+ return () => {
85
+ uncaughtHandlers.delete(own);
86
+ };
87
+ },
80
88
  async flush() {
81
89
  stamp("flush");
82
90
  await options.flush?.();
@@ -100,11 +108,14 @@ const fakeProcess = (options = {}) => {
100
108
  signal: (name) => send(name),
101
109
  trigger: (name) => send(name),
102
110
  message: (value) => send("ipc-message", value),
111
+ uncaught: (error, origin = "uncaughtException") => {
112
+ for (const handler of [...uncaughtHandlers]) handler(error, origin);
113
+ },
103
114
  get exits() {
104
115
  return [...exits];
105
116
  },
106
117
  get handlers() {
107
- let count = 0;
118
+ let count = uncaughtHandlers.size;
108
119
  for (const set of handlers.values()) count += set.size;
109
120
  return count;
110
121
  },