@koeroesi86/node-worker-express 26.10.36903641712-master → 26.10.37633705232-master

package/README.md

@@ -21,3 +21,47 @@ pnpm --filter @koeroesi86/node-worker-express start
 ```
 
 For all options see [types](https://github.com/Koeroesi86/node-webserver/blob/master/packages/node-worker-express/src/types/index.ts).
+
+## Streaming a response
+
+A worker answers a request by calling `callback` once. To send a body that is generated while it goes out, or is too big to hold in memory, use `streamResponse`:
+
+```javascript
+const { streamResponse } = require('@koeroesi86/node-worker-express');
+
+module.exports = async (event, callback) => {
+  async function* lines() {
+    for (let index = 0; index < 1000; index += 1) yield `line ${index}\n`;
+  }
+
+  await streamResponse(callback, { headers: { 'Content-Type': 'text/plain' } }, lines());
+};
+```
+
+The body can be a `Readable` or any async iterable of `Buffer`, `Uint8Array` or `string`. Parts are sent a few at a time and the next ones only
+once the client took the earlier ones, so a slow client slows the source down instead of filling the memory. When the client goes away the source is
+stopped (an async generator runs its `finally`, a `Readable` is destroyed) and `streamResponse` resolves with `false`. The response is sent chunked unless
+you set a `Content-Length`. Static files above 1 MiB are streamed the same way.
+
+Producing very small chunks is wasteful, as every part takes a message to the main process: collect them into parts of some KiB.
+
+## Reading the body of a request
+
+The body is not part of the event a worker is called with: the worker is called at once, and reads the body from `event.bodyStream`, a `Readable` (empty for requests without a body):
+
+```javascript
+module.exports = async (event, callback) => {
+  let size = 0;
+  for await (const chunk of event.bodyStream) size += chunk.length;
+  callback({ statusCode: 200, headers: {}, body: String(size), isBase64Encoded: false });
+};
+```
+
+Only a few parts are on their way to the worker before it has read the earlier ones, so uploads of any size take a flat amount of memory. A worker that needs all of it uses `stream/consumers`:
+`const body = await text(event.bodyStream)` (also `json` and `buffer`). **`event.body` does not exist any more.** Read the body before you answer, as the rest of it is dropped once the response is complete.
+A client that goes away during the upload destroys the stream with an error. `limitRequestBody` (bytes, 0 for none, the default) answers a bigger body with 413. Websockets and static files never have a body.
+
+## Metrics
+
+`await event.getMetrics()` in a worker gives a snapshot of the server (uptime, memory, event loop delay, request counts, worker pools) for health and metrics endpoints, see the README of `@koeroesi86/node-webserver`.
+In the server process `getServerMetrics()` gives the same, and `registerMetricsSource(name, read)` adds a source to it.

package/dist/constants/index.d.ts

@@ -1,7 +1,17 @@
 import { MiddlewareOptions } from '../types';
 export declare enum WORKER_EVENT {
     REQUEST = "WORKER_REQUEST",
+    /** not sent any more, nothing listened to it */
     REQUEST_ACKNOWLEDGE = "WORKER_REQUEST_ACK",
+    /** the client went away before the response was complete, a worker streaming it should stop */
+    REQUEST_ABORT = "WORKER_REQUEST_ABORT",
+    /** a part of a request body that is streamed to the worker, the last one has no body */
+    REQUEST_BODY = "WORKER_REQUEST_BODY",
+    /** the worker took a part of the streamed request body, the server may send another one */
+    REQUEST_BODY_ACKNOWLEDGE = "WORKER_REQUEST_BODY_ACK",
+    /** a worker asks for the metrics of the server */
+    METRICS_REQUEST = "WORKER_METRICS_REQUEST",
+    METRICS = "WORKER_METRICS",
     RESPONSE = "WORKER_RESPONSE",
     RESPONSE_EMIT = "WORKER_RESPONSE_EMIT",
     RESPONSE_ACKNOWLEDGE = "WORKER_RESPONSE_ACK",
@@ -10,6 +20,20 @@ export declare enum WORKER_EVENT {
     WS_CONNECTION_CLOSE = "WS_CONNECTION_CLOSE",
     WS_CONNECTION_CLOSE_ACKNOWLEDGE = "WS_CONNECTION_CLOSE_ACK"
 }
+/** the static worker sends files up to this size in one part, bigger ones are streamed so they do not have to fit into the memory */
+export declare const StaticStreamThreshold: number;
+/** how many parts of a streamed request body may be on their way to the worker before it takes one */
+export declare const RequestBodyWindow = 4;
+/** a worker that stops sooner than this after it started, or with an error, has crashed, in milliseconds */
+export declare const WorkerMinUptime = 5000;
+/**
+ * Starting a worker for a path that crashed twice in a row is refused for this long, doubling with every crash until the maximum,
+ * so that a worker that fails at start does not cost a process for every request. In milliseconds.
+ */
+export declare const WorkerRestartBackoff: {
+    base: number;
+    max: number;
+};
 export declare const ForbiddenPaths: readonly string[];
 export declare enum Protocols {
     http = "HTTP",

package/dist/index-9a1547f9.js

@@ -0,0 +1,76 @@
+'use strict';
+
+var os = require('os');
+var path = require('path');
+
+exports.WORKER_EVENT = void 0;
+(function (WORKER_EVENT) {
+    WORKER_EVENT["REQUEST"] = "WORKER_REQUEST";
+    /** not sent any more, nothing listened to it */
+    WORKER_EVENT["REQUEST_ACKNOWLEDGE"] = "WORKER_REQUEST_ACK";
+    /** the client went away before the response was complete, a worker streaming it should stop */
+    WORKER_EVENT["REQUEST_ABORT"] = "WORKER_REQUEST_ABORT";
+    /** a part of a request body that is streamed to the worker, the last one has no body */
+    WORKER_EVENT["REQUEST_BODY"] = "WORKER_REQUEST_BODY";
+    /** the worker took a part of the streamed request body, the server may send another one */
+    WORKER_EVENT["REQUEST_BODY_ACKNOWLEDGE"] = "WORKER_REQUEST_BODY_ACK";
+    /** a worker asks for the metrics of the server */
+    WORKER_EVENT["METRICS_REQUEST"] = "WORKER_METRICS_REQUEST";
+    WORKER_EVENT["METRICS"] = "WORKER_METRICS";
+    WORKER_EVENT["RESPONSE"] = "WORKER_RESPONSE";
+    WORKER_EVENT["RESPONSE_EMIT"] = "WORKER_RESPONSE_EMIT";
+    WORKER_EVENT["RESPONSE_ACKNOWLEDGE"] = "WORKER_RESPONSE_ACK";
+    WORKER_EVENT["WS_MESSAGE_RECEIVE"] = "WS_MESSAGE_RECEIVE";
+    WORKER_EVENT["WS_MESSAGE_SEND"] = "WS_MESSAGE_SEND";
+    WORKER_EVENT["WS_CONNECTION_CLOSE"] = "WS_CONNECTION_CLOSE";
+    WORKER_EVENT["WS_CONNECTION_CLOSE_ACKNOWLEDGE"] = "WS_CONNECTION_CLOSE_ACK";
+})(exports.WORKER_EVENT || (exports.WORKER_EVENT = {}));
+/** the static worker sends files up to this size in one part, bigger ones are streamed so they do not have to fit into the memory */
+const StaticStreamThreshold = 1024 * 1024;
+/** how many parts of a streamed request body may be on their way to the worker before it takes one */
+const RequestBodyWindow = 4;
+/** a worker that stops sooner than this after it started, or with an error, has crashed, in milliseconds */
+const WorkerMinUptime = 5000;
+/**
+ * Starting a worker for a path that crashed twice in a row is refused for this long, doubling with every crash until the maximum,
+ * so that a worker that fails at start does not cost a process for every request. In milliseconds.
+ */
+const WorkerRestartBackoff = { base: 100, max: 10000 };
+const ForbiddenPaths = ['..'];
+exports.Protocols = void 0;
+(function (Protocols) {
+    Protocols["http"] = "HTTP";
+    Protocols["websocket"] = "WS";
+})(exports.Protocols || (exports.Protocols = {}));
+const DefaultOptions = {
+    root: '',
+    limit: 0,
+    limitPerPath: os.availableParallelism(),
+    warmStaticWorker: true,
+    limitRequestBody: 0,
+    inlineRequestBody: 64 * 1024,
+    limitRequestTimeout: 5000,
+    limitResponseTimeout: 30000,
+    limitQueue: 1000,
+    onStdout: () => { },
+    onStderr: () => { },
+    onExit: () => { },
+    onForbiddenPath: (request, response) => {
+        response.writeHead(500, { 'Content-Type': 'text/plain' });
+        response.end();
+        request.connection.destroy();
+        throw new Error('Forbidden path');
+    },
+    index: [],
+    env: {},
+    staticWorker: path.resolve(__dirname, './staticWorker.js'),
+    cwd: process.cwd(),
+};
+
+exports.DefaultOptions = DefaultOptions;
+exports.ForbiddenPaths = ForbiddenPaths;
+exports.RequestBodyWindow = RequestBodyWindow;
+exports.StaticStreamThreshold = StaticStreamThreshold;
+exports.WorkerMinUptime = WorkerMinUptime;
+exports.WorkerRestartBackoff = WorkerRestartBackoff;
+//# sourceMappingURL=index-9a1547f9.js.map

package/dist/index-9a1547f9.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-9a1547f9.js","sources":["../src/constants/index.ts"],"sourcesContent":[null],"names":["WORKER_EVENT","Protocols"],"mappings":";;;;;AAIYA,8BAoBX;AApBD,CAAA,UAAY,YAAY,EAAA;AACtB,IAAA,YAAA,CAAA,SAAA,CAAA,GAAA,gBAA0B,CAAA;;AAE1B,IAAA,YAAA,CAAA,qBAAA,CAAA,GAAA,oBAA0C,CAAA;;AAE1C,IAAA,YAAA,CAAA,eAAA,CAAA,GAAA,sBAAsC,CAAA;;AAEtC,IAAA,YAAA,CAAA,cAAA,CAAA,GAAA,qBAAoC,CAAA;;AAEpC,IAAA,YAAA,CAAA,0BAAA,CAAA,GAAA,yBAAoD,CAAA;;AAEpD,IAAA,YAAA,CAAA,iBAAA,CAAA,GAAA,wBAA0C,CAAA;AAC1C,IAAA,YAAA,CAAA,SAAA,CAAA,GAAA,gBAA0B,CAAA;AAC1B,IAAA,YAAA,CAAA,UAAA,CAAA,GAAA,iBAA4B,CAAA;AAC5B,IAAA,YAAA,CAAA,eAAA,CAAA,GAAA,sBAAsC,CAAA;AACtC,IAAA,YAAA,CAAA,sBAAA,CAAA,GAAA,qBAA4C,CAAA;AAC5C,IAAA,YAAA,CAAA,oBAAA,CAAA,GAAA,oBAAyC,CAAA;AACzC,IAAA,YAAA,CAAA,iBAAA,CAAA,GAAA,iBAAmC,CAAA;AACnC,IAAA,YAAA,CAAA,qBAAA,CAAA,GAAA,qBAA2C,CAAA;AAC3C,IAAA,YAAA,CAAA,iCAAA,CAAA,GAAA,yBAA2D,CAAA;AAC7D,CAAC,EApBWA,oBAAY,KAAZA,oBAAY,GAoBvB,EAAA,CAAA,CAAA,CAAA;AAED;AACa,MAAA,qBAAqB,GAAG,IAAI,GAAG,KAAK;AAEjD;AACO,MAAM,iBAAiB,GAAG,EAAE;AAEnC;AACO,MAAM,eAAe,GAAG,KAAK;AAEpC;;;AAGG;AACI,MAAM,oBAAoB,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,GAAG;AAEjD,MAAA,cAAc,GAAsB,CAAC,IAAI,EAAW;AAErDC,2BAGX;AAHD,CAAA,UAAY,SAAS,EAAA;AACnB,IAAA,SAAA,CAAA,MAAA,CAAA,GAAA,MAAa,CAAA;AACb,IAAA,SAAA,CAAA,WAAA,CAAA,GAAA,IAAgB,CAAA;AAClB,CAAC,EAHWA,iBAAS,KAATA,iBAAS,GAGpB,EAAA,CAAA,CAAA,CAAA;AAEY,MAAA,cAAc,GAAsB;AAC/C,IAAA,IAAI,EAAE,EAAE;AACR,IAAA,KAAK,EAAE,CAAC;AACR,IAAA,YAAY,EAAE,EAAE,CAAC,oBAAoB,EAAE;AACvC,IAAA,gBAAgB,EAAE,IAAI;AACtB,IAAA,gBAAgB,EAAE,CAAC;IACnB,iBAAiB,EAAE,EAAE,GAAG,IAAI;AAC5B,IAAA,mBAAmB,EAAE,IAAI;AACzB,IAAA,oBAAoB,EAAE,KAAK;AAC3B,IAAA,UAAU,EAAE,IAAI;AAChB,IAAA,QAAQ,EAAE,MAAK,GAAG;AAClB,IAAA,QAAQ,EAAE,MAAK,GAAG;AAClB,IAAA,MAAM,EAAE,MAAK,GAAG;AAChB,IAAA,eAAe,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAI;QACrC,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAC;QAC1D,QAAQ,CAAC,GAAG,EAAE,CAAC;AACf,QAAA,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;AAC7B,QAAA,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;KACnC;AACD,IAAA,KAAK,EAAE,EAAE;AACT,IAAA,GAAG,EAAE,EAAE;IACP,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,mBAAmB,CAAC;AAC1D,IAAA,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;;;;;;;;;;"}

package/dist/index.d.ts

@@ -1,2 +1,6 @@
 export { default as middleware } from './middleware';
 export * from './types';
+export { default as streamResponse } from './streamResponse';
+export type { StreamBody, StreamResponseOptions } from './streamResponse';
+export { getServerMetrics, registerMetricsSource } from './utils/metrics';
+export type { ServerMetrics } from './utils/metrics';