@linebridge/engine-neo 1.0.0

package/lib/engine.js

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview Neo engine - the uWebSockets.js engine adaptor for Linebridge.
+ *
+ * This engine creates a uWS app (plain or SSL), optionally attaches a WebSocket
+ * server via RTEngine, and manages the HTTP request/response lifecycle.
+ *
+ * It is the default and only built-in engine; other engines can be added by
+ * implementing the EngineAdaptor interface and registering them in `engines/index.ts`.
+ */
+import fs from "node:fs";
+import fs_promises from "node:fs/promises";
+import { createRequire } from "node:module";
+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 route_register from "./route_register.js";
+import middleware_register from "./register_middleware.js";
+import listen from "./listen.js";
+import close from "./close.js";
+import on_request from "./on_request.js";
+import request_iterator from "./request_iterator.js";
+let uWebsockets;
+try {
+    // Try loading from the root (when executing from build/out/lib/index.js)
+    uWebsockets = createRequire(import.meta.url)("../uws-wrapper.node");
+}
+catch (e) {
+    try {
+        // Try loading from build/Release (when executing from src/index.ts in monorepo)
+        uWebsockets = createRequire(import.meta.url)("../build/Release/uws-wrapper.node");
+    }
+    catch (e2) {
+        // Try loading from build/out (when executing from src/index.ts in monorepo if already packaged)
+        uWebsockets = createRequire(import.meta.url)("../build/out/uws-wrapper.node");
+    }
+}
+/**
+ * The Neo engine is the uWebSockets.js adaptor.
+ *
+ * It handles app construction (plain or SSL), WebSocket setup, route registration,
+ * middleware registration, and the request/response pipeline.
+ */
+export class NeoEngine extends EngineAdaptor {
+    /** Number of in-flight HTTP requests. Tracked so the server knows when it is idle. */
+    pending_requests_count = 0;
+    /** Callback fired when the pending request count reaches zero. */
+    pending_requests_zero_handler = null;
+    /** Base headers to include in all responses. */
+    base_headers = {};
+    /** Set of registered {method, path} objects to avoid duplicate registrations. */
+    registers = new Set();
+    /** Global middleware stack applied to every request before route handlers run. */
+    middlewares = [];
+    /** Listening port, defaults to 3000. */
+    port = 3000;
+    /** Listening host, defaults to "0.0.0.0". */
+    host = "0.0.0.0";
+    /** Engine-level options merged with uWS constructor options. */
+    options = {
+        is_ssl: false,
+        auto_close: true,
+        trust_proxy: false,
+        max_body_buffer: 16 * 1024,
+        max_body_length: 9 * 1024 * 1024,
+    };
+    /**
+     * Initializes the engine: creates the uWS app, configures SSL if needed,
+     * attaches WebSocket support, and registers the default catch-all route.
+     */
+    initialize = async () => {
+        // raise uWS limits to handle apps with many headers (e.g. large cookie payloads)
+        //@ts-ignore
+        process.env["UWS_HTTP_MAX_HEADERS_COUNT"] = 512;
+        //@ts-ignore
+        process.env["UWS_HTTP_MAX_HEADERS_SIZE"] = 650000;
+        // unless explicitly kept, hide the internal uWS Server header
+        if (!process.env["KEEP_UWS_HEADER"]) {
+            try {
+                //@ts-ignore
+                uWebsockets._cfg("999999990007");
+            }
+            catch (_e) {
+                // womp womp
+            }
+        }
+        // set port and host from server params, falling back to defaults
+        this.port = this.server.params.listenPort ?? this.port;
+        this.host = this.server.params.listenIp ?? this.host;
+        // validate and enable SSL when key/cert paths are provided
+        if (this.server.ssl) {
+            if (this.server.ssl.key && this.server.ssl.cert) {
+                try {
+                    await Promise.all([
+                        fs_promises.access(this.server.ssl.key),
+                        fs_promises.access(this.server.ssl.cert),
+                    ]);
+                    this.options.is_ssl = true;
+                    this.options.key_file_name = this.server.ssl.key;
+                    this.options.cert_file_name = this.server.ssl.cert;
+                }
+                catch (err) {
+                    throw new Error("Cannot access SSL key or cert: " + err);
+                }
+            }
+        }
+        // initialize the uWebsockets app depending on SSL mode
+        if (this.options.is_ssl) {
+            this.uws = uWebsockets.SSLApp({
+                ...this.options,
+                key_file_name: this.server.ssl.key,
+                cert_file_name: this.server.ssl.cert,
+            });
+        }
+        else {
+            this.uws = uWebsockets.App(this.options);
+        }
+        // if socket mode is enabled, use a unix socket path
+        if (toBoolean(process.env.LB_SOCKET_MODE)) {
+            this.socket_path = `/tmp/lb_node_${this.server.params.refName}.sock`;
+            // if the socket path already exists, remove it
+            if (fs.existsSync(this.socket_path)) {
+                fs.unlinkSync(this.socket_path);
+            }
+        }
+        // if websockets are enabled, set up the websocket server
+        if (typeof this.server.params.websockets === "object" &&
+            this.server.params.websockets.enabled === true) {
+            const websocket_attached_path = this.server.params.websockets.path ??
+                `/${this.server.params.refName}`;
+            this.ws = new RTEngine(this.server, {
+                path: websocket_attached_path,
+                onUpgrade: this.server.handleWsUpgrade,
+                onConnection: this.server.handleWsConnection,
+                onDisconnect: this.server.handleWsDisconnect,
+            });
+            // attach the engine adaptor to RTEngine
+            this.ws.engine = this;
+            // attach to uWebsockets with adaptors that bridge uWS events into RTEngine
+            this.uws.ws(websocket_attached_path, {
+                // uWS passes (res, req, context) but RTEngine expects (req, res)
+                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);
+                    ws.poly = poly;
+                    //@ts-ignore polyfill context is Object vs RtEngineSocket's typed shape, but runtime is correct
+                    this.ws.handleConnection(poly);
+                },
+                // forward uWS message events to the polyfill so RTEngine listeners fire
+                message: (ws, message, isBinary) => {
+                    // uWS passes raw ArrayBuffer, but RTEngine expects a string for JSON.parse
+                    const parsed = isBinary
+                        ? message
+                        : Buffer.from(message).toString();
+                    ws.poly?.emit("message", parsed, isBinary);
+                },
+                // forward uWS close events to the polyfill so RTEngine listeners fire
+                close: (ws, code, message) => {
+                    ws.poly?._destroy();
+                    ws.poly?.emit("close", code, message);
+                    delete ws.poly;
+                },
+            });
+            // @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);
+    };
+    /** Starts the server. Bound to the engine instance. */
+    listen = listen.bind(this);
+    /** Gracefully shuts down the server. Bound to the engine instance. */
+    close = close.bind(this);
+    /** Registers a route (HTTP method + path + handler). */
+    register = route_register.bind(this);
+    /** Registers a global middleware that runs before every route handler. */
+    register_middleware = middleware_register.bind(this);
+    /**
+     * 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.
+     */
+    publish(topic, message, is_binary, compress) {
+        return this.uws?.publish(topic, message, is_binary, compress);
+    }
+    /**
+     * Returns the number of subscribers to a topic across all WebSocket connections on this Server instance.
+     */
+    num_of_subscribers(topic) {
+        return this.uws?.numSubscribers(topic);
+    }
+    /** Incoming HTTP request handler. Bound to the engine instance. */
+    on_request = on_request.bind(this);
+    /** Middleware/route iteration loop. Bound to the engine instance. */
+    request_iterator = request_iterator.bind(this);
+    /**
+     * Decrements the pending request counter and fires the zero-handler
+     * when no requests remain in flight.
+     */
+    _resolve_pending_request() {
+        if (this.pending_requests_count < 1)
+            return;
+        this.pending_requests_count--;
+        if (this.pending_requests_count === 0 &&
+            this.pending_requests_zero_handler) {
+            this.pending_requests_zero_handler();
+        }
+    }
+    /**
+     * Default handler for unmatched routes. Responds with a 404 JSON body.
+     */
+    _defaultResponse(req, res) {
+        res.status(404).json({ error: "Not found" });
+    }
+}
+export default NeoEngine;

