uWebSockets.js/docs/index.d.ts

/* Under construction, lots of things to add */

/** Native type representing a raw uSockets struct us_listen_socket. */
export interface us_listen_socket {

}

/** Recognized string types, things C++ can read and understand as strings */
export type RecognizedString = string | ArrayBuffer | Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array;

/** A WebSocket connection that is valid from open to close event */
export interface WebSocket {
    /** Sends a message. Make sure to check getBufferedAmount() before sending. Returns true for success, false for built up backpressure that will drain when time is given. */
    send(message: RecognizedString, isBinary?: boolean, compress?: boolean) : boolean;

    /** Returns the bytes buffered in backpressure. */
    getBufferedAmount() : number;

    /** Gracefully closes this WebSocket. Immediately calls close handler. */
    end(code?: number, shortMessage?: RecognizedString) : WebSocket;

    /** Forcefully closes this WebSocket */
    close() : WebSocket;

    /** Sends a ping control message. Returns true on success, see WebSocket.send. This helper function correlates to WebSocket::send(message, uWS::OpCode::PING, ...). */
    ping(message?: RecognizedString) : boolean;

    /** Subscribe to a topic in MQTT syntax */
    subscribe(topic: RecognizedString) : WebSocket;

    /** Unsubscribe from a topic. Returns true on success, if the WebSocket was subscribed. */
    unsubscribe(topic: RecognizedString) : boolean;

    /** Unsubscribe from all topics. */
    unsubscribeAll() : void;

    /** Publish a message to a topic in MQTT syntax */
    publish(topic: RecognizedString, message: RecognizedString, isBinary?: boolean, compress?: boolean) : WebSocket;

    /** See HttpResponse.cork */
    cork(cb: () => void) : void;

    /** Returns the remote IP address */
    getRemoteAddress() : ArrayBuffer;
    
    /** Arbitrary user data may be attached to this object */
    [key: string]: any;
}

/** An HttpResponse is valid until either onAborted callback or any of the .end/.tryEnd calls succeed. You may attach user data to this object. */
export interface HttpResponse {
    /** Writes the HTTP status message such as "200 OK". */
    writeStatus(status: RecognizedString) : HttpResponse;
    /** Writes key and value to HTTP response. */
    writeHeader(key: RecognizedString, value: RecognizedString) : HttpResponse;
    /** Enters or continues chunked encoding mode. Writes part of the response. End with zero length write. */
    write(chunk: RecognizedString) : HttpResponse;
    /** Ends this response by copying the contents of body. */
    end(body?: RecognizedString) : HttpResponse;
    /** Ends this response, or tries to, by streaming appropriately sized chunks of body. Use in conjunction with onWritable. Returns tuple [ok, hasResponded].*/
    tryEnd(fullBodyOrChunk: RecognizedString, totalSize: number) : [boolean, boolean];

    /** Immediately force closes the connection. */
    close() : HttpResponse;

    /** Returns the global byte write offset for this response. Use with onWritable. */
    getWriteOffset() : number;

    /** Registers a handler for writable events. Continue failed write attempts in here.
     * You MUST return true for success, false for failure.
     * Writing nothing is always success, so by default you must return true.
     */
    onWritable(handler: (offset: number) => boolean) : HttpResponse;

    /** Every HttpResponse MUST have an attached abort handler IF you do not respond
     * to it immediately inside of the callback. Returning from an Http request handler
     * without attaching (by calling onAborted) an abort handler is ill-use and will termiante.
     * When this event emits, the response has been aborted and may not be used. */
    onAborted(handler: () => void) : HttpResponse;

    /** Handler for reading data from POST and such requests. You MUST copy the data of chunk if isLast is not true. We Neuter ArrayBuffers on return, making it zero length.*/
    onData(handler: (chunk: ArrayBuffer, isLast: boolean) => void) : HttpResponse;

    /** Returns the remote IP address */
    getRemoteAddress() : ArrayBuffer;

    /** Corking a response is a performance improvement in both CPU and network, as you ready the IO system for writing multiple chunks at once.
     * By default, you're corked in the immediately executing top portion of the route handler. In all other cases, such as when returning from
     * await, or when being called back from an async database request or anything that isn't directly executing in the route handler, you'll want
     * to cork before calling writeStatus, writeHeader or just write. Corking takes a callback in which you execute the writeHeader, writeStatus and
     * such calls, in one atomic IO operation. This is important, not only for TCP but definitely for TLS where each write would otherwise result
     * in one TLS block being sent off, each with one send syscall.
     * 
     * Example usage:
     * 
     * res.cork(() => {
     *   res.writeStatus("200 OK").writeHeader("Some", "Value").write("Hello world!");
     * });
     */
    cork(cb: () => void) : void;

    /** Arbitrary user data may be attached to this object */
    [key: string]: any;
}

/** An HttpRequest is stack allocated and only accessible during the callback invocation. */
export interface HttpRequest {
    /** Returns the lowercased header value or empty string. */
    getHeader(lowerCaseKey: RecognizedString) : string;
    /** Returns the parsed parameter at index. Corresponds to route. */
    getParameter(index: number) : string;
    /** Returns the URL including initial /slash */
    getUrl() : string;
    /** Returns the HTTP method, useful for "any" routes. */
    getMethod() : string;
    /** Returns the part of URL after ? sign or empty string. */
    getQuery() : string;
    /** Loops over all headers. */
    forEach(cb: (key: string, value: string) => void) : void;
    /** Setting yield to true is to say that this route handler did not handle the route, causing the router to continue looking for a matching route handler, or fail. */
    setYield(yield: boolean) : HttpRequest;
}

