fulmine.js 5.19.2 → 5.19.4

package/src/websocket.js

@@ -18,10 +18,19 @@ limitations under the License.
 
 const { canBeOptimizedWithParams, decodeParam, NullObject } = require("./utils.js");
 
+/** @typedef {import("./router.js")} Router */
+/** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("./request.js")} Request */
+/** @typedef {import("./response.js")} Response */
+/** @typedef {import("./router-utils.js").WsRoute} WsRoute */
+/** @typedef {import("uWebSockets.js").HttpRequest} UwsRequest */
+/** @typedef {import("uWebSockets.js").HttpResponse} UwsResponse */
+/** @typedef {import("uWebSockets.js").us_socket_context_t} UwsContext */
+
 // the parameter names in a path, in the order µWS numbers them
 const PARAM = /:(\w+)/g;
 
-// Handlers µWS calls with the socket. Everything else in a behavior object is a µWS setting
+// Handlers uWS calls with the socket. Everything else in a behavior object is a uWS setting
 // (maxPayloadLength, idleTimeout, compression, ...) and rides through untouched.
 const SOCKET_HANDLERS = ["open", "message", "dropped", "drain", "close", "ping", "pong", "subscription"];
 
@@ -46,15 +55,14 @@ function joinPaths(prefix, path) {
 /**
  * Every websocket route reachable from this router, with the mount paths already applied.
  *
- * Walked separately from the HTTP routes: those fall back to ordinary routing when µWS cannot
- * match them, and a websocket has no fallback to fall back to, so an unmountable one has to be
- * refused out loud instead.
+ * Walked separately from the HTTP routes: those fall back to ordinary routing when uWS cannot
+ * match them, a websocket has no fallback, so an unmountable one is refused out loud.
  *
- * @param {any} router
+ * @param {Router} router
  * @param {string|null} prefix the mount path accumulated so far, or null once a mount was a
  *   shape µWS cannot match, which makes everything below it unreachable
- * @param {any[]} out
- * @param {Set<any>} seen routers already walked, since a router may be mounted twice
+ * @param {WsRoute[]} out
+ * @param {Set<Router>} seen routers already walked, since a router may be mounted twice
  */
 function collectRoutes(router, prefix, out, seen) {
     if (seen.has(router)) {
@@ -97,21 +105,23 @@ function collectRoutes(router, prefix, out, seen) {
 }
 
 /**
- * The µWS upgrade handler for one route: it builds this project's request and response, offers
- * them to the application's own `upgrade` hook, and completes the handshake unless that hook
- * answered the request itself.
+ * The uWS upgrade handler for one route: builds this project's request and response, offers them
+ * to the application's own `upgrade` hook, and completes the handshake unless that hook answered.
  *
- * @param {any} app the application whose request and response classes serve this route
+ * @param {Router} app the router whose request and response classes serve this route
  * @param {string} path the composed path, whose parameters are read back by index
- * @param {any} behavior what the caller registered
- * @returns {(res: any, req: any, context: any) => void}
+ * @param {Record<string, unknown>} behavior what the caller registered
+ * @returns {(res: UwsResponse, req: UwsRequest, context: UwsContext) => void}
  */
 function makeUpgradeHandler(app, path, behavior) {
     const paramNames = [...path.matchAll(PARAM)].map((match) => match[1]);
-    const userUpgrade = behavior.upgrade;
+    // a function, checked by checkBehavior where it was registered
+    const userUpgrade = /** @type {((req: Request, res: Response) => void|Promise<void>)|undefined} */ (
+        behavior.upgrade
+    );
 
     return (res, req, context) => {
-        // read off the µWS request before anything can await: it is neutered on return, and the
+        // read off the uWS request before anything can await: it is neutered on return, and the
         // handshake needs these three even when the upgrade is decided asynchronously
         const key = req.getHeader("sec-websocket-key");
         const protocol = req.getHeader("sec-websocket-protocol");
@@ -121,7 +131,7 @@ function makeUpgradeHandler(app, path, behavior) {
         if (paramNames.length) {
             const params = new NullObject();
             for (let i = 0; i < paramNames.length; i++) {
-                params[paramNames[i]] = decodeParam(req.getParameter(i));
+                params[paramNames[i]] = decodeParam(/** @type {string} */ (req.getParameter(i)));
             }
             request.params = params;
         }
@@ -169,17 +179,16 @@ function makeUpgradeHandler(app, path, behavior) {
             return;
         }
 
-        // an async hook (a session lookup, a token check) outlives this callback, so µWS has to
-        // be told who to call if the client leaves first. Registered now, still inside the
-        // handler, which is the only place µWS accepts it
+        // an async hook outlives this callback, so uWS has to be told who to call if the client
+        // leaves first. Registered now, inside the handler, the only place uWS accepts it
         res.onAborted(() => {
             aborted = true;
             // and on the response too, so a hook that is still awaiting can see the client left
             // rather than working on towards a handshake nobody is waiting for
             response.aborted = true;
         });
-        // and whatever the hook writes now lands outside the cork µWS holds for this callback,
-        // so the response opens its own, exactly as a route handler answering late does
+        // whatever the hook writes now lands outside the cork uWS holds for this callback, so the
+        // response opens its own, exactly as a route handler answering late does
         response._corkNeeded = true;
         decision.then(accept, (err) => {
             if (!aborted && !response.finished) {
@@ -193,11 +202,10 @@ function makeUpgradeHandler(app, path, behavior) {
 }
 
 /**
- * Hands every websocket route this application can reach to µWS. Called from listen(), before
- * the catch-all goes on: µWS routes an upgrade to the websocket route even when a catch-all
- * covers the same path, so the two live side by side.
+ * Hands every websocket route to uWS. Called from listen(), before the catch-all: uWS routes an
+ * upgrade to the websocket route even when a catch-all covers the same path.
  *
- * @param {any} app
+ * @param {Application} app
  */
 function registerWebSocketRoutes(app) {
     const routes = [];
@@ -217,7 +225,7 @@ function registerWebSocketRoutes(app) {
  * used: a handler under a misspelled name would otherwise never run and never say why.
  *
  * @param {string} path
- * @param {any} behavior
+ * @param {unknown} behavior whatever was passed as one, which is what is being checked
  */
 function checkBehavior(path, behavior) {
     if (typeof path !== "string") {

package/src/work.js

@@ -16,27 +16,21 @@ limitations under the License.
 
 // What one request actually made this framework do, read from state it already keeps.
 //
-// Most of what makes this faster than Express is work that does not happen: the Readable and the
-// Writable are not built, the headers are not folded into an object, the query is not parsed, the
-// socket stand-in is not allocated. None of that is visible from the outside, and all of it is one
-// careless middleware away from coming back: a `req.headers.host` where `req.get("host")` would do
-// puts the folded object back on every request, and the answer stays correct, so nothing fails.
+// Most of the speed here is work that does not happen: no Readable, no Writable, no folded headers
+// object, no parsed query, no socket stand-in. One careless middleware brings it back, and the
+// answer stays correct, so nothing fails. Every field below is already kept for other reasons, so
+// asking costs a load and nothing is counted or wrapped for the sake of being asked.
 //
-// Every field below is a property this framework already had to keep for its own reasons, so
-// asking costs a load and nothing is counted, stamped or wrapped for the sake of being asked. That
-// is the whole design rule here: a probe that charges the requests nobody is probing would be
-// paid for by everyone, forever, to be read once.
+// Not here: whether the constructor copied the headers out of uWS. That is about the chain and
+// `routeReport().skipHeaders` reports it already.
 //
-// What is deliberately not here is whether the constructor copied the headers out of µWS. That is
-// a decision about the chain rather than about the request, `routeReport().skipHeaders` reports it
-// already, and the one case where the two differ, a granted route whose request declares a body,
-// would cost a flag written on every request to be read on almost none.
-//
-// The two readers are `express.testing.expectLazy`, which fails a build that lost one of these,
-// and `express.serverTiming()`, which writes them into the header for a browser to show.
+// Read by `express.testing.expectLazy` and by `express.serverTiming()`.
 
 "use strict";
 
+/** @typedef {import("./request.js")} Request */
+/** @typedef {import("./response.js")} Response */
+
 /**
  * @typedef {object} Work
  * @property {boolean} native whether µWS matched this route itself
@@ -50,29 +44,30 @@ limitations under the License.
  */
 
 /**
- * What this request did, as it stands right now: the answer changes while the chain runs, so a
- * reader that wants the whole picture asks at the end of it.
+ * What this request did so far. The answer changes while the chain runs, so ask at the end of it.
  *
- * @param {any} req
- * @param {any} res the response, since half of this is about the response
+ * @param {Request} req
+ * @param {Response} res the response, since half of this is about the response
  * @returns {Work}
  */
 function work(req, res) {
     const native = req.route?._native;
+    // cast for the three the classes do not declare: `body` is deliberately not a field of
+    // Request, and the two stream states are node's own, written when a lazy stream is built
+    const loose = /** @type {{body?: unknown, _readableState?: unknown}} */ (req);
     return {
         native: Boolean(native),
         declarative: Boolean(native?.declarative),
         headers: req._headersBuilt,
         query: req._queryParsed,
-        body: req.body !== undefined,
-        requestStream: req._readableState !== undefined,
-        responseStream: res._writableState !== undefined,
+        body: loose.body !== undefined,
+        requestStream: loose._readableState !== undefined,
+        responseStream: /** @type {{_writableState?: unknown}} */ (res)._writableState !== undefined,
         socket: req._socketBuilt || res._socketBuilt
     };
 }
 
-// The order the two readers list them in: what the request was made to do, cheapest first, so a
-// header and a failure message read the same way.
+// The order both readers list them in, cheapest first, so a header and a failure message agree.
 const NAMES = [
     ["headers", "headers"],
     ["query", "query"],
@@ -83,8 +78,7 @@ const NAMES = [
 ];
 
 /**
- * The names of everything that did happen, for a message or a header. Empty for the request that
- * did none of it, which is the one this framework is built to serve.
+ * The names of everything that did happen, for a message or a header. Empty is the good case.
  *
  * @param {Work} done
  * @returns {string[]}
@@ -92,7 +86,7 @@ const NAMES = [
 function names(done) {
     const listed = [];
     for (const [key, name] of NAMES) {
-        if (/** @type {any} */ (done)[key]) {
+        if (done[key]) {
             listed.push(name);
         }
     }