package/lib/index.d.ts

@@ -0,0 +1,17 @@
+import type { NeoEngine } from "./engine.js";
+import type Request from "./request.js";
+import type Response from "./response.js";
+declare module "linebridge/engines" {
+    interface EnginesRegistry {
+        neo: typeof NeoEngine;
+    }
+}
+declare module "linebridge/types" {
+    interface EnginesRequests<T = any> {
+        neo: Request<T>;
+    }
+    interface EnginesResponses<T = any> {
+        neo: Response<T>;
+    }
+}
+export {};

package/lib/index.js

@@ -0,0 +1 @@
+export {};

package/lib/listen.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Binds the uWS app to a host:port or unix socket and returns a promise
+ * that resolves once the server is listening.
+ *
+ * Optionally registers process-exit handlers so the server auto-closes on termination.
+ */
+import type Engine from "./engine.js";
+/**
+ * Starts the engine's uWS app on the configured host/port or unix socket.
+ *
+ * @returns A promise that resolves when the server is listening, or rejects with an error.
+ */
+export default function (this: Engine): Promise<void>;

package/lib/listen.js

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Binds the uWS app to a host:port or unix socket and returns a promise
+ * that resolves once the server is listening.
+ *
+ * Optionally registers process-exit handlers so the server auto-closes on termination.
+ */
+/** OS signals and events that trigger an automatic server close when auto_close is enabled. */
+const EXIT_EVENTS = ["exit", "SIGINT", "SIGUSR1", "SIGUSR2", "SIGTERM"];
+/**
+ * Starts the engine's uWS app on the configured host/port or unix socket.
+ *
+ * @returns A promise that resolves when the server is listening, or rejects with an error.
+ */
+export default async function () {
+    return new Promise((resolve, reject) => {
+        if (!this.uws) {
+            return reject(new Error("Engine is not initialized"));
+        }
+        /**
+         * Callback invoked by uWS once the server is bound (or fails to bind).
+         */
+        const on_listen_socket = (listen_socket) => {
+            if (listen_socket) {
+                // store the socket handle so we can close it later
+                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()));
+                }
+                resolve();
+            }
+            else {
+                reject("Server.listen(): No Socket Received From uWebsockets.js likely due to an invalid host or busy port.");
+            }
+        };
+        // use a unix socket when socket_path is set, otherwise bind to tcp
+        if (this.socket_path) {
+            this.uws.listen_unix(on_listen_socket, this.socket_path);
+        }
+        else {
+            this.uws.listen(this.host, this.port, on_listen_socket);
+        }
+    });
+}

