@linebridge/engine-neo 1.0.0

package/lib/response.d.ts

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview Full HTTP response wrapper for the Neo engine.
+ *
+ * Wraps a uWS HttpResponse and provides Express-style methods for status codes,
+ * headers, cookies (with signed cookie support), streaming, file serving,
+ * Server-Sent Events, redirects, and JSON/HTML shortcuts.
+ */
+import SSEventStream from "./SSEventStream.js";
+import type { HttpResponse } from "uWebSockets.js";
+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 as BaseHttpResponse } from "linebridge/classes/Handler/http";
+import type Request from "./request.js";
+type EventHandler = (...args: any[]) => void;
+/**
+ * HTTP Response class wrapping a uWS HttpResponse.
+ *
+ * Provides methods for status codes, headers, cookies, streaming, file serving,
+ * event listeners (abort, close, finish), and SSE.
+ *
+ * @typeParam TServer - The server type this response belongs to.
+ */
+export default class Response<TServer = Server<any>> implements BaseHttpResponse {
+    constructor();
+    /** Active SSE stream, if the client requested it. */
+    _sse: SSEventStream | null;
+    /** Per-response local storage for middleware communication. */
+    _locals: any;
+    /** The matched route. */
+    route: Route<TServer> | null;
+    /** Whether the response is in streaming mode. */
+    _streaming: boolean;
+    /** Tracks the furthest middleware index executed to prevent double-next(). */
+    _middleware_cursor: number;
+    /** The paired Request instance. */
+    _wrapped_request: Request;
+    /** The uWS upgrade socket (WebSocket upgrade requests only). */
+    _upgrade_socket: any;
+    /** The raw uWS HttpResponse object. */
+    _raw_response: HttpResponse | null;
+    /** HTTP status code (defaults to 200). */
+    _status_code: number;
+    /** Custom status message (overrides the default from STATUS_CODES). */
+    _status_message: string | null;
+    /** Response headers (key → value or key → string[]). */
+    _headers: Record<string, string | string[]>;
+    /** Set-Cookie headers (name → serialized cookie string). */
+    _cookies: Record<string, string> | null;
+    /** Whether the response has been sent. */
+    completed: boolean;
+    /** Whether headers have been written to the wire. */
+    initiated: boolean;
+    /** If true, the response body is wrapped in uWS `cork()` for batching. */
+    _cork: boolean;
+    /** Has `cork()` already been applied? Prevents double-corking. */
+    _corked: boolean;
+    /** The drain handler registered for backpressure-aware streaming. */
+    _drain_handler: ((offset: number) => boolean) | null;
+    /** Event listeners (abort, close, finish). */
+    _events: Record<string, EventHandler[]> | null;
+    /**
+     * The engine that owns this response.
+     */
+    get engine(): EngineAdaptor | null;
+    /**
+     * Creates a Response instance and registers the uWS `onAborted` callback.
+     *
+     * The `onAborted` handler marks the response as completed, cleans up the
+     * pending request counter, stops body parsing on the paired request, and
+     * fires abort/close event listeners.
+     */
+    static create<TServer extends Server<any>>(raw_response: HttpResponse, route: Route<TServer>, request: any, socket: any): Response<TServer>;
+    /**
+     * Registers an event listener on the response.
+     * Supported events: `"abort"`, `"close"`, `"finish"`.
+     */
+    on(event: string, handler: EventHandler): this;
+    /**
+     * Registers an event listener that fires only once.
+     */
+    once(event: string, handler: EventHandler): this;
+    /**
+     * Removes an event listener.
+     */
+    off(event: string, handler: EventHandler): this;
+    listenerCount(event: string): number;
+    /**
+     * Tracks the current middleware cursor position.
+     *
+     * Throws if a middleware tries to advance backwards (i.e. double-next detection).
+     *
+     * @returns The new cursor position.
+     */
+    _track_middleware_cursor(position: number): number;
+    /**
+     * Wraps a handler in uWS `cork()` for batched writes.
+     * All writes inside the handler are sent in a single TCP segment.
+     */
+    atomic(handler: Function): this;
+    /**
+     * Sets the HTTP status code. Optionally sets a custom status message.
+     */
+    status(code: number, message?: string): this;
+    /**
+     * Sets the `Content-Type` header from a file extension or MIME string.
+     * Prefix the value with a dot to indicate a file extension (e.g. `".html"`).
+     */
+    type(mime_type: string): this;
+    /**
+     * Sets a response header. If the header already exists and `overwrite` is false,
+     * the values are accumulated as an array.
+     */
+    header(name: string, value: string | string[], overwrite?: boolean): this;
+    /**
+     * Sets a `Set-Cookie` header.
+     *
+     * @param name - Cookie name.
+     * @param value - Cookie value. Pass `null` to delete the cookie.
+     * @param expiry - Expiry time in milliseconds from now.
+     * @param options - Cookie options (secure, sameSite, path, etc.).
+     * @param sign_cookie - If true and `options.secret` is set, signs the cookie value.
+     */
+    cookie(name: string, value: string | null, expiry?: number | null, options?: any, sign_cookie?: boolean): this;
+    /**
+     * Upgrades the HTTP connection to a WebSocket.
+     *
+     * @param context - User data to attach to the WebSocket context.
+     */
+    upgrade(context?: any): this | undefined;
+    /**
+     * Writes the status line and all accumulated headers to the uWS response.
+     *
+     * Returns `false` if headers were already initiated (idempotent).
+     */
+    _initiate_response(): boolean;
+    /**
+     * Registers a drain handler for streaming responses.
+     *
+     * @param handler - Called when uWS signals the socket is writable.
+     *   Must return `true` if the chunk was successfully written.
+     */
+    drain(handler: (offset: number) => boolean): void;
+    /**
+     * Sends the response body and marks the response as completed.
+     *
+     * Supports corked (batched) and uncorked paths, streaming mode, and
+     * `endWithoutBody` when a custom `content-length` header is set.
+     *
+     * Fires `finish` and `close` event listeners.
+     */
+    send(body?: any, close_connection?: boolean): this;
+    _uws_write_chunk(chunk: any, total_size?: number): [boolean, boolean];
+    /**
+     * Writes a chunk to the response body.
+     * Initiates headers if not yet sent. Returns false under backpressure.
+     */
+    write(chunk: string): boolean;
+    /**
+     * Streams a single chunk with backpressure support.
+     * If the chunk doesn't fit in the uWS send buffer, it registers a drain handler.
+     */
+    _stream_chunk(chunk: any, total_size?: number): Promise<void>;
+    /**
+     * Streams a Readable to the client chunk by chunk.
+     *
+     * @param readable - A Node.js Readable stream.
+     * @param total_size - Total size hint for uWS `tryEnd`.
+     */
+    stream(readable: any, total_size?: number): Promise<void>;
+    /**
+     * Immediately closes the response (hard abort).
+     */
+    close(): void;
+    /**
+     * Sends a 302 redirect response.
+     */
+    redirect(url: string): boolean;
+    /**
+     * Fast-path send used by the `_invokeHandler`.
+     * Skips cork/uncork logic and writes directly.
+     */
+    _sendFast(body: any): void;
+    /**
+     * Sends a JSON response. Sets `Content-Type: application/json` and
+     * serializes the body with `JSON.stringify`.
+     */
+    json(body: any): this;
+    /**
+     * Sends an HTML response. Sets `Content-Type: text/html`.
+     */
+    html(body: any): this;
+    /**
+     * Per-response local storage for middleware communication.
+     */
+    get locals(): Record<string, any>;
+    /**
+     * The raw uWS HttpResponse.
+     */
+    get raw(): HttpResponse | null;
+    /**
+     * Whether the response has been aborted by the client.
+     */
+    get aborted(): boolean;
+    /**
+     * The uWS upgrade socket handle (WebSocket upgrade requests only).
+     */
+    get upgrade_socket(): any;
+    /**
+     * Accessor for Server-Sent Events.
+     *
+     * Only available on GET requests. Creates a lazy SSEventStream on first access.
+     */
+    get sse(): SSEventStream | undefined;
+    /**
+     * The current uWS write offset. Returns `-1` if the response is completed.
+     */
+    get write_offset(): number;
+    /**
+     * The HTTP status code.
+     */
+    get statusCode(): number;
+    set statusCode(value: number);
+    /**
+     * The HTTP status message.
+     */
+    get statusMessage(): string | null;
+    set statusMessage(value: string | null);
+    /**
+     * Whether response headers have been sent.
+     */
+    get headersSent(): boolean;
+    /**
+     * Appends values to a header (alias for `header()`).
+     */
+    append(name: string, values: any): this;
+    /**
+     * Sets a header value (alias for `header()` with overwrite behaviour).
+     */
+    setHeader(name: string, values: any): this;
+    /**
+     * Writes multiple headers at once from an object.
+     */
+    writeHeaders(headers: any): void;
+    /**
+     * Alias for `writeHeaders()`.
+     */
+    setHeaders(headers: any): void;
+    /**
+     * Writes multiple values for a single header.
+     */
+    writeHeaderValues(name: string, values: any): void;
+    /**
+     * Returns the value(s) of a header.
+     */
+    getHeader(name: string): string | string[];
+    /**
+     * Removes a header.
+     */
+    removeHeader(name: string): void;
+    /**
+     * Sets a cookie (shorthand for `cookie()`).
+     */
+    setCookie(name: string, value: any, options: any): this;
+    /**
+     * Checks if a cookie has been queued.
+     */
+    hasCookie(name: string): boolean;
+    /**
+     * Removes a cookie by setting it to null.
+     */
+    removeCookie(name: string): this;
+    /**
+     * Alias for `removeCookie()`.
+     */
+    clearCookie(name: string): this;
+    /**
+     * Alias for `send()`.
+     */
+    end(data?: any): this;
+    /**
+     * Returns the header value(s) for a given name.
+     */
+    get(name: string): string | undefined;
+    /**
+     * Sets the `Link` header from an object mapping rel → URL.
+     */
+    links(links: any): void;
+    /**
+     * Sets the `Location` header, used for redirects.
+     */
+    location(path: string): this;
+    /**
+     * Sends a status code response.
+     */
+    sendStatus(status_code: number): this;
+    /**
+     * Sets headers using either `(key, value)` or `({ key: value })`.
+     */
+    set(field: any, value: any): void;
+    /**
+     * Sets the `Vary` header.
+     */
+    vary(name: string): this;
+}
+export {};