/** A structure holding settings and handlers for a WebSocket route handler. */
export interface WebSocketBehavior {
    /** Maximum length of received message. */
    maxPayloadLength?: number;
    /** Maximum amount of seconds that may pass without sending or getting a message. */
    idleTimeout?: number;
    /** 0 = no compression, 1 = shared compressor, 2 = dedicated compressor. See C++ project. */
    compression?: CompressOptions;
    /** Maximum length of allowed backpressure per socket when publishing messages. Slow receivers, WebSockets, will be disconnected if needed. */
    maxBackpressure?: number;
    /** Handler for new WebSocket connection. WebSocket is valid from open to close, no errors. */
    open?: (ws: WebSocket, req: HttpRequest) => void;
    /** Handler for a WebSocket message. */
    message?: (ws: WebSocket, message: ArrayBuffer, isBinary: boolean) => void;
    /** Handler for when WebSocket backpressure drains. Check ws.getBufferedAmount(). */
    drain?: (ws: WebSocket) => void;
    /** Handler for close event, no matter if error, timeout or graceful close. You may not use WebSocket after this event. */
    close?: (ws: WebSocket, code: number, message: ArrayBuffer) => void;
    /** Handler for received ping control message. */
    ping?: (ws: WebSocket) => void;
    /** Handler for received pong control message. */
    pong?: (ws: WebSocket) => void;
}

/** Options used when constructing an app. */
export interface AppOptions {
    key_file_name?: RecognizedString;
    cert_file_name?: RecognizedString;
    passphrase?: RecognizedString;
    dh_params_file_name?: RecognizedString;
    /** This translates to SSL_MODE_RELEASE_BUFFERS */
    ssl_prefer_low_memory_usage?: boolean;
}

/** TemplatedApp is either an SSL or non-SSL app. */
export interface TemplatedApp {
    /** Listens to hostname & port. Callback hands either false or a listen socket. */
    listen(host: RecognizedString, port: number, cb: (listenSocket: us_listen_socket) => void): TemplatedApp;
    /** Listens to port. Callback hands either false or a listen socket. */
    listen(port: number, cb: (listenSocket: any) => void): TemplatedApp;
    /** Registers an HTTP GET handler matching specified URL pattern. */
    get(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers an HTTP POST handler matching specified URL pattern. */
    post(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers an HTTP OPTIONS handler matching specified URL pattern. */
    options(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers an HTTP DELETE handler matching specified URL pattern. */
    del(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers an HTTP PATCH handler matching specified URL pattern. */
    patch(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers an HTTP PUT handler matching specified URL pattern. */
    put(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers an HTTP HEAD handler matching specified URL pattern. */
    head(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers an HTTP CONNECT handler matching specified URL pattern. */
    connect(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers an HTTP TRACE handler matching specified URL pattern. */
    trace(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers an HTTP handler matching specified URL pattern on any HTTP method. */
    any(pattern: RecognizedString, handler: (res: HttpResponse, req: HttpRequest) => void) : TemplatedApp;
    /** Registers a handler matching specified URL pattern where WebSocket upgrade requests are caught. */
    ws(pattern: RecognizedString, behavior: WebSocketBehavior) : TemplatedApp;
    /** Publishes a message under topic, for all WebSockets under this app. See WebSocket.publish. */
    publish(topic: RecognizedString, message: RecognizedString, isBinary?: boolean, compress?: boolean) : TemplatedApp;
}

/** Constructs a non-SSL app */
export function App(options?: AppOptions): TemplatedApp;

/** Constructs an SSL app */
export function SSLApp(options: AppOptions): TemplatedApp;

/** Closes a uSockets listen socket. */
export function us_listen_socket_close(listenSocket: us_listen_socket): void;

/** WebSocket compression options */
export type CompressOptions = number;
/** No compression (always a good idea) */
export var DISABLED: CompressOptions;
/** Zero memory overhead compression (recommended) */
export var SHARED_COMPRESSOR: CompressOptions;
/** Sliding dedicated compress window, requires 256KB of memory per socket */
export var DEDICATED_COMPRESSOR: CompressOptions;

/** Sliding dedicated compress window, requires 3KB of memory per socket */
export var DEDICATED_COMPRESSOR_3KB: CompressOptions;
/** Sliding dedicated compress window, requires 4KB of memory per socket */
export var DEDICATED_COMPRESSOR_4KB: CompressOptions;
/** Sliding dedicated compress window, requires 8KB of memory per socket */
export var DEDICATED_COMPRESSOR_8KB: CompressOptions;
/** Sliding dedicated compress window, requires 16KB of memory per socket */
export var DEDICATED_COMPRESSOR_16KB: CompressOptions;
/** Sliding dedicated compress window, requires 32KB of memory per socket */
export var DEDICATED_COMPRESSOR_32KB: CompressOptions;
/** Sliding dedicated compress window, requires 64KB of memory per socket */
export var DEDICATED_COMPRESSOR_64KB: CompressOptions;
/** Sliding dedicated compress window, requires 128KB of memory per socket */
export var DEDICATED_COMPRESSOR_128KB: CompressOptions;
/** Sliding dedicated compress window, requires 256KB of memory per socket */
export var DEDICATED_COMPRESSOR_256KB: CompressOptions;