package/lib/on_request.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview The main HTTP request entry point called by uWS when a request matches a route.
+ *
+ * It creates Request and Response wrappers, runs the middleware + handler pipeline,
+ * and includes a "fast path" optimisation for routes with zero or one middleware.
+ */
+import type { us_socket_context_t, HttpRequest, HttpResponse } from "uWebSockets.js";
+import type { Route } from "linebridge/classes/Route/index";
+import type Engine from "./engine.js";
+/**
+ * Entry point for every incoming HTTP request.
+ *
+ * Wraps the raw uWS request/response objects into framework-level Request/Response
+ * instances, then dispatches through middleware and the route handler.
+ *
+ * @param native_req - Raw uWS HttpRequest.
+ * @param native_res - Raw uWS HttpResponse.
+ * @param route - The matched route object.
+ * @param socket - Upgrade socket context (only set for WebSocket upgrade requests).
+ */
+export default function (this: Engine, native_req: HttpRequest, native_res: HttpResponse, route: Route<any>, socket?: us_socket_context_t | null): any;

package/lib/on_request.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview The main HTTP request entry point called by uWS when a request matches a route.
+ *
+ * It creates Request and Response wrappers, runs the middleware + handler pipeline,
+ * and includes a "fast path" optimisation for routes with zero or one middleware.
+ */
+import Request from "./request.js";
+import Response from "./response.js";
+/** HTTP methods that never carry a request body. */
+const BODYLESS_METHODS = new Set(["GET", "HEAD", "OPTIONS", "TRACE"]);
+/** No-op next() placeholder used when there is no real middleware chain. */
+const EMPTY_NEXT = () => { };
+/**
+ * Entry point for every incoming HTTP request.
+ *
+ * Wraps the raw uWS request/response objects into framework-level Request/Response
+ * instances, then dispatches through middleware and the route handler.
+ *
+ * @param native_req - Raw uWS HttpRequest.
+ * @param native_res - Raw uWS HttpResponse.
+ * @param route - The matched route object.
+ * @param socket - Upgrade socket context (only set for WebSocket upgrade requests).
+ */
+export default function (native_req, native_res, route, socket) {
+    try {
+        const request = Request.create(route, native_req, native_res);
+        const response = Response.create(native_res, route, request, socket);
+        // if a zero-handler is pending (server is draining), reject new requests
+        if (this.pending_requests_zero_handler)
+            return response.close();
+        if (!route.handler) {
+            console.warn(`Route [${route.path}] is registered, but does not have a valid handler.`);
+            this.defaultResponse(request, response);
+            return null;
+        }
+        this.pending_requests_count++;
+        // Start body parsing immediately if needed
+        if (!BODYLESS_METHODS.has(request.method)) {
+            request._body_parser_run(response, this.options.max_body_length);
+        }
+        // fast path: no middleware or at most one global middleware
+        if (this.middlewares.length <= 1 && route.middlewares.length === 0) {
+            return _fastPath.call(this, request, response, route);
+        }
+        // merge global and route-level middlewares
+        const allMiddlewares = route.middlewares.length > 0
+            ? [...this.middlewares, ...route.middlewares]
+            : this.middlewares;
+        return this.request_iterator(request, response, route, allMiddlewares);
+    }
+    catch (exception) {
+        console.error("Internal fatal error:", exception);
+        // try to respond with a 500 even in catastrophic failure
+        native_res.writeStatus("500");
+        native_res.end(JSON.stringify({ fatal: true, error: exception.message }));
+    }
+}
+/**
+ * Optimised path for routes that have zero or one global middleware.
+ * Skips the full iterator overhead.
+ */
+function _fastPath(request, response, route) {
+    const runMiddlewares = () => {
+        if (this.middlewares.length === 1) {
+            const mw = this.middlewares[0];
+            const mwResult = mw.fn(request, response, EMPTY_NEXT, mw.ctx ?? {});
+            // wait for async middleware to finish before calling the handler
+            if (mwResult instanceof Promise) {
+                return mwResult.then(() => {
+                    if (response.completed)
+                        return;
+                    return _executeHandler.call(this, request, response, route);
+                });
+            }
+            if (response.completed)
+                return;
+        }
+        return _executeHandler.call(this, request, response, route);
+    };
+    if (!BODYLESS_METHODS.has(request.method)) {
+        return request.parseBody().then(() => {
+            if (response.completed)
+                return;
+            return runMiddlewares();
+        });
+    }
+    return runMiddlewares();
+}
+/**
+ * Parses the request body (if needed) then invokes the route handler
+ * through the standard Handler.execute path, which uses res.send()
+ * and properly corks writes to uWS.
+ */
+function _executeHandler(request, response, route) {
+    response._cork = true;
+    return route.handler.execute(request, response);
+}

