@n8io/baseline-shutdown 3.0.2 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -12
- package/dist/index.d.ts +29 -6
- package/dist/index.js +21 -8
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -23,15 +23,16 @@ pnpm add @n8io/baseline-shutdown
|
|
|
23
23
|
## Example
|
|
24
24
|
|
|
25
25
|
```ts
|
|
26
|
-
|
|
26
|
+
import { shutdownHandleCreate } from "@n8io/baseline-shutdown";
|
|
27
|
+
|
|
27
28
|
const shutdown = shutdownHandleCreate({
|
|
28
|
-
drainDelayMs:
|
|
29
|
+
drainDelayMs: ENV.SHUTDOWN_DRAIN_DELAY_MS ?? 5_000,
|
|
29
30
|
intakes: [
|
|
30
31
|
{ close: () => httpServerClose(server), name: "http" },
|
|
31
32
|
{ close: () => liveHub.close(), name: "live" },
|
|
32
33
|
],
|
|
33
34
|
resources: [
|
|
34
|
-
{ close: () => queue.
|
|
35
|
+
{ close: () => queue.close(), name: "queue" },
|
|
35
36
|
{ close: () => pgPool.end(), name: "database" },
|
|
36
37
|
{ close: () => health.close(), name: "health" },
|
|
37
38
|
{ close: () => telemetryShutdown(), name: "telemetry" },
|
|
@@ -39,24 +40,25 @@ const shutdown = shutdownHandleCreate({
|
|
|
39
40
|
});
|
|
40
41
|
```
|
|
41
42
|
|
|
42
|
-
|
|
43
|
+
`httpServerClose` is from `@n8io/baseline-http` and `telemetryShutdown` from `@n8io/baseline-telemetry`. A Project does not test the handle itself: it owns process signals and exits the process. Test each step's `close` on its own.
|
|
43
44
|
|
|
44
45
|
## Reference
|
|
45
46
|
|
|
46
47
|
<details><summary><b>Exports</b></summary>
|
|
47
48
|
|
|
48
|
-
| Export | Does
|
|
49
|
-
| -------------------------------------------------------------------------- |
|
|
50
|
-
| `shutdownHandleCreate({ intakes, resources, deadlineMs?, drainDelayMs? })` | Owns `SIGTERM`, `SIGINT`, `uncaughtException` and `unhandledRejection`, and exits the process: 0 when every step closed in time, 1 otherwise or after a crash. A second signal is ignored. |
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
49
|
+
| Export | Does |
|
|
50
|
+
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| `shutdownHandleCreate({ intakes, resources, deadlineMs?, drainDelayMs? })` | Owns `SIGTERM`, `SIGINT`, `uncaughtException` and `unhandledRejection`, and exits the process: 0 when every step closed in time, 1 otherwise or after a crash. A second signal is ignored. A `deadlineMs` that is not an integer over 5000, or a `drainDelayMs` that is not a whole number under `deadlineMs` minus 5000, throws a `TypeError`. |
|
|
52
|
+
| `ShutdownOptions` | The options object above. `null` means the default, as leaving it out does. |
|
|
53
|
+
| `ShutdownHandle` | `isShuttingDown()`, for `/readyz`. |
|
|
54
|
+
| `ShutdownStep` | `{ name, close }`: one intake (HTTP server, live streams, Event handlers) or resource (queue, pools, clients, health, telemetry). |
|
|
53
55
|
|
|
54
56
|
The steps, counted from the signal:
|
|
55
57
|
|
|
56
|
-
1. Waits `drainDelayMs` (default 5 s;
|
|
57
|
-
2. Closes every intake (HTTP server, live streams,
|
|
58
|
+
1. Waits `drainDelayMs` (default 5 s; the Template sets 0 in development) while readiness answers 503.
|
|
59
|
+
2. Closes every intake (HTTP server, live streams, Event handlers) at once. One still open at the cutoff (`deadlineMs` minus 5 s) is logged at warn, and shutdown moves on.
|
|
58
60
|
3. Closes each resource (queue, pools, clients, health, telemetry last) in order. One still open at the deadline is logged at error, with every resource after it.
|
|
59
61
|
4. Gives up at `deadlineMs` (default 25 s), keeping the last 5 s for the resources, and logs `Shutdown finished` with the exit code.
|
|
60
62
|
</details>
|
|
61
63
|
|
|
62
|
-
**Needs**
|
|
64
|
+
**Needs** no peers (it logs through `@n8io/baseline-logger`, a dependency); `SHUTDOWN_DRAIN_DELAY_MS` by the Template's convention (read by the caller, not this Package).
|
package/dist/index.d.ts
CHANGED
|
@@ -1,15 +1,38 @@
|
|
|
1
|
-
|
|
1
|
+
/**
|
|
2
|
+
* One thing to close on shutdown: an intake (HTTP server, live streams, Event handlers) or a
|
|
3
|
+
* resource (the queue, pools, clients, health, telemetry).
|
|
4
|
+
*/
|
|
5
|
+
type ShutdownStep = {
|
|
2
6
|
name: string;
|
|
3
7
|
close: () => Promise<void>;
|
|
4
8
|
};
|
|
9
|
+
/** What `shutdownHandleCreate` closes, and how long it may take. */
|
|
5
10
|
type ShutdownOptions = {
|
|
6
|
-
|
|
7
|
-
|
|
11
|
+
/**
|
|
12
|
+
* When it gives up and exits, counted from the signal, drain delay included. Over 5000: the
|
|
13
|
+
* last 5 s belong to the resources. Default 25 000.
|
|
14
|
+
*/
|
|
15
|
+
deadlineMs?: number | null;
|
|
16
|
+
/**
|
|
17
|
+
* How long readiness answers 503 before the intakes close, so load balancers notice. Under
|
|
18
|
+
* `deadlineMs` minus 5000, so the intakes get time to close. Default 5000; the Template reads
|
|
19
|
+
* `SHUTDOWN_DRAIN_DELAY_MS` and sets 0 in development.
|
|
20
|
+
*/
|
|
21
|
+
drainDelayMs?: number | null;
|
|
22
|
+
/** Closed together; each stops accepting, then waits for its active work. */
|
|
8
23
|
intakes: ShutdownStep[];
|
|
24
|
+
/** Closed one by one, in order, after every intake is done; telemetry last. */
|
|
9
25
|
resources: ShutdownStep[];
|
|
10
26
|
};
|
|
11
|
-
|
|
27
|
+
/** The running shutdown handle. `isShuttingDown()` turns true at the signal, for `/readyz`. */
|
|
28
|
+
type ShutdownHandle = {
|
|
12
29
|
isShuttingDown(): boolean;
|
|
13
30
|
};
|
|
14
|
-
|
|
15
|
-
|
|
31
|
+
/**
|
|
32
|
+
* Owns SIGTERM, SIGINT, uncaughtException and unhandledRejection, and exits the process: 0 when
|
|
33
|
+
* every step closed in time, 1 otherwise or after a crash. Throws a `TypeError` on a
|
|
34
|
+
* `deadlineMs` that is not an integer over 5000, or a `drainDelayMs` that is not a whole number
|
|
35
|
+
* under `deadlineMs` minus 5000.
|
|
36
|
+
*/
|
|
37
|
+
export declare const shutdownHandleCreate: ({ deadlineMs: deadlineMsGiven, drainDelayMs: drainDelayMsGiven, intakes, resources }: ShutdownOptions) => ShutdownHandle;
|
|
38
|
+
export type { ShutdownHandle, ShutdownOptions, ShutdownStep };
|
package/dist/index.js
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { logger } from "@n8io/baseline-logger";
|
|
2
|
-
// src/
|
|
3
|
-
const
|
|
4
|
-
const
|
|
2
|
+
// src/shutdown-handle.ts
|
|
3
|
+
const resourceReserveMs = 5e3;
|
|
4
|
+
const timedOut = Symbol("timedOut");
|
|
5
5
|
const timeout = (ms) => new Promise((resolve) => {
|
|
6
|
-
setTimeout(() => resolve(
|
|
6
|
+
setTimeout(() => resolve(timedOut), Math.max(0, ms));
|
|
7
7
|
});
|
|
8
8
|
const stepClose = async (kind, step) => {
|
|
9
9
|
try {
|
|
@@ -14,12 +14,25 @@ const stepClose = async (kind, step) => {
|
|
|
14
14
|
return false;
|
|
15
15
|
}
|
|
16
16
|
};
|
|
17
|
-
const
|
|
17
|
+
const deadlineMsDefault = 25e3;
|
|
18
|
+
const drainDelayMsDefault = 5e3;
|
|
19
|
+
/**
|
|
20
|
+
* Owns SIGTERM, SIGINT, uncaughtException and unhandledRejection, and exits the process: 0 when
|
|
21
|
+
* every step closed in time, 1 otherwise or after a crash. Throws a `TypeError` on a
|
|
22
|
+
* `deadlineMs` that is not an integer over 5000, or a `drainDelayMs` that is not a whole number
|
|
23
|
+
* under `deadlineMs` minus 5000.
|
|
24
|
+
*/
|
|
25
|
+
const shutdownHandleCreate = ({ deadlineMs: deadlineMsGiven, drainDelayMs: drainDelayMsGiven, intakes, resources }) => {
|
|
26
|
+
const deadlineMs = deadlineMsGiven ?? deadlineMsDefault;
|
|
27
|
+
const drainDelayMs = drainDelayMsGiven ?? drainDelayMsDefault;
|
|
28
|
+
if (!Number.isInteger(deadlineMs) || deadlineMs <= resourceReserveMs) throw new TypeError(`shutdownHandleCreate: deadlineMs must be an integer over ${resourceReserveMs}, not ${deadlineMs}`);
|
|
29
|
+
if (!Number.isInteger(drainDelayMs) || drainDelayMs < 0) throw new TypeError(`shutdownHandleCreate: drainDelayMs must be a whole number, not ${drainDelayMs}`);
|
|
30
|
+
if (drainDelayMs >= deadlineMs - resourceReserveMs) throw new TypeError(`shutdownHandleCreate: drainDelayMs must be under deadlineMs minus ${resourceReserveMs} (${deadlineMs - resourceReserveMs}), not ${drainDelayMs}`);
|
|
18
31
|
let shuttingDown = false;
|
|
19
32
|
let crashed = false;
|
|
20
33
|
const shutdownRun = async (drainMs) => {
|
|
21
34
|
let clean = true;
|
|
22
|
-
const cutoff = timeout(deadlineMs -
|
|
35
|
+
const cutoff = timeout(deadlineMs - resourceReserveMs);
|
|
23
36
|
const deadline = timeout(deadlineMs);
|
|
24
37
|
await Promise.race([timeout(drainMs), cutoff]);
|
|
25
38
|
const open = new Set(intakes);
|
|
@@ -29,13 +42,13 @@ const shutdownHandleCreate = ({ deadlineMs = 25e3, drainDelayMs = 5e3, intakes,
|
|
|
29
42
|
return closed;
|
|
30
43
|
}));
|
|
31
44
|
const intakeResult = await Promise.race([intakesDone, cutoff]);
|
|
32
|
-
if (intakeResult ===
|
|
45
|
+
if (intakeResult === timedOut) {
|
|
33
46
|
clean = false;
|
|
34
47
|
for (const intake of open) logger.warn(`Intake ${intake.name} still open at the cutoff`);
|
|
35
48
|
} else if (intakeResult.includes(false)) clean = false;
|
|
36
49
|
for (const [index, resource] of resources.entries()) {
|
|
37
50
|
const closed = await Promise.race([stepClose("Resource", resource), deadline]);
|
|
38
|
-
if (closed ===
|
|
51
|
+
if (closed === timedOut) {
|
|
39
52
|
clean = false;
|
|
40
53
|
for (const left of resources.slice(index)) logger.error(`Resource ${left.name} still open at the deadline`);
|
|
41
54
|
break;
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@n8io/baseline-shutdown",
|
|
3
|
-
"version": "3.0
|
|
4
|
-
"description": "Graceful shutdown:
|
|
3
|
+
"version": "3.1.0",
|
|
4
|
+
"description": "Graceful shutdown on SIGTERM: stop taking work, let running work finish, then close resources in order inside a deadline.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"engines": {
|
|
@@ -27,11 +27,12 @@
|
|
|
27
27
|
"registry": "https://registry.npmjs.org"
|
|
28
28
|
},
|
|
29
29
|
"dependencies": {
|
|
30
|
-
"@n8io/baseline-logger": "^3.1.
|
|
30
|
+
"@n8io/baseline-logger": "^3.1.2"
|
|
31
31
|
},
|
|
32
32
|
"scripts": {
|
|
33
33
|
"build": "tsdown",
|
|
34
34
|
"check": "tsc --noEmit && pnpm pack --out dist/package.tgz && publint dist/package.tgz --strict && attw dist/package.tgz --profile esm-only",
|
|
35
|
-
"test": "vitest run"
|
|
35
|
+
"test": "vitest run",
|
|
36
|
+
"test:unit": "vitest run"
|
|
36
37
|
}
|
|
37
38
|
}
|