From d945b2fc707ea1be40d37d7c21d4682cf60a28c2 Mon Sep 17 00:00:00 2001 From: RatchetS2 <19169837+RatchetS2@users.noreply.github.com> Date: Thu, 30 Jan 2025 20:43:06 +0100 Subject: [PATCH] Update index.d.ts --- docs/index.d.ts | 55 ++++++++++++++++++++----------------------------- 1 file changed, 22 insertions(+), 33 deletions(-) diff --git a/docs/index.d.ts b/docs/index.d.ts index 5199f608..b5a582f6 100644 --- a/docs/index.d.ts +++ b/docs/index.d.ts @@ -110,31 +110,20 @@ export interface WebSocket { /** 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". - * This has to be called first in any response, otherwise - * it will be called automatically with "200 OK". - * - * If you want to send custom headers in a WebSocket - * upgrade response, you have to call writeStatus with - * "101 Switching Protocols" before you call writeHeader, - * otherwise your first call to writeHeader will call - * writeStatus with "200 OK" and the upgrade will fail. - * - * As you can imagine, we format outgoing responses in a linear - * buffer, not in a hash table. You can read about this in - * the user manual under "corking". - */ - /** Pause http body streaming (throttle) */ pause() : void; /** Resume http body streaming (unthrottle) */ resume() : void; + /** Writes the HTTP status message, such as "200 OK". + * This must be called first in any response, otherwise the default status "200 OK" will be used. + * + * If you want to send custom headers in a WebSocket upgrade response, + * you must call writeStatus with "101 Switching Protocols" before you call writeHeader, + * otherwise the status will be set to "200 OK" and the upgrade will fail. */ writeStatus(status: RecognizedString) : HttpResponse; - /** Writes key and value to HTTP response. - * See writeStatus and corking. - */ + /** Writes key and value to HTTP response. See writeStatus and corking. */ writeHeader(key: RecognizedString, value: RecognizedString) : HttpResponse; /** Enters or continues chunked encoding mode. Writes part of the response. End with zero length write. Returns true if no backpressure was added. */ write(chunk: RecognizedString) : boolean; @@ -151,19 +140,20 @@ export interface 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. - */ + /** Handler for retrying previously failed write attempts. + * You MUST return false on rewrite failure and true otherwise. + * This must be used in conjunction with tryEnd. */ 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 terminate. - * When this event emits, the response has been aborted and may not be used. */ + /** Every HttpResponse MUST have an attached abort handler IF you perform any asynchronous operation. + * Returning from an Http request handler without attaching an abort handler is ill-use and will throw. + * When this event is emitted, 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.*/ + /** Handler for reading Http request's body data. + * Must be attached before performing any asynchronous operation, otherwise data will be lost. + * You MUST copy the ArrayBuffer's data 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 in binary format (4 or 16 bytes). */ @@ -181,15 +171,14 @@ export interface HttpResponse { /** 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. + * to cork before calling writeStatus, writeHeader, write or end functions. Corking takes a callback in which you execute 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!"); + * res.writeStatus("200 OK").writeHeader("Some", "Value").end("Hello world!"); * }); * ``` */ @@ -218,7 +207,7 @@ export interface HttpRequest { getQuery() : string; /** Returns a decoded query parameter value or undefined. */ getQuery(key: string) : string | undefined; - /** Loops over all headers. */ + /** Loops over all headers. Keys and values are in lowercase. */ 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; @@ -328,7 +317,7 @@ export interface TemplatedApp { /** Registers a synchronous callback on missing server names. See /examples/ServerName.js. */ missingServerName(cb: (hostname: string) => void) : TemplatedApp; /** Attaches a "filter" function to track socket connections / disconnections */ - filter(cb: (res: HttpResponse, count: Number) => void | Promise) : TemplatedApp; + filter(cb: (res: HttpResponse, count: number) => void | Promise) : TemplatedApp; /** Closes all sockets including listen sockets. This will forcefully terminate all connections. */ close() : TemplatedApp; }