@mark1russell7/algebra 0.8.5 → 0.8.6
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 +66 -2
- package/build/clock-BPLEBlb6.d.ts +48 -0
- package/build/clock.d.ts +2 -47
- package/build/index.d.ts +2 -273
- package/build/index.js +4 -1009
- package/build/index.js.map +1 -1
- package/build/replay.js +24 -1
- package/build/replay.js.map +1 -0
- package/build/run-DTmtHPlK.js +1142 -0
- package/build/run-DTmtHPlK.js.map +1 -0
- package/build/run-Dol_e0Xa.d.ts +330 -0
- package/build/run.d.ts +2 -0
- package/build/run.js +1 -0
- package/build/states-DXQbSbfM.js +13 -0
- package/build/states-DXQbSbfM.js.map +1 -0
- package/package.json +5 -1
- package/build/replay-CGyXKaW3.js +0 -33
- package/build/replay-CGyXKaW3.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @mark1russell7/algebra
|
|
2
2
|
|
|
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.
|
|
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. `runMachine` operates a live instance of a document on a clock.
|
|
4
4
|
|
|
5
5
|
## The machine document
|
|
6
6
|
|
|
@@ -61,6 +61,62 @@ const problems = replay(CONNECTION_MACHINE, recorded, { machine: CONNECTION_MACH
|
|
|
61
61
|
// for example ["c1: app.machine.connection has no transition from OPEN on open to OPEN"]
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
+
## The run
|
|
65
|
+
|
|
66
|
+
`runMachine(doc, options)` starts a live instance of a machine document on a clock. It gives the run: `state`, `send(event)` and `stop()`. The run follows these rules:
|
|
67
|
+
|
|
68
|
+
- **Transitions.** `send(event)` takes the transition of the document from the state on the event, and gives it. It gives undefined when the state has no transition on the event. An event that the document does not name is an error.
|
|
69
|
+
- **Timers.** In sequence, these events operate the timers: the event, each event that the transition emits, and `enter:<to>`. A transition to the state that it leaves also enters that state again. An event without a transition also operates the timers.
|
|
70
|
+
- **Arms and cancels.** An event of `cancels` stops a timer. An event of `arms` starts it again from its full duration. An event in the two lists stops the timer, as in `detection`.
|
|
71
|
+
- **Durations.** The run reads each duration from `timerOf`, with the knob values of the options or the defaults of the knobs. It converts the duration to milliseconds exactly. A duration with no bound, for example a knob at its `off` value, starts no timer.
|
|
72
|
+
- **Backoff timers.** A backoff timer starts again after it fires, with its next wait. An event of its `resets` sets its count to 0.
|
|
73
|
+
- **The start and the end.** At the start, the instance enters its start state, thus `enter:<state>` can arm a timer. The entry to a final state stops each timer. `stop()` stops each timer, and after it each send does nothing.
|
|
74
|
+
- **A record for the replay.** `onTransition` gets each transition in the form that `replay` reads. Thus a recorded run replays against its document with no problem.
|
|
75
|
+
|
|
76
|
+
The example is the lock of an app. The lock arms after 2000 ms with no load of a page. Each stop of a load starts that time again.
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
import type { Machine, Transition } from "@mark1russell7/algebra";
|
|
80
|
+
import { fakeClock } from "@mark1russell7/algebra/clock";
|
|
81
|
+
import { replay } from "@mark1russell7/algebra/replay";
|
|
82
|
+
import { runMachine } from "@mark1russell7/algebra/run";
|
|
83
|
+
|
|
84
|
+
const LOCK: Machine = {
|
|
85
|
+
format: "mark1russell7.machine/1",
|
|
86
|
+
id: "app.machine.lock",
|
|
87
|
+
title: "A lock that arms after a quiet time",
|
|
88
|
+
layer: "self",
|
|
89
|
+
version: "1.0.0",
|
|
90
|
+
sources: [{ ref: "the app", rung: "implemented" }],
|
|
91
|
+
states: { loading: { initial: true }, armed: {} },
|
|
92
|
+
events: { start: { kind: "app" }, stop: { kind: "app" }, press: { kind: "app" }, settled: { kind: "timer" }, reload: { kind: "app" } },
|
|
93
|
+
knobs: { settle: { key: "settle", scope: "lock", unit: "ms", default: 2000 } },
|
|
94
|
+
timers: {
|
|
95
|
+
settle: { duration: { knob: "settle", unit: "ms" }, arms: ["stop"], cancels: ["start", "press", "reload"], fires: "settled" },
|
|
96
|
+
},
|
|
97
|
+
transitions: [
|
|
98
|
+
{ id: "lock.arm", from: "loading", to: "armed", on: ["press", "settled"] },
|
|
99
|
+
{ id: "lock.reload", from: "armed", to: "loading", on: "reload" },
|
|
100
|
+
],
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
const clock = fakeClock();
|
|
104
|
+
const trace: Transition[] = [];
|
|
105
|
+
const lock = runMachine(LOCK, { clock, onTransition: (transition) => trace.push(transition) });
|
|
106
|
+
lock.send("start");
|
|
107
|
+
lock.send("stop"); // a load, at 0 ms
|
|
108
|
+
await clock.advance(1500);
|
|
109
|
+
lock.send("start");
|
|
110
|
+
lock.send("stop"); // a second load, 1500 ms later: the time starts again
|
|
111
|
+
await clock.advance(1999);
|
|
112
|
+
lock.state; // "loading"
|
|
113
|
+
await clock.advance(1);
|
|
114
|
+
lock.state; // "armed", 2000 ms after the last load
|
|
115
|
+
replay(LOCK, trace); // []
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
An app gives `realClock` of `@mark1russell7/algebra/clock` in place of the fake clock. The entry `@mark1russell7/algebra/run` does not import zod, thus a client in a browser can operate its own machines.
|
|
119
|
+
|
|
64
120
|
## The clock
|
|
65
121
|
|
|
66
122
|
`@mark1russell7/algebra/clock` gives the clock of a runtime and a fake clock for tests. The entry imports nothing: no `node:` module, no zod and no other package. Thus a client in a browser can use it. The service and collections read time through it.
|
|
@@ -90,6 +146,14 @@ The package uses [`@mark1russell7/quantity`](https://www.npmjs.com/package/@mark
|
|
|
90
146
|
|
|
91
147
|
The root entry has the machine types, the consistency checks and the algebra. It does not import `zod`.
|
|
92
148
|
|
|
149
|
+
| Entry | What it has | `zod` |
|
|
150
|
+
| --- | --- | --- |
|
|
151
|
+
| `@mark1russell7/algebra` | The machine types, the consistency checks, the algebra, `replay` and `runMachine` | No |
|
|
152
|
+
| `@mark1russell7/algebra/clock` | The clock of a runtime and a fake clock for tests | No |
|
|
153
|
+
| `@mark1russell7/algebra/replay` | The replay of a trace against a machine document | No |
|
|
154
|
+
| `@mark1russell7/algebra/run` | The run of a live instance of a machine document | No |
|
|
155
|
+
| `@mark1russell7/algebra/schema` | `machineSchema`, the schema of a machine document | Yes |
|
|
156
|
+
|
|
93
157
|
The schema is in the entry `@mark1russell7/algebra/schema`. That entry uses `zod` as an optional peer dependency, as `@mark1russell7/quantity/schema` does. An application that does not parse documents can install the package without `zod`.
|
|
94
158
|
|
|
95
159
|
**From 0.7 to 0.8.** The root entry does not give `machineSchema`. Import it from `@mark1russell7/algebra/schema`.
|
|
@@ -118,7 +182,7 @@ detection(tcp, idle, { name: "blackhole", passes: [] }, values).first?.timer; //
|
|
|
118
182
|
|
|
119
183
|
`pnpm --filter @mark1russell7/algebra test` starts the tests. Each test writes its own small machines. The machines are a socket with the timers of a kernel's TCP, a server over the socket, and a driver with a backoff. The tests compute each model at the defaults of Linux 6.6, and the rounding of the timer wheel. They also compute the backoff waits, recovery after a stall, and detection for each fault.
|
|
120
184
|
|
|
121
|
-
The replay tests use a machine with its own names, and they hold the entry of the replay without zod. A test of the root entry fails if the root imports zod.
|
|
185
|
+
The replay tests use a machine with its own names, and they hold the entry of the replay without zod. The tests of the run use a lock, a call with a backoff and a connection with a keepalive, on the fake clock. Each run of the lock with 4 steps or fewer replays against its document with no problem. A test of the root entry fails if the root imports zod.
|
|
122
186
|
|
|
123
187
|
The tests of the algebra on the real documents are in `@mark1russell7/machines`.
|
|
124
188
|
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* This function stops a timer that `Clock.after` started. A second use does nothing. A clock of
|
|
3
|
+
* the platform also gives `unref`: after it, the timer does not keep a Node process alive.
|
|
4
|
+
*/
|
|
5
|
+
type Cancel = (() => void) & {
|
|
6
|
+
readonly unref?: (() => void) | undefined;
|
|
7
|
+
};
|
|
8
|
+
/**
|
|
9
|
+
* A clock gives the monotonic time in milliseconds, and it starts a function after a delay. The
|
|
10
|
+
* runtime reads time only through a clock. Thus a test can give a fake clock, and the timing of
|
|
11
|
+
* the runtime is then exact and repeatable.
|
|
12
|
+
*/
|
|
13
|
+
interface Clock {
|
|
14
|
+
/** This method gives the monotonic time, in milliseconds. A step of the wall clock does not move it. */
|
|
15
|
+
now(): number;
|
|
16
|
+
/** This method starts `run` after `ms` milliseconds, and gives the function that stops it. */
|
|
17
|
+
after(ms: number, run: () => void): Cancel;
|
|
18
|
+
}
|
|
19
|
+
/** These options make a clock of the platform. */
|
|
20
|
+
interface PlatformClockOptions {
|
|
21
|
+
/** True makes each timer not keep a Node process alive. The default is false, as with `setTimeout`. */
|
|
22
|
+
readonly unref?: boolean | undefined;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* This function makes a clock of the platform: `performance.now()` and `setTimeout`. Each cancel
|
|
26
|
+
* that it gives also has `unref`. A delay longer than `setTimeout` takes waits in steps.
|
|
27
|
+
*/
|
|
28
|
+
declare const platformClock: (options?: PlatformClockOptions) => Clock;
|
|
29
|
+
/**
|
|
30
|
+
* This clock reads `performance.now()` and uses `setTimeout`. Its timers do not keep a Node
|
|
31
|
+
* process alive, thus a timer that is not stopped cannot stop the exit of the process.
|
|
32
|
+
*/
|
|
33
|
+
declare const realClock: Clock;
|
|
34
|
+
/** A fake clock moves only when a test tells it to. */
|
|
35
|
+
interface FakeClock extends Clock {
|
|
36
|
+
/** This method moves the clock forward by `ms`, and it starts each timer that comes due, in sequence. */
|
|
37
|
+
advance(ms: number): Promise<void>;
|
|
38
|
+
/**
|
|
39
|
+
* This method moves the clock forward by `ms` and starts no timer, as a blocked event loop does.
|
|
40
|
+
* The next `advance` then starts each timer that came due during the block, late.
|
|
41
|
+
*/
|
|
42
|
+
block(ms: number): void;
|
|
43
|
+
/** This count is the number of timers that are not stopped and not called. */
|
|
44
|
+
readonly pending: number;
|
|
45
|
+
}
|
|
46
|
+
/** This function makes a fake clock. Its time starts at `start` milliseconds. */
|
|
47
|
+
declare const fakeClock: (start?: number) => FakeClock;
|
|
48
|
+
export { fakeClock as a, PlatformClockOptions as i, Clock as n, platformClock as o, FakeClock as r, realClock as s, Cancel as t };
|
package/build/clock.d.ts
CHANGED
|
@@ -1,47 +1,2 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
* the platform also gives `unref`: after it, the timer does not keep a Node process alive.
|
|
4
|
-
*/
|
|
5
|
-
export type Cancel = (() => void) & {
|
|
6
|
-
readonly unref?: (() => void) | undefined;
|
|
7
|
-
};
|
|
8
|
-
/**
|
|
9
|
-
* A clock gives the monotonic time in milliseconds, and it starts a function after a delay. The
|
|
10
|
-
* runtime reads time only through a clock. Thus a test can give a fake clock, and the timing of
|
|
11
|
-
* the runtime is then exact and repeatable.
|
|
12
|
-
*/
|
|
13
|
-
export interface Clock {
|
|
14
|
-
/** This method gives the monotonic time, in milliseconds. A step of the wall clock does not move it. */
|
|
15
|
-
now(): number;
|
|
16
|
-
/** This method starts `run` after `ms` milliseconds, and gives the function that stops it. */
|
|
17
|
-
after(ms: number, run: () => void): Cancel;
|
|
18
|
-
}
|
|
19
|
-
/** These options make a clock of the platform. */
|
|
20
|
-
export interface PlatformClockOptions {
|
|
21
|
-
/** True makes each timer not keep a Node process alive. The default is false, as with `setTimeout`. */
|
|
22
|
-
readonly unref?: boolean | undefined;
|
|
23
|
-
}
|
|
24
|
-
/**
|
|
25
|
-
* This function makes a clock of the platform: `performance.now()` and `setTimeout`. Each cancel
|
|
26
|
-
* that it gives also has `unref`. A delay longer than `setTimeout` takes waits in steps.
|
|
27
|
-
*/
|
|
28
|
-
export declare const platformClock: (options?: PlatformClockOptions) => Clock;
|
|
29
|
-
/**
|
|
30
|
-
* This clock reads `performance.now()` and uses `setTimeout`. Its timers do not keep a Node
|
|
31
|
-
* process alive, thus a timer that is not stopped cannot stop the exit of the process.
|
|
32
|
-
*/
|
|
33
|
-
export declare const realClock: Clock;
|
|
34
|
-
/** A fake clock moves only when a test tells it to. */
|
|
35
|
-
export interface FakeClock extends Clock {
|
|
36
|
-
/** This method moves the clock forward by `ms`, and it starts each timer that comes due, in sequence. */
|
|
37
|
-
advance(ms: number): Promise<void>;
|
|
38
|
-
/**
|
|
39
|
-
* This method moves the clock forward by `ms` and starts no timer, as a blocked event loop does.
|
|
40
|
-
* The next `advance` then starts each timer that came due during the block, late.
|
|
41
|
-
*/
|
|
42
|
-
block(ms: number): void;
|
|
43
|
-
/** This count is the number of timers that are not stopped and not called. */
|
|
44
|
-
readonly pending: number;
|
|
45
|
-
}
|
|
46
|
-
/** This function makes a fake clock. Its time starts at `start` milliseconds. */
|
|
47
|
-
export declare const fakeClock: (start?: number) => FakeClock;
|
|
1
|
+
import { a as fakeClock, i as PlatformClockOptions, n as Clock, o as platformClock, r as FakeClock, s as realClock, t as Cancel } from "./clock-BPLEBlb6.js";
|
|
2
|
+
export { Cancel, Clock, FakeClock, PlatformClockOptions, fakeClock, platformClock, realClock };
|
package/build/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { a as Realization, c as Unit, d as machineProblems, f as readsFired, i as Over, l as Vantage, n as FIRED, o as Timer, r as Machine, s as TransitionDef, t as Expr, u as exprKnobs } from "./machine-yGpVFyfh.js";
|
|
2
2
|
import { i as replay, n as Replayable, r as Transition, t as ReplayOptions } from "./replay-DRTZc7Pw.js";
|
|
3
|
-
import {
|
|
3
|
+
import { A as timerBand, C as parseExpr, D as recovery, E as realizationOf, M as timerUnder, N as transitionOn, O as stackedDetection, S as overValues, T as realizationKnobs, _ as detection, a as Detection, b as firings, c as KnobValues, d as Recovery, f as ScheduleOptions, g as algebraProblems, h as TimerBounds, i as Band, j as timerOf, k as synGiveUpSends, l as Manifestation, m as Situation, n as RunMachineOptions, o as Detector, p as Scheduled, r as runMachine, s as Firing, t as MachineRun, u as Node, v as errnoOf, w as probeTrain, x as modelSource, y as evaluate } from "./run-Dol_e0Xa.js";
|
|
4
4
|
/** This function gives one value or many values as an array. */
|
|
5
5
|
export declare const arr: <T>(value: T | readonly T[]) => readonly T[];
|
|
6
6
|
/** This function gives the states that a transition leaves. The state "*" is each state that is not final. */
|
|
@@ -22,275 +22,4 @@ export declare const fromStates: (m: Pick<Machine, "states">, from: string | rea
|
|
|
22
22
|
* lowest floor. On a host with other flows, a scan can find some, and the floor is higher.
|
|
23
23
|
*/
|
|
24
24
|
export declare const conntrackFloor: (max: number, hz: number, expired?: number) => number;
|
|
25
|
-
|
|
26
|
-
* This module has the closed forms of the algebra. They give the duration of a timer of a
|
|
27
|
-
* machine, and how late and how early it can fire, from the values of its knobs.
|
|
28
|
-
*
|
|
29
|
-
* A machine document writes each duration in one of four forms (`machine.ts`): a constant, a knob,
|
|
30
|
-
* arithmetic over its knobs, or a named model. The arithmetic uses the value of each knob in the
|
|
31
|
-
* unit that the document gives to that knob. Thus `tcp_keepalive / 3` of Redis divides whole
|
|
32
|
-
* seconds, as Redis does. A model is the formula of the implementation itself, for example the
|
|
33
|
-
* retransmission budget of the kernel. The values are exact rationals, not floats: 0.2 s × 1023
|
|
34
|
-
* is 204.6 s, not 204.60000000000002.
|
|
35
|
-
*
|
|
36
|
-
* A knob without a value makes the result unknown, and the result names the knob. A knob that
|
|
37
|
-
* nothing sets (no bound) makes a duration without an end.
|
|
38
|
-
*/
|
|
39
|
-
/** 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. */
|
|
40
|
-
type KnobValues = (name: string) => Extent | Unknown | undefined;
|
|
41
|
-
/** Timer bounds tell how long a timer operates, how late it can fire and how early, each in the unit of its document. */
|
|
42
|
-
interface TimerBounds {
|
|
43
|
-
readonly duration: Extent | Unknown;
|
|
44
|
-
readonly lateness?: Extent | Unknown | undefined;
|
|
45
|
-
readonly early?: Extent | Unknown | undefined;
|
|
46
|
-
}
|
|
47
|
-
/** A node is the arithmetic of a document, after the parse. */
|
|
48
|
-
type Node = {
|
|
49
|
-
readonly op: "num";
|
|
50
|
-
readonly n: Rational;
|
|
51
|
-
} | {
|
|
52
|
-
readonly op: "knob";
|
|
53
|
-
readonly name: string;
|
|
54
|
-
} | {
|
|
55
|
-
readonly op: "+" | "-" | "*" | "/";
|
|
56
|
-
readonly a: Node;
|
|
57
|
-
readonly b: Node;
|
|
58
|
-
} | {
|
|
59
|
-
readonly op: "neg";
|
|
60
|
-
readonly a: Node;
|
|
61
|
-
} | {
|
|
62
|
-
readonly op: "min" | "max" | "floor" | "ceil" | "pow";
|
|
63
|
-
readonly args: readonly Node[];
|
|
64
|
-
};
|
|
65
|
-
/** This function parses the arithmetic of a document, or it throws an error that tells where the text stops making sense. */
|
|
66
|
-
export declare const parseExpr: (text: string) => Node;
|
|
67
|
-
/**
|
|
68
|
-
* This function gives the SYNs that a connect sends before it gives up: the first SYN and each
|
|
69
|
-
* retransmission (`synGiveUpWaits`). A connect whose SYN does not leave adds each of them to the field
|
|
70
|
-
* `drop` of conntrack, and each retransmission to `TCPRetransFail`.
|
|
71
|
-
*/
|
|
72
|
-
export declare const synGiveUpSends: (retries: number, linear: number) => number;
|
|
73
|
-
/**
|
|
74
|
-
* This function evaluates one duration of a timer of a machine, in the unit that its document
|
|
75
|
-
* gives it. The waits of a backoff timer read `fired`, which tells which wait.
|
|
76
|
-
*/
|
|
77
|
-
export declare const evaluate: (doc: Machine, expr: Expr, values: KnobValues, fired?: number) => Extent | Unknown;
|
|
78
|
-
/**
|
|
79
|
-
* This function gives the bounds of a timer of a machine: how long it operates, how late it can
|
|
80
|
-
* fire, how early. For a backoff timer, it gives one of its waits: the wait after `fired` firings.
|
|
81
|
-
*/
|
|
82
|
-
export declare const timerOf: (doc: Machine, timer: string, values: KnobValues, fired?: number) => TimerBounds;
|
|
83
|
-
/** A firing is one firing of a backoff timer, after `fired` firings: its time from the arming. */
|
|
84
|
-
interface Firing {
|
|
85
|
-
readonly fired: number;
|
|
86
|
-
/** This time is the sum of the waits to this firing, each less how early it can fire. */
|
|
87
|
-
readonly low: Quantity;
|
|
88
|
-
/** This time is the sum of the waits to this firing, each plus how late it can fire. */
|
|
89
|
-
readonly high: Quantity;
|
|
90
|
-
}
|
|
91
|
-
/** A recovery tells when the firings of a backoff timer move a connection again after a stall. */
|
|
92
|
-
interface Recovery {
|
|
93
|
-
/** These are its firings from its arming, up to the first one that surely comes after the end of the stall. */
|
|
94
|
-
readonly firings: readonly Firing[];
|
|
95
|
-
/**
|
|
96
|
-
* These are the firings that can be the first after the end of the stall. There is more than one
|
|
97
|
-
* when the end falls in the bounds of a firing: that firing can come before the end or after it.
|
|
98
|
-
*/
|
|
99
|
-
readonly first: readonly number[];
|
|
100
|
-
/** This time is the earliest time of the first firing after the end of the stall, from the arming. */
|
|
101
|
-
readonly low: Quantity;
|
|
102
|
-
/** This time is the latest time of that firing, from the arming. */
|
|
103
|
-
readonly high: Quantity;
|
|
104
|
-
}
|
|
105
|
-
/**
|
|
106
|
-
* This function gives the recovery from a stall. A backoff timer continues to fire through a
|
|
107
|
-
* stall, and what each firing sends gets through only after the stall ends. Thus the connection
|
|
108
|
-
* moves again at the first firing at the end or after it. That firing can be most of a wait after
|
|
109
|
-
* the end. A stall that stops immediately after one firing costs almost all of the next, longer
|
|
110
|
-
* wait.
|
|
111
|
-
*
|
|
112
|
-
* The stall counts from the arming of the timer, which is the send that the stall first lost. The
|
|
113
|
-
* waits add, and so do how early and how late each can fire.
|
|
114
|
-
*/
|
|
115
|
-
export declare const recovery: (doc: Machine, timer: string, values: KnobValues, stall: Extent) => Recovery | Unknown;
|
|
116
|
-
/** A band is the range of times in which a timer fires, from its arming. */
|
|
117
|
-
interface Band {
|
|
118
|
-
/** This time is the duration less how early the timer can fire. */
|
|
119
|
-
readonly low: Extent;
|
|
120
|
-
/** This time is the duration plus how late the timer can fire. */
|
|
121
|
-
readonly high: Extent;
|
|
122
|
-
}
|
|
123
|
-
/**
|
|
124
|
-
* This function gives the band of a timer from its bounds, exactly, in `unit`. The band goes from
|
|
125
|
-
* its duration less its early bound to its duration plus its lateness. A bound that the document
|
|
126
|
-
* does not give is zero. A duration without an end gives a band without an end. A keepalive of 11 s, 4 ms early and 352 ms
|
|
127
|
-
* late, gives 10.996 s to 11.352 s.
|
|
128
|
-
*/
|
|
129
|
-
export declare const timerBand: (bounds: TimerBounds, unit?: string) => Band | Unknown;
|
|
130
|
-
/** A scheduled firing is one firing of a backoff timer, and its time on the timeline. */
|
|
131
|
-
interface Scheduled {
|
|
132
|
-
/** This count is the wait that ends in this firing: the wait after `fired` firings. */
|
|
133
|
-
readonly fired: number;
|
|
134
|
-
/** This time is the sum of the waits to this firing, from the first wait of the schedule, in seconds. */
|
|
135
|
-
readonly at: Quantity;
|
|
136
|
-
}
|
|
137
|
-
/** These options tell where the firings of a schedule start and stop. Each stop that they give applies. */
|
|
138
|
-
interface ScheduleOptions {
|
|
139
|
-
/** This count is the first wait of the schedule. The default is 0, the wait from the arming. */
|
|
140
|
-
readonly from?: number | undefined;
|
|
141
|
-
/** This count is the most firings to give. */
|
|
142
|
-
readonly count?: number | undefined;
|
|
143
|
-
/** This time stops the schedule: the schedule keeps no firing after it. */
|
|
144
|
-
readonly until?: Extent | undefined;
|
|
145
|
-
/** This time stops the schedule after the first firing at it or after it. That firing is in the schedule. */
|
|
146
|
-
readonly reach?: Extent | undefined;
|
|
147
|
-
}
|
|
148
|
-
/**
|
|
149
|
-
* This function gives the firings of a backoff timer on a timeline: the sum of its waits, exactly,
|
|
150
|
-
* from the wait `from`. It stops at the first wait that is not a known amount, or at a stop of the
|
|
151
|
-
* options, or after 4096 firings. Each time is the duration of the waits, without how early or
|
|
152
|
-
* late each can fire.
|
|
153
|
-
*
|
|
154
|
-
* Two examples: the retransmission timer of Linux gives the send of each retransmission. The
|
|
155
|
-
* retry of a call with a deadline gives the start of each try.
|
|
156
|
-
*/
|
|
157
|
-
export declare const firings: (doc: Machine, timer: string, values: KnobValues, options: ScheduleOptions) => Scheduled[];
|
|
158
|
-
/**
|
|
159
|
-
* This function gives the times of a train of probes, exactly, in seconds. The first probe is at
|
|
160
|
-
* `first`, and each next probe is one `interval` later, `count` probes in all. A first time without
|
|
161
|
-
* an end gives no probe. An interval without an end gives only the first probe. Keepalive at its
|
|
162
|
-
* defaults sends its probes at 7200 s, 7275 s, and so on to 7800 s.
|
|
163
|
-
*/
|
|
164
|
-
export declare const probeTrain: (first: Extent, interval: Extent, count: number) => Quantity[];
|
|
165
|
-
/**
|
|
166
|
-
* This function gives how long a mechanism takes where a machine operates, from the realization
|
|
167
|
-
* of its document. The realization is one of its timers, whole, or its own duration, lateness and
|
|
168
|
-
* early bound over the knobs of the machine. It gives undefined when the document does not realize the mechanism.
|
|
169
|
-
*/
|
|
170
|
-
export declare const realizationOf: (doc: Machine, mechanism: string, values: KnobValues) => TimerBounds | undefined;
|
|
171
|
-
/** This function gives the knobs that a realization reads, by the names of the machine for them. */
|
|
172
|
-
export declare const realizationKnobs: (doc: Machine, mechanism: string) => string[];
|
|
173
|
-
/** This function gives what in a document the algebra cannot read: arithmetic that does not parse, or a model that it does not have. */
|
|
174
|
-
export declare const algebraProblems: (doc: Machine) => string[];
|
|
175
|
-
/** This function gives the source of the formula of a named model, for a reader of a result. */
|
|
176
|
-
export declare const modelSource: (name: string) => string | undefined;
|
|
177
|
-
/**
|
|
178
|
-
* A manifestation is what a failure lets back to the machine: the incoming events that continue
|
|
179
|
-
* to arrive while it lasts. A black hole lets nothing back. The kernel of a frozen process
|
|
180
|
-
* continues to acknowledge what it gets and to answer keepalive probes, thus its ACKs continue to
|
|
181
|
-
* arrive.
|
|
182
|
-
*/
|
|
183
|
-
interface Manifestation {
|
|
184
|
-
readonly name: string;
|
|
185
|
-
readonly passes: readonly string[];
|
|
186
|
-
/**
|
|
187
|
-
* These are the events that the failure itself sends one time, for example the FIN of a process
|
|
188
|
-
* that stopped with SIGKILL. A delivered event that a transition takes from the state of the connection detects the
|
|
189
|
-
* failure at once.
|
|
190
|
-
*/
|
|
191
|
-
readonly delivers?: readonly string[] | undefined;
|
|
192
|
-
/**
|
|
193
|
-
* This errno replaces ETIMEDOUT when one of these timers gives up. Linux keeps an ICMP error on
|
|
194
|
-
* an established socket as a soft error, and the timeout reports it (`tcp_write_err`). An ICMP
|
|
195
|
-
* counts only when it quotes a segment in the window (`tcp_v4_err`). A retransmission is in the
|
|
196
|
-
* window. A keepalive probe uses the sequence number before `snd_una`, thus its ICMP does not count.
|
|
197
|
-
*/
|
|
198
|
-
readonly errno?: {
|
|
199
|
-
readonly errno: string;
|
|
200
|
-
readonly timers: readonly string[];
|
|
201
|
-
} | undefined;
|
|
202
|
-
/**
|
|
203
|
-
* These are the durations that the failure changes, by timer. For example, an ICMP host
|
|
204
|
-
* unreachable for each retransmission reverts the backoff of the retransmission timer.
|
|
205
|
-
*/
|
|
206
|
-
readonly replaces?: Readonly<Record<string, {
|
|
207
|
-
readonly duration?: Expr;
|
|
208
|
-
readonly lateness?: Expr;
|
|
209
|
-
readonly early?: Expr;
|
|
210
|
-
}>> | undefined;
|
|
211
|
-
}
|
|
212
|
-
/** A situation is the activity of the connection when the failure started. */
|
|
213
|
-
interface Situation {
|
|
214
|
-
/** This name is the state of the machine, for example ESTABLISHED. */
|
|
215
|
-
readonly state: string;
|
|
216
|
-
/** This flag tells if it had sent data that the peer had not acknowledged. */
|
|
217
|
-
readonly inFlight: boolean;
|
|
218
|
-
}
|
|
219
|
-
/** A detector is a timer that can still fire, how long it operates, and the event that it fires. */
|
|
220
|
-
interface Detector {
|
|
221
|
-
readonly timer: string;
|
|
222
|
-
readonly fires: string;
|
|
223
|
-
readonly duration: Extent | Unknown;
|
|
224
|
-
/** This identifier is the machine below whose timer it is, when the timer is not of the machine itself (`over`). */
|
|
225
|
-
readonly beneath?: string | undefined;
|
|
226
|
-
}
|
|
227
|
-
/** A detection is the result of the minimum over the live detectors. */
|
|
228
|
-
interface Detection {
|
|
229
|
-
/** These are the timers that can still fire, the soonest first. */
|
|
230
|
-
readonly detectors: readonly Detector[];
|
|
231
|
-
/** This detector is the first to fire, or null when none can fire in a known time: a silent failure. */
|
|
232
|
-
readonly first: Detector | null;
|
|
233
|
-
/** These are the live detectors whose time nothing gives. Then `first` is only an upper bound. */
|
|
234
|
-
readonly unsettled: readonly string[];
|
|
235
|
-
/** These are the timers that are armed but cannot fire, and the reason for each. */
|
|
236
|
-
readonly held: ReadonlyArray<{
|
|
237
|
-
readonly timer: string;
|
|
238
|
-
readonly why: string;
|
|
239
|
-
}>;
|
|
240
|
-
/**
|
|
241
|
-
* These are the events that the failure delivers and that a transition takes from the state:
|
|
242
|
-
* each detects the failure at once, before any timer. The errno is the errno of the transition,
|
|
243
|
-
* or null for an end of file.
|
|
244
|
-
*/
|
|
245
|
-
readonly delivered: ReadonlyArray<{
|
|
246
|
-
readonly event: string;
|
|
247
|
-
readonly to: string;
|
|
248
|
-
readonly errno: string | null;
|
|
249
|
-
}>;
|
|
250
|
-
}
|
|
251
|
-
/**
|
|
252
|
-
* This function gives the detection: the minimum over the detectors that are live in the
|
|
253
|
-
* situation. The entry to the state arms a timer, and so does what the failure causes: data in
|
|
254
|
-
* flight without an acknowledgment gets a retransmission. An event that occurs cancels a timer.
|
|
255
|
-
*
|
|
256
|
-
* An event that arms the timer again, and that the failure continues to let through, stops it
|
|
257
|
-
* before it fires. For example, the kernel of a frozen process answers each keepalive probe.
|
|
258
|
-
* Without a live detector, the failure is silent at the level of this machine. Only something
|
|
259
|
-
* above it, the timeout of an application or a heartbeat, can find it. The result is only as good
|
|
260
|
-
* as the events that the document names.
|
|
261
|
-
*/
|
|
262
|
-
export declare const detection: (doc: Machine, situation: Situation, manifestation: Manifestation, values: KnobValues) => Detection;
|
|
263
|
-
/**
|
|
264
|
-
* This function gives the bounds of a timer of a machine under a failure: its own bounds, with each
|
|
265
|
-
* duration that the manifestation replaces.
|
|
266
|
-
*/
|
|
267
|
-
export declare const timerUnder: (doc: Machine, timer: string, values: KnobValues, manifestation: Manifestation, fired?: number) => TimerBounds;
|
|
268
|
-
/**
|
|
269
|
-
* This function gives the errno of a detection by a timer: the errno of the transition that its
|
|
270
|
-
* event takes from the state. A soft error of the manifestation replaces ETIMEDOUT, but only for
|
|
271
|
-
* the timers whose segments its ICMP quotes in the window.
|
|
272
|
-
*/
|
|
273
|
-
export declare const errnoOf: (doc: Machine, state: string, detector: {
|
|
274
|
-
readonly timer: string;
|
|
275
|
-
readonly fires: string;
|
|
276
|
-
}, manifestation: Manifestation) => string | null;
|
|
277
|
-
/** This function gives the transition that a machine takes from a state on an event, by its document. */
|
|
278
|
-
export declare const transitionOn: (doc: Machine, state: string, event: string) => TransitionDef | undefined;
|
|
279
|
-
/**
|
|
280
|
-
* This function gives the values of a machine for the machine that it operates on. These are the
|
|
281
|
-
* knobs that it sets, evaluated over its own knobs, and the other knobs of the lower machine. The
|
|
282
|
-
* keepAlive of ioredis at 5000 ms is the keepidle of the kernel at 5 s.
|
|
283
|
-
*/
|
|
284
|
-
export declare const overValues: (upper: Machine, upperValues: KnobValues, lowerValues: KnobValues) => KnobValues;
|
|
285
|
-
/**
|
|
286
|
-
* This function gives the detection through the machine that a machine operates on. The detectors
|
|
287
|
-
* of the lower machine are live in the state below the state of this machine. They use the knobs
|
|
288
|
-
* that this machine sets.
|
|
289
|
-
*
|
|
290
|
-
* Each one reaches this machine as the event that the end of the lower
|
|
291
|
-
* machine gives. They are beside the timers of this machine, and the first of all of them is the
|
|
292
|
-
* first detection. A failure lets nothing new through to a machine above the socket, only the end
|
|
293
|
-
* of the socket. Thus the timers of this machine see only what its state arms.
|
|
294
|
-
*/
|
|
295
|
-
export declare const stackedDetection: (upper: Machine, lower: Machine, situation: Situation, manifestation: Manifestation, upperValues: KnobValues, lowerValues: KnobValues) => Detection;
|
|
296
|
-
export { type Band, type Detection, type Detector, type Expr, FIRED, type Firing, type KnobValues, type Machine, type Manifestation, type Node, type Over, type Realization, type Recovery, type ReplayOptions, type Replayable, type ScheduleOptions, type Scheduled, type Situation, type Timer, type TimerBounds, type Transition, type TransitionDef, type Unit, type Vantage, exprKnobs, machineProblems, readsFired, replay };
|
|
25
|
+
export { type Band, type Detection, type Detector, type Expr, FIRED, type Firing, type KnobValues, type Machine, type MachineRun, type Manifestation, type Node, type Over, type Realization, type Recovery, type ReplayOptions, type Replayable, type RunMachineOptions, type ScheduleOptions, type Scheduled, type Situation, type Timer, type TimerBounds, type Transition, type TransitionDef, type Unit, type Vantage, algebraProblems, detection, errnoOf, evaluate, exprKnobs, firings, machineProblems, modelSource, overValues, parseExpr, probeTrain, readsFired, realizationKnobs, realizationOf, recovery, replay, runMachine, stackedDetection, synGiveUpSends, timerBand, timerOf, timerUnder, transitionOn };
|