package/lib/register.d.ts

@@ -0,0 +1,17 @@
+import NeoEngine from "./engine.js";
+import type NeoRequest from "./request.js";
+import type NeoResponse from "./response.js";
+export * from "./engine.js";
+declare module "linebridge/engines" {
+    interface EnginesRegistry {
+        neo: typeof NeoEngine;
+    }
+}
+declare module "linebridge/types" {
+    interface EnginesRequests<T> {
+        neo: NeoRequest<T>;
+    }
+    interface EnginesResponses<T> {
+        neo: NeoResponse<T>;
+    }
+}

package/lib/register.js

@@ -0,0 +1,5 @@
+import NeoEngine from "./engine.js";
+import { registerEngine } from "linebridge/engines";
+console.log("NEO Engine register via hook");
+registerEngine("neo", NeoEngine);
+export * from "./engine.js";

package/lib/register_middleware.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Registers a global middleware that runs before every route handler.
+ *
+ * Middlewares can be passed as a plain async function or as a Handler wrapper.
+ * If a plain function is passed, it is automatically wrapped in a Handler.
+ */
+import type Engine from "./engine.js";
+/**
+ * Adds a middleware to the engine's global middleware stack.
+ *
+ * @param middleware - Either a raw `(req, res, next) => void` function
+ *   or a pre-built Handler instance.
+ */
+export default function (this: Engine, middleware: any): void;

