fulmine.js 5.19.2 → 5.19.3

package/src/nest.js

@@ -14,8 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// require("fulmine.js/nest"): the Nest HTTP adapter, so a Nest application runs on µWS without
-// anyone having to write this file themselves.
+// require("fulmine.js/nest"): the Nest HTTP adapter, so a Nest application runs on uWS.
 //
 //     import { NestFactory } from "@nestjs/core";
 //     import { FulmineExpressAdapter } from "fulmine.js/nest";
@@ -23,24 +22,17 @@ limitations under the License.
 //     const app = await NestFactory.create(AppModule, new FulmineExpressAdapter());
 //     await app.listen(3000);
 //
-// @nestjs/platform-express takes any Express instance, and this is one, so everything above the
-// adapter - controllers, pipes, guards, interceptors - is untouched. Three things below it are not,
-// and they are the whole reason this file exists:
+// @nestjs/platform-express takes any Express instance and this is one, so controllers, pipes,
+// guards and interceptors are untouched. Only three methods below the adapter need overriding:
 //
-//   - initHttpServer wraps the instance in http.createServer() and listens on that. Every request
-//     would then arrive through node's parser and be replayed into µWS's shapes by node-shim.js,
-//     which is the slow path that exists for supertest. The app already answers as an http.Server,
-//     so it is the server instead of being put inside one.
-//   - registerParserMiddleware decides whether Nest's body parsers are already in the chain by
-//     scanning app.router.stack for them. There is no layer array here to scan, routes are compiled
-//     rather than kept as layers, so the answer was always "no" and a second call added a second
-//     pair. It is remembered here instead, which is the same answer by a different route.
-//   - httpsOptions asks node to make a TLS server out of the instance. TLS here belongs to µWS and
-//     is configured when the app is built, so that combination is refused with the line to write
-//     rather than silently starting a plaintext server.
+//   - initHttpServer wraps the instance in http.createServer(). That would push every request
+//     through node's parser and node-shim.js, the slow path. The app is already an http.Server.
+//   - registerParserMiddleware looks for Nest's body parsers in app.router.stack. There is no
+//     layer array here, so the answer was always "no" and a second call added a second pair.
+//   - httpsOptions asks node for a TLS server. TLS belongs to uWS and is set when the app is
+//     built, so that combination is refused.
 //
-// @nestjs/platform-express is an optional peer dependency: this file is the only one that requires
-// it, and nothing loads this file unless you ask for it by name.
+// @nestjs/platform-express is an optional peer dependency, only this file requires it.
 
 "use strict";
 
