fulmine.js 5.19.2 → 5.19.4

package/src/testing.js

@@ -16,28 +16,31 @@ limitations under the License.
 
 // express.testing: what listen() decided about each route, as something a test can assert on.
 //
-// A route is answered by µWS itself only while it stays eligible, and eligibility is not a property
-// of the route alone: a `const` in the wrong place, a middleware that reads a header, a new route
-// written above an old one, and it quietly falls back to the ordinary router. The answer is still
-// correct, which is why nothing complains. What changes is the throughput, and by the time anyone
-// notices, the commit that did it is three weeks back.
+// A route is answered by uWS itself only while it stays eligible: a `const` in the wrong place, a
+// middleware that reads a header, a new route above an old one, and it falls back to the ordinary
+// router. The answer stays correct, so nothing complains, only the throughput changes.
 //
-// `npx fulmine profile` prints the same verdicts for a human to read. This is the half a test can
-// hold on to, so a pull request that loses the fast path fails in CI with the reason written out
-// instead of being found in production.
+// `npx fulmine profile` prints the same verdicts for a human. This is the half a test can hold on
+// to, so a pull request that loses the fast path fails in CI.
 
 "use strict";
 
 const { work, names: workNames } = require("./work.js");
 
+/** @typedef {import("./request.js")} Request */
+/** @typedef {import("./response.js")} Response */
+/** @typedef {import("./router.js")} Router */
+/** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
+
 /**
  * Every route of an application and of the routers mounted under it, each with the path it answers
  * from the outside.
  *
- * @param {any} router
+ * @param {Router} router
  * @param {string} prefix
- * @param {any[]} [into]
- * @returns {{route: any, full: string}[]}
+ * @param {{route: RouteEntry, full: string}[]} [into]
+ * @returns {{route: RouteEntry, full: string}[]}
  */
 function collectRoutes(router, prefix, into = []) {
     for (const route of router._routes ?? []) {
@@ -55,7 +58,7 @@ function collectRoutes(router, prefix, into = []) {
  * Compiles the routes, which is what listen() does before it binds, without binding anything. Once
  * per application: a second compilation would register everything with µWS twice.
  *
- * @param {any} app
+ * @param {Application} app
  */
 function compileOnce(app) {
     if (app.listenCalled || app._testingCompiled) {
@@ -68,11 +71,10 @@ function compileOnce(app) {
 /**
  * What compiling the routes decided, one entry per route, in the order they were registered.
  *
- * This is the primitive the two assertions below are written on, and it is exported because an
- * application with rules of its own is better served asserting them itself: how many routes may
- * fall back, which ones may read headers, that the one route carrying the traffic is declarative.
+ * The primitive the two assertions below are written on. Exported so an application with rules of
+ * its own can assert them directly.
  *
- * @param {any} app an application, listening or not
+ * @param {Application} app an application, listening or not
  * @returns {{method: string, path: string, native: boolean, declarative: boolean, skipHeaders: boolean,
  *   skipQuery: boolean, reason: string|undefined}[]}
  */
@@ -94,8 +96,8 @@ function routeReport(app) {
 /**
  * Whether one of the patterns given names this route.
  *
- * A pattern is a path as it was registered, not a URL: "/api/items/:id" and not "/api/items/7". It
- * may carry the method, "GET /health", and it may end in "*" to name everything under a prefix.
+ * A pattern is a path as registered, not a URL: "/api/items/:id", not "/api/items/7". It may carry
+ * the method, "GET /health", and may end in "*" for everything under a prefix.
  *
  * @param {{method: string, path: string}} entry
  * @param {string} pattern
@@ -118,10 +120,10 @@ function names(entry, pattern) {
 }
 
 /**
- * The routes the patterns name, refusing a pattern that names none: a test that asserts about a
- * route it misspelled has to fail rather than pass on an empty list.
+ * The routes the patterns name. A pattern that names none throws, so a misspelled route fails
+ * instead of passing on an empty list.
  *
- * @param {any} app
+ * @param {Application} app
  * @param {string|string[]} patterns
  * @param {string} caller the name in the message
  * @returns {ReturnType<typeof routeReport>}
@@ -152,12 +154,10 @@ function select(app, patterns, caller) {
 }
 
 /**
- * Throws unless every route named is answered by µWS itself.
- *
- * The message is the point: it names each route that fell back and why, in the same words
- * `npx fulmine profile` uses, so the failure says what to change.
+ * Throws unless every route named is answered by uWS itself. The message names each route that
+ * fell back and why, in the same words `npx fulmine profile` uses.
  *
- * @param {any} app
+ * @param {Application} app
  * @param {string|string[]} patterns paths as they were registered, "GET /path" to pin the method,
  *   a trailing "*" for everything under a prefix
  */
@@ -174,12 +174,12 @@ function expectNative(app, patterns) {
 }
 
 /**
- * Why a route µWS already matches is still not compiled into a response.
+ * Why a route uWS already matches is still not compiled into a response.
  *
  * The handler is the last answer, not the first: three refusals come before it, and blaming the
- * handler for one of those sends the reader to rewrite something that was already simple enough.
+ * handler sends the reader to rewrite something that was already simple enough.
  *
- * @param {any} app
+ * @param {Application} app
  * @param {{path: string}} entry
  * @returns {string}
  */
@@ -200,10 +200,10 @@ function whyNotCompiled(app, entry) {
 }
 
 /**
- * Throws unless every route named is answered from a response written at startup, which is the
- * step past native: µWS answers it without entering javascript at all.
+ * Throws unless every route named is answered from a response written at startup. One step past
+ * native: uWS answers it without entering javascript.
  *
- * @param {any} app
+ * @param {Application} app
  * @param {string|string[]} patterns as in expectNative
  */
 function expectDeclarative(app, patterns) {
@@ -228,31 +228,29 @@ function expectDeclarative(app, patterns) {
  * What this one request made the framework do, asked from inside a handler or from a `finish`
  * listener. See src/work.js for what each field means and why asking is free.
  *
- * @param {any} req
- * @param {any} res
+ * @param {Request} req
+ * @param {Response} res
  * @returns {import("./work.js").Work}
  */
 function workReport(req, res) {
     return work(req, res);
 }
 
-// The work a fast request does none of, which is what expectLazy is about. The route verdict is
-// not in here: expectNative and expectDeclarative are what assert on that.
+// The work a fast request does none of. The route verdict is not here, expectNative and
+// expectDeclarative assert on that.
 const LAZY = ["headers", "query", "body", "requestStream", "responseStream", "socket"];
 
 /**
  * Throws if this request built anything it did not have to.
  *
- * The route verdict is a property of the application and holds for every request; this is the
- * other half, which holds for one. A route can stay native and still slow down request by request,
- * because a middleware read `req.headers.host` or piped instead of sending: the answer stays
- * correct, the route report stays green, and the throughput does not.
+ * The route verdict holds for every request, this holds for one. A native route still slows down
+ * request by request if a middleware reads `req.headers.host` or pipes instead of sending.
  *
- * `allow` names what is fine here, which is most of the point: a route that parses a body is
- * asserted as one that parses a body and nothing else.
+ * `allow` names what is fine here: a route that parses a body is asserted as one that parses a
+ * body and nothing else.
  *
- * @param {any} req
- * @param {any} res
+ * @param {Request} req
+ * @param {Response} res
  * @param {object} [options]
  * @param {string[]} [options.allow] fields of the report this route is expected to do anyway
  */
@@ -266,7 +264,7 @@ function expectLazy(req, res, options) {
     const done = work(req, res);
     const unwanted = { ...done };
     for (const field of allowed) {
-        /** @type {any} */ (unwanted)[field] = false;
+        unwanted[field] = false;
     }
     const listed = workNames(unwanted);
     if (listed.length === 0) {

package/src/usage.js

@@ -18,15 +18,16 @@ limitations under the License.
 
 const acorn = require("acorn");
 
+/** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
+
 // Marks a middleware the analysis may trust on a GET request without reading its source: the
 // body parsers set it, whose prologue only reads body-framing headers and leaves a bodyless
 // GET alone (and a GET that declares a body falls back to the full header copy).
 const kGetSafe = Symbol("fulmine.getSafe");
 
-// What a handler may do with `req` and still let the header copy be skipped: members whose
-// reads never reach a header. Anything else, computed access included, keeps the copy.
-// req.res and req.app are deliberately absent: the walk judges only the member directly on
-// the parameter, so anything that can reach another object could reach headers through it.
+// What a handler may do with `req` and still let the header copy be skipped: members whose reads
+// never reach a header. Anything else, computed access included, keeps the copy. req.res and
+// req.app are absent because they could reach headers through another object.
 const REQ_OK = new Set(["query", "params", "body", "method", "path", "url", "baseUrl", "originalUrl", "route"]);
 
 // Reading any of these needs the query string fetched: req.url and req.originalUrl carry it
@@ -70,9 +71,8 @@ const QUERY = 8; // reads req.query, req.url or req.originalUrl
 const verdicts = new WeakMap();
 
 /**
- * What one callback provably does, as a mask of the facts above. The default is UNKNOWN: any
- * shape this walk does not understand and any alias of req, res or next could do anything.
- * That inversion is what makes source analysis sound to act on.
+ * What one callback provably does, as a mask of the facts above. The default is UNKNOWN: any shape
+ * this walk does not understand, and any alias of req, res or next, could do anything.
  *
  * @param {Function} fn
  * @returns {number}
@@ -109,7 +109,7 @@ function analyze(fn) {
         // class methods and native functions do not parse alone, and unread code is unknown code
         return UNKNOWN;
     }
-    let root = /** @type {any} */ (tree.body[0]);
+    let root = /** @type {import("acorn").AnyNode} */ (tree.body[0]);
     if (!root) {
         return UNKNOWN;
     }
@@ -124,7 +124,8 @@ function analyze(fn) {
         return UNKNOWN;
     }
 
-    const params = /** @type {any[]} */ (root.params);
+    // checked by the loop below, which answers UNKNOWN for anything else
+    const params = /** @type {import("acorn").Identifier[]} */ (root.params);
     // rest or destructured parameters alias the objects somewhere the walk cannot follow
     for (const p of params) {
         if (p.type !== "Identifier") {
@@ -135,9 +136,8 @@ function analyze(fn) {
     const resName = params[1] ? params[1].name : null;
     const nextName = params[2] ? params[2].name : null;
 
-    // Every appearance of the three names in the whole body is judged, nested functions
-    // included: an inner binding that shadows one of them only makes this stricter, never
-    // looser, so scope tracking is not needed for soundness.
+    // Every appearance of the three names is judged, nested functions included. An inner binding
+    // that shadows one only makes this stricter, so no scope tracking is needed.
     let mask = 0;
     walk(root.body, null, (node, parent) => {
         if (mask & UNKNOWN) {
@@ -192,11 +192,10 @@ function analyze(fn) {
             return;
         }
         if (name === nextName) {
-            // calling next is how a chain advances, and past its end or with an error the
-            // request lands in the framework's own final answer, which the constructor's
-            // accept pre-read covers. Anything but a direct call aliases the continuation,
-            // and an argument that could be the string "route" would leave the chain for
-            // routes nobody analyzed, so only shapes that cannot be a string pass.
+            // calling next is how a chain advances, and past its end the request lands in the
+            // framework's own final answer, which the constructor's accept pre-read covers.
+            // Anything but a direct call aliases the continuation, and an argument that could be
+            // the string "route" would leave the chain, so only non-string shapes pass.
             if (!parent || parent.type !== "CallExpression" || parent.callee !== node) {
                 mask |= UNKNOWN;
                 return;
@@ -235,9 +234,11 @@ function analyze(fn) {
  * Walks every node, handing each its parent. Arrays and nested objects are entered, nothing
  * is interpreted: the judging happens in the visitor.
  *
- * @param {any} node
- * @param {any} parent
- * @param {(node: any, parent: any) => void} visit
+ * @param {any} node an acorn node, or an array or a scalar under one: walked by key, so no shape
+ *   is assumed
+ * @param {any} parent its parent node, or null at the root
+ * @param {(node: any, parent: any) => void} visit handed every node, loose because the visitor
+ *   reads edges of its own off each
  */
 function walk(node, parent, visit) {
     if (!node || typeof node.type !== "string") {
@@ -265,12 +266,11 @@ function walk(node, parent, visit) {
  * What a native route's whole chain provably never does, so the request constructor may leave
  * that work undone: skipHeaders spares the header copy, skipQuery the query fetch.
  *
- * A callback that calls next() bare passes anywhere but in the terminal route, where it would
- * fall out of the chain: there it only passes when the caller established that no later route
- * could catch the fall-through. The framework's own 404 answers with the path alone, so the
- * fall-through itself needs neither headers nor query.
+ * A bare next() passes anywhere but in the terminal route, where it falls out of the chain: there
+ * it passes only when no later route could catch the fall-through. The framework's own 404 answers
+ * from the path alone.
  *
- * @param {any[]} chain the routes the native handler runs, in order, this route last
+ * @param {RouteEntry[]} chain the routes the native handler runs, in order, this route last
  * @param {boolean} allowTerminalNext whether a fall-through past the chain lands only in the
  *   framework's own final answer
  * @returns {{skipHeaders: boolean, skipQuery: boolean}}