fulmine.js 5.13.3 → 5.14.0

package/README.md

@@ -551,6 +551,7 @@ app.ws("/room/:id", {
 - **The behavior object is µWS's**, settings included: `maxPayloadLength`, `idleTimeout`, `compression`, `maxBackpressure`, `sendPingsAutomatically` and the rest are passed through untouched, as are the `open`, `message`, `drain`, `close`, `ping`, `pong`, `dropped` and `subscription` handlers. The socket is µWS's too, so `send`, `subscribe`, `publish`, `cork` and `getBufferedAmount` behave exactly as its documentation describes.
 - **`upgrade(req, res)` is this project's addition.** It runs before the handshake with the same `Request` and `Response` your routes get, so a session, a token or a header decides whether the socket opens. Answering the response, with `res.sendStatus(401)` or any other write, declines the upgrade. Returning a promise holds the handshake until it settles, which is what an authentication lookup needs.
 - **`ws.req` is that request**, and it outlives the response: the client's address, headers, query and params are readable from any handler for as long as the socket is open. Hanging your own values on it in `upgrade` is how per-connection state gets to `message`.
+- **A hook that awaits can be left holding a dead request.** The client may go while a token is being checked, and µWS frees the response when it does, so `res.aborted` says whether there is still anybody to answer. Writing to a response that was aborted does nothing rather than throwing.
 - **Routers work.** `router.ws("/lobby", ...)` mounted with `app.use("/chat", router)` serves `/chat/lobby`.
 - **Paths are the ones µWS matches**: literal, or with parameters that are a whole segment such as `/room/:id`. Anything else throws where it is written rather than failing to match later.
 - **Broadcasting from outside a socket**: `app.publish(topic, message)` and `app.numSubscribers(topic)`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.13.3",
+    "version": "5.14.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "exports": {

package/src/middlewares.js

@@ -210,9 +210,8 @@ function runVerify(req, res, next, options, buf) {
     } catch (e) {
         const err = /** @type {any} */ (e);
         next(
-            bodyError(err.message, err.status ?? err.statusCode ?? 403, err.type ?? "entity.verify.failed", {
-                body: buf,
-                stack: err.stack
+            asBodyError(err, err.status ?? err.statusCode ?? 403, err.type ?? "entity.verify.failed", {
+                body: buf
             })
         );
         return false;
@@ -249,6 +248,15 @@ function strictSyntaxMessage(text, char) {
     return "strict violation";
 }
 
+// The name http-errors gives each status body-parser answers with. An application reading
+// err.name, or a logger printing it, sees "PayloadTooLargeError" from Express and would have
+// seen a bare "Error" here.
+const BODY_ERROR_NAMES = {
+    400: "BadRequestError",
+    413: "PayloadTooLargeError",
+    415: "UnsupportedMediaTypeError"
+};
+
 /**
  * The error a body parser hands to next(), shaped as body-parser shapes it: with a status, since
  * `res.status(err.status || 500)` would otherwise answer 500 to a request that was merely too
@@ -262,6 +270,25 @@ function strictSyntaxMessage(text, char) {
  */
 function bodyError(message, status, type, extra) {
     const err = /** @type {any} */ (new Error(message));
+    if (BODY_ERROR_NAMES[status]) {
+        err.name = BODY_ERROR_NAMES[status];
+    }
+    return asBodyError(err, status, type, extra);
+}
+
+/**
+ * The same, for an error somebody else made: the SyntaxError JSON.parse threw, or whatever a
+ * verify hook threw. http-errors decorates such an error rather than replacing it, so its name,
+ * its stack and any property the thrower put on it are all still there when the application
+ * reads it.
+ *
+ * @param {any} err
+ * @param {number} status
+ * @param {string} type body-parser's own name for the kind of failure
+ * @param {object} [extra] anything else body-parser puts on that particular error
+ * @returns {Error}
+ */
+function asBodyError(err, status, type, extra) {
     // 4xx is the client's to see; a 5xx here would be the server's own problem and stays hidden
     err.expose = status < 500;
     err.statusCode = status;
@@ -1246,17 +1273,23 @@ const json = createBodyParser(
             // eslint-disable-next-line no-control-regex
             const first = text.match(/^[\x20\x09\x0a\x0d]*([^\x20\x09\x0a\x0d])/)?.[1];
             if (first !== "{" && first !== "[") {
-                return next(bodyError(strictSyntaxMessage(text, first), 400, "entity.parse.failed", { body: text }));
+                // a SyntaxError rather than an Error, since that is what body-parser builds here and
+                // what an application testing `err instanceof SyntaxError` looks for
+                return next(
+                    asBodyError(new SyntaxError(strictSyntaxMessage(text, first)), 400, "entity.parse.failed", {
+                        body: text
+                    })
+                );
             }
         }
 
         try {
             req.body = JSON.parse(text, options.reviver);
         } catch (e) {
-            // the JSON error's own message, which is what body-parser keeps, so an application
-            // showing err.message still says where the parse gave up
+            // V8's own error, which is what body-parser hands on: its message says where the parse
+            // gave up, and it is still the SyntaxError an application may be testing for
             const err = /** @type {any} */ (e);
-            return next(bodyError(err.message, 400, "entity.parse.failed", { body: text }));
+            return next(asBodyError(err, 400, "entity.parse.failed", { body: text }));
         }
 
         next();

package/src/types.d.ts

@@ -115,6 +115,13 @@ declare module "fulmine.js" {
         export import NextFunction = e.NextFunction;
         export import Locals = e.Locals;
         export import Request = e.Request;
+
+        // The application, the socket and the behaviour, nameable from outside. `export =` leaves
+        // everything declared beside it out of reach of an import, so anything wrapping ws() had
+        // to write ReturnType<typeof express> and index into it to say what it takes.
+        export type FulmineApplication = Fulmine;
+        export type FulmineSocket = FulmineWebSocket;
+        export type FulmineWebSocketBehavior = WebSocketBehavior;
         export import RequestHandler = e.RequestHandler;
         export import RequestParamHandler = e.RequestParamHandler;
         export import Response = e.Response;
@@ -136,15 +143,21 @@ declare module "fulmine.js" {
         uWS.WebSocketBehavior<SocketData>,
         "upgrade" | "open" | "message" | "dropped" | "drain" | "close" | "ping" | "pong" | "subscription"
     > & {
-        upgrade?: (req: e.Request, res: e.Response) => void | Promise<void>;
-        open?: (ws: FulmineWebSocket) => void;
-        message?: (ws: FulmineWebSocket, message: ArrayBuffer, isBinary: boolean) => void;
-        dropped?: (ws: FulmineWebSocket, message: ArrayBuffer, isBinary: boolean) => void;
-        drain?: (ws: FulmineWebSocket) => void;
-        close?: (ws: FulmineWebSocket, code: number, message: ArrayBuffer) => void;
-        ping?: (ws: FulmineWebSocket, message: ArrayBuffer) => void;
-        pong?: (ws: FulmineWebSocket, message: ArrayBuffer) => void;
-        subscription?: (ws: FulmineWebSocket, topic: ArrayBuffer, newCount: number, oldCount: number) => void;
+        // The return types are µWS's own: it awaits nothing, but open, message and dropped are
+        // declared there as returning void or a promise, and narrowing that here made an async
+        // handler a type error against the library this wraps.
+        // Methods rather than function-typed properties, so a handler may narrow the request or
+        // the socket to one carrying what the upgrade hook hung on it, which is how this project
+        // says per-connection state is kept
+        upgrade?(req: e.Request, res: e.Response): void | Promise<void>;
+        open?(ws: FulmineWebSocket): void | Promise<void>;
+        message?(ws: FulmineWebSocket, message: ArrayBuffer, isBinary: boolean): void | Promise<void>;
+        dropped?(ws: FulmineWebSocket, message: ArrayBuffer, isBinary: boolean): void | Promise<void>;
+        drain?(ws: FulmineWebSocket): void;
+        close?(ws: FulmineWebSocket, code: number, message: ArrayBuffer): void;
+        ping?(ws: FulmineWebSocket, message: ArrayBuffer): void;
+        pong?(ws: FulmineWebSocket, message: ArrayBuffer): void;
+        subscription?(ws: FulmineWebSocket, topic: ArrayBuffer, newCount: number, oldCount: number): void;
     };
 
     // interfaces rather than aliases: `this` is how ws() answers the router or the app it was
@@ -202,6 +215,12 @@ declare module "fulmine.js" {
 // prototype, so a route only has them where that middleware ran, which the optional marks say.
 declare namespace Express {
     interface Response {
+        /**
+         * Whether the client went away before this response was answered. µWS frees the response
+         * then and writing to it does nothing, so a handler that awaited something checks this
+         * first. Express has no counterpart, which is why it is optional here.
+         */
+        aborted?: boolean;
         /** Adds a mark of your own. A mark with only a description is a legal entry. */
         timing?(name: string, duration?: number, description?: string): this;
         /** Times a piece of work under a name. A promise is timed to where it settles. */

package/src/websocket.js

@@ -174,6 +174,9 @@ function makeUpgradeHandler(app, path, behavior) {
         // handler, which is the only place µWS 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