@dokebi/web 0.4.7 → 0.4.9

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/AI.md CHANGED
@@ -44,6 +44,7 @@ dokebi-web:
44
44
  |---|---|---|---|
45
45
  | `host` | string | `127.0.0.1` | listen address |
46
46
  | `port` | integer | 0 | 0..65535; 0 picks an ephemeral port |
47
+ | `listen` | boolean | true | (0.4.8, [D-0221](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0221-process-roles.md)) `false`: open no port — a worker process started from the same code with its own dokebi.yaml (`DOKEBI_CONFIG`). Routes are still registered (`inject` answers), nothing listens, `address` stays undefined and `/health/live` and `/health/ready` are not reachable; info `Web server not listening` (`WEB_NOT_LISTENING`) once. In place of the socket the plugin holds the process open until the app drains (0.4.9: before it, a worker with no other open connection exited right after it started). `dokebi verify` skips its HTTP check for such a settings file (@dokebi/cli 0.4.45). To probe a worker over HTTP, give it a port nothing routes traffic to instead |
47
48
  | `maxBodyBytes` | integer | 1048576 | request body limit, 1 B..64 MiB |
48
49
  | `bodyLimit` | integer | — | deprecated name of `maxBodyBytes` (D-0071): warns `OPTION_DEPRECATED`; setting both is `INVALID_OPTIONS` |
49
50
  | `maxRouteBodyBytes` | integer 1..1073741824 | 67108864 | the largest `bodyLimit` one route may declare for itself (64 MiB; at least `maxBodyBytes`); a larger one fails the start with `INVALID_ROUTE` ([D-0122](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0122-studio-terminal-needs.md), below) |
