@linebridge/engine-neo 1.0.0

package/lib/request.js

@@ -0,0 +1,400 @@
+/**
+ * @fileoverview Full HTTP request wrapper for the Neo engine.
+ *
+ * Wraps a raw uWS HttpRequest and provides high-level accessors for headers,
+ * body parsing (JSON, text, urlencoded, buffer), cookies, IP resolution,
+ * and path/query parameters.
+ */
+import * as cookie from "cookie";
+import querystring from "fast-querystring";
+import signature from "cookie-signature";
+/**
+ * HTTP Request class wrapping a uWS HttpRequest.
+ *
+ * Provides parsed access to the request path, query string, headers, cookies,
+ * and body. Body parsing is lazy and supports JSON, text, urlencoded, and buffer.
+ *
+ * @typeParam TServer - The server type this request belongs to.
+ */
+export default class Request {
+    constructor() { }
+    /** Per-request local storage for middleware communication. */
+    _locals;
+    /** Whether the response stream is paused. */
+    _paused;
+    /** HTTP method string, normalized (e.g. "GET", "DELETE"). */
+    _method;
+    /** Full URL including query string. */
+    _url;
+    /** URL path portion without query string. */
+    _path;
+    /** Raw query string (without leading `?`). */
+    _query_str;
+    /** Resolved remote IP address. */
+    _remote_ip;
+    /** Resolved proxy IP address. */
+    _remote_proxy_ip;
+    /** Parsed cookies (lazy). */
+    _cookies;
+    /** URL path parameters extracted by uWS (e.g. `/user/:id`). */
+    _path_parameters;
+    /** Parsed query string parameters (lazy). */
+    _query_parameters;
+    /** The raw uWS HttpRequest object. */
+    _raw_request;
+    /** The raw uWS HttpResponse object (needed for `onData` and `getRemoteAddress`). */
+    _raw_response;
+    /** Request headers extracted synchronously. */
+    _headers;
+    /** Whether all body chunks have been received. */
+    _received;
+    /** Total bytes received so far for the body. */
+    _body_received_bytes;
+    /** Has the onData listener been registered for body parsing? */
+    _body_parser_on_data_registered;
+    /** Parsed body (populated lazily by `.json()`, `.text()`, etc.). */
+    _body;
+    /** The type that `.parseBody()` resolved to. */
+    _body_type;
+    /** Raw body buffer, populated after body is fully received. */
+    _body_raw;
+    /** Promise that resolves once all body data is received and parsed. */
+    _body_promise;
+    /** Callback invoked when body data is fully received. */
+    _onDone;
+    /** Context object for sharing data between middlewares and the handler. */
+    ctx;
+    /** The matched route for this request. */
+    route;
+    /**
+     * Creates a Request instance from raw uWS objects.
+     */
+    static create(route, raw_request, raw_response) {
+        const req = new Request();
+        req._raw_request = raw_request;
+        req._raw_response = raw_response;
+        req.route = route;
+        req.ctx = route.ctx || Object.create(null);
+        req._query_str = raw_request.getQuery();
+        req._path = raw_request.getUrl();
+        req._received = true;
+        // normalize method - uWS uses "del" internally, we want "DELETE"
+        const rawMethod = raw_request.getMethod();
+        req._method = rawMethod === "del" ? "DELETE" : rawMethod.toUpperCase();
+        // Capture ALL headers synchronously. uWS HttpRequest is invalid after the first await.
+        req._headers = {};
+        raw_request.forEach((key, value) => {
+            req._headers[key] = value;
+        });
+        // extract path parameters (e.g. `/user/:id` → `{ id: "42" }`)
+        const keys = route.pathParametersKey;
+        if (keys.length > 0) {
+            const params = Object.create(null);
+            for (let i = 0; i < keys.length; i++) {
+                params[keys[i][0]] = raw_request.getParameter(keys[i][1]);
+            }
+            req._path_parameters = params;
+        }
+        return req;
+    }
+    /**
+     * The engine that owns this request.
+     */
+    get engine() {
+        return this.route?.engine || null;
+    }
+    /**
+     * The raw uWS HttpRequest.
+     */
+    get raw() {
+        return this._raw_request;
+    }
+    /**
+     * Lazily-parsed headers as a plain object.
+     * Header names are lowercased by uWS.
+     */
+    get headers() {
+        return this._headers;
+    }
+    /**
+     * Pauses the underlying response stream.
+     * Used during body parsing to apply backpressure.
+     */
+    pause() {
+        if (!this._paused) {
+            this._paused = true;
+            this._raw_response.pause();
+        }
+        return this;
+    }
+    /**
+     * Resumes the underlying response stream.
+     */
+    resume() {
+        if (this._paused) {
+            this._paused = false;
+            this._raw_response.resume();
+        }
+        return this;
+    }
+    /**
+     * Signs a string with a secret using the same algorithm as `cookie-signature`.
+     */
+    sign(string, secret) {
+        return signature.sign(string, secret);
+    }
+    /**
+     * Unsigns a signed value. Returns the original string or `undefined` on failure.
+     */
+    unsign(signed_value, secret) {
+        const unsigned_value = signature.unsign(signed_value, secret);
+        return unsigned_value !== false ? unsigned_value : undefined;
+    }
+    /**
+     * Starts the body parser by registering a uWS `onData` callback.
+     *
+     * This is called before any body-consuming method (`.json()`, `.text()`, etc.)
+     * to begin buffering incoming body chunks.
+     */
+    _body_parser_run(response, limit_bytes) {
+        if (this._body_parser_on_data_registered)
+            return true;
+        this._received = false;
+        this._body_received_bytes = 0;
+        this._body_parser_on_data_registered = true;
+        const chunks = [];
+        const max_buffer = this.engine?.options.max_body_buffer ?? 1024 * 1024;
+        this._raw_response.onData((chunk, is_last) => {
+            if (response.completed)
+                return;
+            if (chunk.byteLength > 0) {
+                this._body_received_bytes += chunk.byteLength;
+                if (this._body_received_bytes > limit_bytes) {
+                    response.status(413).send("Payload Too Large");
+                    this._received = true;
+                    return;
+                }
+                const chunkCopy = Buffer.allocUnsafe(chunk.byteLength);
+                chunkCopy.set(new Uint8Array(chunk));
+                chunks.push(chunkCopy);
+                if (this._body_received_bytes > max_buffer &&
+                    !this._body_promise) {
+                    this.pause();
+                }
+            }
+            if (is_last) {
+                this._received = true;
+                if (chunks.length === 0) {
+                    this._body_raw = Buffer.allocUnsafe(0);
+                }
+                else if (chunks.length === 1) {
+                    this._body_raw = chunks[0];
+                }
+                else {
+                    this._body_raw = Buffer.concat(chunks, this._body_received_bytes);
+                }
+                if (this._onDone) {
+                    this._onDone();
+                    this._onDone = null;
+                }
+            }
+        });
+        return true;
+    }
+    /**
+     * Returns the entire request body as a Buffer.
+     */
+    async buffer() {
+        if (this._body_type === "buffer") {
+            return this._body;
+        }
+        await this.parseBody();
+        return this._body_raw || Buffer.allocUnsafe(0);
+    }
+    /**
+     * Returns the entire request body as a string.
+     */
+    async text() {
+        if (this._body_type === "text") {
+            return this._body;
+        }
+        await this.parseBody();
+        return typeof this._body === "string" ? this._body : "";
+    }
+    /**
+     * Parses the request body as JSON.
+     */
+    async json(default_value = {}) {
+        if (this._body_type === "json") {
+            return this._body;
+        }
+        try {
+            await this.parseBody();
+        }
+        catch (error) {
+            if (default_value !== undefined) {
+                return default_value;
+            }
+            throw error;
+        }
+        return this._body;
+    }
+    /**
+     * Parses the request body as URL-encoded form data.
+     */
+    async urlencoded() {
+        if (this._body_type === "urlencoded") {
+            return this._body;
+        }
+        await this.parseBody();
+        return this._body;
+    }
+    get locals() {
+        if (!this._locals) {
+            this._locals = Object.create(null);
+        }
+        return this._locals;
+    }
+    /** Whether the request stream is paused. */
+    get paused() {
+        return this._paused;
+    }
+    /** Normalized HTTP method (uppercase). */
+    get method() {
+        return this._method;
+    }
+    /** Full URL (path + query string). */
+    get url() {
+        if (this._url) {
+            return this._url;
+        }
+        this._url = this._path + (this._query_str ? "?" + this._query_str : "");
+        return this._url;
+    }
+    /** URL path (no query string). */
+    get path() {
+        return this._path;
+    }
+    /** Parsed query string parameters. */
+    get query() {
+        if (this._query_parameters) {
+            return this._query_parameters;
+        }
+        this._query_parameters = querystring.parse(this._query_str);
+        return this._query_parameters;
+    }
+    /** URL path parameters extracted (e.g. `/user/:id` → `{ id: "42" }`). */
+    get params() {
+        return this._path_parameters;
+    }
+    /**
+     * Parsed cookies from the `Cookie` header.
+     * Parsed lazily on first access.
+     */
+    get cookies() {
+        if (this._cookies) {
+            return this._cookies;
+        }
+        const header = this.headers["cookie"];
+        this._cookies = header
+            ? cookie.parseCookie(header)
+            : Object.create(null);
+        return this._cookies;
+    }
+    /** The parsed body. Populated after calling `.parseBody()`, `.json()`, `.text()`, etc. */
+    get body() {
+        return this._body;
+    }
+    /**
+     * Automatically parses the request body based on `Content-Type`.
+     */
+    async parseBody() {
+        if (this._body_promise)
+            return this._body_promise;
+        this._body_promise = new Promise((resolve) => {
+            if (this._received) {
+                return resolve(this._finalize_body());
+            }
+            this._onDone = () => {
+                resolve(this._finalize_body());
+            };
+        });
+        return this._body_promise;
+    }
+    /**
+     * Decodes the raw body buffer based on Content-Type.
+     */
+    _finalize_body() {
+        if (this._body !== undefined)
+            return this._body;
+        const raw = this._body_raw || Buffer.allocUnsafe(0);
+        const contentType = this._headers["content-type"] || "";
+        if (contentType.includes("application/json")) {
+            try {
+                this._body = JSON.parse(raw.toString());
+                this._body_type = "json";
+            }
+            catch {
+                this._body = {};
+                this._body_type = "json";
+            }
+        }
+        else if (contentType.includes("application/x-www-form-urlencoded")) {
+            this._body = querystring.parse(raw.toString());
+            this._body_type = "urlencoded";
+        }
+        else if (contentType.includes("text/") ||
+            contentType.includes("application/xml") ||
+            contentType.includes("application/javascript") ||
+            !contentType) {
+            this._body = raw.toString();
+            this._body_type = "text";
+        }
+        else {
+            this._body = raw;
+            this._body_type = "buffer";
+        }
+        return this._body;
+    }
+    /**
+     * Resolved remote IP address.
+     *
+     * When `trust_proxy` is enabled, it reads from `x-forwarded-for`.
+     * Otherwise, it uses the direct remote address from uWS.
+     */
+    get ip() {
+        if (this._remote_ip) {
+            return this._remote_ip;
+        }
+        const x_forwarded_for = this.locals._xff;
+        const trust_proxy = this.engine?.options.trust_proxy;
+        if (trust_proxy && x_forwarded_for) {
+            // take the first IP in the x-forwarded-for chain (the original client)
+            const commaIdx = x_forwarded_for.indexOf(",");
+            this._remote_ip =
+                commaIdx === -1
+                    ? x_forwarded_for.trim()
+                    : x_forwarded_for.slice(0, commaIdx).trim();
+        }
+        else {
+            try {
+                this._remote_ip = Buffer.from(this._raw_response.getRemoteAddressAsText()).toString();
+            }
+            catch {
+                // Fallback for when the socket is already closed
+                this._remote_ip = "";
+            }
+        }
+        return this._remote_ip;
+    }
+    /**
+     * The proxy IP as reported by uWS.
+     */
+    get proxy_ip() {
+        if (this._remote_proxy_ip) {
+            return this._remote_proxy_ip;
+        }
+        this._remote_proxy_ip = Buffer.from(this._raw_response.getProxiedRemoteAddressAsText()).toString();
+        return this._remote_proxy_ip;
+    }
+}

