@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 CHANGED
@@ -23,15 +23,16 @@ pnpm add @n8io/baseline-shutdown
23
23
  ## Example
24
24
 
25
25
  ```ts
26
- // httpServerClose: @n8io/baseline-http; telemetryShutdown: @n8io/baseline-telemetry
26
+ import { shutdownHandleCreate } from "@n8io/baseline-shutdown";
27
+
27
28
  const shutdown = shutdownHandleCreate({
28
- drainDelayMs: envLocal ? 0 : 5_000,
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.stop(), name: "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
- 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
+ `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
- | `ShutdownHandle` | `isShuttingDown()`, for `/readyz`. |
52
- | `ShutdownStep` | `{ name, close }`: one intake (HTTP server, live streams, Consumers) or resource (queue, pools, clients, health, telemetry). |
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; 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
+ 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** nothing beyond `@n8io/baseline-logger`, which it logs each failed step through. No env.
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
- export type ShutdownStep = {
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
- deadlineMs?: number;
7
- drainDelayMs?: number;
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
- export type ShutdownHandle = {
27
+ /** The running shutdown handle. `isShuttingDown()` turns true at the signal, for `/readyz`. */
28
+ type ShutdownHandle = {
12
29
  isShuttingDown(): boolean;
13
30
  };
14
- export declare const shutdownHandleCreate: ({ deadlineMs, drainDelayMs, intakes, resources }: ShutdownOptions) => ShutdownHandle;
15
- export {};
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/index.ts
3
- const RESOURCE_RESERVE_MS = 5e3;
4
- const TIMED_OUT = Symbol("timedOut");
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(TIMED_OUT), Math.max(0, ms));
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 shutdownHandleCreate = ({ deadlineMs = 25e3, drainDelayMs = 5e3, intakes, resources }) => {
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 - RESOURCE_RESERVE_MS);
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 === TIMED_OUT) {
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 === TIMED_OUT) {
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.2",
4
- "description": "Graceful shutdown: drain, close intakes together, then resources in order.",
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.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
  }