@linebridge/engine-neo 1.1.0 → 1.2.2

package/README.md

@@ -5,7 +5,7 @@ The official, high-performance HTTP and WebSocket engine for [Linebridge](https:
 ## Installation
 
 ```bash
-npm install @linebridge/engine-neo
+pnpm add @linebridge/engine-neo
 ```
 
 ## Usage
@@ -22,5 +22,4 @@ import "@linebridge/engine-neo"
 
 This project is licensed under the **MIT License**.
 
-It includes software developed by uNetworking AB and uWebSockets.js contributors, which is licensed under the **Apache License 2.0**.
-See the [LICENSE](./LICENSE) file for more details.
+It includes software developed by uNetworking AB and uWebSockets.js contributors, which is licensed under the **Apache License 2.0**. See the [LICENSE](./LICENSE) file for more details.

package/lib/engine.d.ts

@@ -15,6 +15,8 @@ import uws_wrapper, { type uWebsockets } from "./uws.js";
 import RTEngine from "linebridge/classes/RtEngine/index";
 import { EngineAdaptor } from "linebridge/classes/EngineAdaptor/index";
 import { Route } from "linebridge/classes/Route/index";
+import route_register from "./route_register.js";
+import middleware_register from "./register_middleware.js";
 /**
  * Options that control the engine's behaviour.
  */
@@ -76,9 +78,9 @@ export declare class NeoEngine extends EngineAdaptor {
     /** Gracefully shuts down the server. Bound to the engine instance. */
     close: () => Promise<boolean>;
     /** Registers a route (HTTP method + path + handler). */
-    register: (route: import("linebridge/classes/Route/index").RouteAlike) => void;
+    register: OmitThisParameter<typeof route_register>;
     /** Registers a global middleware that runs before every route handler. */
-    register_middleware: (middleware: any) => void;
+    register_middleware: OmitThisParameter<typeof middleware_register>;
     /**
      * Publish a message to a topic in MQTT syntax to all WebSocket connections on this Server instance.
      * You cannot publish using wildcards, only fully specified topics.
@@ -91,7 +93,7 @@ export declare class NeoEngine extends EngineAdaptor {
     /** Incoming HTTP request handler. Bound to the engine instance. */
     on_request: (native_req: uWebsockets.HttpRequest, native_res: uWebsockets.HttpResponse, route: Route<any, "server"[]>, socket?: uWebsockets.us_socket_context_t | null | undefined) => any;
     /** Middleware/route iteration loop. Bound to the engine instance. */
-    request_iterator: (request: Request<any>, response: Response<any>, route: Route<Server<"neo">, "server"[]>, allMiddlewares: Handler<HandlerKind>[], cursor?: number | undefined) => Promise<void>;
+    request_iterator: (request: Request<any>, response: Response<any>, route: Route<Server<"neo">, "server"[]>, allMiddlewares: Handler<HandlerKind.middleware>[], cursor?: number | undefined) => Promise<void>;
     /**
      * Decrements the pending request counter and fires the zero-handler
      * when no requests remain in flight.

package/lib/engine.js

@@ -14,7 +14,7 @@ import toBoolean from "linebridge/utils/toBoolean";
 import RTEngine from "linebridge/classes/RtEngine/index";
 import { EngineAdaptor } from "linebridge/classes/EngineAdaptor/index";
 import { Route } from "linebridge/classes/Route/index";
-import WebsocketPolyfill from "./ws/Websocket.js";
+import Websocket from "./ws/Websocket.js";
 import route_register from "./route_register.js";
 import middleware_register from "./register_middleware.js";
 import listen from "./listen.js";
@@ -128,7 +128,7 @@ export class NeoEngine extends EngineAdaptor {
                 upgrade: (res, req, _context) => this.ws.handleUpgrade(req, res),
                 // wrap raw uWS websocket with the polyfill so RTEngine gets EventEmitter + helpers
                 open: (ws) => {
-                    const poly = new WebsocketPolyfill(ws);
+                    const poly = new Websocket(ws);
                     ws.poly = poly;
                     //@ts-ignore polyfill context is Object vs RtEngineSocket's typed shape, but runtime is correct
                     this.ws.handleConnection(poly);
@@ -151,12 +151,15 @@ export class NeoEngine extends EngineAdaptor {
             // @ts-ignore
             global.websockets = this.ws;
         }
-        // create the default route
-        const defaultRoute = new Route();
-        defaultRoute.method = "any";
-        defaultRoute.path = "/*";
-        defaultRoute.fn = this._defaultResponse;
-        this.register(defaultRoute);
+        if (!toBoolean(process.env.LB_SOCKET_MODE)) {
+            // create the default route
+            const defaultRoute = new Route();
+            defaultRoute.method = "any";
+            defaultRoute.path = "/*";
+            defaultRoute.fn = this._defaultResponse;
+            defaultRoute._initialize(this.server);
+            this.register(defaultRoute);
+        }
     };
     /** Starts the server. Bound to the engine instance. */
     listen = listen.bind(this);
@@ -200,7 +203,9 @@ export class NeoEngine extends EngineAdaptor {
      * Default handler for unmatched routes. Responds with a 404 JSON body.
      */
     _defaultResponse(req, res) {
-        res.status(404).json({ error: "Not found" });
+        res.status(404)
+            .setHeader("content-type", "application/json")
+            ._sendFast(`{"error":"Not found"}`);
     }
 }
 export { uws_wrapper as uWebsockets };

package/lib/listen.js

@@ -25,7 +25,9 @@ export default async function () {
                 this.listen_socket = listen_socket;
                 // optionally register process-exit listeners for graceful shutdown
                 if (this.options.auto_close) {
-                    EXIT_EVENTS.forEach((type) => process.once(type, () => this.close()));
+                    EXIT_EVENTS.forEach((type) => process.once(type, () => {
+                        void this.server._fireClose();
+                    }));
                 }
                 resolve();
             }

package/lib/request_iterator.d.ts

@@ -9,7 +9,7 @@ import type Engine from "./engine.js";
 import type Request from "./request.js";
 import type Response from "./response.js";
 import type { Route } from "linebridge/classes/Route/index";
-import type { Handler } from "linebridge/classes/Handler/index";
+import type { Handler, HandlerKind } from "linebridge/classes/Handler/index";
 /**
  * Recursively iterates the middleware chain, then calls the route handler.
  *
@@ -19,4 +19,4 @@ import type { Handler } from "linebridge/classes/Handler/index";
  *
  * @param cursor - Zero-based index into the middleware array. Increments on each recursion.
  */
-export default function (this: Engine, request: Request<any>, response: Response<any>, route: Route<typeof this.server>, allMiddlewares: Handler[], cursor?: number): Promise<void>;
+export default function (this: Engine, request: Request<any>, response: Response<any>, route: Route<typeof this.server>, allMiddlewares: Handler<HandlerKind.middleware>[], cursor?: number): Promise<void>;

package/lib/route_register.d.ts

@@ -1,5 +1,5 @@
-import type Engine from "./engine.js";
-import { RouteAlike } from "linebridge/classes/Route/index";
+import type { Route } from "linebridge/classes/Route/index";
+import type { NeoEngine } from "./engine.js";
 /**
  * Registers a route with the engine's uWS app.
  *
@@ -7,4 +7,4 @@ import { RouteAlike } from "linebridge/classes/Route/index";
  *
  * @throws {Error} If the engine is not initialized or the route is invalid.
  */
-export default function (this: Engine, route: RouteAlike): void;
+export default function (this: NeoEngine, route: Route): void;

package/lib/route_register.js

@@ -1,5 +1,3 @@
-import { Route, } from "linebridge/classes/Route/index";
-import { HandlerKind } from "linebridge/classes/Handler/index";
 /**
  * Registers a route with the engine's uWS app.
  *
@@ -11,57 +9,25 @@ export default function (route) {
     if (!this.uws) {
         throw new Error("Engine is not initialized");
     }
-    let routeInstance;
-    // support passing a class constructor or an already-constructed instance
-    if (typeof route === "function") {
-        try {
-            routeInstance = new route();
-        }
-        catch (err) {
-            console.error(`Failed to construct route class:\n`, err);
-            return;
-        }
-    }
-    else if (route instanceof Route) {
-        routeInstance = route;
-    }
-    else if (typeof route.fn === "function") {
-        routeInstance = new Route();
-        routeInstance.kind = HandlerKind.http;
-        routeInstance.path = route.path ?? "/";
-        routeInstance.method = route.method ?? "get";
-        routeInstance.useContexts = route.useContexts ?? [];
-        routeInstance.useMiddlewares = route.useMiddlewares ?? [];
-        routeInstance.fn = route.fn;
-    }
-    else {
-        throw new Error("Invalid route provided");
-    }
-    // try to initialize the route
-    try {
-        routeInstance._initialize(this.server);
-    }
-    catch (err) {
-        console.error(`Failed to initialize route:\n`, err);
-        return;
-    }
     // normalize DELETE method for uWS compatibility (uWS uses "del" internally)
-    if (routeInstance.method === "delete") {
-        routeInstance.method = "del";
+    if (route.method === "delete") {
+        route.method = "del";
     }
     // verify the method is a valid uWS route method before registering
-    if (typeof this.uws[routeInstance.method] !== "function") {
-        console.warn(`Invalid method (${routeInstance.method}) for route handler [${routeInstance.path}]\nSkipping route..`);
+    if (typeof this.uws[route.method] !== "function") {
+        console.warn(`Invalid method (${route.method}) for route handler [${route.path}]\nSkipping route..`);
         return;
     }
     this.registers.add({
-        kind: routeInstance.kind,
-        method: routeInstance.method,
-        path: routeInstance.path,
-        useContexts: routeInstance.useContexts,
-        useMiddlewares: routeInstance.useMiddlewares,
-        _source_file: routeInstance._source_file,
-        handler: routeInstance.handler,
+        kind: route.kind,
+        method: route.method,
+        path: route.path,
+        useContexts: route.useContexts,
+        useMiddlewares: route.useMiddlewares,
+        _source_file: route._source_file,
+        handler: route.handler,
     });
-    this.uws[routeInstance.method](routeInstance.path, (res, req) => this.on_request(req, res, routeInstance));
+    if (route.kind === "http") {
+        this.uws[route.method](route.path, (res, req) => this.on_request(req, res, route));
+    }
 }

package/lib/utils.d.ts

@@ -10,5 +10,5 @@ declare function wrap_object(original: any, target: any): void;
  * @param {BufferEncoding} encoding
  * @returns {String} String
  */
-declare function array_buffer_to_string(array_buffer: ArrayBuffer, encoding?: BufferEncoding): any;
+declare function array_buffer_to_string(array_buffer: ArrayBuffer, encoding?: BufferEncoding): string;
 export { array_buffer_to_string, wrap_object };

package/lib/ws/Websocket.d.ts

@@ -1,173 +1,125 @@
 import { EventEmitter } from "tseep/lib/ee-safe.js";
-import { Readable, Writable } from "stream";
-export default class Websocket extends EventEmitter {
+import { Readable, Writable } from "node:stream";
+import type { uWebsockets } from "../uws.js";
+/** Any payload accepted by uWebSockets or produced by streams. */
+export type WebsocketMessage = string | Buffer | ArrayBuffer | ArrayBufferView;
+/** Events emitted by the websocket polyfill. */
+export type WebsocketEventMap = {
+    [event in string | symbol]: (...args: any[]) => void;
+} & {
+    message: (message: WebsocketMessage, is_binary: boolean) => void;
+    close: (code: number, message: WebsocketMessage) => void;
+    drain: () => void;
+    ping: (message: WebsocketMessage) => void;
+    pong: (message: WebsocketMessage) => void;
+};
+/**
+ * Raw uws websocket with the context and polyfill attached by the engine.
+ * The native wrapper merges the upgrade user data into the socket object.
+ */
+export interface WebsocketRaw<TContext = Record<string, any>> extends uWebsockets.WebSocket<{
+    context?: TContext;
+}> {
+    context?: TContext;
+    poly?: Websocket<TContext>;
+}
+declare const FRAGMENTS: {
+    readonly FIRST: "FIRST";
+    readonly MIDDLE: "MIDDLE";
+    readonly LAST: "LAST";
+};
+type Fragment = (typeof FRAGMENTS)[keyof typeof FRAGMENTS];
+export default class Websocket<TContext = Record<string, any>> extends EventEmitter<WebsocketEventMap> {
     #private;
-    constructor(ws: any);
-    /**
-     * Binds an event listener to this `Websocket` instance.
-     * See the Node.js `EventEmitter` documentation for more details on this extended method.
-     * @param {('message'|'close'|'drain'|'ping'|'pong')} eventName
-     * @param {Function} listener
-     * @returns {Websocket}
-     */
-    on(eventName: ('message' | 'close' | 'drain' | 'ping' | 'pong'), listener: Function): Websocket;
-    /**
-     * Binds a `one-time` event listener to this `Websocket` instance.
-     * See the Node.js `EventEmitter` documentation for more details on this extended method.
-     * @param {('message'|'close'|'drain'|'ping'|'pong')} eventName
-     * @param {Function} listener
-     * @returns {Websocket}
-     */
-    once(eventName: ('message' | 'close' | 'drain' | 'ping' | 'pong'), listener: Function): Websocket;
+    constructor(ws: WebsocketRaw<TContext>);
     /**
-     * Alias of uWS.cork() method. Accepts a callback with multiple operations for network efficiency.
-     *
-     * @param {Function} callback
-     * @returns {Websocket}
+     * Alias of uws cork, used to batch multiple operations for efficiency.
      */
-    atomic(callback: Function): Websocket;
+    atomic(callback: () => void): Websocket<TContext> | uWebsockets.WebSocket<{
+        context?: TContext;
+    }>;
     /**
-     * Sends a message to websocket connection.
-     * Returns true if message was sent successfully.
-     * Returns false if message was not sent due to buil up backpressure.
-     *
-     * @param {String|Buffer|ArrayBuffer} message
-     * @param {Boolean=} is_binary
-     * @param {Boolean=} compress
-     * @returns {Boolean}
+     * Sends a message over the connection.
+     * Returns the uws send status, or false when the socket is closed.
      */
-    send(message: string | Buffer | ArrayBuffer, is_binary?: boolean | undefined, compress?: boolean | undefined): boolean;
+    send(message: WebsocketMessage, is_binary?: boolean, compress?: boolean): number | false;
     /**
      * Sends a ping control message.
-     * Returns Boolean depending on backpressure similar to send().
-     *
-     * @param {String|Buffer|ArrayBuffer=} message
-     * @returns {Boolean}
      */
-    ping(message?: (string | Buffer | ArrayBuffer) | undefined): boolean;
+    ping(message?: WebsocketMessage): number | false;
     /**
-     * Destroys this polyfill Websocket component and derefernces the underlying ws object
+     * Destroys this polyfill and dereferences the underlying socket.
      * @private
      */
-    private _destroy;
+    _destroy(): void;
     /**
-     * Gracefully closes websocket connection by sending specified code and short message.
-     *
-     * @param {Number=} code
-     * @param {(String|Buffer|ArrayBuffer)=} message
+     * Gracefully closes the connection, sending an optional code and message.
      */
-    close(code?: number | undefined, message?: (string | Buffer | ArrayBuffer) | undefined): void;
+    close(code?: number, message?: WebsocketMessage): void;
     /**
-     * Forcefully closes websocket connection.
-     * No websocket close code/message is sent.
-     * This will immediately emit the 'close' event.
+     * Forcefully closes the connection without a close message.
      */
     destroy(): void;
     /**
-     * Returns whether this `Websocket` is subscribed to the specified topic.
-     *
-     * @param {String} topic
-     * @returns {Boolean}
+     * Returns whether this connection is subscribed to the topic.
      */
     is_subscribed(topic: string): boolean;
     /**
-     * Subscribe to a topic in MQTT syntax.
-     * MQTT syntax includes things like "root/child/+/grandchild" where "+" is a wildcard and "root/#" where "#" is a terminating wildcard.
-     *
-     * @param {String} topic
-     * @returns {Boolean}
+     * Subscribes to a topic in mqtt syntax.
      */
     subscribe(topic: string): boolean;
     /**
-     * Unsubscribe from a topic.
-     * Returns true on success, if the WebSocket was subscribed.
-     *
-     * @param {String} topic
-     * @returns {Boolean}
+     * Unsubscribes from a topic.
      */
     unsubscribe(topic: string): boolean;
     /**
-     * Publish a message to a topic in MQTT syntax.
-     * You cannot publish using wildcards, only fully specified topics.
-     *
-     * @param {String} topic
-     * @param {String|Buffer|ArrayBuffer} message
-     * @param {Boolean=} is_binary
-     * @param {Boolean=} compress
+     * Publishes a message to a topic in mqtt syntax.
      */
-    publish(topic: string, message: string | Buffer | ArrayBuffer, is_binary?: boolean | undefined, compress?: boolean | undefined): any;
+    publish(topic: string, message: WebsocketMessage, is_binary?: boolean, compress?: boolean): boolean;
     /**
-     * Buffers the provided fragment and returns the last buffered fragment.
-     *
-     * @param {String|Buffer|ArrayBuffer} fragment
-     * @returns {String|Buffer|ArrayBuffer|undefined}
+     * Buffers the provided fragment and returns the previously buffered one.
      */
-    _buffer_fragment(fragment: string | Buffer | ArrayBuffer): string | Buffer | ArrayBuffer | undefined;
+    _buffer_fragment(fragment?: WebsocketMessage): WebsocketMessage | undefined;
     /**
-     * Initiates fragment based message writing with uWS and writes appropriate chunk based on provided type parameter.
-     *
-     * @param {String} type
-     * @param {String|Buffer|ArrayBuffer} chunk
-     * @param {Boolean=} is_binary
-     * @param {Boolean=} compress
-     * @param {Function=} callback
-     * @returns {Boolean}
+     * Writes a fragment using the appropriate uws fragment method.
      */
-    _write(type: string, chunk: string | Buffer | ArrayBuffer, is_binary?: boolean | undefined, compress?: boolean | undefined, callback?: Function | undefined): boolean;
+    _write(type: Fragment, chunk: WebsocketMessage, is_binary?: boolean, compress?: boolean, callback?: () => void): number;
     /**
-     * Streams the provided chunk while pausing the stream being consumed during backpressure.
-     *
-     * @param {Readable} stream
-     * @param {String} type
-     * @param {Buffer|ArrayBuffer} chunk
-     * @param {Boolean} is_binary
+     * Streams a chunk, pausing the source stream while under backpressure.
      */
-    _stream_chunk(stream: Readable, type: string, chunk: Buffer | ArrayBuffer, is_binary: boolean): void;
+    _stream_chunk(stream: Readable, type: Fragment, chunk: WebsocketMessage, is_binary: boolean): void;
     /**
-     * This method is used to stream a message to the receiver.
-     * Note! The data is by default streamed as Binary due to how partial fragments are sent.
-     * This is done to prevent processing errors depending on client's receiver's incoming fragment processing strategy.
-     *
-     * @param {Readable} readable A Readable stream which will be consumed as message
-     * @param {Boolean=} is_binary Whether data being streamed is in binary. Default: true
-     * @returns {Promise}
+     * Streams a readable as a single fragmented message.
      */
-    stream(readable: Readable, is_binary?: boolean | undefined): Promise<any>;
+    stream(readable: Readable, is_binary?: boolean): Promise<void>;
     /**
-     * Underlying uWS.Websocket object
+     * Underlying uws websocket object.
      */
-    get raw(): any;
+    get raw(): WebsocketRaw<TContext> | null;
     /**
-     * Returns IP address of this websocket connection.
-     * @returns {String}
+     * Remote ip address of this connection.
      */
     get ip(): string;
     /**
-     * Returns context values from the response.update(context) connection upgrade call.
-     * @returns {Object}
+     * Context values attached during the upgrade.
      */
-    get context(): Object;
+    get context(): TContext;
     /**
-     * Returns whether is websocket connection is closed.
-     * @returns {Boolean}
+     * Whether this connection is closed.
      */
     get closed(): boolean;
     /**
-     * Returns the bytes buffered in backpressure.
-     * This is similar to the bufferedAmount property in the browser counterpart.
-     * @returns {Number}
+     * Bytes currently buffered in backpressure.
      */
     get buffered(): number;
     /**
-     * Returns a list of topics this websocket is subscribed to.
-     * @returns {Array<String>}
+     * Topics this connection is subscribed to.
      */
-    get topics(): Array<string>;
+    get topics(): string[];
     /**
-     * Returns a Writable stream associated with this response to be used for piping streams.
-     * Note! You can only retrieve/use only one writable at any given time.
-     *
-     * @returns {Writable}
+     * Writable stream bound to this connection for piping.
+     * Only one writable can be used at a time.
      */
     get writable(): Writable;
 }
+export {};

package/lib/ws/Websocket.js

@@ -1,5 +1,5 @@
 import { EventEmitter } from "tseep/lib/ee-safe.js";
-import { Readable, Writable } from "stream";
+import { Readable, Writable } from "node:stream";
 import { array_buffer_to_string } from "../utils.js";
 const FRAGMENTS = {
     FIRST: "FIRST",
@@ -11,78 +11,37 @@ export default class Websocket extends EventEmitter {
     #ip;
     #context;
     #stream;
+    #buffered_fragment;
     #closed = false;
     constructor(ws) {
-        // Initialize event emitter
         super();
-        // Parse information about websocket connection
         this.#ws = ws;
         this.#context = ws.context || {};
         this.#ip = array_buffer_to_string(ws.getRemoteAddressAsText());
     }
-    /* EventEmitter overrides */
-    /**
-     * Binds an event listener to this `Websocket` instance.
-     * See the Node.js `EventEmitter` documentation for more details on this extended method.
-     * @param {('message'|'close'|'drain'|'ping'|'pong')} eventName
-     * @param {Function} listener
-     * @returns {Websocket}
-     */
-    on(eventName, listener) {
-        // Pass all events to EventEmitter
-        super.on(eventName, listener);
-        return this;
-    }
-    /**
-     * Binds a `one-time` event listener to this `Websocket` instance.
-     * See the Node.js `EventEmitter` documentation for more details on this extended method.
-     * @param {('message'|'close'|'drain'|'ping'|'pong')} eventName
-     * @param {Function} listener
-     * @returns {Websocket}
-     */
-    once(eventName, listener) {
-        // Pass all events to EventEmitter
-        super.once(eventName, listener);
-        return this;
-    }
     /**
-     * Alias of uWS.cork() method. Accepts a callback with multiple operations for network efficiency.
-     *
-     * @param {Function} callback
-     * @returns {Websocket}
+     * Alias of uws cork, used to batch multiple operations for efficiency.
      */
     atomic(callback) {
         return this.#ws ? this.#ws.cork(callback) : this;
     }
     /**
-     * Sends a message to websocket connection.
-     * Returns true if message was sent successfully.
-     * Returns false if message was not sent due to buil up backpressure.
-     *
-     * @param {String|Buffer|ArrayBuffer} message
-     * @param {Boolean=} is_binary
-     * @param {Boolean=} compress
-     * @returns {Boolean}
+     * Sends a message over the connection.
+     * Returns the uws send status, or false when the socket is closed.
      */
     send(message, is_binary, compress) {
-        // Send message through uWS connection
         if (this.#ws)
             return this.#ws.send(message, is_binary, compress);
         return false;
     }
     /**
      * Sends a ping control message.
-     * Returns Boolean depending on backpressure similar to send().
-     *
-     * @param {String|Buffer|ArrayBuffer=} message
-     * @returns {Boolean}
      */
     ping(message) {
-        // Send ping OPCODE message through uWS connection
         return this.#ws ? this.#ws.ping(message) : false;
     }
     /**
-     * Destroys this polyfill Websocket component and derefernces the underlying ws object
+     * Destroys this polyfill and dereferences the underlying socket.
      * @private
      */
     _destroy() {
@@ -90,74 +49,47 @@ export default class Websocket extends EventEmitter {
         this.#closed = true;
     }
     /**
-     * Gracefully closes websocket connection by sending specified code and short message.
-     *
-     * @param {Number=} code
-     * @param {(String|Buffer|ArrayBuffer)=} message
+     * Gracefully closes the connection, sending an optional code and message.
      */
     close(code, message) {
-        // Close websocket using uWS.end() method which gracefully closes connections
         if (this.#ws)
             this.#ws.end(code, message);
     }
     /**
-     * Forcefully closes websocket connection.
-     * No websocket close code/message is sent.
-     * This will immediately emit the 'close' event.
+     * Forcefully closes the connection without a close message.
      */
     destroy() {
         if (this.#ws)
             this.#ws.close();
     }
     /**
-     * Returns whether this `Websocket` is subscribed to the specified topic.
-     *
-     * @param {String} topic
-     * @returns {Boolean}
+     * Returns whether this connection is subscribed to the topic.
      */
     is_subscribed(topic) {
         return this.#ws ? this.#ws.isSubscribed(topic) : false;
     }
     /**
-     * Subscribe to a topic in MQTT syntax.
-     * MQTT syntax includes things like "root/child/+/grandchild" where "+" is a wildcard and "root/#" where "#" is a terminating wildcard.
-     *
-     * @param {String} topic
-     * @returns {Boolean}
+     * Subscribes to a topic in mqtt syntax.
      */
     subscribe(topic) {
         return this.#ws ? this.#ws.subscribe(topic) : false;
     }
     /**
-     * Unsubscribe from a topic.
-     * Returns true on success, if the WebSocket was subscribed.
-     *
-     * @param {String} topic
-     * @returns {Boolean}
+     * Unsubscribes from a topic.
      */
     unsubscribe(topic) {
         return this.#ws ? this.#ws.unsubscribe(topic) : false;
     }
     /**
-     * Publish a message to a topic in MQTT syntax.
-     * You cannot publish using wildcards, only fully specified topics.
-     *
-     * @param {String} topic
-     * @param {String|Buffer|ArrayBuffer} message
-     * @param {Boolean=} is_binary
-     * @param {Boolean=} compress
+     * Publishes a message to a topic in mqtt syntax.
      */
     publish(topic, message, is_binary, compress) {
         return this.#ws
             ? this.#ws.publish(topic, message, is_binary, compress)
             : false;
     }
-    #buffered_fragment;
     /**
-     * Buffers the provided fragment and returns the last buffered fragment.
-     *
-     * @param {String|Buffer|ArrayBuffer} fragment
-     * @returns {String|Buffer|ArrayBuffer|undefined}
+     * Buffers the provided fragment and returns the previously buffered one.
      */
     _buffer_fragment(fragment) {
         const current = this.#buffered_fragment;
@@ -165,217 +97,157 @@ export default class Websocket extends EventEmitter {
         return current;
     }
     /**
-     * Initiates fragment based message writing with uWS and writes appropriate chunk based on provided type parameter.
-     *
-     * @param {String} type
-     * @param {String|Buffer|ArrayBuffer} chunk
-     * @param {Boolean=} is_binary
-     * @param {Boolean=} compress
-     * @param {Function=} callback
-     * @returns {Boolean}
+     * Writes a fragment using the appropriate uws fragment method.
      */
     _write(type, chunk, is_binary, compress, callback) {
-        // Ensure websocket still exists before attempting to write
-        if (this.#ws) {
-            // Attempt to send this fragment using the appropriate fragment method from uWS
-            let sent;
-            switch (type) {
-                case FRAGMENTS.FIRST:
-                    sent = this.#ws.sendFirstFragment(chunk, is_binary, compress);
-                    break;
-                case FRAGMENTS.MIDDLE:
-                    sent = this.#ws.sendFragment(chunk, is_binary, compress);
-                    break;
-                case FRAGMENTS.LAST:
-                    sent = this.#ws.sendLastFragment(chunk, is_binary, compress);
-                    break;
-                default:
-                    throw new Error("Websocket._write() -> Invalid Fragment type constant provided.");
-            }
-            if (sent) {
-                // Invoke the callback if chunk was sent successfully
-                if (callback)
-                    callback();
-            }
-            else {
-                // Wait for this connection to drain before retrying this chunk
-                this.once("drain", () => this._write(type, chunk, is_binary, compress, callback));
-            }
-            // Return the sent status for consumer
-            return sent;
+        if (!this.#ws) {
+            throw new Error("Websocket is no longer connected.");
+        }
+        let sent;
+        switch (type) {
+            case FRAGMENTS.FIRST:
+                sent = this.#ws.sendFirstFragment(chunk, is_binary, compress);
+                break;
+            case FRAGMENTS.MIDDLE:
+                sent = this.#ws.sendFragment(chunk, compress);
+                break;
+            case FRAGMENTS.LAST:
+                sent = this.#ws.sendLastFragment(chunk, compress);
+                break;
+            default:
+                throw new Error("Websocket._write() -> invalid fragment type constant provided.");
+        }
+        if (sent) {
+            if (callback)
+                callback();
         }
-        // Throw an error with NOT_CONNECTED message to be caught by executor
-        throw new Error("Websocket is no longer connected.");
+        else {
+            // wait for drain before retrying this chunk
+            this.once("drain", () => this._write(type, chunk, is_binary, compress, callback));
+        }
+        return sent;
     }
     /**
-     * Streams the provided chunk while pausing the stream being consumed during backpressure.
-     *
-     * @param {Readable} stream
-     * @param {String} type
-     * @param {Buffer|ArrayBuffer} chunk
-     * @param {Boolean} is_binary
+     * Streams a chunk, pausing the source stream while under backpressure.
      */
     _stream_chunk(stream, type, chunk, is_binary) {
-        // Break execution if connection is no longer connected
         if (this.#ws === null)
             return;
-        // Attempt to write this chunk
         const sent = this._write(type, chunk, is_binary);
         if (!sent) {
-            // Pause the readable stream as we failed to write this chunk
             stream.pause();
-            // Wait for this connection to be drained before trying again
             this.once("drain", () => this._stream_chunk(stream, type, chunk, is_binary));
         }
         else if (stream.isPaused()) {
-            // Resume the stream if it has been paused and we sent a chunk successfully
             stream.resume();
         }
     }
     /**
-     * This method is used to stream a message to the receiver.
-     * Note! The data is by default streamed as Binary due to how partial fragments are sent.
-     * This is done to prevent processing errors depending on client's receiver's incoming fragment processing strategy.
-     *
-     * @param {Readable} readable A Readable stream which will be consumed as message
-     * @param {Boolean=} is_binary Whether data being streamed is in binary. Default: true
-     * @returns {Promise}
+     * Streams a readable as a single fragmented message.
      */
     stream(readable, is_binary = true) {
-        // Ensure readable is an instance of a stream.Readable
-        if (!(readable instanceof Readable))
+        if (!(readable instanceof Readable)) {
             throw new Error("Websocket.stream(readable) -> readable must be a Readable stream.");
-        // Prevent multiple streams from taking place
-        if (this.#stream)
-            throw new Error("Websocket.stream(readable) -> You may not stream data while another stream operation is active on this websocket. Make sure you are not already streaming or piping a stream to this websocket.");
-        // Return a promise which resolves once stream has finished
-        const scope = this;
+        }
+        if (this.#stream) {
+            throw new Error("Websocket.stream(readable) -> you may not stream data while another stream operation is active on this websocket.");
+        }
         return new Promise((resolve) => {
-            // Store the readable as the pending stream for this connection
-            scope.#stream = readable;
-            // Bind a listener for the 'data' event to consume chunks
-            let is_first = true; // By default, we will send the first chunk as a fragment
+            this.#stream = readable;
+            let is_first = true;
             readable.on("data", (chunk) => {
-                // Check to see if we have a fragment to send post buffering
-                const fragment = scope._buffer_fragment(chunk);
-                if (fragment) {
-                    // Stream the retrieved current fragment
-                    scope._stream_chunk(readable, is_first ? FRAGMENTS.FIRST : FRAGMENTS.MIDDLE, fragment, is_binary);
-                    // If this was the first chunk, invert the is_first boolean
-                    if (is_first)
-                        is_first = false;
-                }
+                const fragment = this._buffer_fragment(chunk);
+                if (!fragment)
+                    return;
+                this._stream_chunk(readable, is_first ? FRAGMENTS.FIRST : FRAGMENTS.MIDDLE, fragment, is_binary);
+                if (is_first)
+                    is_first = false;
             });
-            // Create a callback for ending the readable consumption
             const end_stream = () => {
-                // Retrieve the last buffered fragment to send as last or only chunk
-                const fragment = scope._buffer_fragment();
-                // If we streamed no individual fragments aka. the is_first flag was set to true, then we did no streaming and can simply send the last fragment as a message
+                const fragment = this._buffer_fragment();
                 if (is_first) {
-                    scope.#ws.send(fragment, is_binary);
+                    this.#ws.send(fragment, is_binary);
                 }
                 else {
-                    // Stream the final chunk as last fragment
-                    scope._stream_chunk(scope.#stream, FRAGMENTS.LAST, fragment, is_binary);
+                    this._stream_chunk(readable, FRAGMENTS.LAST, fragment, is_binary);
                 }
-                // Clean up the readable
-                scope.#stream = undefined;
+                this.#stream = undefined;
                 resolve();
             };
-            // Bind listeners to end the framented write procedure
             readable.once("end", end_stream);
         });
     }
-    /* Websocket Getters */
+    /* getters */
     /**
-     * Underlying uWS.Websocket object
+     * Underlying uws websocket object.
      */
     get raw() {
         return this.#ws;
     }
     /**
-     * Returns IP address of this websocket connection.
-     * @returns {String}
+     * Remote ip address of this connection.
      */
     get ip() {
         return this.#ip;
     }
     /**
-     * Returns context values from the response.update(context) connection upgrade call.
-     * @returns {Object}
+     * Context values attached during the upgrade.
      */
     get context() {
         return this.#context;
     }
     /**
-     * Returns whether is websocket connection is closed.
-     * @returns {Boolean}
+     * Whether this connection is closed.
      */
     get closed() {
         return this.#closed;
     }
     /**
-     * Returns the bytes buffered in backpressure.
-     * This is similar to the bufferedAmount property in the browser counterpart.
-     * @returns {Number}
+     * Bytes currently buffered in backpressure.
      */
     get buffered() {
         return this.#ws ? this.#ws.getBufferedAmount() : 0;
     }
     /**
-     * Returns a list of topics this websocket is subscribed to.
-     * @returns {Array<String>}
+     * Topics this connection is subscribed to.
      */
     get topics() {
         return this.#ws ? this.#ws.getTopics() : [];
     }
     /**
-     * Returns a Writable stream associated with this response to be used for piping streams.
-     * Note! You can only retrieve/use only one writable at any given time.
-     *
-     * @returns {Writable}
+     * Writable stream bound to this connection for piping.
+     * Only one writable can be used at a time.
      */
     get writable() {
-        // Prevent multiple streaming operations from taking place
-        const scope = this;
-        if (this.#stream)
-            throw new Error("Websocket.writable -> You may only access and utilize one writable stream at any given time. Make sure you are not already streaming or piping a stream to this websocket.");
-        // Create a new writable stream object which will write with the _write method
+        if (this.#stream) {
+            throw new Error("Websocket.writable -> you may only access and utilize one writable stream at any given time.");
+        }
         let is_first = true;
-        this.#stream = new Writable({
-            write: (chunk, encoding, callback) => {
-                // Buffer the incoming chunk as a fragment
-                const fragment = scope._buffer_fragment(chunk);
-                // Check to see if we have a fragment to send post buffering
+        const writable = new Writable({
+            write: (chunk, _encoding, callback) => {
+                const fragment = this._buffer_fragment(chunk);
                 if (fragment) {
-                    // Write the current retrieved fragment
-                    scope._write(is_first ? FRAGMENTS.FIRST : FRAGMENTS.MIDDLE, fragment, true, false, callback);
-                    // Invert the is_first boolean after first fragment
+                    this._write(is_first ? FRAGMENTS.FIRST : FRAGMENTS.MIDDLE, fragment, true, false, callback);
                     if (is_first)
                         is_first = false;
                 }
                 else {
-                    // Trigger the callback even if don't have a fragment to continue consuming
                     callback();
                 }
             },
         });
-        // Create a callback for ending the writable usage
+        this.#stream = writable;
         const end_stream = () => {
-            // Retrieve the last buffered fragment to write as last or only chunk
-            const fragment = scope._buffer_fragment();
+            const fragment = this._buffer_fragment();
             if (is_first) {
-                scope.#ws.send(fragment, true, false);
-                scope.#ws.stream = undefined;
+                this.#ws.send(fragment, true, false);
+                this.#stream = undefined;
             }
             else {
-                // Write the final empty chunk as last fragment and cleanup the writable
-                scope._write(FRAGMENTS.LAST, fragment, true, false, () => (scope.#stream = undefined));
+                this._write(FRAGMENTS.LAST, fragment, true, false, () => (this.#stream = undefined));
             }
         };
-        // Bind listeners to end the fragmented write procedure
-        this.#stream.on("finish", end_stream);
-        // Return the writable stream
-        return this.#stream;
+        writable.on("finish", end_stream);
+        return writable;
     }
 }

package/lib/ws/WebsocketRoute.d.ts

@@ -0,0 +1,86 @@
+import { type uWebsockets } from "../uws.js";
+import Websocket, { type WebsocketRaw } from "./Websocket.js";
+export type WebsocketMessageType = "String" | "Buffer" | "ArrayBuffer";
+export interface WebsocketRouteOptions {
+    idle_timeout: number;
+    message_type: WebsocketMessageType;
+    compression: uWebsockets.CompressOptions;
+    max_backpressure: number;
+    max_payload_length: number;
+}
+interface WebsocketRouteApp {
+    routes: Record<string, Record<string, any>>;
+    uws_instance: uWebsockets.TemplatedApp;
+    _create_route(options: {
+        method: string;
+        pattern: string;
+        handler: (request: any, response: any) => void;
+        options?: Record<string, any>;
+    }): void;
+    _handle_uws_request(route: any, request: uWebsockets.HttpRequest, response: uWebsockets.HttpResponse, socket_context: uWebsockets.us_socket_context_t): void;
+}
+export interface WebsocketRouteConstructorOptions {
+    app: WebsocketRouteApp;
+    pattern: string;
+    handler: (websocket: Websocket) => void;
+    options?: Partial<WebsocketRouteOptions>;
+}
+type MessageParser = (message: ArrayBuffer) => string | Buffer | ArrayBuffer;
+export default class WebsocketRoute {
+    #private;
+    app: WebsocketRouteApp;
+    pattern: string;
+    handler: (websocket: Websocket) => void;
+    options: WebsocketRouteOptions;
+    constructor({ app, pattern, handler, options, }: WebsocketRouteConstructorOptions);
+    /**
+     * Returns a parser that converts a uws ArrayBuffer to the configured type.
+     */
+    _get_message_parser(type: WebsocketMessageType): MessageParser;
+    /**
+     * Loads the companion upgrade route from the app routes.
+     * @private
+     */
+    _load_companion_route(): void;
+    /**
+     * Sets the upgrade route used for incoming upgrade requests.
+     * @private
+     */
+    _set_upgrade_route(route: any): void;
+    /**
+     * Creates the uws ws route that powers this instance.
+     * @private
+     */
+    _create_uws_route(): void;
+    /**
+     * Handles the uws open event.
+     * @private
+     */
+    _on_open(ws: WebsocketRaw): void;
+    /**
+     * Handles the uws ping event.
+     * @private
+     */
+    _on_ping(ws: WebsocketRaw, message?: ArrayBuffer): void;
+    /**
+     * Handles the uws pong event.
+     * @private
+     */
+    _on_pong(ws: WebsocketRaw, message?: ArrayBuffer): void;
+    /**
+     * Handles the uws drain event.
+     * @private
+     */
+    _on_drain(ws: WebsocketRaw): void;
+    /**
+     * Handles the uws message event.
+     * @private
+     */
+    _on_message(ws: WebsocketRaw, message: ArrayBuffer | undefined, is_binary: boolean): void;
+    /**
+     * Handles the uws close event.
+     * @private
+     */
+    _on_close(ws: WebsocketRaw, code: number, message?: ArrayBuffer): void;
+}
+export {};

package/lib/ws/WebsocketRoute.js

@@ -0,0 +1,139 @@
+import uws_wrapper from "../uws.js";
+import Websocket from "./Websocket.js";
+import { wrap_object, array_buffer_to_string } from "../utils.js";
+export default class WebsocketRoute {
+    #upgrade_with;
+    #message_parser;
+    app;
+    pattern;
+    handler;
+    options = {
+        idle_timeout: 32,
+        message_type: "String",
+        compression: uws_wrapper.DISABLED,
+        max_backpressure: 1024 * 1024,
+        max_payload_length: 32 * 1024,
+    };
+    constructor({ app, pattern, handler, options, }) {
+        this.app = app;
+        this.pattern = pattern;
+        this.handler = handler;
+        // merge user options over the local defaults
+        wrap_object(this.options, options ?? {});
+        this.#message_parser = this._get_message_parser(this.options.message_type);
+        this._load_companion_route();
+        this._create_uws_route();
+    }
+    /**
+     * Returns a parser that converts a uws ArrayBuffer to the configured type.
+     */
+    _get_message_parser(type) {
+        switch (type) {
+            case "String":
+                return (array_buffer) => array_buffer_to_string(array_buffer);
+            case "Buffer":
+                // copy the buffer because uws deallocates it after this sync call
+                return (array_buffer) => Buffer.concat([Buffer.from(array_buffer)]);
+            case "ArrayBuffer":
+                return (array_buffer) => array_buffer;
+            default:
+                throw new Error("Server.ws(options) -> options.message_type must be one of ['String', 'Buffer', 'ArrayBuffer']");
+        }
+    }
+    /**
+     * Loads the companion upgrade route from the app routes.
+     * @private
+     */
+    _load_companion_route() {
+        const companion = this.app.routes["upgrade"][this.pattern];
+        if (companion) {
+            this.#upgrade_with = companion;
+            return;
+        }
+        // create a temporary default route that upgrades every request
+        this.app._create_route({
+            method: "upgrade",
+            pattern: this.pattern,
+            handler: (_request, response) => response.upgrade(),
+            options: {
+                _temporary: true,
+            },
+        });
+        this.#upgrade_with = this.app.routes["upgrade"][this.pattern];
+    }
+    /**
+     * Sets the upgrade route used for incoming upgrade requests.
+     * @private
+     */
+    _set_upgrade_route(route) {
+        this.#upgrade_with = route;
+    }
+    /**
+     * Creates the uws ws route that powers this instance.
+     * @private
+     */
+    _create_uws_route() {
+        const { compression, idle_timeout, max_backpressure, max_payload_length, } = this.options;
+        const uws_options = {
+            compression,
+            idleTimeout: idle_timeout,
+            maxBackpressure: max_backpressure,
+            maxPayloadLength: max_payload_length,
+        };
+        // pipe upgrade requests through the app request lifecycle
+        uws_options.upgrade = (uws_response, uws_request, socket_context) => this.app._handle_uws_request(this.#upgrade_with, uws_request, uws_response, socket_context);
+        uws_options.open = (ws) => this._on_open(ws);
+        uws_options.drain = (ws) => this._on_drain(ws);
+        uws_options.ping = (ws, message) => this._on_ping(ws, message);
+        uws_options.pong = (ws, message) => this._on_pong(ws, message);
+        uws_options.close = (ws, code, message) => this._on_close(ws, code, message);
+        uws_options.message = (ws, message, is_binary) => this._on_message(ws, message, is_binary);
+        this.app.uws_instance.ws(this.pattern, uws_options);
+    }
+    /**
+     * Handles the uws open event.
+     * @private
+     */
+    _on_open(ws) {
+        ws.poly = new Websocket(ws);
+        this.handler(ws.poly);
+    }
+    /**
+     * Handles the uws ping event.
+     * @private
+     */
+    _on_ping(ws, message = new ArrayBuffer(0)) {
+        ws.poly.emit("ping", this.#message_parser(message));
+    }
+    /**
+     * Handles the uws pong event.
+     * @private
+     */
+    _on_pong(ws, message = new ArrayBuffer(0)) {
+        ws.poly.emit("pong", this.#message_parser(message));
+    }
+    /**
+     * Handles the uws drain event.
+     * @private
+     */
+    _on_drain(ws) {
+        ws.poly.emit("drain");
+    }
+    /**
+     * Handles the uws message event.
+     * @private
+     */
+    _on_message(ws, message = new ArrayBuffer(0), is_binary) {
+        ws.poly.emit("message", this.#message_parser(message), is_binary);
+    }
+    /**
+     * Handles the uws close event.
+     * @private
+     */
+    _on_close(ws, code, message = new ArrayBuffer(0)) {
+        ws.poly._destroy();
+        ws.poly.emit("close", code, this.#message_parser(message));
+        // release the polyfill so it can be garbage collected
+        delete ws.poly;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linebridge/engine-neo",
-  "version": "1.1.0",
+  "version": "1.2.2",
   "publishConfig": {
     "access": "public"
   },
@@ -34,6 +34,6 @@
     "tseep": "^1.3.1"
   },
   "scripts": {
-    "postinstall": "node install.mjs"
+    "install": "node install.mjs"
   }
 }