/* 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; } /** 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 lots of memory per socket */ export var DEDICATED_COMPRESSOR: CompressOptions;