@n8io/baseline-shutdown 3.0.1 → 3.0.2

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.
Files changed (2) hide show
  1. package/README.md +34 -15
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,28 +1,29 @@
1
1
  # @n8io/baseline-shutdown
2
2
 
3
- Graceful shutdown in a fixed order: stop taking work, let running work finish, then close resources one by one.
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
- ## Exports
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
- - `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.
12
- 1. Waits `drainDelayMs` (default 5 s; pass 0 outside production) while readiness answers 503.
13
- 2. Closes every intake (HTTP server, live streams, Consumers) at once.
14
- 3. Closes each resource (queue, pools, clients, health, telemetry last) in order.
15
- 4. Gives up at `deadlineMs` (default 25 s), keeping the last 5 s for the resources.
16
- - `ShutdownHandle`: `isShuttingDown()`, for `/readyz`.
17
- - `ShutdownStep`: `{ name, close }`.
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
- import { shutdownHandleCreate } from "@n8io/baseline-shutdown";
24
- import { telemetryShutdown } from "@n8io/baseline-telemetry";
25
-
26
+ // httpServerClose: @n8io/baseline-http; telemetryShutdown: @n8io/baseline-telemetry
26
27
  const shutdown = shutdownHandleCreate({
27
28
  drainDelayMs: envLocal ? 0 : 5_000,
28
29
  intakes: [
@@ -38,6 +39,24 @@ const shutdown = shutdownHandleCreate({
38
39
  });
39
40
  ```
40
41
 
41
- ## Needs
42
+ Test it with fake timers: spy on `process.on` to catch its listeners and on `process.exit` to read the code, then emit `SIGTERM` and run the timers. Test each step's `close` on its own.
43
+
44
+ ## Reference
45
+
46
+ <details><summary><b>Exports</b></summary>
47
+
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
+ | `ShutdownHandle` | `isShuttingDown()`, for `/readyz`. |
52
+ | `ShutdownStep` | `{ name, close }`: one intake (HTTP server, live streams, Consumers) or resource (queue, pools, clients, health, telemetry). |
53
+
54
+ The steps, counted from the signal:
55
+
56
+ 1. Waits `drainDelayMs` (default 5 s; pass 0 outside production) while readiness answers 503.
57
+ 2. Closes every intake (HTTP server, live streams, Consumers) at once. One still open at the cutoff (`deadlineMs` minus 5 s) is logged at warn, and shutdown moves on.
58
+ 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
+ 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
+ </details>
42
61
 
43
- Nothing beyond `@n8io/baseline-logger`, which it logs each failed step through. No env.
62
+ **Needs** nothing beyond `@n8io/baseline-logger`, which it logs each failed step through. No env.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@n8io/baseline-shutdown",
3
- "version": "3.0.1",
3
+ "version": "3.0.2",
4
4
  "description": "Graceful shutdown: drain, close intakes together, then resources in order.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -27,7 +27,7 @@
27
27
  "registry": "https://registry.npmjs.org"
28
28
  },
29
29
  "dependencies": {
30
- "@n8io/baseline-logger": "^3.0.0"
30
+ "@n8io/baseline-logger": "^3.1.1"
31
31
  },
32
32
  "scripts": {
33
33
  "build": "tsdown",