@n8io/baseline-shutdown 3.0.1 → 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 +36 -15
- package/dist/index.d.ts +29 -6
- package/dist/index.js +21 -8
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -1,36 +1,38 @@
|
|
|
1
1
|
# @n8io/baseline-shutdown
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Rollouts that let running work finish**: on SIGTERM, stop taking work, let running work finish, then close resources one by one, always inside the deadline.
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
6
|
pnpm add @n8io/baseline-shutdown
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
<p align="center"><img src="https://raw.githubusercontent.com/n8io/baseline/main/docs/readme/shutdown-order.svg" width="880" alt="Shutdown on a 25 second timeline. A 5 second drain while /readyz answers 503, then the http and live intakes close together, then queue, database, health and telemetry close one by one, and the process exits 0, well before the 20 second intake cutoff and the 25 second deadline."></p>
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
11
|
+
## Guarantees
|
|
12
|
+
|
|
13
|
+
| You get | How |
|
|
14
|
+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| **Out of rotation first** | `isShuttingDown()` turns true at the signal, so readiness answers 503 while the process keeps serving for `drainDelayMs`. |
|
|
16
|
+
| **Running work finishes** | Every intake closes at once; each stops accepting, then waits for its active work. |
|
|
17
|
+
| **Resources outlive their users** | Resources close one by one, in the order you list them, after every intake is done; telemetry last flushes everything. |
|
|
18
|
+
| **Always exits, always on time** | At `deadlineMs` it gives up and exits, keeping the last 5 s for the resources even when an intake hangs. |
|
|
19
|
+
| **An honest exit code** | 0 when every step closed in time; 1 when a step threw or ran late, or after a crash. |
|
|
20
|
+
| **Crashes shut down too** | `uncaughtException` and `unhandledRejection` are logged at fatal and run the same shutdown, with no drain. |
|
|
21
|
+
| **One broken step stops nothing** | A step that throws is logged at error, and the rest still close. |
|
|
18
22
|
|
|
19
23
|
## Example
|
|
20
24
|
|
|
21
25
|
```ts
|
|
22
|
-
import { httpServerClose } from "@n8io/baseline-http";
|
|
23
26
|
import { shutdownHandleCreate } from "@n8io/baseline-shutdown";
|
|
24
|
-
import { telemetryShutdown } from "@n8io/baseline-telemetry";
|
|
25
27
|
|
|
26
28
|
const shutdown = shutdownHandleCreate({
|
|
27
|
-
drainDelayMs:
|
|
29
|
+
drainDelayMs: ENV.SHUTDOWN_DRAIN_DELAY_MS ?? 5_000,
|
|
28
30
|
intakes: [
|
|
29
31
|
{ close: () => httpServerClose(server), name: "http" },
|
|
30
32
|
{ close: () => liveHub.close(), name: "live" },
|
|
31
33
|
],
|
|
32
34
|
resources: [
|
|
33
|
-
{ close: () => queue.
|
|
35
|
+
{ close: () => queue.close(), name: "queue" },
|
|
34
36
|
{ close: () => pgPool.end(), name: "database" },
|
|
35
37
|
{ close: () => health.close(), name: "health" },
|
|
36
38
|
{ close: () => telemetryShutdown(), name: "telemetry" },
|
|
@@ -38,6 +40,25 @@ const shutdown = shutdownHandleCreate({
|
|
|
38
40
|
});
|
|
39
41
|
```
|
|
40
42
|
|
|
41
|
-
|
|
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.
|
|
44
|
+
|
|
45
|
+
## Reference
|
|
46
|
+
|
|
47
|
+
<details><summary><b>Exports</b></summary>
|
|
48
|
+
|
|
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). |
|
|
55
|
+
|
|
56
|
+
The steps, counted from the signal:
|
|
57
|
+
|
|
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.
|
|
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.
|
|
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.
|
|
62
|
+
</details>
|
|
42
63
|
|
|
43
|
-
|
|
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.
|
|
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
|
}
|