@@ -48,10 +40,10 @@ const { ExpressAdapter } = require("@nestjs/platform-express");
 const fulmine = require("./index.js");
 
 /**
- * Nest's Express adapter, listening on µWebSockets.js instead of on node.
+ * Nest's Express adapter, listening on uWebSockets.js instead of node.
  *
- * Pass a configured app when you need one, `new FulmineExpressAdapter(fulmine({ uwsOptions }))`;
- * with no argument it builds a default one, the same as `new ExpressAdapter()` does.
+ * Pass a configured app when you need one, `new FulmineExpressAdapter(fulmine({ uwsOptions }))`.
+ * With no argument it builds a default one, like `new ExpressAdapter()`.
  */
 class FulmineExpressAdapter extends ExpressAdapter {
     /**
@@ -60,8 +52,7 @@ class FulmineExpressAdapter extends ExpressAdapter {
     constructor(instance) {
         super(instance || fulmine());
         /**
-         * Whether Nest's body parsers are in the chain, standing in for the layer array Express
-         * has and this does not. See registerParserMiddleware below.
+         * Stands in for the layer array Express has. See registerParserMiddleware below.
          * @type {boolean}
          */
         this._parsersRegistered = false;
@@ -84,10 +75,7 @@ class FulmineExpressAdapter extends ExpressAdapter {
         this.httpServer = this.getInstance();
         if (options?.forceCloseConnections) {
             // trackOpenConnections() listens for 'connection', which nothing emits: the sockets
-            // belong to µWS and never become node ones. Said out loud, because a shutdown that
-            // quietly waits forever for what it thinks it can destroy is worse than one that does
-            // not offer to. Through Nest's own logger, so the line arrives where every other line
-            // from the framework does; it is private in the typings and inherited all the same
+            // belong to uWS. Warned through Nest's own logger, private in the typings but there
             /** @type {any} */ (this).logger.warn(
                 "forceCloseConnections has no effect on fulmine.js: the sockets belong to µWS. " +
                     "app.close() stops accepting and waits for the requests in flight; an idle keep-alive " +
@@ -97,11 +85,9 @@ class FulmineExpressAdapter extends ExpressAdapter {
     }
 
     /**
-     * Nest's json and urlencoded parsers, added once however often this is called.
-     *
-     * Express answers "are they there already" by scanning `app.router.stack` for a layer whose
-     * handler is named `jsonParser` or `urlencodedParser`. There is no such array here, so the scan
-     * answered no every time and a second call put a second pair in front of every request.
+     * Nest's json and urlencoded parsers, added once however often this is called. Express looks
+     * for them in `app.router.stack`; there is no such array here, so a second call was putting a
+     * second pair in front of every request.
      *
      * @param {string} [prefix]
      * @param {boolean} [rawBody]
@@ -114,6 +100,5 @@ class FulmineExpressAdapter extends ExpressAdapter {
     }
 }
 
-// a named export and nothing else: `import { FulmineExpressAdapter } from "fulmine.js/nest"`, which
-// is how @nestjs/platform-express exports ExpressAdapter too
+// a named export, the way @nestjs/platform-express exports ExpressAdapter
 module.exports = { FulmineExpressAdapter };

package/src/node-shim.js

@@ -15,12 +15,12 @@ limitations under the License.
 */
 
 // A uWS-shaped request and response backed by node's own, so an app can serve what arrived through
-// http.createServer. Nothing on this path is fast, and it is not meant to be: it is what lets
-// supertest and http.createServer(app) work, which is what an app has to be a function for.
+// http.createServer. Nothing here is fast and it does not need to be: it is what makes supertest
+// and http.createServer(app) work.
 //
-// Request and Response ask uWS for eighteen things and this answers all eighteen. Where the two
-// models disagree node's gives way: cork only runs its callback, and a status is remembered rather
-// than sent, since node writes the head with the first byte of body.
+// Request and Response ask uWS for eighteen things and this answers all eighteen. Where the models
+// disagree node's gives way: cork only runs its callback, and a status is remembered rather than
+// sent, since node writes the head with the first byte of body.
 
 const { IncomingMessage } = require("http");
 
@@ -92,9 +92,8 @@ function toArrayBuffer(chunk) {
 /**
  * What uWS calls an HttpRequest, over node's IncomingMessage.
  *
- * Only valid for as long as the response is, which here is longer than uWS allows: node keeps the
- * headers alive, so nothing has to be copied out in a hurry. Request copies them anyway, since it
- * cannot tell which kind of request it is holding.
+ * Valid as long as the response is, which is longer than uWS allows: node keeps the headers alive.
+ * Request copies them anyway, since it cannot tell which kind of request it is holding.
  */
 class NodeHttpRequest {
     /** @param {import("http").IncomingMessage} req */
@@ -162,9 +161,8 @@ class NodeHttpRequest {
 /**
  * What uWS calls an HttpResponse, over node's ServerResponse.
  *
- * The status and the headers are held until node writes the head on its own, which it does when the
- * first byte of body goes out. That is why writeStatus only remembers: sending it here would send
- * the headers too, before the ones still to come had been set.
+ * The status and the headers are held until node writes the head, which it does with the first byte
+ * of body. So writeStatus only remembers: sending it here would send the headers too early.
  */
 class NodeHttpResponse {
     /**
@@ -391,7 +389,7 @@ class NodeHttpResponse {
 
 /**
  * Whether these are node's own request and response rather than this project's.
- * @param {any} req
+ * @param {any} req anything a caller handed the router, which is the point of the check
  */
 function isNodeRequest(req) {
     return req instanceof IncomingMessage;
@@ -400,7 +398,7 @@ function isNodeRequest(req) {
 /**
  * Serves a request that arrived through node's HTTP server with the given router or app.
  *
- * @param {any} router
+ * @param {any} router the router or application serving this request
  * @param {import("http").IncomingMessage} nodeReq
  * @param {import("http").ServerResponse} nodeRes
  * @param {(err?: any) => void} [next] called when nothing in the router answered