@mark1russell7/algebra 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +67 -2
- package/build/index.d.ts +386 -0
- package/build/index.js +916 -0
- package/build/index.js.map +1 -0
- package/package.json +66 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mark Russell
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,68 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mark1russell7/algebra
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
State machines as data, and the timer algebra over them. A machine document gives the states, transitions, timers and knobs of one machine, for example Linux TCP. The algebra then gives how long each timer operates, in exact rationals, from the values of the knobs. It also gives which timer finds a failure first, and when a connection moves again after a stall.
|
|
4
|
+
|
|
5
|
+
## The machine document
|
|
6
|
+
|
|
7
|
+
A machine document has the format `mark1russell7.machine/1`, and `machineSchema` accepts it.
|
|
8
|
+
|
|
9
|
+
- **States and transitions.** A transition goes from one or more states to a state, on one or more events. The state `"*"` is each state that is not final.
|
|
10
|
+
- **Timers.** A timer has a duration, the events that arm it, the events that cancel it, and the event that it fires. It can also have a lateness and an early bound.
|
|
11
|
+
- **Durations.** A duration is a constant, a knob, arithmetic over knobs (`+ - * /`, `min`, `max`, `floor`, `ceil`), or a named model.
|
|
12
|
+
- **Knobs.** Each knob has its key in its system, its scope, its unit and its default. A switch or a choice has the unit `null`.
|
|
13
|
+
- **Backoff timers.** A backoff timer starts again after it fires, and each wait is longer than the last. Its waits read `fired`: the number of times that it fired after a reset.
|
|
14
|
+
- **Layers.** A machine can operate on another machine (`over`): a driver on its kernel socket. Each state of the upper machine is on a state of the lower machine. Some knobs of the upper machine set knobs of the lower machine. The end of the lower machine arrives as an event of the upper machine.
|
|
15
|
+
- **Realizations.** A machine can give the time of a mechanism (`realizes`): one of its timers, or a time of its own over its knobs.
|
|
16
|
+
|
|
17
|
+
`machineProblems` finds the problems of consistency in a document. For example, a transition names a state, an event or a timer that does not exist.
|
|
18
|
+
|
|
19
|
+
## The algebra
|
|
20
|
+
|
|
21
|
+
- **Exact values.** `evaluate` and `timerOf` give a duration in the unit of its document, with exact rational arithmetic. Thus 0.2 s × 1023 is 204.6 s. A knob without a value gives an unknown result that names the knob. A knob that nothing sets gives a duration without an end.
|
|
22
|
+
- **Models.** A model is the formula of an implementation. The package has these models:
|
|
23
|
+
- `linux.retrans-budget`: the retransmission give-up of the kernel (`tcp_model_timeout`). At the defaults it is 924.6 s.
|
|
24
|
+
- `linux.retrans-step`: how late the give-up comes after its budget, at the real RTO of the path.
|
|
25
|
+
- `linux.rto-wait` and `linux.rto-wait-lateness`: one wait of the retransmission timer, from the tail loss probe, and its rounding.
|
|
26
|
+
- `linux.keepalive-lateness`, `linux.wheel` and `linux.jiffy`: the rounding of the timer wheel at the HZ of the kernel.
|
|
27
|
+
- `linux.syn-giveup`: the SYN give-up of 6.5 and later, with linear timeouts. At the defaults it is 131 s.
|
|
28
|
+
- `ioredis.retry-base`: the reconnect delay of ioredis 6, min(2^(times − 1) × 50, 5000) ms.
|
|
29
|
+
- `linux.rto-wait-reverted` and `linux.retrans-step-reverted`: the retransmissions when each one gets an ICMP host or net unreachable. The revert of RFC 6069 (`tcp_ld_RTO_revert`) takes back each doubling, thus each wait is one RTO.
|
|
30
|
+
- **Detection.** `detection` gives the minimum over the timers that are live in the situation of the connection. With no live timer, the failure is silent at this level. `stackedDetection` adds the timers of the machine below.
|
|
31
|
+
- **Manifestations.** A manifestation tells which incoming events a failure lets through. A black hole lets nothing through. The kernel of a frozen process continues to send ACKs, which stop keepalive before it fires. A manifestation can also tell:
|
|
32
|
+
- the events that the failure sends one time (`delivers`), for example the FIN of a process that stopped with SIGKILL. Such an event detects the failure at once (`Detection.delivered`).
|
|
33
|
+
- the errno that replaces ETIMEDOUT at a timeout (`errno`). An ICMP error on an established socket is a soft error, and the timeout gives it (`errnoOf`).
|
|
34
|
+
- the durations that the failure changes, by timer (`replaces`). `timerUnder` gives the bounds of a timer under the failure.
|
|
35
|
+
- **Recovery.** `recovery` tells when a backoff timer moves a connection again after a stall. The connection moves at the first firing at the end of the stall or after it. A stall of 3.5 s on Linux TCP holds a request for approximately 6.5 s.
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
pnpm add @mark1russell7/algebra zod
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The package uses [`@mark1russell7/quantity`](https://www.npmjs.com/package/@mark1russell7/quantity) for each amount, and both packages use `zod` as a peer dependency.
|
|
44
|
+
|
|
45
|
+
## Example
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import { detection, machineSchema, timerOf } from "@mark1russell7/algebra";
|
|
49
|
+
|
|
50
|
+
const tcp = machineSchema.parse(linuxTcpDocument);
|
|
51
|
+
const values = (name: string) =>
|
|
52
|
+
({
|
|
53
|
+
keepidle: { value: 7200, unit: "s" },
|
|
54
|
+
keepintvl: { value: 75, unit: "s" },
|
|
55
|
+
keepcnt: { value: 9, unit: "count" },
|
|
56
|
+
})[name];
|
|
57
|
+
|
|
58
|
+
timerOf(tcp, "keepalive", values).duration; // { value: 7875, unit: "s" }
|
|
59
|
+
|
|
60
|
+
const idle = { state: "ESTABLISHED", inFlight: false };
|
|
61
|
+
detection(tcp, idle, { name: "blackhole", passes: [] }, values).first?.timer; // "keepalive"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Tests
|
|
65
|
+
|
|
66
|
+
`pnpm --filter @mark1russell7/algebra test` starts the tests. Four machine documents are their fixtures: Linux TCP, conntrack TCP, the Redis server and ioredis. The tests compute the defaults of Linux 6.6 and the rounding of the timer wheel. They also compute the scaled cells of the harness, the backoff waits, recovery after a stall, and detection for each fault.
|
|
67
|
+
|
|
68
|
+
`pnpm --filter @mark1russell7/algebra build` writes the package for npm into `build/`.
|
package/build/index.d.ts
ADDED
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
import { Extent, Quantity, Rational, Unknown } from "@mark1russell7/quantity";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
//#region src/machine.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* `mark1russell7.machine/1` is a state machine as data.
|
|
6
|
+
*
|
|
7
|
+
* One document describes one machine, and three readers share it: the conformance checker
|
|
8
|
+
* (states, transitions, observer mappings), the algebra (the closed forms of timers over knobs)
|
|
9
|
+
* and the simulator (the arm, cancel and fire events of timers). The format is small on purpose:
|
|
10
|
+
* no hierarchy, no actions other than `emits`, and guards as documented text.
|
|
11
|
+
*/
|
|
12
|
+
/** A unit is a unit that @mark1russell7/quantity stores: a time or a count, which is all that the timers of a machine read. */
|
|
13
|
+
type Unit = string;
|
|
14
|
+
/** An expression is a duration: a constant, a knob, arithmetic over knobs, or a named model of them. */
|
|
15
|
+
type Expr = {
|
|
16
|
+
readonly const: number;
|
|
17
|
+
readonly unit: Unit;
|
|
18
|
+
} | {
|
|
19
|
+
readonly knob: string;
|
|
20
|
+
readonly unit: Unit;
|
|
21
|
+
} | {
|
|
22
|
+
readonly expr: string;
|
|
23
|
+
readonly unit: Unit;
|
|
24
|
+
} | {
|
|
25
|
+
readonly model: string;
|
|
26
|
+
readonly knobs: readonly string[];
|
|
27
|
+
readonly unit: Unit;
|
|
28
|
+
};
|
|
29
|
+
/** A timer has a duration, the events that arm and cancel it, and the event that it fires. */
|
|
30
|
+
interface Timer {
|
|
31
|
+
readonly duration: Expr;
|
|
32
|
+
readonly lateness?: Expr | undefined;
|
|
33
|
+
readonly early?: Expr | undefined;
|
|
34
|
+
readonly arms: readonly string[];
|
|
35
|
+
readonly cancels?: readonly string[] | undefined;
|
|
36
|
+
readonly fires: string;
|
|
37
|
+
/**
|
|
38
|
+
* A backoff timer starts again after it fires, and each wait is longer than the last. Examples
|
|
39
|
+
* are the retransmission timer of the kernel and the reconnect of a driver. Its duration, lateness and
|
|
40
|
+
* early bound are those of one wait. They can read `fired`: the number of times that it fired
|
|
41
|
+
* after the last of its `resets`.
|
|
42
|
+
*/
|
|
43
|
+
readonly backoff?: {
|
|
44
|
+
readonly resets: readonly string[];
|
|
45
|
+
} | undefined;
|
|
46
|
+
readonly note?: string | undefined;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* This name is what the waits of a backoff timer read for the number of times that it fired after
|
|
50
|
+
* a reset, from 0. It is not a knob, because nothing sets it. It is the count of the timer itself.
|
|
51
|
+
*/
|
|
52
|
+
export declare const FIRED = "fired";
|
|
53
|
+
/**
|
|
54
|
+
* A realization tells how long a mechanism takes where the machine operates. It is one of the
|
|
55
|
+
* timers of the machine, whole, or a time of its own over the knobs of the machine. It has a
|
|
56
|
+
* lateness and an early bound, as a timer has. The idle refresh of the Redis server is the idle
|
|
57
|
+
* time of its keepalive, rounded on the timer wheel of the kernel. That is the first firing of its
|
|
58
|
+
* keepalive timer, not the whole timer.
|
|
59
|
+
*/
|
|
60
|
+
type Realization = {
|
|
61
|
+
readonly timer: string;
|
|
62
|
+
} | {
|
|
63
|
+
readonly duration: Expr;
|
|
64
|
+
readonly lateness?: Expr | undefined;
|
|
65
|
+
readonly early?: Expr | undefined;
|
|
66
|
+
readonly note?: string | undefined;
|
|
67
|
+
};
|
|
68
|
+
/**
|
|
69
|
+
* An over tells the machine that this machine operates on, and how: a driver on its kernel socket.
|
|
70
|
+
* Each state of this machine is on a state of the lower machine. Some knobs of this machine set
|
|
71
|
+
* knobs of the lower machine. The end of the lower machine arrives as an event of this machine.
|
|
72
|
+
*
|
|
73
|
+
* The driver ioredis 6 sets the keepalive idle time of the kernel from its keepAlive option,
|
|
74
|
+
* through setKeepAlive of Node. That function also sets the probe interval and count. The driver
|
|
75
|
+
* learns of the end of the socket as stream.close.
|
|
76
|
+
*/
|
|
77
|
+
interface Over {
|
|
78
|
+
/** This identifier is the machine below, as a graph identifies its document. */
|
|
79
|
+
readonly machine: string;
|
|
80
|
+
/** This map gives the state of the lower machine that each state of this machine is on. */
|
|
81
|
+
readonly states: Readonly<Record<string, string>>;
|
|
82
|
+
/** These are the knobs of the lower machine that this machine sets, by their lower names, over its own knobs. */
|
|
83
|
+
readonly sets: Readonly<Record<string, Expr>>;
|
|
84
|
+
/** This event is the event of this machine that the end of the lower machine arrives as. */
|
|
85
|
+
readonly ends: string;
|
|
86
|
+
readonly note?: string | undefined;
|
|
87
|
+
}
|
|
88
|
+
/** A transition goes from one or more states to a state, on one or more events. */
|
|
89
|
+
interface TransitionDef {
|
|
90
|
+
readonly id: string;
|
|
91
|
+
readonly from: string | readonly string[];
|
|
92
|
+
readonly to: string;
|
|
93
|
+
readonly on: string | readonly string[];
|
|
94
|
+
readonly guard?: string | undefined;
|
|
95
|
+
readonly timer?: string | undefined;
|
|
96
|
+
readonly emits?: readonly string[] | undefined;
|
|
97
|
+
readonly errno?: string | undefined;
|
|
98
|
+
readonly note?: string | undefined;
|
|
99
|
+
readonly source?: string | undefined;
|
|
100
|
+
}
|
|
101
|
+
/** A vantage is the layer that a machine is seen from. */
|
|
102
|
+
type Vantage = "wire" | "kernel" | "middlebox" | "proxy" | "driver" | "server" | "canary" | "injector" | "self";
|
|
103
|
+
/** A machine is one state machine document. */
|
|
104
|
+
interface Machine {
|
|
105
|
+
readonly format: "mark1russell7.machine/1";
|
|
106
|
+
readonly id: string;
|
|
107
|
+
readonly title: string;
|
|
108
|
+
readonly layer: Vantage;
|
|
109
|
+
readonly version: string;
|
|
110
|
+
readonly conditions?: Readonly<Record<string, string>> | undefined;
|
|
111
|
+
readonly sources: ReadonlyArray<{
|
|
112
|
+
readonly ref: string;
|
|
113
|
+
readonly rung: "normative" | "implemented" | "documented" | "observed" | "derived";
|
|
114
|
+
readonly note?: string | undefined;
|
|
115
|
+
}>;
|
|
116
|
+
readonly states: Readonly<Record<string, {
|
|
117
|
+
readonly initial?: boolean | undefined;
|
|
118
|
+
readonly final?: boolean | undefined;
|
|
119
|
+
readonly pseudo?: boolean | undefined;
|
|
120
|
+
readonly note?: string | undefined;
|
|
121
|
+
}>>;
|
|
122
|
+
readonly events: Readonly<Record<string, {
|
|
123
|
+
readonly kind: "rx" | "tx" | "app" | "timer" | "local" | "packet" | "peer";
|
|
124
|
+
readonly note?: string | undefined;
|
|
125
|
+
}>>;
|
|
126
|
+
readonly knobs: Readonly<Record<string, {
|
|
127
|
+
readonly key: string;
|
|
128
|
+
readonly scope: string;
|
|
129
|
+
readonly unit: Unit | null;
|
|
130
|
+
readonly default: number | null;
|
|
131
|
+
readonly note?: string | undefined;
|
|
132
|
+
}>>;
|
|
133
|
+
readonly timers: Readonly<Record<string, Timer>>;
|
|
134
|
+
/** These are the mechanisms whose time this machine gives, by the identifier of each mechanism. */
|
|
135
|
+
readonly realizes?: Readonly<Record<string, Realization>> | undefined;
|
|
136
|
+
/** This is the machine that this machine operates on, for a machine on another machine. */
|
|
137
|
+
readonly over?: Over | undefined;
|
|
138
|
+
readonly transitions: readonly TransitionDef[];
|
|
139
|
+
readonly observe?: Readonly<Record<string, {
|
|
140
|
+
readonly states: Readonly<Record<string, string>>;
|
|
141
|
+
readonly hides?: readonly string[] | undefined;
|
|
142
|
+
readonly fidelity: "complete" | "sampled" | "lossy" | "derived";
|
|
143
|
+
readonly note?: string | undefined;
|
|
144
|
+
}>> | undefined;
|
|
145
|
+
readonly generated?: {
|
|
146
|
+
readonly from: string;
|
|
147
|
+
readonly by: string;
|
|
148
|
+
} | undefined;
|
|
149
|
+
}
|
|
150
|
+
/** This schema accepts a machine document. */
|
|
151
|
+
export declare const machineSchema: z.ZodType<Machine>;
|
|
152
|
+
/** This function gives one value or many values as an array. */
|
|
153
|
+
export declare const arr: <T>(value: T | readonly T[]) => readonly T[];
|
|
154
|
+
/** This function gives the knobs that a duration reads, by the names of the machine for them. */
|
|
155
|
+
export declare const exprKnobs: (e: Expr) => string[];
|
|
156
|
+
/** This function tells if a duration reads the number of times that its timer fired, as the waits of a backoff do. */
|
|
157
|
+
export declare const readsFired: (e: Expr) => boolean;
|
|
158
|
+
/** This function gives the states that a transition leaves. The state "*" is each state that is not final. */
|
|
159
|
+
export declare const fromStates: (m: Machine, from: string | readonly string[]) => string[];
|
|
160
|
+
/**
|
|
161
|
+
* This function gives the problems in the consistency of a document. Each state, event, timer and
|
|
162
|
+
* knob that it refers to must exist, and it must have an initial state. A reader refuses a
|
|
163
|
+
* machine with problems, and does not draw half of it.
|
|
164
|
+
*/
|
|
165
|
+
export declare const machineProblems: (m: Machine) => string[];
|
|
166
|
+
//#endregion
|
|
167
|
+
//#region src/algebra.d.ts
|
|
168
|
+
/**
|
|
169
|
+
* This module has the closed forms of the algebra. They give the duration of a timer of a
|
|
170
|
+
* machine, and how late and how early it can fire, from the values of its knobs.
|
|
171
|
+
*
|
|
172
|
+
* A machine document writes each duration in one of four forms (`machine.ts`): a constant, a knob,
|
|
173
|
+
* arithmetic over its knobs, or a named model. The arithmetic uses the value of each knob in the
|
|
174
|
+
* unit that the document gives to that knob. Thus `tcp_keepalive / 3` of Redis divides whole
|
|
175
|
+
* seconds, as Redis does. A model is the formula of the implementation itself, for example the
|
|
176
|
+
* retransmission budget of the kernel. The values are exact rationals, not floats: 0.2 s × 1023
|
|
177
|
+
* is 204.6 s, not 204.60000000000002.
|
|
178
|
+
*
|
|
179
|
+
* A knob without a value makes the result unknown, and the result names the knob. A knob that
|
|
180
|
+
* nothing sets (no bound) makes a duration without an end.
|
|
181
|
+
*/
|
|
182
|
+
/** This function gives the value of each knob, by the name of the machine for it: an amount, no bound, or unknown and the reason. */
|
|
183
|
+
type KnobValues = (name: string) => Extent | Unknown | undefined;
|
|
184
|
+
/** Timer bounds tell how long a timer operates, how late it can fire and how early, each in the unit of its document. */
|
|
185
|
+
interface TimerBounds {
|
|
186
|
+
readonly duration: Extent | Unknown;
|
|
187
|
+
readonly lateness?: Extent | Unknown | undefined;
|
|
188
|
+
readonly early?: Extent | Unknown | undefined;
|
|
189
|
+
}
|
|
190
|
+
/** A node is the arithmetic of a document, after the parse. */
|
|
191
|
+
type Node = {
|
|
192
|
+
readonly op: "num";
|
|
193
|
+
readonly n: Rational;
|
|
194
|
+
} | {
|
|
195
|
+
readonly op: "knob";
|
|
196
|
+
readonly name: string;
|
|
197
|
+
} | {
|
|
198
|
+
readonly op: "+" | "-" | "*" | "/";
|
|
199
|
+
readonly a: Node;
|
|
200
|
+
readonly b: Node;
|
|
201
|
+
} | {
|
|
202
|
+
readonly op: "neg";
|
|
203
|
+
readonly a: Node;
|
|
204
|
+
} | {
|
|
205
|
+
readonly op: "min" | "max" | "floor" | "ceil";
|
|
206
|
+
readonly args: readonly Node[];
|
|
207
|
+
};
|
|
208
|
+
/** This function parses the arithmetic of a document, or it throws an error that tells where the text stops making sense. */
|
|
209
|
+
export declare const parseExpr: (text: string) => Node;
|
|
210
|
+
/**
|
|
211
|
+
* This function evaluates one duration of a timer of a machine, in the unit that its document
|
|
212
|
+
* gives it. The waits of a backoff timer read `fired`, which tells which wait.
|
|
213
|
+
*/
|
|
214
|
+
export declare const evaluate: (doc: Machine, expr: Expr, values: KnobValues, fired?: number) => Extent | Unknown;
|
|
215
|
+
/**
|
|
216
|
+
* This function gives the bounds of a timer of a machine: how long it operates, how late it can
|
|
217
|
+
* fire, how early. For a backoff timer, it gives one of its waits: the wait after `fired` firings.
|
|
218
|
+
*/
|
|
219
|
+
export declare const timerOf: (doc: Machine, timer: string, values: KnobValues, fired?: number) => TimerBounds;
|
|
220
|
+
/** A firing is one firing of a backoff timer, after `fired` firings: its time from the arming. */
|
|
221
|
+
interface Firing {
|
|
222
|
+
readonly fired: number;
|
|
223
|
+
/** This time is the sum of the waits to this firing, each less how early it can fire. */
|
|
224
|
+
readonly low: Quantity;
|
|
225
|
+
/** This time is the sum of the waits to this firing, each plus how late it can fire. */
|
|
226
|
+
readonly high: Quantity;
|
|
227
|
+
}
|
|
228
|
+
/** A recovery tells when the firings of a backoff timer move a connection again after a stall. */
|
|
229
|
+
interface Recovery {
|
|
230
|
+
/** These are its firings from its arming, up to the first one that surely comes after the end of the stall. */
|
|
231
|
+
readonly firings: readonly Firing[];
|
|
232
|
+
/**
|
|
233
|
+
* These are the firings that can be the first after the end of the stall. There is more than one
|
|
234
|
+
* when the end falls in the bounds of a firing: that firing can come before the end or after it.
|
|
235
|
+
*/
|
|
236
|
+
readonly first: readonly number[];
|
|
237
|
+
/** This time is the earliest time of the first firing after the end of the stall, from the arming. */
|
|
238
|
+
readonly low: Quantity;
|
|
239
|
+
/** This time is the latest time of that firing, from the arming. */
|
|
240
|
+
readonly high: Quantity;
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* This function gives the recovery from a stall. A backoff timer continues to fire through a
|
|
244
|
+
* stall, and what each firing sends gets through only after the stall ends. Thus the connection
|
|
245
|
+
* moves again at the first firing at the end or after it. That firing can be most of a wait after
|
|
246
|
+
* the end. A stall that stops immediately after one firing costs almost all of the next, longer
|
|
247
|
+
* wait.
|
|
248
|
+
*
|
|
249
|
+
* The stall counts from the arming of the timer, which is the send that the stall first lost. The
|
|
250
|
+
* waits add, and so do how early and how late each can fire.
|
|
251
|
+
*/
|
|
252
|
+
export declare const recovery: (doc: Machine, timer: string, values: KnobValues, stall: Extent) => Recovery | Unknown;
|
|
253
|
+
/**
|
|
254
|
+
* This function gives how long a mechanism takes where a machine operates, from the realization
|
|
255
|
+
* of its document. The realization is one of its timers, whole, or its own duration, lateness and
|
|
256
|
+
* early bound over the knobs of the machine. It gives undefined when the document does not realize the mechanism.
|
|
257
|
+
*/
|
|
258
|
+
export declare const realizationOf: (doc: Machine, mechanism: string, values: KnobValues) => TimerBounds | undefined;
|
|
259
|
+
/** This function gives the knobs that a realization reads, by the names of the machine for them. */
|
|
260
|
+
export declare const realizationKnobs: (doc: Machine, mechanism: string) => string[];
|
|
261
|
+
/** This function gives what in a document the algebra cannot read: arithmetic that does not parse, or a model that it does not have. */
|
|
262
|
+
export declare const algebraProblems: (doc: Machine) => string[];
|
|
263
|
+
/** This function gives the source of the formula of a named model, for a reader of a result. */
|
|
264
|
+
export declare const modelSource: (name: string) => string | undefined;
|
|
265
|
+
/**
|
|
266
|
+
* A manifestation is what a failure lets back to the machine: the incoming events that continue
|
|
267
|
+
* to arrive while it lasts. A black hole lets nothing back. The kernel of a frozen process
|
|
268
|
+
* continues to acknowledge what it gets and to answer keepalive probes, thus its ACKs continue to
|
|
269
|
+
* arrive.
|
|
270
|
+
*/
|
|
271
|
+
interface Manifestation {
|
|
272
|
+
readonly name: string;
|
|
273
|
+
readonly passes: readonly string[];
|
|
274
|
+
/**
|
|
275
|
+
* These are the events that the failure itself sends one time, for example the FIN of a process
|
|
276
|
+
* that stopped with SIGKILL. A delivered event that a transition takes from the state of the connection detects the
|
|
277
|
+
* failure at once.
|
|
278
|
+
*/
|
|
279
|
+
readonly delivers?: readonly string[] | undefined;
|
|
280
|
+
/**
|
|
281
|
+
* This errno replaces ETIMEDOUT when one of these timers gives up. Linux keeps an ICMP error on
|
|
282
|
+
* an established socket as a soft error, and the timeout reports it (tcp_write_err). An ICMP
|
|
283
|
+
* counts only when it quotes a segment in the window (tcp_v4_err). A retransmission is in the
|
|
284
|
+
* window. A keepalive probe uses the sequence number before snd_una, thus its ICMP does not count.
|
|
285
|
+
*/
|
|
286
|
+
readonly errno?: {
|
|
287
|
+
readonly errno: string;
|
|
288
|
+
readonly timers: readonly string[];
|
|
289
|
+
} | undefined;
|
|
290
|
+
/**
|
|
291
|
+
* These are the durations that the failure changes, by timer. For example, an ICMP host
|
|
292
|
+
* unreachable for each retransmission reverts the backoff of the retransmission timer.
|
|
293
|
+
*/
|
|
294
|
+
readonly replaces?: Readonly<Record<string, {
|
|
295
|
+
readonly duration?: Expr;
|
|
296
|
+
readonly lateness?: Expr;
|
|
297
|
+
readonly early?: Expr;
|
|
298
|
+
}>> | undefined;
|
|
299
|
+
}
|
|
300
|
+
/** A situation is the activity of the connection when the failure started. */
|
|
301
|
+
interface Situation {
|
|
302
|
+
/** This name is the state of the machine, for example ESTABLISHED. */
|
|
303
|
+
readonly state: string;
|
|
304
|
+
/** This flag tells if it had sent data that the peer had not acknowledged. */
|
|
305
|
+
readonly inFlight: boolean;
|
|
306
|
+
}
|
|
307
|
+
/** A detector is a timer that can still fire, how long it operates, and the event that it fires. */
|
|
308
|
+
interface Detector {
|
|
309
|
+
readonly timer: string;
|
|
310
|
+
readonly fires: string;
|
|
311
|
+
readonly duration: Extent | Unknown;
|
|
312
|
+
/** This identifier is the machine below whose timer it is, when the timer is not of the machine itself (`over`). */
|
|
313
|
+
readonly beneath?: string | undefined;
|
|
314
|
+
}
|
|
315
|
+
/** A detection is the result of the minimum over the live detectors. */
|
|
316
|
+
interface Detection {
|
|
317
|
+
/** These are the timers that can still fire, the soonest first. */
|
|
318
|
+
readonly detectors: readonly Detector[];
|
|
319
|
+
/** This detector is the first to fire, or null when none can fire in a known time: a silent failure. */
|
|
320
|
+
readonly first: Detector | null;
|
|
321
|
+
/** These are the live detectors whose time nothing gives. Then `first` is only an upper bound. */
|
|
322
|
+
readonly unsettled: readonly string[];
|
|
323
|
+
/** These are the timers that are armed but cannot fire, and the reason for each. */
|
|
324
|
+
readonly held: ReadonlyArray<{
|
|
325
|
+
readonly timer: string;
|
|
326
|
+
readonly why: string;
|
|
327
|
+
}>;
|
|
328
|
+
/**
|
|
329
|
+
* These are the events that the failure delivers and that a transition takes from the state:
|
|
330
|
+
* each detects the failure at once, before any timer. The errno is the errno of the transition,
|
|
331
|
+
* or null for an end of file.
|
|
332
|
+
*/
|
|
333
|
+
readonly delivered: ReadonlyArray<{
|
|
334
|
+
readonly event: string;
|
|
335
|
+
readonly to: string;
|
|
336
|
+
readonly errno: string | null;
|
|
337
|
+
}>;
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* This function gives the detection: the minimum over the detectors that are live in the
|
|
341
|
+
* situation. The entry to the state arms a timer, and so does what the failure causes: data in
|
|
342
|
+
* flight without an acknowledgment gets a retransmission. An event that occurs cancels a timer.
|
|
343
|
+
*
|
|
344
|
+
* An event that arms the timer again, and that the failure continues to let through, stops it
|
|
345
|
+
* before it fires. For example, the kernel of a frozen process answers each keepalive probe.
|
|
346
|
+
* Without a live detector, the failure is silent at the level of this machine. Only something
|
|
347
|
+
* above it, the timeout of an application or a heartbeat, can find it. The result is only as good
|
|
348
|
+
* as the events that the document names.
|
|
349
|
+
*/
|
|
350
|
+
export declare const detection: (doc: Machine, situation: Situation, manifestation: Manifestation, values: KnobValues) => Detection;
|
|
351
|
+
/**
|
|
352
|
+
* This function gives the bounds of a timer of a machine under a failure: its own bounds, with each
|
|
353
|
+
* duration that the manifestation replaces.
|
|
354
|
+
*/
|
|
355
|
+
export declare const timerUnder: (doc: Machine, timer: string, values: KnobValues, manifestation: Manifestation, fired?: number) => TimerBounds;
|
|
356
|
+
/**
|
|
357
|
+
* This function gives the errno of a detection by a timer: the errno of the transition that its
|
|
358
|
+
* event takes from the state. A soft error of the manifestation replaces ETIMEDOUT, but only for
|
|
359
|
+
* the timers whose segments its ICMP quotes in the window.
|
|
360
|
+
*/
|
|
361
|
+
export declare const errnoOf: (doc: Machine, state: string, detector: {
|
|
362
|
+
readonly timer: string;
|
|
363
|
+
readonly fires: string;
|
|
364
|
+
}, manifestation: Manifestation) => string | null;
|
|
365
|
+
/** This function gives the transition that a machine takes from a state on an event, by its document. */
|
|
366
|
+
export declare const transitionOn: (doc: Machine, state: string, event: string) => TransitionDef | undefined;
|
|
367
|
+
/**
|
|
368
|
+
* This function gives the values of a machine for the machine that it operates on. These are the
|
|
369
|
+
* knobs that it sets, evaluated over its own knobs, and the other knobs of the lower machine. The
|
|
370
|
+
* keepAlive of ioredis at 5000 ms is the keepidle of the kernel at 5 s.
|
|
371
|
+
*/
|
|
372
|
+
export declare const overValues: (upper: Machine, upperValues: KnobValues, lowerValues: KnobValues) => KnobValues;
|
|
373
|
+
/**
|
|
374
|
+
* This function gives the detection through the machine that a machine operates on. The detectors
|
|
375
|
+
* of the lower machine are live in the state below the state of this machine. They use the knobs
|
|
376
|
+
* that this machine sets.
|
|
377
|
+
*
|
|
378
|
+
* Each one reaches this machine as the event that the end of the lower
|
|
379
|
+
* machine gives. They are beside the timers of this machine, and the first of all of them is the
|
|
380
|
+
* first detection. A failure lets nothing new through to a machine above the socket, only the end
|
|
381
|
+
* of the socket. Thus the timers of this machine see only what its state arms.
|
|
382
|
+
*/
|
|
383
|
+
export declare const stackedDetection: (upper: Machine, lower: Machine, situation: Situation, manifestation: Manifestation, upperValues: KnobValues, lowerValues: KnobValues) => Detection;
|
|
384
|
+
//#endregion
|
|
385
|
+
export type { Detection, Detector, Expr, Firing, KnobValues, Machine, Manifestation, Node, Over, Realization, Recovery, Situation, Timer, TimerBounds, TransitionDef, Unit, Vantage };
|
|
386
|
+
//# sourceMappingURL=index.d.ts.map
|