package/dist/index.js CHANGED
@@ -39,6 +39,8 @@ export { errorFormat, FORM_SUBMISSION_HEADER, requestErrorFormat, SEALED_FETCH_H
39
39
  export { SEALED_LOCATION_HEADER, SEALED_PATH_HEADER, } from './seal.js';
40
40
  export { DEFAULT_DIRECTIVES, } from './security-headers.js';
41
41
  /** Set by `dokebi verify` on the app it starts (D-0065 §11); the header echoes it. */
42
+ /** The longest timer delay Node takes (about 24.8 days); the keep-alive never fires in practice. */
43
+ const KEEP_ALIVE_MS = 2 ** 31 - 1;
42
44
  const VERIFY_TOKEN_ENV = 'DOKEBI_VERIFY_TOKEN';
43
45
  const VERIFY_HEADER = 'x-dokebi-verify';
44
46
  /**
@@ -390,6 +392,14 @@ class WebOwner {
390
392
  /** A draining worker's idle wait ended and it closed the connections still idle (D-0036). */
391
393
  #idleClosed = false;
392
394
  #address;
395
+ /** `listen: false` was logged once (D-0221). */
396
+ #notListening = false;
397
+ /**
398
+ * D-0221: with `listen: false` this holds the process open in place of the listening socket,
399
+ * until the drain or close: a worker process with no other open handle would otherwise exit
400
+ * right after it started.
401
+ */
402
+ #keepAlive;
393
403
  #sealing;
394
404
  /** D-0149: the security headers of every answer. */
395
405
  #security;
@@ -525,6 +535,7 @@ class WebOwner {
525
535
  logger.log('debug', 'Web server configured', {
526
536
  host: options.host,
527
537
  port: options.port,
538
+ listen: options.listen,
528
539
  bodyLimit: options.maxBodyBytes,
529
540
  maxRouteBodyBytes: options.maxRouteBodyBytes,
530
541
  binaryBody: options.binaryBody,
@@ -1574,10 +1585,25 @@ class WebOwner {
1574
1585
  longestBodyMs: this.#longestBodyMs,
1575
1586
  });
1576
1587
  }
1577
- /** Listens unless this process does not serve (`runtime.serving` false, D-0063 §4). */
1588
+ /**
1589
+ * Listens unless this process does not serve (`runtime.serving` false, D-0063 §4) or its
1590
+ * dokebi.yaml says so (`listen: false`, a worker process of the same code, D-0221).
1591
+ */
1578
1592
  async listen() {
1579
1593
  if (this.#address !== undefined)
1580
1594
  return;
1595
+ if (!this.options.listen) {
1596
+ if (!this.#notListening) {
1597
+ this.#notListening = true;
1598
+ if (!this.#draining && !this.#closed)
1599
+ this.#keepAlive = setInterval(() => undefined, KEEP_ALIVE_MS);
1600
+ this.context.logger.log('info', 'Web server not listening', {
1601
+ code: 'WEB_NOT_LISTENING',
1602
+ reason: 'listen: false',
1603
+ });
1604
+ }
1605
+ return;
1606
+ }
1581
1607
  const runtime = this.context.runtime ?? this.context.app.runtime;
1582
1608
  if (!runtime.serving) {
1583
1609
  this.context.logger.log('debug', 'Web server not listening', {
@@ -1605,6 +1631,7 @@ class WebOwner {
1605
1631
  }
1606
1632
  async drain(signal, deadline) {
1607
1633
  this.#draining = true;
1634
+ this.#releaseProcess();
1608
1635
  this.#frozen = true;
1609
1636
  const started = performance.now();
1610
1637
  const logger = this.context.logger;
@@ -2398,8 +2425,16 @@ class WebOwner {
2398
2425
  json: () => JSON.parse(response.body),
2399
2426
  });
2400
2427
  }
2428
+ /** Lets the process end once nothing else holds it (`listen: false`, D-0221). */
2429
+ #releaseProcess() {
2430
+ if (this.#keepAlive === undefined)
2431
+ return;
2432
+ clearInterval(this.#keepAlive);
2433
+ this.#keepAlive = undefined;
2434
+ }
2401
2435
  async close() {
2402
2436
  this.#closed = true;
2437
+ this.#releaseProcess();
2403
2438
  const started = performance.now();
2404
2439
  const { ended } = this.#connections.close();
2405
2440
  try {
@@ -2558,6 +2593,7 @@ class WebRuntime {
2558
2593
  describe: () => ({
2559
2594
  host: options.host,
2560
2595
  port: options.port,
2596
+ listen: options.listen,
2561
2597
  healthRoutes: options.healthRoutes ? { ...options.healthRoutes } : false,
2562
2598
  formBody: options.formBody,
2563
2599
  maxBodyBytes: options.maxBodyBytes,
@@ -2594,7 +2630,7 @@ class WebRuntime {
2594
2630
  }
2595
2631
  export const createPlugin = definePlugin({
2596
2632
  name: 'dokebi-web',
2597
- version: '0.4.7',
2633
+ version: '0.4.9',
2598
2634
  core: '^0.4.2',
2599
2635
  options: declaration,
2600
2636
  entry: (input) => new WebEntryInput(input),
package/dist/options.d.ts CHANGED
@@ -26,6 +26,7 @@ export declare const options: import("@dokebi/core").OptionsDeclaration<{
26
26
  readonly maxBytes: number;
27
27
  readonly ms: number;
28
28
  };
29
+ readonly listen: boolean;
29
30
  readonly logRepeatWindowMs: number;
30
31
  readonly maxBodyBytes: number;
31
32
  readonly maxRouteBodyBytes: number;
package/dist/options.js CHANGED
@@ -22,6 +22,10 @@ export const options = defineOptions({
22
22
  default: 0,
23
23
  description: 'Port to listen on; 0 picks a free one.',
24
24
  }),
25
+ listen: o.boolean({
26
+ default: true,
27
+ description: 'Open the port. false: a process that serves no HTTP (a worker process started from the same code with another dokebi.yaml): routes are still registered, nothing listens, and /health/live and /health/ready are not served (D-0221).',
28
+ }),
25
29
  maxBodyBytes: o.integer({
26
30
  minimum: 1,
27
31
  maximum: 67108864,
@@ -17,6 +17,11 @@
17
17
  "default": 0,
18
18
  "description": "Port to listen on; 0 picks a free one."
19
19
  },
20
+ "listen": {
21
+ "type": "boolean",
22
+ "default": true,
23
+ "description": "Open the port. false: a process that serves no HTTP (a worker process started from the same code with another dokebi.yaml): routes are still registered, nothing listens, and /health/live and /health/ready are not served (D-0221)."
24
+ },
20
25
  "maxBodyBytes": {
21
26
  "type": "integer",
22
27
  "minimum": 1,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dokebi/web",
3
- "version": "0.4.7",
3
+ "version": "0.4.9",
4
4
  "description": "Fastify 5 HTTP server owned by a Dokebi app: 503 before ready, health routes, drain and cluster handover.",
5
5
  "keywords": [
6
6
  "dokebi",