@mark1russell7/service 0.8.9 → 0.8.11
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 +52 -7
- package/build/host.d.ts +145 -11
- package/build/host.js +400 -28
- package/build/host.js.map +1 -1
- package/build/index.js +1 -267
- package/build/index.js.map +1 -1
- package/build/{ports-DZoipkSD.d.ts → ports-B1ayTL-j.d.ts} +13 -1
- package/build/process-7R9M29wN.js +437 -0
- package/build/process-7R9M29wN.js.map +1 -0
- package/build/testing.d.ts +3 -1
- package/build/testing.js +11 -0
- package/build/testing.js.map +1 -1
- package/package.json +5 -5
- package/build/process-Oe0Abbsm.js +0 -170
- package/build/process-Oe0Abbsm.js.map +0 -1
package/README.md
CHANGED
|
@@ -608,22 +608,28 @@ Each effect goes through a port (`HostPorts`): the commands, the files, the proc
|
|
|
608
608
|
| `writeDiscovery`, `readDiscovery`, `removeDiscovery` | The discovery file: the process ID, the port, the address and the start time |
|
|
609
609
|
| `stopTree(pid, ports)` | The stop of a process tree by its process ID |
|
|
610
610
|
| `probeOnce`, `parseEnvFile`, `rotatingLog` | A ready probe, an env file and a log file with rotation |
|
|
611
|
+
| `watchTargets(spec, ports, { onChange })` | The outside watcher: the health of each target, from a probe on its own loop |
|
|
612
|
+
| `watchProblems` | The problems of a watch spec |
|
|
611
613
|
|
|
612
|
-
- **The task.** On Windows, `installService` writes the XML of a scheduled task and gives it to `schtasks /Create`. The task starts at logon or each day, as the user, without a window. It starts the program again after a failure.
|
|
614
|
+
- **The task.** On Windows, `installService` writes the XML of a scheduled task and gives it to `schtasks /Create`. The task starts at logon, at boot or each day, as the user, without a window. It starts the program again after a failure.
|
|
613
615
|
- **The unit.** On Linux, `installService` writes a systemd user unit in `$XDG_CONFIG_HOME/systemd/user` and enables it. A daily start also gets a timer. Other platforms get `unsupported`, and nothing changes.
|
|
616
|
+
- **The start at boot.** `start: "boot"` starts the program when the computer starts, before a logon. Thus a program starts again after a power cut, and it does not wait for the user. A boot start is in the background.
|
|
617
|
+
- **The background.** `background: true` runs the program when the user is not logged on. On Windows, the task gets an S4U logon, and Windows keeps no password. Thus the task has no access to a network share that needs the credentials of the user. On Linux, the install starts `loginctl enable-linger`. Thus the user manager of systemd starts at boot and stays after the logout. The removal keeps the linger, because other units can need it.
|
|
618
|
+
- **The elevation.** Task Scheduler refuses a boot trigger and an S4U logon from a shell that is not elevated (`Access is denied`). Thus the owner of the computer starts the install of a task in the background one time, in a shell of an administrator. The problem of the outcome tells so.
|
|
614
619
|
- **The outcomes.** Each operation gives data, not a throw: `done`, `failed` with each command and its output, `refused` with the problems of the spec, or `unsupported`.
|
|
615
620
|
- **The lock.** The lock file has the process ID and its start time. Thus a new process with the same ID does not hold the lock. A lock whose process stopped is stale, and the next take removes it.
|
|
616
621
|
- **The discovery file.** A client reads the port and the address of a running instance from it. `readDiscovery` tells `running`, `absent`, `stale` or `malformed`, and it does not throw.
|
|
617
|
-
- **The sequence of a group.** A program starts when each program of its `after` is ready. A ready probe is an HTTP status, a TCP connection or a command that gives 0. The times of a probe are quantities.
|
|
622
|
+
- **The sequence of a group.** A program starts when each program of its `after` is ready. A ready probe is an HTTP status, a TCP connection or a command that gives 0. An HTTP probe can also examine the times in its JSON answer (`fresh`). The times of a probe are quantities.
|
|
618
623
|
- **A program that stops.** It starts again after the backoff of its `retrier`. The count of tries goes back to 0 after the program is ready for `resetAfter`. A program also waits until its `after` programs are ready again.
|
|
619
624
|
- **A program that is not ready in its time.** The supervisor stops it after `within`, and starts it again after the backoff. The state of the program tells the reason.
|
|
625
|
+
- **A program that hangs.** A hung program does not exit, thus only a probe finds it. With `alive`, the supervisor uses a liveness probe each `interval` after the program is ready. After `failures` failures in sequence, it stops the program in stages and starts it again after the backoff. A pass sets the count to 0. Without `alive`, only an exit starts a program again.
|
|
620
626
|
- **One instance of each program.** Each program has its own lock. The supervisor holds the lock for its child, thus a second supervisor of the same group gets `held` and starts nothing.
|
|
621
627
|
- **The files of a program.** Its output goes to `<stateDir>/logs/<name>.log`, which rotates at its size. Its environment is the host, then its env file, then its `env`. It also gets its own `cwd`.
|
|
622
628
|
- **The staged stop.** The supervisor stops the programs in the reverse sequence. A program with an IPC channel gets the message `"shutdown"`, which `svc.trigger("ipc-message", …)` matches. Else Linux sends SIGTERM, and Windows starts `taskkill /T /PID` without `/F`.
|
|
623
629
|
- **The stop of the tree.** After the grace, Windows starts `taskkill /T /F /PID <pid>`. Linux sends SIGKILL to the process group of the child. The host does not stop a process by its name or its command line at any time.
|
|
624
630
|
|
|
625
631
|
```ts
|
|
626
|
-
// group.js: the
|
|
632
|
+
// group.js: the boot task starts this supervisor as the user
|
|
627
633
|
import { daemon, service } from "@mark1russell7/service";
|
|
628
634
|
import { nodeHostPorts, superviseGroup } from "@mark1russell7/service/host";
|
|
629
635
|
|
|
@@ -643,7 +649,9 @@ const group = superviseGroup(
|
|
|
643
649
|
envFile: "/var/lib/stack/api.env",
|
|
644
650
|
after: ["db"],
|
|
645
651
|
ipc: true,
|
|
646
|
-
ready: { probe: { kind: "http", url: "http://127.0.0.1:8080/
|
|
652
|
+
ready: { probe: { kind: "http", url: "http://127.0.0.1:8080/readiness" }, interval: ms(500), timeout: ms(250), within: s(30) },
|
|
653
|
+
// three failures in sequence, 10 s apart, stop a hung api, and the supervisor starts it again
|
|
654
|
+
alive: { probe: { kind: "http", url: "http://127.0.0.1:8080/liveness" }, interval: s(10), timeout: s(2), failures: 3 },
|
|
647
655
|
listen: { port: 8080, url: "http://127.0.0.1:8080/" },
|
|
648
656
|
},
|
|
649
657
|
],
|
|
@@ -661,18 +669,55 @@ await host.run();
|
|
|
661
669
|
```
|
|
662
670
|
|
|
663
671
|
```ts
|
|
664
|
-
// install.js: the owner of the computer starts this one time
|
|
672
|
+
// install.js: the owner of the computer starts this one time, in a shell of an administrator on Windows
|
|
665
673
|
import { installService, nodeHostPorts } from "@mark1russell7/service/host";
|
|
666
674
|
|
|
667
675
|
const outcome = await installService(
|
|
668
|
-
{ name: "stack", description: "The stack", program: process.execPath, args: ["group.js"], start: "
|
|
676
|
+
{ name: "stack", description: "The stack", program: process.execPath, args: ["group.js"], start: "boot", restart: { after: { value: 1, unit: "min" } }, stateDir: "/var/lib/stack" },
|
|
669
677
|
nodeHostPorts(),
|
|
670
678
|
);
|
|
671
|
-
console.log(outcome.kind);
|
|
679
|
+
console.log(outcome.kind === "failed" ? outcome.problem : outcome.kind);
|
|
672
680
|
```
|
|
673
681
|
|
|
674
682
|
- **The stop of the group.** The phase `tear down dependencies` caps `group.stop()`. Give that phase a cap above the sum of the graces of the programs.
|
|
675
683
|
|
|
684
|
+
### The outside watcher
|
|
685
|
+
|
|
686
|
+
A heartbeat from a program tells only that the program sends. `watchTargets` probes the targets from a second computer. Thus it also finds a program that answers while its work stopped. It also finds a failure of the provider of the heartbeat.
|
|
687
|
+
|
|
688
|
+
- **The targets.** Each target has a probe, an interval, a timeout and a jitter. Each target polls on its own loop, on the clock of the ports.
|
|
689
|
+
- **The verdict.** The default is a debounce: 3 failed polls in sequence make a target down, and 2 passed polls make it up. A window measures the time of the failures.
|
|
690
|
+
- **The health.** A target is `unknown` at the start. Its first pass makes it `up`, and its verdict makes it `down`. `onChange` gets each change, with the reason of the latest failed poll.
|
|
691
|
+
- **The freshness bounds.** With `fresh`, an HTTP probe also reads its answer as JSON. Each bound names a time with a JSON Pointer (RFC 6901), and it gives the largest age.
|
|
692
|
+
- **The times.** A time is epoch milliseconds or an ISO 8601 text. A missing time fails. The age is from the wall clock of the watcher, or from the time of the target at `now`.
|
|
693
|
+
- **The size.** The probe reads up to 1 MiB of the answer. A larger answer fails.
|
|
694
|
+
- **The alerts.** The watcher sends no message. The `onChange` handler sends the alert on a path that does not go through the target.
|
|
695
|
+
|
|
696
|
+
```ts
|
|
697
|
+
// watch.js: the outside watcher of the stack, on a second computer
|
|
698
|
+
import { nodeHostPorts, watchTargets } from "@mark1russell7/service/host";
|
|
699
|
+
|
|
700
|
+
const s = (value: number) => ({ value, unit: "s" });
|
|
701
|
+
const watcher = watchTargets(
|
|
702
|
+
{
|
|
703
|
+
targets: [
|
|
704
|
+
{ name: "api", probe: { kind: "http", url: "http://stack.internal:8080/liveness" }, interval: s(30), timeout: s(5) },
|
|
705
|
+
{
|
|
706
|
+
name: "pipeline",
|
|
707
|
+
// the newest test delivery is 26 h old or younger
|
|
708
|
+
probe: { kind: "http", url: "http://stack.internal:8080/freshness", fresh: [{ pointer: "/delivery/lastTestSendAt", within: { value: 26, unit: "h" } }] },
|
|
709
|
+
interval: { value: 5, unit: "min" },
|
|
710
|
+
timeout: s(10),
|
|
711
|
+
verdict: { type: "debounce", failAfter: 2, recoverAfter: 1 },
|
|
712
|
+
},
|
|
713
|
+
],
|
|
714
|
+
},
|
|
715
|
+
nodeHostPorts(),
|
|
716
|
+
// notify: the path of the alert, outside the stack
|
|
717
|
+
{ onChange: (change) => notify(`${change.target} is ${change.to}: ${change.why ?? "it passes again"}`) },
|
|
718
|
+
);
|
|
719
|
+
```
|
|
720
|
+
|
|
676
721
|
## The testing subpath
|
|
677
722
|
|
|
678
723
|
`@mark1russell7/service/testing` has the seams that a test of a service needs:
|
package/build/host.d.ts
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* of programs that start in sequence. Each effect of the system goes through `HostPorts`.
|
|
5
5
|
* A test gives `fakeHost()` of `./testing`, and a program gives `nodeHostPorts()`.
|
|
6
6
|
*/
|
|
7
|
-
import { a as FilePort, c as
|
|
7
|
+
import { a as FilePort, c as NetPort, d as SpawnRequest, f as StopSignal, i as CommandResult, l as ProcessMark, n as CommandOptions, o as HostPorts, p as joinPath, r as CommandPort, s as HttpAnswer, t as ChildHandle, u as ProcessesPort } from "./ports-B1ayTL-j.js";
|
|
8
8
|
import { t as Backoff } from "./backoff-QTRGfkEK.js";
|
|
9
9
|
import { Y as MessageShape, c as Logger } from "./logger-B6drv9w0.js";
|
|
10
10
|
import { n as Clock } from "./clock-DpVgpY4h.js";
|
|
@@ -12,9 +12,10 @@ import { Quantity } from "@mark1russell7/quantity";
|
|
|
12
12
|
/**
|
|
13
13
|
* A service start tells when the system starts the program.
|
|
14
14
|
* - `logon`: at the logon of the user. The program runs until it stops.
|
|
15
|
+
* - `boot`: at the start of the computer, before a logon. The program runs until it stops. It runs in the background.
|
|
15
16
|
* - `{ daily: "HH:MM" }`: each day at that local time, as a job that runs to its end.
|
|
16
17
|
*/
|
|
17
|
-
type ServiceStart = "logon" | {
|
|
18
|
+
type ServiceStart = "logon" | "boot" | {
|
|
18
19
|
readonly daily: string;
|
|
19
20
|
};
|
|
20
21
|
/** A restart policy tells how long the system waits before it starts a program again after it stops. */
|
|
@@ -33,8 +34,15 @@ interface ServiceSpec {
|
|
|
33
34
|
/** This folder is the working folder of the program. */
|
|
34
35
|
readonly cwd?: string | undefined;
|
|
35
36
|
readonly start: ServiceStart;
|
|
36
|
-
/** This policy starts a program at logon again after it stops. Null starts it only at
|
|
37
|
+
/** This policy starts a program at logon or at boot again after it stops. Null starts it only at its start. A daily job has no restart. */
|
|
37
38
|
readonly restart: RestartPolicy | null;
|
|
39
|
+
/**
|
|
40
|
+
* True runs the program when the user is not logged on. On Windows, the task gets an S4U logon, and Task Scheduler
|
|
41
|
+
* then refuses the task from a shell that is not elevated. On Linux, the install sets the linger of the user
|
|
42
|
+
* (`loginctl enable-linger`), thus the user manager of systemd starts at boot and stays after the logout.
|
|
43
|
+
* The default is true for a boot start, and false for the other starts.
|
|
44
|
+
*/
|
|
45
|
+
readonly background?: boolean | undefined;
|
|
38
46
|
/** This folder keeps the files of the host, for example the task file of Windows. */
|
|
39
47
|
readonly stateDir: string;
|
|
40
48
|
/** On Windows, `hidden` starts the program through `conhost --headless`, thus no window opens. The default is `hidden`. */
|
|
@@ -65,9 +73,11 @@ export declare const systemdArg: (arg: string) => string;
|
|
|
65
73
|
/**
|
|
66
74
|
* This function gives the task file of Windows for a spec, as text. It is a pure function: the same
|
|
67
75
|
* spec and context give the same text. Each start boundary is in the past, thus the task does not wait for a date.
|
|
68
|
-
* - A start at logon gets a logon trigger
|
|
69
|
-
* minutes. The task ignores a start while its program runs (`IgnoreNew`).
|
|
76
|
+
* - A start at logon gets a logon trigger, and a start at boot gets a boot trigger. With a restart, a time trigger
|
|
77
|
+
* also starts the task each few minutes. The task ignores a start while its program runs (`IgnoreNew`).
|
|
70
78
|
* - A daily start gets a calendar trigger at its time. A start that the computer missed occurs when it can (`StartWhenAvailable`).
|
|
79
|
+
* - A spec in the background gets an S4U logon: the task runs when the user is not logged on, and Windows keeps no password.
|
|
80
|
+
* Otherwise the task runs only in the session of the user (`InteractiveToken`).
|
|
71
81
|
* Task Scheduler reads the file as UTF-16 with a byte order mark: give the text to `utf16le`.
|
|
72
82
|
*/
|
|
73
83
|
export declare const renderTaskXml: (spec: ServiceSpec, context: TaskContext) => string;
|
|
@@ -75,11 +85,12 @@ export declare const renderTaskXml: (spec: ServiceSpec, context: TaskContext) =>
|
|
|
75
85
|
export declare const utf16le: (text: string) => Uint8Array;
|
|
76
86
|
/**
|
|
77
87
|
* This function gives the systemd user unit of a spec (`<name>.service`), as text. It is a pure function.
|
|
78
|
-
* - A start at logon is a service of the type `simple`, wanted by `default.target`. With a restart, it has `Restart=on-failure`.
|
|
88
|
+
* - A start at logon or at boot is a service of the type `simple`, wanted by `default.target`. With a restart, it has `Restart=on-failure`.
|
|
89
|
+
* The unit is the same for the two starts: the linger of the user (`installService`) starts the user manager at boot.
|
|
79
90
|
* - A daily start is a service of the type `oneshot` with no `[Install]` section. Its timer (`renderSystemdTimer`) starts it.
|
|
80
91
|
*/
|
|
81
92
|
export declare const renderSystemdUnit: (spec: ServiceSpec) => string;
|
|
82
|
-
/** This function gives the systemd timer (`<name>.timer`) of a daily spec, or null for a start at logon. It is a pure function. */
|
|
93
|
+
/** This function gives the systemd timer (`<name>.timer`) of a daily spec, or null for a start at logon or at boot. It is a pure function. */
|
|
83
94
|
export declare const renderSystemdTimer: (spec: ServiceSpec) => string | null;
|
|
84
95
|
/**
|
|
85
96
|
* This margin is the time after a recorded start in which a process can start and still be the same
|
|
@@ -315,7 +326,9 @@ export declare const servicePaths: (spec: ServiceSpec, ports: HostPorts) => Serv
|
|
|
315
326
|
* This function installs a service of the user, and by default starts it. It does not throw.
|
|
316
327
|
* - On Windows, it writes the task file in UTF-16 to `stateDir`, and starts `schtasks /Create /XML <file> /F`, then `schtasks /Run`.
|
|
317
328
|
* - On Linux, it writes the unit (and the timer of a daily job), then starts `systemctl --user daemon-reload` and `enable`.
|
|
329
|
+
* For a spec in the background, it first starts `loginctl enable-linger` for the user.
|
|
318
330
|
* A second install replaces the first. Give it the ports of a test, thus no test installs a real task.
|
|
331
|
+
* On Windows, Task Scheduler refuses a spec in the background from a shell that is not elevated: the problem then tells so.
|
|
319
332
|
*/
|
|
320
333
|
export declare const installService: (spec: ServiceSpec, ports: HostPorts, options?: InstallOptions) => Promise<ServiceOutcome>;
|
|
321
334
|
/**
|
|
@@ -330,8 +343,8 @@ export declare const startService: (spec: ServiceSpec, ports: HostPorts) => Prom
|
|
|
330
343
|
* This function stops a service, and keeps it stopped until `startService`. It does not throw.
|
|
331
344
|
* - On Windows, it disables the task, thus its time trigger does not start it again, and ends the task.
|
|
332
345
|
* With a discovery file, it then stops the process tree of the instance. Windows has no signal that a child can catch.
|
|
333
|
-
* - On Linux, it disables the unit of a logon
|
|
334
|
-
* Thus the next login or the next calendar time does not start it again. The stop sends SIGTERM,
|
|
346
|
+
* - On Linux, it disables the unit of a service at logon or at boot, or the timer of a daily job, and stops it.
|
|
347
|
+
* Thus the next login, the next boot or the next calendar time does not start it again. The stop sends SIGTERM,
|
|
335
348
|
* thus `run()` stops in its stages. A daily job that operates stops too.
|
|
336
349
|
*/
|
|
337
350
|
export declare const stopService: (spec: ServiceSpec, ports: HostPorts, options?: InstanceOptions) => Promise<ServiceOutcome>;
|
|
@@ -340,9 +353,23 @@ export declare const stopService: (spec: ServiceSpec, ports: HostPorts, options?
|
|
|
340
353
|
* have gives `installed: false`. A malformed or stale discovery file gives its read, and not a throw.
|
|
341
354
|
*/
|
|
342
355
|
export declare const serviceStatus: (spec: ServiceSpec, ports: HostPorts, options?: InstanceOptions) => Promise<ServiceStatus>;
|
|
356
|
+
/**
|
|
357
|
+
* A freshness bound reads one time in the JSON answer of an http probe. The time is epoch
|
|
358
|
+
* milliseconds or an ISO 8601 text. The probe fails when the time is older than `within`, or when
|
|
359
|
+
* the answer does not have it.
|
|
360
|
+
*/
|
|
361
|
+
interface FreshnessBound {
|
|
362
|
+
/** This JSON Pointer (RFC 6901) names the time in the answer, for example `/delivery/lastTestSendAt`. */
|
|
363
|
+
readonly pointer: string;
|
|
364
|
+
/** This time is the largest age that passes. */
|
|
365
|
+
readonly within: Quantity;
|
|
366
|
+
}
|
|
343
367
|
/**
|
|
344
368
|
* A ready probe tells when a program is ready.
|
|
345
|
-
* - `http`: a GET request to the address gives the status, 200 by default.
|
|
369
|
+
* - `http`: a GET request to the address gives the status, 200 by default. With `fresh`, the answer
|
|
370
|
+
* is also JSON, and each bound of `fresh` passes. The age of a time is measured from `now`: a
|
|
371
|
+
* JSON Pointer to the time of the target in the answer. Without `now`, the wall clock of the host
|
|
372
|
+
* gives the time.
|
|
346
373
|
* - `tcp`: a TCP connection to the port opens. The default host is `127.0.0.1`.
|
|
347
374
|
* - `command`: a command gives the exit code 0.
|
|
348
375
|
*/
|
|
@@ -350,6 +377,8 @@ type ReadyProbe = {
|
|
|
350
377
|
readonly kind: "http";
|
|
351
378
|
readonly url: string;
|
|
352
379
|
readonly status?: number | undefined;
|
|
380
|
+
readonly fresh?: readonly FreshnessBound[] | undefined;
|
|
381
|
+
readonly now?: string | undefined;
|
|
353
382
|
} | {
|
|
354
383
|
readonly kind: "tcp";
|
|
355
384
|
readonly port: number;
|
|
@@ -367,10 +396,99 @@ type ProbeResult = {
|
|
|
367
396
|
readonly ok: false;
|
|
368
397
|
readonly why: string;
|
|
369
398
|
};
|
|
399
|
+
/** This size is the largest answer that a probe with freshness bounds reads: 1 MiB. */
|
|
400
|
+
export declare const PROBE_BODY_LIMIT = 1048576;
|
|
370
401
|
/** This function gives the problems of a probe: each value that a probe cannot use. */
|
|
371
402
|
export declare const probeProblems: (probe: ReadyProbe) => string[];
|
|
372
403
|
/** This function uses a probe one time, in a timeout of milliseconds. It does not throw. */
|
|
373
404
|
export declare const probeOnce: (probe: ReadyProbe, timeout: number, ports: HostPorts) => Promise<ProbeResult>;
|
|
405
|
+
/**
|
|
406
|
+
* A verdict tells when a target goes down and when it comes up again.
|
|
407
|
+
* - `debounce`: `failAfter` failed polls in sequence make it down, and `recoverAfter` passed polls in sequence make it up.
|
|
408
|
+
* - `window`: failures for the time `failAfter` make it down. Passes for the time `recoverAfter` make it up. Without
|
|
409
|
+
* `recoverAfter`, the first pass makes it up.
|
|
410
|
+
*/
|
|
411
|
+
type TargetVerdict = {
|
|
412
|
+
readonly type: "debounce";
|
|
413
|
+
readonly failAfter: number;
|
|
414
|
+
readonly recoverAfter: number;
|
|
415
|
+
} | {
|
|
416
|
+
readonly type: "window";
|
|
417
|
+
readonly failAfter: Quantity;
|
|
418
|
+
readonly recoverAfter?: Quantity | undefined;
|
|
419
|
+
};
|
|
420
|
+
/** A watch target is one thing that a watcher probes on its own loop. */
|
|
421
|
+
interface WatchTarget {
|
|
422
|
+
/** This name is unique in the spec. A change names its target with it. */
|
|
423
|
+
readonly name: string;
|
|
424
|
+
readonly probe: ReadyProbe;
|
|
425
|
+
/** This time is between the starts of two polls. */
|
|
426
|
+
readonly interval: Quantity;
|
|
427
|
+
/** This time is the most that one poll waits. It is not above the interval. */
|
|
428
|
+
readonly timeout: Quantity;
|
|
429
|
+
/** This fraction moves each interval by up to ± its part, thus two watchers do not poll in step. The default is 0.1. */
|
|
430
|
+
readonly jitter?: number | undefined;
|
|
431
|
+
/** The default is a debounce: 3 failures make it down, and 2 passes make it up. */
|
|
432
|
+
readonly verdict?: TargetVerdict | undefined;
|
|
433
|
+
}
|
|
434
|
+
/** A watch spec lists the targets of one watcher. */
|
|
435
|
+
interface WatchSpec {
|
|
436
|
+
readonly targets: readonly WatchTarget[];
|
|
437
|
+
}
|
|
438
|
+
/** The health of a target is `unknown` until its first verdict. */
|
|
439
|
+
type TargetHealth = "unknown" | "up" | "down";
|
|
440
|
+
/** A target change is one transition of the health of a target. */
|
|
441
|
+
interface TargetChange {
|
|
442
|
+
readonly target: string;
|
|
443
|
+
readonly from: TargetHealth;
|
|
444
|
+
readonly to: "up" | "down";
|
|
445
|
+
/** This time is the wall time of the change, in milliseconds after the epoch. */
|
|
446
|
+
readonly at: number;
|
|
447
|
+
/** This text tells why the latest poll failed, for a change to down. It is null for a change to up. */
|
|
448
|
+
readonly why: string | null;
|
|
449
|
+
}
|
|
450
|
+
/** A target state is what a watcher knows of one target at this time. */
|
|
451
|
+
interface TargetState {
|
|
452
|
+
readonly name: string;
|
|
453
|
+
readonly health: TargetHealth;
|
|
454
|
+
/** This time is the wall time of the latest change of the health, or of the start. */
|
|
455
|
+
readonly since: number;
|
|
456
|
+
/** This result is the latest poll, or null before the first poll. */
|
|
457
|
+
readonly last: ProbeResult | null;
|
|
458
|
+
/** This time is the wall time of the latest poll, or null. */
|
|
459
|
+
readonly lastAt: number | null;
|
|
460
|
+
/** This count is the failed polls in sequence. */
|
|
461
|
+
readonly failures: number;
|
|
462
|
+
}
|
|
463
|
+
interface WatchOptions {
|
|
464
|
+
/** This function gets each change of the health of a target. A throw in it does not stop the watcher. */
|
|
465
|
+
readonly onChange: (change: TargetChange) => void;
|
|
466
|
+
/** This function gives a number in [0, 1) for the jitter. The default is `Math.random`. */
|
|
467
|
+
readonly random?: (() => number) | undefined;
|
|
468
|
+
/** This function gets each transition of the poller and the latch of each target, with the name of the target. */
|
|
469
|
+
readonly trace?: ((target: string, from: string, to: string, on: string) => void) | undefined;
|
|
470
|
+
}
|
|
471
|
+
/** A target watch is a running watcher. */
|
|
472
|
+
interface TargetWatch {
|
|
473
|
+
/** This method gives the state of each target, in the sequence of the spec. */
|
|
474
|
+
states(): TargetState[];
|
|
475
|
+
/** This method polls each target one time at once, outside its loop, and gives the states after the polls. */
|
|
476
|
+
pollNow(): Promise<TargetState[]>;
|
|
477
|
+
/** This method stops each loop. A stopped watcher gives no change. */
|
|
478
|
+
stop(): void;
|
|
479
|
+
}
|
|
480
|
+
/** This verdict is the default: 3 failures in sequence make a target down, and 2 passes make it up. */
|
|
481
|
+
export declare const DEFAULT_VERDICT: TargetVerdict;
|
|
482
|
+
/** This function gives the problems of a watch spec: each value that the watcher cannot use. */
|
|
483
|
+
export declare const watchProblems: (spec: WatchSpec) => string[];
|
|
484
|
+
/**
|
|
485
|
+
* This function starts a watcher of targets: an outside prober. Each target has its own loop of polls, on the
|
|
486
|
+
* clock of the ports, with a jitter. A verdict turns the polls into the health of the target: a debounce or a
|
|
487
|
+
* window. A target is `unknown` at the start. Its first pass makes it up, and its verdict makes it down. Each change
|
|
488
|
+
* goes to `onChange`, with the reason of the latest failed poll. The watcher throws at the start when the spec has a
|
|
489
|
+
* problem.
|
|
490
|
+
*/
|
|
491
|
+
export declare const watchTargets: (spec: WatchSpec, ports: HostPorts, options: WatchOptions) => TargetWatch;
|
|
374
492
|
/** An env file is the variables of a file of environment variables, and the problem of each line that it skipped. */
|
|
375
493
|
interface EnvFile {
|
|
376
494
|
readonly env: Readonly<Record<string, string>>;
|
|
@@ -419,6 +537,20 @@ interface ReadySpec {
|
|
|
419
537
|
/** This time is the most that the program can take to be ready. After it, the supervisor stops the program and starts it again. */
|
|
420
538
|
readonly within: Quantity;
|
|
421
539
|
}
|
|
540
|
+
/**
|
|
541
|
+
* An alive spec tells how the supervisor finds that a ready program still works. A program can hang and not exit:
|
|
542
|
+
* its process stays, and only a probe finds it. After `failures` failures in sequence, the supervisor stops the
|
|
543
|
+
* program in stages and starts it again after its backoff.
|
|
544
|
+
*/
|
|
545
|
+
interface AliveSpec {
|
|
546
|
+
readonly probe: ReadyProbe;
|
|
547
|
+
/** This time is the pause between two uses of the probe. The first use is one interval after the program is ready. */
|
|
548
|
+
readonly interval: Quantity;
|
|
549
|
+
/** This time is the most that one use of the probe can take. */
|
|
550
|
+
readonly timeout: Quantity;
|
|
551
|
+
/** This count of failures in sequence stops the program: a whole number of 1 or more. A pass sets the count to 0. */
|
|
552
|
+
readonly failures: number;
|
|
553
|
+
}
|
|
422
554
|
/** A program restart tells how the supervisor starts a program again after it stops. */
|
|
423
555
|
interface ProgramRestart {
|
|
424
556
|
/** This backoff gives the wait before each start again, in milliseconds, as `retrier` uses it. */
|
|
@@ -450,6 +582,8 @@ interface ProgramSpec {
|
|
|
450
582
|
readonly after?: readonly string[] | undefined;
|
|
451
583
|
/** This spec tells when the program is ready. Without it, the program is ready when it starts. */
|
|
452
584
|
readonly ready?: ReadySpec | undefined;
|
|
585
|
+
/** This spec tells how the supervisor finds that the ready program still works. Without it, only an exit starts the program again. */
|
|
586
|
+
readonly alive?: AliveSpec | undefined;
|
|
453
587
|
/** This policy starts the program again after it stops. The default is `DEFAULT_RESTART`. Null does not start it again. */
|
|
454
588
|
readonly restart?: ProgramRestart | null | undefined;
|
|
455
589
|
/** This spec tells the log file. The default is `<stateDir>/logs/<name>.log`, 10 MB, with 3 old files. Null keeps no log. */
|
|
@@ -540,4 +674,4 @@ interface NodeHostOptions {
|
|
|
540
674
|
* Only a program uses it. A test gives `fakeHost()` of `./testing`, thus it starts no process and installs no task.
|
|
541
675
|
*/
|
|
542
676
|
export declare const nodeHostPorts: (options?: NodeHostOptions) => HostPorts;
|
|
543
|
-
export { type ChildHandle, type CommandOptions, type CommandPort, type CommandRecord, type CommandResult, type Discovery, type DiscoveryFields, type DiscoveryRead, type EnvFile, type FilePort, type GroupOptions, type GroupSpec, type GroupSupervisor, type HostPorts, type InstallOptions, type InstanceLock, type InstanceOptions, type LockOptions, type LockOwner, type LockResult, type LockState, type LogSpec, type NetPort, type NodeHostOptions, type ProbeResult, type ProcessMark, type ProcessesPort, type ProgramPhase, type ProgramRestart, type ProgramSpec, type ProgramState, type ReadDiscoveryOptions, type ReadyProbe, type ReadySpec, type RestartPolicy, type RotatingLog, type ServiceOutcome, type ServicePaths, type ServiceSpec, type ServiceStart, type ServiceStatus, type SpawnRequest, type StopSignal, type StopSpec, type TaskContext, type TreeStopOutcome, joinPath };
|
|
677
|
+
export { type AliveSpec, type ChildHandle, type CommandOptions, type CommandPort, type CommandRecord, type CommandResult, type Discovery, type DiscoveryFields, type DiscoveryRead, type EnvFile, type FilePort, type FreshnessBound, type GroupOptions, type GroupSpec, type GroupSupervisor, type HostPorts, type HttpAnswer, type InstallOptions, type InstanceLock, type InstanceOptions, type LockOptions, type LockOwner, type LockResult, type LockState, type LogSpec, type NetPort, type NodeHostOptions, type ProbeResult, type ProcessMark, type ProcessesPort, type ProgramPhase, type ProgramRestart, type ProgramSpec, type ProgramState, type ReadDiscoveryOptions, type ReadyProbe, type ReadySpec, type RestartPolicy, type RotatingLog, type ServiceOutcome, type ServicePaths, type ServiceSpec, type ServiceStart, type ServiceStatus, type SpawnRequest, type StopSignal, type StopSpec, type TargetChange, type TargetHealth, type TargetState, type TargetVerdict, type TargetWatch, type TaskContext, type TreeStopOutcome, type WatchOptions, type WatchSpec, type WatchTarget, joinPath };
|