@mark1russell7/service 0.8.18 → 0.8.20
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 +19 -0
- package/build/backoff.d.ts +44 -2
- package/build/{builder-zO48Vgoj.d.ts → builder.d.ts} +14 -101
- package/build/builder.js +499 -0
- package/build/builder.js.map +1 -0
- package/build/{call-context-DDhcVvn5.d.ts → call-context.d.ts} +3 -4
- package/build/channel.d.ts +1 -1
- package/build/{core-BSzt4RI2.d.ts → client/core.d.ts} +32 -61
- package/build/{machine-BhVeHr_m.js → client/core.js} +4 -153
- package/build/client/core.js.map +1 -0
- package/build/{dial-ChwIcvd4.d.ts → client/dial.d.ts} +3 -4
- package/build/client/dial.js +52 -0
- package/build/client/dial.js.map +1 -0
- package/build/client/machine.js +29 -0
- package/build/client/machine.js.map +1 -0
- package/build/client/meets.d.ts +35 -0
- package/build/client/meets.js +78 -0
- package/build/client/meets.js.map +1 -0
- package/build/clock.d.ts +1 -1
- package/build/conformance.d.ts +122 -0
- package/build/conformance.js +470 -0
- package/build/conformance.js.map +1 -0
- package/build/contract.d.ts +28 -0
- package/build/contract.js +184 -0
- package/build/contract.js.map +1 -0
- package/build/description.d.ts +161 -0
- package/build/description.js +11 -0
- package/build/description.js.map +1 -0
- package/build/drains.js +35 -0
- package/build/drains.js.map +1 -0
- package/build/events.d.ts +25 -0
- package/build/fakes.d.ts +43 -0
- package/build/fakes.js +93 -0
- package/build/fakes.js.map +1 -0
- package/build/grpc/client.d.ts +153 -0
- package/build/grpc/client.js +474 -0
- package/build/grpc/client.js.map +1 -0
- package/build/grpc/connection.d.ts +97 -0
- package/build/grpc/connection.js +59 -0
- package/build/grpc/connection.js.map +1 -0
- package/build/grpc/machine.d.ts +12 -0
- package/build/grpc/machine.js +149 -0
- package/build/grpc/machine.js.map +1 -0
- package/build/grpc/meets.d.ts +14 -0
- package/build/grpc/meets.js +105 -0
- package/build/grpc/meets.js.map +1 -0
- package/build/grpc/starting.d.ts +33 -0
- package/build/grpc/starting.js +89 -0
- package/build/grpc/starting.js.map +1 -0
- package/build/grpc.d.ts +9 -303
- package/build/grpc.js +7 -854
- package/build/health.d.ts +93 -0
- package/build/health.js +223 -0
- package/build/health.js.map +1 -0
- package/build/heartbeat.d.ts +1 -1
- package/build/host/discovery.d.ts +61 -0
- package/build/host/discovery.js +113 -0
- package/build/host/discovery.js.map +1 -0
- package/build/host/env.d.ts +14 -0
- package/build/host/env.js +57 -0
- package/build/host/env.js.map +1 -0
- package/build/host/fakes.d.ts +82 -0
- package/build/host/fakes.js +239 -0
- package/build/host/fakes.js.map +1 -0
- package/build/host/group.d.ts +142 -0
- package/build/host/group.js +517 -0
- package/build/host/group.js.map +1 -0
- package/build/host/install.d.ts +96 -0
- package/build/host/install.js +330 -0
- package/build/host/install.js.map +1 -0
- package/build/host/lock.d.ts +78 -0
- package/build/host/lock.js +190 -0
- package/build/host/lock.js.map +1 -0
- package/build/host/logs.d.ts +26 -0
- package/build/host/logs.js +48 -0
- package/build/host/logs.js.map +1 -0
- package/build/host/node.d.ts +14 -0
- package/build/host/node.js +309 -0
- package/build/host/node.js.map +1 -0
- package/build/{ports-B1ayTL-j.d.ts → host/ports.d.ts} +15 -16
- package/build/host/ports.js +17 -0
- package/build/host/ports.js.map +1 -0
- package/build/host/probes.d.ts +51 -0
- package/build/host/probes.js +139 -0
- package/build/host/probes.js.map +1 -0
- package/build/host/processes.d.ts +32 -0
- package/build/host/processes.js +63 -0
- package/build/host/processes.js.map +1 -0
- package/build/host/render.d.ts +84 -0
- package/build/host/render.js +235 -0
- package/build/host/render.js.map +1 -0
- package/build/host/watch.d.ts +90 -0
- package/build/host/watch.js +165 -0
- package/build/host/watch.js.map +1 -0
- package/build/host.d.ts +13 -671
- package/build/host.js +12 -2126
- package/build/http/answers.js +29 -0
- package/build/http/answers.js.map +1 -0
- package/build/http/fake-server.js +61 -0
- package/build/http/fake-server.js.map +1 -0
- package/build/http/outcome.d.ts +115 -0
- package/build/http/outcome.js +325 -0
- package/build/http/outcome.js.map +1 -0
- package/build/http/probes.d.ts +83 -0
- package/build/http/probes.js +232 -0
- package/build/http/probes.js.map +1 -0
- package/build/http/transport.d.ts +165 -0
- package/build/http/transport.js +517 -0
- package/build/http/transport.js.map +1 -0
- package/build/http-client/client.d.ts +121 -0
- package/build/http-client/client.js +330 -0
- package/build/http-client/client.js.map +1 -0
- package/build/http-client/connection.d.ts +78 -0
- package/build/http-client/connection.js +54 -0
- package/build/http-client/connection.js.map +1 -0
- package/build/http-client/machine.d.ts +14 -0
- package/build/http-client/machine.js +109 -0
- package/build/http-client/machine.js.map +1 -0
- package/build/http-client/meets.d.ts +11 -0
- package/build/http-client/meets.js +74 -0
- package/build/http-client/meets.js.map +1 -0
- package/build/http-client/session.d.ts +87 -0
- package/build/http-client/session.js +99 -0
- package/build/http-client/session.js.map +1 -0
- package/build/http-client/starting.d.ts +25 -0
- package/build/http-client/starting.js +65 -0
- package/build/http-client/starting.js.map +1 -0
- package/build/http-client.d.ts +9 -330
- package/build/http-client.js +8 -707
- package/build/http.d.ts +5 -353
- package/build/http.js +3 -1086
- package/build/identity.d.ts +16 -0
- package/build/identity.js +44 -0
- package/build/identity.js.map +1 -0
- package/build/index.d.ts +35 -412
- package/build/index.js +24 -3277
- package/build/knobs.d.ts +1 -0
- package/build/{knobs-BJcz6m01.js → knobs.js} +2 -34
- package/build/knobs.js.map +1 -0
- package/build/latch.d.ts +29 -0
- package/build/latch.js +122 -0
- package/build/latch.js.map +1 -0
- package/build/{rules-HyFCBStQ.d.ts → law.d.ts} +19 -37
- package/build/law.js +149 -0
- package/build/law.js.map +1 -0
- package/build/lifecycle.d.ts +144 -0
- package/build/lifecycle.js +411 -0
- package/build/lifecycle.js.map +1 -0
- package/build/limiter/machine.d.ts +40 -0
- package/build/limiter/machine.js +279 -0
- package/build/limiter/machine.js.map +1 -0
- package/build/{policy-CBcK2XGg.d.ts → limiter/policy.d.ts} +28 -29
- package/build/{policy-UYALkqVq.js → limiter/policy.js} +10 -9
- package/build/limiter/policy.js.map +1 -0
- package/build/{limiter-Cm8nC-Gd.d.ts → limiter/quota.d.ts} +50 -76
- package/build/{limiter-Bgy6Gmvl.js → limiter/quota.js} +32 -425
- package/build/limiter/quota.js.map +1 -0
- package/build/{store-DFwFKrsB.d.ts → limiter/store.d.ts} +10 -11
- package/build/limiter/store.js +145 -0
- package/build/limiter/store.js.map +1 -0
- package/build/limiter.d.ts +4 -3
- package/build/limiter.js +4 -2
- package/build/lint.d.ts +152 -0
- package/build/lint.js +576 -0
- package/build/lint.js.map +1 -0
- package/build/logger.d.ts +71 -0
- package/build/logger.js +183 -0
- package/build/logger.js.map +1 -0
- package/build/machines.d.ts +41 -0
- package/build/machines.js +451 -0
- package/build/machines.js.map +1 -0
- package/build/metrics.d.ts +53 -0
- package/build/metrics.js +111 -0
- package/build/metrics.js.map +1 -0
- package/build/mongodb/client.d.ts +131 -0
- package/build/mongodb/client.js +388 -0
- package/build/mongodb/client.js.map +1 -0
- package/build/mongodb/connection.d.ts +112 -0
- package/build/mongodb/connection.js +12 -0
- package/build/mongodb/connection.js.map +1 -0
- package/build/mongodb/machine.d.ts +14 -0
- package/build/mongodb/machine.js +122 -0
- package/build/mongodb/machine.js.map +1 -0
- package/build/mongodb/meets.d.ts +15 -0
- package/build/mongodb/meets.js +103 -0
- package/build/mongodb/meets.js.map +1 -0
- package/build/mongodb/starting.d.ts +29 -0
- package/build/mongodb/starting.js +77 -0
- package/build/mongodb/starting.js.map +1 -0
- package/build/mongodb.d.ts +8 -296
- package/build/mongodb.js +7 -682
- package/build/operation.d.ts +27 -0
- package/build/{operation-DF73RZOI.js → operation.js} +2 -2
- package/build/operation.js.map +1 -0
- package/build/otel.d.ts +2 -2
- package/build/pg/client.d.ts +96 -0
- package/build/pg/client.js +277 -0
- package/build/pg/client.js.map +1 -0
- package/build/pg/connection.d.ts +75 -0
- package/build/pg/connection.js +11 -0
- package/build/pg/connection.js.map +1 -0
- package/build/pg/machine.d.ts +13 -0
- package/build/pg/machine.js +111 -0
- package/build/pg/machine.js.map +1 -0
- package/build/pg/meets.d.ts +14 -0
- package/build/pg/meets.js +83 -0
- package/build/pg/meets.js.map +1 -0
- package/build/pg/starting.d.ts +26 -0
- package/build/pg/starting.js +62 -0
- package/build/pg/starting.js.map +1 -0
- package/build/pg.d.ts +8 -219
- package/build/pg.js +7 -525
- package/build/poller.d.ts +9 -0
- package/build/poller.js +152 -0
- package/build/poller.js.map +1 -0
- package/build/process.d.ts +114 -0
- package/build/process.js +170 -0
- package/build/process.js.map +1 -0
- package/build/profiles.d.ts +68 -0
- package/build/profiles.js +120 -0
- package/build/profiles.js.map +1 -0
- package/build/{queue-DXdw1vLO.d.ts → queue.d.ts} +16 -29
- package/build/queue.js +279 -0
- package/build/queue.js.map +1 -0
- package/build/rabbitmq/client.d.ts +144 -0
- package/build/rabbitmq/client.js +426 -0
- package/build/rabbitmq/client.js.map +1 -0
- package/build/rabbitmq/connection.d.ts +91 -0
- package/build/rabbitmq/connection.js +15 -0
- package/build/rabbitmq/connection.js.map +1 -0
- package/build/rabbitmq/machine.d.ts +13 -0
- package/build/rabbitmq/machine.js +159 -0
- package/build/rabbitmq/machine.js.map +1 -0
- package/build/rabbitmq/meets.d.ts +12 -0
- package/build/rabbitmq/meets.js +96 -0
- package/build/rabbitmq/meets.js.map +1 -0
- package/build/rabbitmq/starting.d.ts +27 -0
- package/build/rabbitmq/starting.js +67 -0
- package/build/rabbitmq/starting.js.map +1 -0
- package/build/rabbitmq.d.ts +8 -283
- package/build/rabbitmq.js +7 -742
- package/build/redis/client.d.ts +86 -0
- package/build/redis/client.js +285 -0
- package/build/redis/client.js.map +1 -0
- package/build/redis/connection.d.ts +57 -0
- package/build/redis/connection.js +11 -0
- package/build/redis/connection.js.map +1 -0
- package/build/redis/limiter.d.ts +43 -0
- package/build/redis/limiter.js +164 -0
- package/build/redis/limiter.js.map +1 -0
- package/build/redis/machine.d.ts +12 -0
- package/build/redis/machine.js +144 -0
- package/build/redis/machine.js.map +1 -0
- package/build/redis/meets.d.ts +11 -0
- package/build/redis/meets.js +75 -0
- package/build/redis/meets.js.map +1 -0
- package/build/redis/operations.d.ts +5 -0
- package/build/redis/operations.js +114 -0
- package/build/redis/operations.js.map +1 -0
- package/build/redis.d.ts +10 -207
- package/build/redis.js +9 -771
- package/build/requests.d.ts +66 -0
- package/build/requests.js +279 -0
- package/build/requests.js.map +1 -0
- package/build/retrier.d.ts +62 -0
- package/build/{retrier-Dnjhvxol.js → retrier.js} +2 -2
- package/build/retrier.js.map +1 -0
- package/build/routes.d.ts +35 -0
- package/build/routes.js +77 -0
- package/build/routes.js.map +1 -0
- package/build/rules.d.ts +19 -2
- package/build/stops.d.ts +51 -0
- package/build/stops.js +86 -0
- package/build/stops.js.map +1 -0
- package/build/testing.d.ts +8 -270
- package/build/testing.js +4 -1027
- package/build/testing.js.map +1 -1
- package/build/timing.d.ts +63 -0
- package/build/{timing-DZl36uXs.js → timing.js} +2 -2
- package/build/timing.js.map +1 -0
- package/build/units.d.ts +17 -0
- package/build/units.js +236 -0
- package/build/units.js.map +1 -0
- package/build/watchdog.d.ts +34 -0
- package/build/watchdog.js +53 -0
- package/build/watchdog.js.map +1 -0
- package/build/websocket/client.d.ts +136 -0
- package/build/websocket/client.js +422 -0
- package/build/websocket/client.js.map +1 -0
- package/build/websocket/connection.d.ts +83 -0
- package/build/websocket/connection.js +57 -0
- package/build/websocket/connection.js.map +1 -0
- package/build/websocket/machine.d.ts +12 -0
- package/build/websocket/machine.js +155 -0
- package/build/websocket/machine.js.map +1 -0
- package/build/websocket/meets.d.ts +14 -0
- package/build/websocket/meets.js +92 -0
- package/build/websocket/meets.js.map +1 -0
- package/build/websocket/starting.d.ts +25 -0
- package/build/websocket/starting.js +69 -0
- package/build/websocket/starting.js.map +1 -0
- package/build/websocket.d.ts +9 -264
- package/build/websocket.js +8 -774
- package/build/worker.d.ts +92 -0
- package/build/worker.js +153 -0
- package/build/worker.js.map +1 -0
- package/package.json +4 -3
- package/build/backoff-QTRGfkEK.d.ts +0 -45
- package/build/clock-DpVgpY4h.d.ts +0 -2
- package/build/grpc.js.map +0 -1
- package/build/host.js.map +0 -1
- package/build/http-client.js.map +0 -1
- package/build/http.js.map +0 -1
- package/build/index.js.map +0 -1
- package/build/knobs-BJcz6m01.js.map +0 -1
- package/build/lifecycle-D0J-zwZF.d.ts +0 -374
- package/build/limiter-Bgy6Gmvl.js.map +0 -1
- package/build/logger-B6drv9w0.d.ts +0 -488
- package/build/machine-BhVeHr_m.js.map +0 -1
- package/build/mongodb.js.map +0 -1
- package/build/operation-DF73RZOI.js.map +0 -1
- package/build/pg.js.map +0 -1
- package/build/policy-UYALkqVq.js.map +0 -1
- package/build/process-7R9M29wN.js +0 -437
- package/build/process-7R9M29wN.js.map +0 -1
- package/build/rabbitmq.js.map +0 -1
- package/build/redis.js.map +0 -1
- package/build/requests-DD2ALv0_.js +0 -583
- package/build/requests-DD2ALv0_.js.map +0 -1
- package/build/retrier-Dnjhvxol.js.map +0 -1
- package/build/timing-DZl36uXs.js.map +0 -1
- package/build/websocket.js.map +0 -1
package/build/host.d.ts
CHANGED
|
@@ -4,674 +4,16 @@
|
|
|
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 {
|
|
8
|
-
import {
|
|
9
|
-
import {
|
|
10
|
-
import {
|
|
11
|
-
import {
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
};
|
|
21
|
-
/** A restart policy tells how long the system waits before it starts a program again after it stops. */
|
|
22
|
-
interface RestartPolicy {
|
|
23
|
-
/** This time is the wait before the next start. On Windows, the task starts again at whole minutes, 1 minute or more. */
|
|
24
|
-
readonly after: Quantity;
|
|
25
|
-
}
|
|
26
|
-
/** A service spec tells which program the system runs as a user service, and when. */
|
|
27
|
-
interface ServiceSpec {
|
|
28
|
-
/** This name is the name of the Windows task and of the systemd unit: letters, digits, `.`, `_` and `-`. */
|
|
29
|
-
readonly name: string;
|
|
30
|
-
readonly description: string;
|
|
31
|
-
/** This path is the full path of the program, for example the path of Node. */
|
|
32
|
-
readonly program: string;
|
|
33
|
-
readonly args: readonly string[];
|
|
34
|
-
/** This folder is the working folder of the program. */
|
|
35
|
-
readonly cwd?: string | undefined;
|
|
36
|
-
readonly start: ServiceStart;
|
|
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. */
|
|
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;
|
|
46
|
-
/** This folder keeps the files of the host, for example the task file of Windows. */
|
|
47
|
-
readonly stateDir: string;
|
|
48
|
-
/** On Windows, `hidden` starts the program through `conhost --headless`, thus no window opens. The default is `hidden`. */
|
|
49
|
-
readonly console?: "hidden" | "visible" | undefined;
|
|
50
|
-
/** This time is the most that one run can take. The default is no limit. */
|
|
51
|
-
readonly timeLimit?: Quantity | undefined;
|
|
52
|
-
}
|
|
53
|
-
/** These are the parts of the task of Windows that come from the system, not from the spec. */
|
|
54
|
-
interface TaskContext {
|
|
55
|
-
/** This text is the user of the task, for example `HOST\name`. */
|
|
56
|
-
readonly user: string;
|
|
57
|
-
/** This path is the path of `conhost.exe`, for a hidden console. */
|
|
58
|
-
readonly conhost: string;
|
|
59
|
-
}
|
|
60
|
-
/** This function gives the problems of a service spec: each value that the task or the unit cannot use. */
|
|
61
|
-
export declare const serviceProblems: (spec: ServiceSpec) => string[];
|
|
62
|
-
/**
|
|
63
|
-
* This function quotes one argument for a command line of Windows, by the rules of `CommandLineToArgvW`.
|
|
64
|
-
* It doubles each backslash before a quote and at the end. One pass keeps the time linear.
|
|
65
|
-
*/
|
|
66
|
-
export declare const windowsArg: (arg: string) => string;
|
|
67
|
-
/**
|
|
68
|
-
* This function quotes one argument for the `ExecStart` line of a systemd unit. It writes `%` as
|
|
69
|
-
* `%%` and `$` as `$$`, thus systemd expands no specifier and no variable. An argument with a space,
|
|
70
|
-
* a quote, a backslash or a `;` goes in double quotes.
|
|
71
|
-
*/
|
|
72
|
-
export declare const systemdArg: (arg: string) => string;
|
|
73
|
-
/**
|
|
74
|
-
* This function gives the task file of Windows for a spec, as text. It is a pure function: the same
|
|
75
|
-
* spec and context give the same text. Each start boundary is in the past, thus the task does not wait for a date.
|
|
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`).
|
|
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`).
|
|
81
|
-
* Task Scheduler reads the file as UTF-16 with a byte order mark: give the text to `utf16le`.
|
|
82
|
-
*/
|
|
83
|
-
export declare const renderTaskXml: (spec: ServiceSpec, context: TaskContext) => string;
|
|
84
|
-
/** This function encodes a text as UTF-16, little-endian, with a byte order mark: the encoding that Task Scheduler reads. */
|
|
85
|
-
export declare const utf16le: (text: string) => Uint8Array;
|
|
86
|
-
/**
|
|
87
|
-
* This function gives the systemd user unit of a spec (`<name>.service`), as text. It is a pure function.
|
|
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.
|
|
90
|
-
* - A daily start is a service of the type `oneshot` with no `[Install]` section. Its timer (`renderSystemdTimer`) starts it.
|
|
91
|
-
*/
|
|
92
|
-
export declare const renderSystemdUnit: (spec: ServiceSpec) => string;
|
|
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. */
|
|
94
|
-
export declare const renderSystemdTimer: (spec: ServiceSpec) => string | null;
|
|
95
|
-
/**
|
|
96
|
-
* This margin is the time after a recorded start in which a process can start and still be the same
|
|
97
|
-
* process, in milliseconds. A start time on Linux comes in ticks of 10 ms, and a step of the wall clock moves a time.
|
|
98
|
-
*/
|
|
99
|
-
export declare const START_MARGIN_MS = 1e3;
|
|
100
|
-
/**
|
|
101
|
-
* This function tells if the process of a mark is alive and is the same process. Windows and Linux
|
|
102
|
-
* use a process ID again after a process stops. Thus a live process that started after the mark is a
|
|
103
|
-
* different process. A start time that the system does not give proves nothing, and the process counts as the same.
|
|
104
|
-
*/
|
|
105
|
-
export declare const sameProcess: (mark: ProcessMark, ports: HostPorts) => Promise<boolean>;
|
|
106
|
-
/**
|
|
107
|
-
* A tree stop outcome tells what a tree stop did.
|
|
108
|
-
* - `stopped`: the stop went to the process and to each process under it.
|
|
109
|
-
* - `absent`: no process with the ID was alive.
|
|
110
|
-
* - `failed`: the process is alive and the stop did not go. The problem tells why.
|
|
111
|
-
*/
|
|
112
|
-
type TreeStopOutcome = {
|
|
113
|
-
readonly kind: "stopped";
|
|
114
|
-
} | {
|
|
115
|
-
readonly kind: "absent";
|
|
116
|
-
} | {
|
|
117
|
-
readonly kind: "failed";
|
|
118
|
-
readonly problem: string;
|
|
119
|
-
};
|
|
120
|
-
/**
|
|
121
|
-
* This function stops a process and each process under it, by its ID only. It does not find a process by
|
|
122
|
-
* its name or its command line. On Windows, it starts `taskkill /T /F /PID <pid>`. On Linux, it sends
|
|
123
|
-
* SIGKILL to the process group of the ID, or to the process when it leads no group. It does not throw.
|
|
124
|
-
*/
|
|
125
|
-
export declare const stopTree: (pid: number, ports: HostPorts) => Promise<TreeStopOutcome>;
|
|
126
|
-
/**
|
|
127
|
-
* A discovery record tells where a running instance listens. The instance writes it after its start,
|
|
128
|
-
* and a client reads it to find the instance. The file is JSON, one record.
|
|
129
|
-
*/
|
|
130
|
-
interface Discovery {
|
|
131
|
-
/** This number is the process ID of the instance. */
|
|
132
|
-
readonly pid: number;
|
|
133
|
-
/** This text is the start time of the process, as an ISO 8601 time. */
|
|
134
|
-
readonly startedAt: string;
|
|
135
|
-
/** This number is the port that the instance listens on, or null. */
|
|
136
|
-
readonly port: number | null;
|
|
137
|
-
/** This text is the address of the instance, for example `http://127.0.0.1:8080/`, or null. */
|
|
138
|
-
readonly url: string | null;
|
|
139
|
-
/** These fields are more data of the instance, for example its version. */
|
|
140
|
-
readonly extra?: Readonly<Record<string, unknown>> | undefined;
|
|
141
|
-
}
|
|
142
|
-
/**
|
|
143
|
-
* A discovery read is what a read of the discovery file found. A read does not throw.
|
|
144
|
-
* - `running`: the file names a live process, and its start time does not prove that it is a different process.
|
|
145
|
-
* - `absent`: no file.
|
|
146
|
-
* - `stale`: the file names a process that stopped, or a new process with the same ID.
|
|
147
|
-
* - `malformed`: the file is not a discovery record, or the read failed. The problem tells why.
|
|
148
|
-
*/
|
|
149
|
-
type DiscoveryRead = {
|
|
150
|
-
readonly kind: "running";
|
|
151
|
-
readonly record: Discovery;
|
|
152
|
-
} | {
|
|
153
|
-
readonly kind: "absent";
|
|
154
|
-
} | {
|
|
155
|
-
readonly kind: "stale";
|
|
156
|
-
readonly record: Discovery;
|
|
157
|
-
readonly why: string;
|
|
158
|
-
} | {
|
|
159
|
-
readonly kind: "malformed";
|
|
160
|
-
readonly problem: string;
|
|
161
|
-
};
|
|
162
|
-
/** These options go with a read of the discovery file. */
|
|
163
|
-
interface ReadDiscoveryOptions {
|
|
164
|
-
/** True removes a stale or malformed file. The default is false. */
|
|
165
|
-
readonly clean?: boolean | undefined;
|
|
166
|
-
}
|
|
167
|
-
/** This function reads a discovery record from a text. It gives the record, or the problem as a text. */
|
|
168
|
-
export declare const parseDiscovery: (text: string) => Discovery | string;
|
|
169
|
-
/** These fields describe where this process listens. */
|
|
170
|
-
interface DiscoveryFields {
|
|
171
|
-
readonly port?: number | null | undefined;
|
|
172
|
-
readonly url?: string | null | undefined;
|
|
173
|
-
readonly extra?: Readonly<Record<string, unknown>> | undefined;
|
|
174
|
-
}
|
|
175
|
-
/** This function gives the discovery record of the process of the host, with its start time. */
|
|
176
|
-
export declare const discoveryOf: (fields: DiscoveryFields, ports: HostPorts) => Discovery;
|
|
177
|
-
/** This function writes a discovery file. The write replaces the file in one step, thus a reader sees the old record or the new one. */
|
|
178
|
-
export declare const writeDiscovery: (path: string, record: Discovery, ports: HostPorts) => Promise<void>;
|
|
179
|
-
/**
|
|
180
|
-
* This function reads a discovery file and examines its process. It does not throw: a file that is not
|
|
181
|
-
* a record, or a failed read, gives `malformed`. With `clean`, it removes a stale or malformed file.
|
|
182
|
-
*/
|
|
183
|
-
export declare const readDiscovery: (path: string, ports: HostPorts, options?: ReadDiscoveryOptions) => Promise<DiscoveryRead>;
|
|
184
|
-
/** This function removes a discovery file when it names the process `pid`, by default the process of the host. It tells if it removed the file. */
|
|
185
|
-
export declare const removeDiscovery: (path: string, ports: HostPorts, pid?: number) => Promise<boolean>;
|
|
186
|
-
/**
|
|
187
|
-
* A lock owner is the record in a lock file: the process that holds the lock. The record can also
|
|
188
|
-
* have the child process that it holds the lock for. The lock is held while one of the two is alive.
|
|
189
|
-
*/
|
|
190
|
-
interface LockOwner extends ProcessMark {
|
|
191
|
-
readonly child?: ProcessMark | undefined;
|
|
192
|
-
}
|
|
193
|
-
/** An instance lock is a lock that this process holds. */
|
|
194
|
-
interface InstanceLock {
|
|
195
|
-
readonly path: string;
|
|
196
|
-
readonly owner: LockOwner;
|
|
197
|
-
/** This method writes a new child process in the record, or no child with null. */
|
|
198
|
-
update(child: ProcessMark | null): Promise<void>;
|
|
199
|
-
/** This method removes the lock file, when it still has the record of this lock. A second use does nothing. */
|
|
200
|
-
release(): Promise<void>;
|
|
201
|
-
}
|
|
202
|
-
/**
|
|
203
|
-
* A lock result tells what a try to take the lock found.
|
|
204
|
-
* - `acquired`: this process holds the lock. `recovered` tells why a stale lock went first, or it is null.
|
|
205
|
-
* - `held`: a live process holds the lock. Its owner is in the result.
|
|
206
|
-
* - `failed`: the lock did not come free, or the file system failed. The problem tells why.
|
|
207
|
-
*/
|
|
208
|
-
type LockResult = {
|
|
209
|
-
readonly kind: "acquired";
|
|
210
|
-
readonly lock: InstanceLock;
|
|
211
|
-
readonly recovered: string | null;
|
|
212
|
-
} | {
|
|
213
|
-
readonly kind: "held";
|
|
214
|
-
readonly owner: LockOwner;
|
|
215
|
-
} | {
|
|
216
|
-
readonly kind: "failed";
|
|
217
|
-
readonly problem: string;
|
|
218
|
-
};
|
|
219
|
-
/**
|
|
220
|
-
* A lock state is what an examination of a lock file found. An examination does not throw.
|
|
221
|
-
* - `free`: no file.
|
|
222
|
-
* - `held`: the record names a live process.
|
|
223
|
-
* - `stale`: the record names processes that stopped. The next take removes the file.
|
|
224
|
-
* - `malformed`: the file is not a record, or the read failed.
|
|
225
|
-
*/
|
|
226
|
-
type LockState = {
|
|
227
|
-
readonly kind: "free";
|
|
228
|
-
} | {
|
|
229
|
-
readonly kind: "held";
|
|
230
|
-
readonly owner: LockOwner;
|
|
231
|
-
} | {
|
|
232
|
-
readonly kind: "stale";
|
|
233
|
-
readonly owner: LockOwner;
|
|
234
|
-
readonly why: string;
|
|
235
|
-
} | {
|
|
236
|
-
readonly kind: "malformed";
|
|
237
|
-
readonly problem: string;
|
|
238
|
-
};
|
|
239
|
-
/** These options go with a take of the lock. */
|
|
240
|
-
interface LockOptions {
|
|
241
|
-
/** This count is the number of reads of a malformed file before the take removes it. The default is 3. */
|
|
242
|
-
readonly tries?: number | undefined;
|
|
243
|
-
/** This time is the pause between two reads of a malformed file, in milliseconds. The default is 100. */
|
|
244
|
-
readonly pause?: number | undefined;
|
|
245
|
-
/** This child process goes in the record at the take. */
|
|
246
|
-
readonly child?: ProcessMark | undefined;
|
|
247
|
-
}
|
|
248
|
-
/** This function reads a lock owner from the text of a lock file, or gives null for a text that is not a record. */
|
|
249
|
-
export declare const parseLockOwner: (text: string) => LockOwner | null;
|
|
250
|
-
/** This function gives the text of a lock file for an owner. */
|
|
251
|
-
export declare const lockText: (owner: LockOwner) => string;
|
|
252
|
-
/** This function examines a lock file. It does not throw. */
|
|
253
|
-
export declare const inspectInstanceLock: (path: string, ports: HostPorts) => Promise<LockState>;
|
|
254
|
-
/**
|
|
255
|
-
* This function takes the lock of one instance: a lock file with the record of this process. Thus a
|
|
256
|
-
* second instance does not start. It does not throw.
|
|
257
|
-
* - A file whose owner and child stopped is stale: it goes, and the take tries again.
|
|
258
|
-
* - A malformed file can be the file of a take that writes at this time. The take reads it again after
|
|
259
|
-
* a pause, and after `tries` reads, it removes it.
|
|
260
|
-
* - A file whose owner or child is alive gives `held`.
|
|
261
|
-
*/
|
|
262
|
-
export declare const acquireInstanceLock: (path: string, ports: HostPorts, options?: LockOptions) => Promise<LockResult>;
|
|
263
|
-
/** A command record is one command that a service operation started, and its result. */
|
|
264
|
-
interface CommandRecord {
|
|
265
|
-
readonly file: string;
|
|
266
|
-
readonly args: readonly string[];
|
|
267
|
-
readonly code: number;
|
|
268
|
-
readonly out: string;
|
|
269
|
-
}
|
|
270
|
-
/**
|
|
271
|
-
* A service outcome tells what a service operation did. An operation does not throw.
|
|
272
|
-
* - `done`: each command gave 0. `commands` and `files` tell what the operation did.
|
|
273
|
-
* - `failed`: a command gave a code that is not 0, or the file system failed. The problem tells which.
|
|
274
|
-
* - `refused`: the spec has problems, and the operation did nothing.
|
|
275
|
-
* - `unsupported`: the platform is not Windows or Linux, and the operation did nothing.
|
|
276
|
-
*/
|
|
277
|
-
type ServiceOutcome = {
|
|
278
|
-
readonly kind: "done";
|
|
279
|
-
readonly commands: readonly CommandRecord[];
|
|
280
|
-
readonly files: readonly string[];
|
|
281
|
-
} | {
|
|
282
|
-
readonly kind: "failed";
|
|
283
|
-
readonly commands: readonly CommandRecord[];
|
|
284
|
-
readonly problem: string;
|
|
285
|
-
} | {
|
|
286
|
-
readonly kind: "refused";
|
|
287
|
-
readonly problems: readonly string[];
|
|
288
|
-
} | {
|
|
289
|
-
readonly kind: "unsupported";
|
|
290
|
-
readonly platform: string;
|
|
291
|
-
};
|
|
292
|
-
/** A service status tells if the system has the service, its state, and the instance of the discovery file. */
|
|
293
|
-
interface ServiceStatus {
|
|
294
|
-
/** This flag tells if the system has the task or the unit. */
|
|
295
|
-
readonly installed: boolean;
|
|
296
|
-
/**
|
|
297
|
-
* This text is the state that the system gives, for example `Running` or `Ready` from `schtasks`, or
|
|
298
|
-
* `active` or `inactive` from `systemctl`. It is `unknown` when the system gives no state.
|
|
299
|
-
*/
|
|
300
|
-
readonly state: string;
|
|
301
|
-
/** This is the read of the discovery file, or null without a discovery path. */
|
|
302
|
-
readonly instance: DiscoveryRead | null;
|
|
303
|
-
/** These are the commands that the status started. */
|
|
304
|
-
readonly commands: readonly CommandRecord[];
|
|
305
|
-
}
|
|
306
|
-
/** These options go with an install. */
|
|
307
|
-
interface InstallOptions {
|
|
308
|
-
/** True starts the service after the install. The default is true. */
|
|
309
|
-
readonly start?: boolean | undefined;
|
|
310
|
-
}
|
|
311
|
-
/** These options go with an operation that stops the instance: the discovery file that names it. */
|
|
312
|
-
interface InstanceOptions {
|
|
313
|
-
/** This path is the discovery file of the instance. With it, the operation stops the process tree of a live instance. */
|
|
314
|
-
readonly discovery?: string | undefined;
|
|
315
|
-
}
|
|
316
|
-
/** These are the files of a service on this platform. */
|
|
317
|
-
interface ServicePaths {
|
|
318
|
-
/** This path is the task file on Windows, or the unit on Linux. */
|
|
319
|
-
readonly unit: string;
|
|
320
|
-
/** This path is the timer of a daily job on Linux, or null. */
|
|
321
|
-
readonly timer: string | null;
|
|
322
|
-
}
|
|
323
|
-
/** This function gives the files of a service on the platform of the ports. */
|
|
324
|
-
export declare const servicePaths: (spec: ServiceSpec, ports: HostPorts) => ServicePaths;
|
|
325
|
-
/**
|
|
326
|
-
* This function installs a service of the user, and by default starts it. It does not throw.
|
|
327
|
-
* - On Windows, it writes the task file in UTF-16 to `stateDir`, and starts `schtasks /Create /XML <file> /F`, then `schtasks /Run`.
|
|
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.
|
|
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.
|
|
332
|
-
*/
|
|
333
|
-
export declare const installService: (spec: ServiceSpec, ports: HostPorts, options?: InstallOptions) => Promise<ServiceOutcome>;
|
|
334
|
-
/**
|
|
335
|
-
* This function removes a service. It does not throw. On Windows, it ends the task and deletes it. On
|
|
336
|
-
* Linux, it disables and stops the unit, removes its files and reloads systemd. With a discovery file,
|
|
337
|
-
* it then stops the process tree of an instance that stays.
|
|
338
|
-
*/
|
|
339
|
-
export declare const uninstallService: (spec: ServiceSpec, ports: HostPorts, options?: InstanceOptions) => Promise<ServiceOutcome>;
|
|
340
|
-
/** This function enables a service and starts it. It does not throw. On Windows, it enables the task and runs it. */
|
|
341
|
-
export declare const startService: (spec: ServiceSpec, ports: HostPorts) => Promise<ServiceOutcome>;
|
|
342
|
-
/**
|
|
343
|
-
* This function stops a service, and keeps it stopped until `startService`. It does not throw.
|
|
344
|
-
* - On Windows, it disables the task, thus its time trigger does not start it again, and ends the task.
|
|
345
|
-
* With a discovery file, it then stops the process tree of the instance. Windows has no signal that a child can catch.
|
|
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,
|
|
348
|
-
* thus `run()` stops in its stages. A daily job that operates stops too.
|
|
349
|
-
*/
|
|
350
|
-
export declare const stopService: (spec: ServiceSpec, ports: HostPorts, options?: InstanceOptions) => Promise<ServiceOutcome>;
|
|
351
|
-
/**
|
|
352
|
-
* This function gives the status of a service. It does not throw. A service that the system does not
|
|
353
|
-
* have gives `installed: false`. A malformed or stale discovery file gives its read, and not a throw.
|
|
354
|
-
*/
|
|
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
|
-
}
|
|
367
|
-
/**
|
|
368
|
-
* A ready probe tells when a program is ready.
|
|
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.
|
|
373
|
-
* - `tcp`: a TCP connection to the port opens. The default host is `127.0.0.1`.
|
|
374
|
-
* - `command`: a command gives the exit code 0.
|
|
375
|
-
*/
|
|
376
|
-
type ReadyProbe = {
|
|
377
|
-
readonly kind: "http";
|
|
378
|
-
readonly url: string;
|
|
379
|
-
readonly status?: number | undefined;
|
|
380
|
-
readonly fresh?: readonly FreshnessBound[] | undefined;
|
|
381
|
-
readonly now?: string | undefined;
|
|
382
|
-
} | {
|
|
383
|
-
readonly kind: "tcp";
|
|
384
|
-
readonly port: number;
|
|
385
|
-
readonly host?: string | undefined;
|
|
386
|
-
} | {
|
|
387
|
-
readonly kind: "command";
|
|
388
|
-
readonly program: string;
|
|
389
|
-
readonly args: readonly string[];
|
|
390
|
-
readonly cwd?: string | undefined;
|
|
391
|
-
};
|
|
392
|
-
/** A probe result is the result of one use of a probe. A failure tells why. */
|
|
393
|
-
type ProbeResult = {
|
|
394
|
-
readonly ok: true;
|
|
395
|
-
} | {
|
|
396
|
-
readonly ok: false;
|
|
397
|
-
readonly why: string;
|
|
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;
|
|
401
|
-
/** This function gives the problems of a probe: each value that a probe cannot use. */
|
|
402
|
-
export declare const probeProblems: (probe: ReadyProbe) => string[];
|
|
403
|
-
/** This function uses a probe one time, in a timeout of milliseconds. It does not throw. */
|
|
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;
|
|
492
|
-
/** An env file is the variables of a file of environment variables, and the problem of each line that it skipped. */
|
|
493
|
-
interface EnvFile {
|
|
494
|
-
readonly env: Readonly<Record<string, string>>;
|
|
495
|
-
readonly problems: readonly string[];
|
|
496
|
-
}
|
|
497
|
-
/**
|
|
498
|
-
* This function reads a file of environment variables, one `KEY=value` on each line. It is a pure
|
|
499
|
-
* function. It does not throw: it skips a bad line and gives its problem.
|
|
500
|
-
* - A blank line and a line that starts with `#` are skipped. A line can start with `export `.
|
|
501
|
-
* - A value in single quotes is literal. A value in double quotes has the escapes `\n`, `\t`, `\"` and `\\`.
|
|
502
|
-
* - A value without quotes ends at ` #`, and its spaces at the two ends go.
|
|
503
|
-
* - A key that comes again replaces its value.
|
|
504
|
-
*/
|
|
505
|
-
export declare const parseEnvFile: (text: string) => EnvFile;
|
|
506
|
-
/** A log spec tells where the output of a program goes, and when the file rotates. */
|
|
507
|
-
interface LogSpec {
|
|
508
|
-
/** This path is the log file. */
|
|
509
|
-
readonly path: string;
|
|
510
|
-
/** This size is the most that the file gets before it rotates, for example `{ value: 10, unit: "MB" }`. */
|
|
511
|
-
readonly maxSize: Quantity;
|
|
512
|
-
/** This count is the number of old files that stay: `<path>.1` is the newest. 0 keeps no old file. */
|
|
513
|
-
readonly keep: number;
|
|
514
|
-
}
|
|
515
|
-
/** A rotating log writes data to a file, and rotates the file at its size. */
|
|
516
|
-
interface RotatingLog {
|
|
517
|
-
/** This method adds data to the log. The writes occur in sequence. A failed write does not throw. */
|
|
518
|
-
write(chunk: string | Uint8Array): void;
|
|
519
|
-
/** This promise ends when each write before it is done. */
|
|
520
|
-
flush(): Promise<void>;
|
|
521
|
-
/** This count is the number of writes that failed. */
|
|
522
|
-
readonly failures: number;
|
|
523
|
-
}
|
|
524
|
-
/**
|
|
525
|
-
* This function makes a rotating log on a file port. Before a write that makes the file larger than
|
|
526
|
-
* `maxSize`, the file rotates: `<path>.<keep>` goes, each `<path>.<n>` becomes `<path>.<n + 1>`, and the
|
|
527
|
-
* file becomes `<path>.1`. A chunk larger than the size goes into a new file of its own.
|
|
528
|
-
*/
|
|
529
|
-
export declare const rotatingLog: (spec: LogSpec, files: FilePort) => RotatingLog;
|
|
530
|
-
/** A ready spec tells how the supervisor finds that a program is ready. */
|
|
531
|
-
interface ReadySpec {
|
|
532
|
-
readonly probe: ReadyProbe;
|
|
533
|
-
/** This time is the pause between two uses of the probe. */
|
|
534
|
-
readonly interval: Quantity;
|
|
535
|
-
/** This time is the most that one use of the probe can take. */
|
|
536
|
-
readonly timeout: Quantity;
|
|
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. */
|
|
538
|
-
readonly within: Quantity;
|
|
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
|
-
}
|
|
554
|
-
/** A program restart tells how the supervisor starts a program again after it stops. */
|
|
555
|
-
interface ProgramRestart {
|
|
556
|
-
/** This backoff gives the wait before each start again, in milliseconds, as `retrier` uses it. */
|
|
557
|
-
readonly backoff: Backoff;
|
|
558
|
-
/** This time is how long a program is ready before its count of tries goes back to 0. */
|
|
559
|
-
readonly resetAfter: Quantity;
|
|
560
|
-
}
|
|
561
|
-
/** A stop spec tells how the supervisor stops a program. */
|
|
562
|
-
interface StopSpec {
|
|
563
|
-
/** This time is the wait for the staged stop, before the supervisor stops the process tree. */
|
|
564
|
-
readonly grace: Quantity;
|
|
565
|
-
/** This message goes on the IPC channel of a child that has one. The default is `"shutdown"`, which `run()` can match. */
|
|
566
|
-
readonly message?: MessageShape | undefined;
|
|
567
|
-
/** This signal goes to a child without an IPC channel on Linux. The default is `SIGTERM`. */
|
|
568
|
-
readonly signal?: "SIGINT" | "SIGTERM" | undefined;
|
|
569
|
-
}
|
|
570
|
-
/** A program spec tells one program of a group, and what it needs before it starts. */
|
|
571
|
-
interface ProgramSpec {
|
|
572
|
-
/** This name is the name of the program in the group: letters, digits, `.`, `_` and `-`. */
|
|
573
|
-
readonly name: string;
|
|
574
|
-
readonly program: string;
|
|
575
|
-
readonly args?: readonly string[] | undefined;
|
|
576
|
-
readonly cwd?: string | undefined;
|
|
577
|
-
/** These variables go to the program. They replace the variables of the env file and of the host. */
|
|
578
|
-
readonly env?: Readonly<Record<string, string>> | undefined;
|
|
579
|
-
/** This file gives variables to the program at each start (`parseEnvFile`). They replace the variables of the host. */
|
|
580
|
-
readonly envFile?: string | undefined;
|
|
581
|
-
/** These are the programs that must be ready before this program starts. */
|
|
582
|
-
readonly after?: readonly string[] | undefined;
|
|
583
|
-
/** This spec tells when the program is ready. Without it, the program is ready when it starts. */
|
|
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;
|
|
587
|
-
/** This policy starts the program again after it stops. The default is `DEFAULT_RESTART`. Null does not start it again. */
|
|
588
|
-
readonly restart?: ProgramRestart | null | undefined;
|
|
589
|
-
/** This spec tells the log file. The default is `<stateDir>/logs/<name>.log`, 10 MB, with 3 old files. Null keeps no log. */
|
|
590
|
-
readonly log?: LogSpec | null | undefined;
|
|
591
|
-
/** True gives the child an IPC channel, for the staged stop of a Node program. The default is false. */
|
|
592
|
-
readonly ipc?: boolean | undefined;
|
|
593
|
-
/** This spec tells the stop. The default is a grace of 10 s. */
|
|
594
|
-
readonly stop?: StopSpec | undefined;
|
|
595
|
-
/** These fields go in the discovery file of the program, `<stateDir>/<name>.json`. */
|
|
596
|
-
readonly listen?: {
|
|
597
|
-
readonly port?: number | null | undefined;
|
|
598
|
-
readonly url?: string | null | undefined;
|
|
599
|
-
} | undefined;
|
|
600
|
-
}
|
|
601
|
-
/** A group spec tells a group of programs that one supervisor starts in sequence and keeps alive. */
|
|
602
|
-
interface GroupSpec {
|
|
603
|
-
readonly name: string;
|
|
604
|
-
/** This folder keeps the lock, the discovery file and the log of each program. */
|
|
605
|
-
readonly stateDir: string;
|
|
606
|
-
readonly programs: readonly ProgramSpec[];
|
|
607
|
-
}
|
|
608
|
-
/** These options go with a supervisor. */
|
|
609
|
-
interface GroupOptions {
|
|
610
|
-
/** This function gives a number in [0, 1) for the jitter of the backoff. The default is `Math.random`. */
|
|
611
|
-
readonly random?: (() => number) | undefined;
|
|
612
|
-
}
|
|
613
|
-
/**
|
|
614
|
-
* A program phase tells where a program of a group is.
|
|
615
|
-
* - `waiting`: a program that it needs is not ready.
|
|
616
|
-
* - `starting`: it runs, and its probe did not pass.
|
|
617
|
-
* - `ready`: it runs, and its probe passed.
|
|
618
|
-
* - `backoff`: it stopped, and it starts again after its backoff.
|
|
619
|
-
* - `held`: another instance holds its lock. The supervisor tries again after the backoff.
|
|
620
|
-
* - `exited`: it stopped, and it has no restart.
|
|
621
|
-
* - `stopping`, `stopped`: the stop of the group.
|
|
622
|
-
*/
|
|
623
|
-
type ProgramPhase = "waiting" | "starting" | "ready" | "backoff" | "held" | "exited" | "stopping" | "stopped";
|
|
624
|
-
/** A program state is the state of one program of a group, for a status. */
|
|
625
|
-
interface ProgramState {
|
|
626
|
-
readonly name: string;
|
|
627
|
-
readonly phase: ProgramPhase;
|
|
628
|
-
/** This number is the process ID of the child, or null. */
|
|
629
|
-
readonly pid: number | null;
|
|
630
|
-
/** This count is the number of starts again since the start of the group. */
|
|
631
|
-
readonly restarts: number;
|
|
632
|
-
/** This text tells the last problem, for example why the probe failed, or it is null. */
|
|
633
|
-
readonly detail: string | null;
|
|
634
|
-
}
|
|
635
|
-
/** A group supervisor starts the programs of a group in sequence, starts each again after it stops, and stops them in stages. */
|
|
636
|
-
interface GroupSupervisor {
|
|
637
|
-
/** This method starts each program whose programs are ready. A second use does nothing. */
|
|
638
|
-
start(): void;
|
|
639
|
-
/** This method stops each program in the reverse sequence of the start. A second use gives the same promise. */
|
|
640
|
-
stop(): Promise<void>;
|
|
641
|
-
/** This method gives the state of each program, in the sequence of the spec. */
|
|
642
|
-
states(): readonly ProgramState[];
|
|
643
|
-
}
|
|
644
|
-
/**
|
|
645
|
-
* This restart is the default. The first wait is 1 s, and each wait after it is two times longer, to 1 min.
|
|
646
|
-
* The jitter subtracts up to half of each wait. The count of tries goes back to 0 after 1 min ready.
|
|
647
|
-
*/
|
|
648
|
-
export declare const DEFAULT_RESTART: ProgramRestart;
|
|
649
|
-
/**
|
|
650
|
-
* This function gives the start sequence of a group, as layers of names. Each program of a layer needs only programs of the
|
|
651
|
-
* layers before it. A program in a cycle, or after an unknown program, is in no layer. `groupProblems` names it.
|
|
652
|
-
*/
|
|
653
|
-
export declare const startOrder: (spec: GroupSpec) => string[][];
|
|
654
|
-
/** This function gives the problems of a group spec: each value that the supervisor cannot use. */
|
|
655
|
-
export declare const groupProblems: (spec: GroupSpec) => string[];
|
|
656
|
-
/**
|
|
657
|
-
* This function makes the supervisor of a group. It refuses a spec with problems. Each effect goes
|
|
658
|
-
* through the ports, thus a test gives `fakeHost()` and starts no process.
|
|
659
|
-
* - A program starts when each program of its `after` is ready. It takes its lock first, thus a second instance does not start.
|
|
660
|
-
* - A program with a probe is ready when its probe passes. A program that is not ready in `within` stops, and starts again.
|
|
661
|
-
* - A program that stops starts again after the backoff of its `retrier`, when its programs are ready.
|
|
662
|
-
* - Its output goes to its rotating log. Its environment is the host, then its env file, then its `env`.
|
|
663
|
-
* - The stop goes in the reverse sequence: the staged stop first, and after the grace, the stop of the process tree by its ID.
|
|
664
|
-
*/
|
|
665
|
-
export declare const superviseGroup: (spec: GroupSpec, ports: HostPorts, options?: GroupOptions) => GroupSupervisor;
|
|
666
|
-
/** These options go with the ports of Node. */
|
|
667
|
-
interface NodeHostOptions {
|
|
668
|
-
readonly logger?: Logger | undefined;
|
|
669
|
-
/** This clock gives the time and the timers. The default is `realClock`. */
|
|
670
|
-
readonly clock?: Clock | undefined;
|
|
671
|
-
}
|
|
672
|
-
/**
|
|
673
|
-
* This function gives the host ports of Node: `child_process`, `fs/promises`, `net`, `fetch` and `process`.
|
|
674
|
-
* Only a program uses it. A test gives `fakeHost()` of `./testing`, thus it starts no process and installs no task.
|
|
675
|
-
*/
|
|
676
|
-
export declare const nodeHostPorts: (options?: NodeHostOptions) => HostPorts;
|
|
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 };
|
|
7
|
+
import { ChildHandle, CommandOptions, CommandPort, CommandResult, FilePort, HostPorts, HttpAnswer, NetPort, ProcessMark, ProcessesPort, SpawnRequest, StopSignal, joinPath } from "./host/ports.js";
|
|
8
|
+
import { RestartPolicy, ServiceSpec, ServiceStart, TaskContext, renderSystemdTimer, renderSystemdUnit, renderTaskXml, serviceProblems, systemdArg, utf16le, windowsArg } from "./host/render.js";
|
|
9
|
+
import { START_MARGIN_MS, TreeStopOutcome, sameProcess, stopTree } from "./host/processes.js";
|
|
10
|
+
import { Discovery, DiscoveryFields, DiscoveryRead, ReadDiscoveryOptions, discoveryOf, parseDiscovery, readDiscovery, removeDiscovery, writeDiscovery } from "./host/discovery.js";
|
|
11
|
+
import { InstanceLock, LockOptions, LockOwner, LockResult, LockState, acquireInstanceLock, inspectInstanceLock, lockText, parseLockOwner } from "./host/lock.js";
|
|
12
|
+
import { CommandRecord, InstallOptions, InstanceOptions, ServiceOutcome, ServicePaths, ServiceStatus, installService, servicePaths, serviceStatus, startService, stopService, uninstallService } from "./host/install.js";
|
|
13
|
+
import { FreshnessBound, PROBE_BODY_LIMIT, ProbeResult, ReadyProbe, probeOnce, probeProblems } from "./host/probes.js";
|
|
14
|
+
import { DEFAULT_VERDICT, TargetChange, TargetHealth, TargetState, TargetVerdict, TargetWatch, WatchOptions, WatchSpec, WatchTarget, watchProblems, watchTargets } from "./host/watch.js";
|
|
15
|
+
import { EnvFile, parseEnvFile } from "./host/env.js";
|
|
16
|
+
import { LogSpec, RotatingLog, rotatingLog } from "./host/logs.js";
|
|
17
|
+
import { AliveSpec, DEFAULT_RESTART, GroupOptions, GroupSpec, GroupSupervisor, ProgramPhase, ProgramRestart, ProgramSpec, ProgramState, ReadySpec, StopSpec, groupProblems, startOrder, superviseGroup } from "./host/group.js";
|
|
18
|
+
import { NodeHostOptions, nodeHostPorts } from "./host/node.js";
|
|
19
|
+
export { type AliveSpec, type ChildHandle, type CommandOptions, type CommandPort, type CommandRecord, type CommandResult, DEFAULT_RESTART, DEFAULT_VERDICT, 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, PROBE_BODY_LIMIT, type ProbeResult, type ProcessMark, type ProcessesPort, type ProgramPhase, type ProgramRestart, type ProgramSpec, type ProgramState, type ReadDiscoveryOptions, type ReadyProbe, type ReadySpec, type RestartPolicy, type RotatingLog, START_MARGIN_MS, 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, acquireInstanceLock, discoveryOf, groupProblems, inspectInstanceLock, installService, joinPath, lockText, nodeHostPorts, parseDiscovery, parseEnvFile, parseLockOwner, probeOnce, probeProblems, readDiscovery, removeDiscovery, renderSystemdTimer, renderSystemdUnit, renderTaskXml, rotatingLog, sameProcess, servicePaths, serviceProblems, serviceStatus, startOrder, startService, stopService, stopTree, superviseGroup, systemdArg, uninstallService, utf16le, watchProblems, watchTargets, windowsArg, writeDiscovery };
|