package/lib/register_middleware.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Registers a global middleware that runs before every route handler.
+ *
+ * Middlewares can be passed as a plain async function or as a Handler wrapper.
+ * If a plain function is passed, it is automatically wrapped in a Handler.
+ */
+import { Handler, HandlerKind } from "linebridge/classes/Handler/index";
+/**
+ * Adds a middleware to the engine's global middleware stack.
+ *
+ * @param middleware - Either a raw `(req, res, next) => void` function
+ *   or a pre-built Handler instance.
+ */
+export default function (middleware) {
+    let middlewareCtx;
+    if (middleware &&
+        typeof middleware === "object" &&
+        !(middleware instanceof Handler) &&
+        typeof middleware.fn === "function") {
+        if (Array.isArray(middleware.useContexts) &&
+            middleware.useContexts.length > 0) {
+            middlewareCtx = {};
+            const allContexts = Object.assign({}, this.server.contexts, this.server.base_contexts);
+            for (const ctxKey of middleware.useContexts) {
+                if (ctxKey in allContexts) {
+                    middlewareCtx[ctxKey] = allContexts[ctxKey];
+                }
+            }
+        }
+        middleware = middleware.fn;
+    }
+    // auto-wrap plain functions so they work with the Handler lifecycle
+    if (!(middleware instanceof Handler)) {
+        middleware = new Handler({
+            kind: HandlerKind.middleware,
+            engine: this,
+            fn: middleware,
+            ctx: middlewareCtx,
+        });
+    }
+    this.middlewares.push(middleware);
+}

package/lib/request.d.ts