package/lib/request_iterator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview The middleware iteration loop.
+ *
+ * Walks through the middleware array one element at a time, calling each
+ * middleware's `execute` method with a `next` callback that recurses into the
+ * next middleware or the final route handler.
+ */
+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";
+/**
+ * Recursively iterates the middleware chain, then calls the route handler.
+ *
+ * On the first call (cursor === 0) it parses the request body (if needed).
+ * Each middleware receives `(req, res, next)`. If a middleware does not call `next()`,
+ * the iterator auto-advances to avoid hanging (unless the response was already sent).
+ *
+ * @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>;

package/lib/request_iterator.js

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview The middleware iteration loop.
+ *
+ * Walks through the middleware array one element at a time, calling each
+ * middleware's `execute` method with a `next` callback that recurses into the
+ * next middleware or the final route handler.
+ */
+/** HTTP methods that never carry a request body. */
+const BODYLESS_METHODS = new Set(["GET", "HEAD", "OPTIONS", "TRACE"]);
+/**
+ * Recursively iterates the middleware chain, then calls the route handler.
+ *
+ * On the first call (cursor === 0) it parses the request body (if needed).
+ * Each middleware receives `(req, res, next)`. If a middleware does not call `next()`,
+ * the iterator auto-advances to avoid hanging (unless the response was already sent).
+ *
+ * @param cursor - Zero-based index into the middleware array. Increments on each recursion.
+ */
+export default async function (request, response, route, allMiddlewares, cursor = 0) {
+    if (response.completed)
+        return;
+    const middleware = allMiddlewares[cursor];
+    try {
+        // on the first middleware, parse the request body before passing control
+        if (cursor == 0) {
+            response._cork = true;
+            if (!BODYLESS_METHODS.has(request.method)) {
+                await request.parseBody();
+                if (response.completed)
+                    return;
+            }
+        }
+        if (middleware) {
+            // track the cursor position to detect double-next() calls
+            response._track_middleware_cursor(cursor);
+            let nextCalled = false;
+            /**
+             * Advances to the next middleware or the route handler.
+             */
+            const next = async () => {
+                nextCalled = true;
+                await this.request_iterator(request, response, route, allMiddlewares, cursor + 1);
+            };
+            await middleware.execute(request, response, next);
+            // if middleware didn't call next() and didn't send a response, auto-advance
+            if (!nextCalled && !response.completed) {
+                await next();
+            }
+        }
+        else {
+            // no more middlewares - execute the route handler
+            await route.handler.execute(request, response);
+        }
+    }
+    catch (error) {
+        console.error("Unhandled error:", error);
+        if (!response.completed) {
+            response.status(500).json({ error: error.message });
+        }
+    }
+}