177 lines
9.3 KiB
TypeScript
177 lines
9.3 KiB
TypeScript
/* Under construction, lots of things to add */
|
|
|
|
/** Native type representing a raw uSockets struct us_listen_socket. */
|
|
interface us_listen_socket {
|
|
|
|
}
|
|
|
|
/** Recognized string types, things C++ can read and understand as strings */
|
|
type RecognizedString = string | ArrayBuffer | Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array;
|
|
|
|
/** A WebSocket connection that is valid from open to close event */
|
|
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;
|
|
|
|
/** Gradefully closes this WebSocket. Immediately calls close handler. */
|
|
end(code?: number, shortMessage?: RecognizedString) : WebSocket;
|
|
|
|
/** Forefully closes this WebSocket. Immediately calls close handler. */
|
|
close() : WebSocket;
|
|
|
|
/** 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;
|
|
|
|
/** Publish a message to a topic in MQTT syntax */
|
|
publish(topic: RecognizedString, message: RecognizedString, isBinary?: boolean, compress?: boolean) : WebSocket;
|
|
|
|
/** 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. */
|
|
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;
|
|
|
|
/** Arbitrary user data may be attached to this object */
|
|
[key: string]: any;
|
|
}
|
|
|
|
/** An HttpRequest is stack allocated and only accessible during the callback invocation. */
|
|
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;
|
|
}
|
|
|
|
/** A structure holding settings and handlers for a WebSocket route handler. */
|
|
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. */
|
|
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. */
|
|
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;
|