@@ -0,0 +1,168 @@
+/**
+ * @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 type { HttpRequest, HttpResponse } from "uWebSockets.js";
+import type { Request as BaseHttpRequest } from "linebridge/classes/Handler/http";
+import type { EngineAdaptor } from "linebridge/classes/EngineAdaptor/index";
+import type { Route } from "linebridge/classes/Route/index";
+import type { Server } from "linebridge/server";
+import type Response from "./response.js";
+/**
+ * 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<TServer = Server<any>> implements BaseHttpRequest {
+    constructor();
+    /** Per-request local storage for middleware communication. */
+    _locals: any;
+    /** Whether the response stream is paused. */
+    _paused: boolean;
+    /** HTTP method string, normalized (e.g. "GET", "DELETE"). */
+    _method: string;
+    /** Full URL including query string. */
+    _url: string;
+    /** URL path portion without query string. */
+    _path: string;
+    /** Raw query string (without leading `?`). */
+    _query_str: string;
+    /** Resolved remote IP address. */
+    _remote_ip: string;
+    /** Resolved proxy IP address. */
+    _remote_proxy_ip: string;
+    /** Parsed cookies (lazy). */
+    _cookies: any;
+    /** URL path parameters extracted by uWS (e.g. `/user/:id`). */
+    _path_parameters: any;
+    /** Parsed query string parameters (lazy). */
+    _query_parameters: any;
+    /** The raw uWS HttpRequest object. */
+    _raw_request: HttpRequest;
+    /** The raw uWS HttpResponse object (needed for `onData` and `getRemoteAddress`). */
+    _raw_response: HttpResponse;
+    /** Request headers extracted synchronously. */
+    _headers: Record<string, string>;
+    /** Whether all body chunks have been received. */
+    _received: boolean;
+    /** Total bytes received so far for the body. */
+    _body_received_bytes: number;
+    /** Has the onData listener been registered for body parsing? */
+    _body_parser_on_data_registered: boolean;
+    /** Parsed body (populated lazily by `.json()`, `.text()`, etc.). */
+    _body: any;
+    /** The type that `.parseBody()` resolved to. */
+    _body_type: string | null;
+    /** Raw body buffer, populated after body is fully received. */
+    _body_raw: Buffer | null;
+    /** Promise that resolves once all body data is received and parsed. */
+    _body_promise: Promise<any> | null;
+    /** Callback invoked when body data is fully received. */
+    _onDone: (() => void) | null;
+    /** Context object for sharing data between middlewares and the handler. */
+    ctx: Record<string, any>;
+    /** The matched route for this request. */
+    route: Route<TServer> | null;
+    /**
+     * Creates a Request instance from raw uWS objects.
+     */
+    static create<TServer extends Server<any>>(route: Route<TServer>, raw_request: HttpRequest, raw_response: HttpResponse): Request<TServer>;
+    /**
+     * The engine that owns this request.
+     */
+    get engine(): EngineAdaptor | null;
+    /**
+     * The raw uWS HttpRequest.
+     */
+    get raw(): HttpRequest;
+    /**
+     * Lazily-parsed headers as a plain object.
+     * Header names are lowercased by uWS.
+     */
+    get headers(): Record<string, string>;
+    /**
+     * Pauses the underlying response stream.
+     * Used during body parsing to apply backpressure.
+     */
+    pause(): this;
+    /**
+     * Resumes the underlying response stream.
+     */
+    resume(): this;
+    /**
+     * Signs a string with a secret using the same algorithm as `cookie-signature`.
+     */
+    sign(string: string, secret: string): string;
+    /**
+     * Unsigns a signed value. Returns the original string or `undefined` on failure.
+     */
+    unsign(signed_value: string, secret: string): string | 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: Response<TServer>, limit_bytes: number): boolean;
+    /**
+     * Returns the entire request body as a Buffer.
+     */
+    buffer(): Promise<Buffer>;
+    /**
+     * Returns the entire request body as a string.
+     */
+    text(): Promise<string>;
+    /**
+     * Parses the request body as JSON.
+     */
+    json(default_value?: {}): Promise<any>;
+    /**
+     * Parses the request body as URL-encoded form data.
+     */
+    urlencoded(): Promise<any>;
+    get locals(): any;
+    /** Whether the request stream is paused. */
+    get paused(): boolean;
+    /** Normalized HTTP method (uppercase). */
+    get method(): string;
+    /** Full URL (path + query string). */
+    get url(): string;
+    /** URL path (no query string). */
+    get path(): string;
+    /** Parsed query string parameters. */
+    get query(): any;
+    /** URL path parameters extracted (e.g. `/user/:id` → `{ id: "42" }`). */
+    get params(): any;
+    /**
+     * Parsed cookies from the `Cookie` header.
+     * Parsed lazily on first access.
+     */
+    get cookies(): any;
+    /** The parsed body. Populated after calling `.parseBody()`, `.json()`, `.text()`, etc. */
+    get body(): any;
+    /**
+     * Automatically parses the request body based on `Content-Type`.
+     */
+    parseBody(): Promise<any>;
+    /**
+     * Decodes the raw body buffer based on Content-Type.
+     */
+    _finalize_body(): any;
+    /**
+     * 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(): string;
+    /**
+     * The proxy IP as reported by uWS.
+     */
+    get proxy_ip(): string;
+}