@bjoernboss/mws 1.0.0 → 1.1.0

package/dist/client.d.ts

@@ -2,18 +2,19 @@ import * as libLog from "./log.js";
 import * as libBuilder from "./builder.js";
 import * as libCache from "./cache.js";
 import * as libBase from "./base.js";
+import * as libServer from "./server.js";
 import * as libStream from "stream";
 import * as libUrl from "url";
 import * as libWs from "ws";
 import * as libHttp from "http";
 declare class ClientContext {
-    dropLogTag: () => void;
     path: string;
+    identity: string;
     translationCount: number;
     busyCount: number;
     headerPatchCount: number;
     htmlPatchCount: number;
-    constructor(path: string, translationCount: number, busyCount: number, headerPatchCount: number, htmlPatchCount: number);
+    constructor(path: string, identity: string, translationCount: number, busyCount: number, headerPatchCount: number, htmlPatchCount: number);
 }
 declare class ClientBase extends libLog.Logger {
     private _config;
@@ -21,15 +22,62 @@ declare class ClientBase extends libLog.Logger {
     protected _translation: Record<string, string | null>[];
     protected constructor(url: libUrl.URL, kind: string, config: BurntClientConfig);
     protected constructor(client: ClientBase, kind: string, config: BurntClientConfig);
+    /** raw request origin (no host will result in '_'; host will be lower-case) */
     readonly url: libUrl.URL;
+    /** path relative to current module */
     get path(): string;
+    /** configuration used by this client */
     get config(): BurntClientConfig;
+    /** check if the path relative to the current module is a sub path or the same of the given test base path (can be /base or /base/...) */
     isSubPathOf(base: string): boolean;
+    /** check if the path relative to the current module is inside of the given test base path (must be truly inside; /base/...) */
     isInsideOf(base: string): boolean;
+    /** create a path relative from the current module into the clients traversed server space */
     makePath(path: string): string;
 }
+type ClientSocketEvents = {
+    'data': (data: Buffer) => void;
+    'close': () => void;
+};
+/** look at the state and modify the headers accordingly (only add or remove headers, must not try to alter the response) */
 export type HeaderPatch = (status: libBase.StatusType, headers: Record<string, string>) => void;
+/** look at the page and modify it or the headers accordingly (can be interrupted by returning an alternate response) */
 export type HtmlPatch = (page: libBuilder.HtmlPage, status: libBase.StatusType, headers: Record<string, string>) => Promise<void>;
+/** type to invoke to update the logging tag (empty string will hide the tag entry;
+ *	null will completely remove the tag; other values will update the tag) */
+export type SocketLogTag = (value?: string) => void;
+/**
+ *	Does not throw any exceptions, unless explicitly stated.
+ *	Http HEAD aware (will silently drain any data sent from a HEAD request).
+ *
+ *	Request is considered acknowledged, as soon as a response has been triggered or a preparation started.
+ *	Path remains URI encoded, as it was received, and path building will use the same encoded paths.
+ *	Repeated request responding may override any ongoing responses and may terminate the connection; depending on the prior state.
+ *	Not responded to requests will result in [not-found].
+ *
+ *	Receiving data: Will automatically decode the stream and ensure a given maximum is not passed
+ *		=> Any errors while receiving will either auto-respond or send the connection into the broken state, and fail the receive reader (stream user does not need to respond).
+ *		=> Will terminate a connection, if the upload is not consumed or the client errors.
+ *		=> Premature destroying of receive reader will result in the connection being gracefully terminated.
+ *		=> All data must have been received before the response is completed.
+ *	Responding data: Will automatically encode the stream and send the header accordingly
+ *		=> Will automatically determine if encoding is to be used
+ *		=> Checks if promised number of bytes is provided
+ *		=> Will automatically error, if the broken state is detected, and will auto-respond or send the connection into the broken state (stream user does not need to respond).
+ *
+ *	A response sent while another is being prepared (acknowledged) will override it and close the connection.
+ *	A response sent while data is already being streamed (header sent) will break the connection.
+ *	Normal responses automatically add ClientConfig.responseCacheControl, if no other cache control is specified.
+ *	File responses will automatically add ClientConfig.fileCacheControl/ClientConfig.immutableCacheControl, if no other cache control is specified.
+ *	Responses will either use the dedicated responder interface and its highWaterMark, or a responder interface, which caches up to socket.highWaterMark.
+ *
+ *	Upgrade requests, which were not accepted, will be closed after responding.
+ *	An accept attempt must be fully awaited before completing the handling procedure.
+ *
+ *	Defaults [Accept-Ranges] normally to 'none' or to 'bytes' for files
+ *	Defaults [Vary] to 'Accept-Encoding'.
+ *	Defaults [Connection] to 'close' for upgrade requests and for some error responses.
+ */
 export declare class ClientRequest extends ClientBase {
     private _headerPatcher;
     private _htmlPatcher;
@@ -37,7 +85,7 @@ export declare class ClientRequest extends ClientBase {
     private _throughput;
     private _native;
     private _request;
-    private _cache;
+    private _server;
     private constructor();
     private constructQuickResponse;
     private failThroughput;
@@ -52,109 +100,151 @@ export declare class ClientRequest extends ClientBase {
     private sendClientWrite;
     private sendClientData;
     private receiveClientData;
-    _pushTranslation(map: Record<string, string | null>, identity: string): ClientContext | null;
+    _pushTranslation(map: Record<string, string | null> | null, identity: string): ClientContext | null;
     _restoreSnapshot(snapshot: ClientContext): void;
-    static fromRequest(protocol: string, request: libHttp.IncomingMessage, response: libHttp.ServerResponse, options?: {
-        config?: BurntClientConfig | ClientConfig;
-        cache?: libCache.CacheHost | libCache.CacheConfig | libCache.BurntCacheConfig;
-    }): ClientRequest;
-    static fromUpgrade(protocol: string, request: libHttp.IncomingMessage, socket: libStream.Duplex, head: Buffer, options?: {
-        config?: BurntClientConfig | ClientConfig;
-        cache?: libCache.CacheHost | libCache.CacheConfig | libCache.BurntCacheConfig;
-        wss?: libWs.WebSocketServer;
-    }): ClientRequest;
-    finalizeConnection(): Promise<void>;
+    static _fromRequest(protocol: string, request: libHttp.IncomingMessage, response: libHttp.ServerResponse, config: BurntClientConfig, server: libServer.Server): ClientRequest;
+    static _fromUpgrade(protocol: string, request: libHttp.IncomingMessage, socket: libStream.Duplex, head: Buffer, config: BurntClientConfig, server: libServer.Server, wss: libWs.WebSocketServer): ClientRequest;
+    _finalizeConnection(): Promise<void>;
+    /** respond with an internal error and kill the connection */
     killConnection(reason: string): void;
+    /** server the client originates from */
+    get server(): libServer.Server;
+    /** cache host used by this server and client */
     get cache(): libCache.CacheHost;
+    /** request has not yet been acknowledged in any way */
     get unhandled(): boolean;
+    /** request has been acknowledged or already processed */
     get claimed(): boolean;
+    /** resolves whenever the response has been determined (is broken or a response header has been sent) */
     get responded(): Promise<void>;
+    /** resolves whenever the request has been fully processed */
     get completed(): Promise<void>;
+    /** http request headers */
     get headers(): libHttp.IncomingHttpHeaders;
+    /** http request method */
     get method(): string;
+    /** was the http request a head request */
     get isHead(): boolean;
+    /** return the string formatted media-type (or empty string for no media type) */
     getMediaType(): string;
+    /** check the content-type for a media-type and otherwise return the default type */
     getMediaTypeCharset(defEncoding: string): string;
+    /** ensure the media-type is one of the list and otherwise return null and auto-respond with [unsupported-media-type] (defaults to first type, if [noneIsFirst]) */
     requireMediaType(types: libBase.MediaType[] | libBase.MediaType, options?: {
         noneIsFirst?: boolean;
         headers?: Record<string, string>;
     }): libBase.MediaType | null;
+    /** ensure the method is one of the list and otherwise return null and auto-respond with [method-not-allowed]
+     *	if [headExplicit] is false, method will substitute HEAD for GET, framework will consume the remaining body */
     requireMethod(methods: string[] | string, options?: {
         headExplicit?: boolean;
         headers?: Record<string, string>;
     }): string | null;
+    /** register a callback to check if the request is still being processed (delays throughput
+     *	termintion and resets connection timeout; will only be considered within this handler context) */
     busyCheck(cb: () => boolean): void;
+    /** register a callback to be invoked once the response is sent, to adjust the
+     *	headers to be sent (will only be considered within this handler context) */
     patchHeaders(cb: HeaderPatch): void;
+    /** register a callback to be invoked if html is built, to adjust the headers or
+     *	the content to be sent (will only be considered within this handler context) */
     patchHtmlPage(cb: HtmlPatch): void;
+    /** respond with [internal-error] and a default text response (always considered an error; reason is logged server-side only) */
     respondInternalError(reason: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [forbidden] and a default text response (reason is logged server-side only) */
     respondForbidden(reason: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with a any response of the given configuration (defaults to media-type: text/unknown/-, status: ok);
+     *	if [lightResponse], the content length is suppressed for head responses (to accomodate short-circuiting responding) */
     respond(content: string | Buffer | null, options?: {
         media?: libBase.MediaType;
         status?: libBase.StatusType;
         headers?: Record<string, string>;
         lightResponse?: boolean;
     }): void;
+    /** respond with [ok] and either a message or a default response */
     respondOk(options?: {
         message?: string;
         headers?: Record<string, string>;
     }): void;
+    /** respond with [created] and either a message or a default response (ensure target is properly URI encoded) */
     respondCreated(target: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [not-modified] and no body (ensure the etag and/or last-modified is set) */
     respondNotModified(options?: {
         etag?: string;
         lastModified?: string;
         headers?: Record<string, string>;
     }): void;
+    /** respond with [precondition-failed] and a default text response (ensure the etag and/or last-modified is set) */
     respondPreconditionFailed(reason: string, options?: {
         etag?: string;
         lastModified?: string;
         headers?: Record<string, string>;
     }): void;
+    /** respond with [bad-request] and a default text response */
     respondBadRequest(reason: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [range-not-satisfiable] and a default text response */
     respondRangeIssue(range: string, size: number, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [conflict] and a default text response */
     respondConflict(conflict: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [not-found] and a default text response */
     respondNotFound(options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [unsupported-media-type] and a default text response */
     respondUnsupported(used: string, allowed: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [method-not-allowed] and a default text response */
     respondMethodNotAllowed(method: string, allowed: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [request-timeout] and a default text response */
     respondRequestTimeout(reason: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [content-too-large] and a default text response */
     respondContentTooLarge(allowed: number, atLeastProvided: number, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [update-required] and a default text response */
     respondUpdateRequired(upgrade: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [see-other] to the given target and a default text response (forces method GET; ensure target is properly URI encoded) */
     respondSeeOther(target: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [temporary-redirect] to the given target and a default text response (preserves method; ensure target is properly URI encoded) */
     respondTemporaryRedirect(target: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with [permanent-redirect] to the given target and a default text response (preserves method; ensure target is properly URI encoded) */
     respondPermanentRedirect(target: string, options?: {
         headers?: Record<string, string>;
     }): void;
+    /** respond with html, can be built on by parent modules, sent once the request has been fully processed
+     *	(default status is ok; for HEAD builds, no actual content will be constructed or estimated in size)
+     *	automatically adds ClientConfig.responseCacheControl, if no other cache control is specified */
     respondHtml(page: libBuilder.HtmlPage, options?: {
         status?: libBase.StatusType;
         headers?: Record<string, string>;
     }): Promise<void>;
+    /** [no-throw but errors] send data with [media type] and [status] and return a writable stream (default: status is ok, media is unknown, dynamicEncode is true);
+     *	if a content size is provided, stream expects exactly this amount of bytes; if [dynamicEncode], the encoder will be dynamically negotiated
+     *	based on the content; for a HEAD request, no encoding will be negotiated, no lengths verified, and the written data will just be drained
+     *	(can immediately be ended using '.end()'); automatically adds ClientConfig.responseCacheControl, if no other cache control is specified */
     respondData(options?: {
         status?: libBase.StatusType;
         media?: libBase.MediaType;
@@ -162,51 +252,86 @@ export declare class ClientRequest extends ClientBase {
         dynamicEncode?: boolean;
         headers?: Record<string, string>;
     }): libStream.Writable;
+    /** try to respond with the given file, return false, if the file does not exist (range aware, HEAD aware); specify [checkFreshness] to
+     *	re-validate the file stats on disk before serving from cache; the media type can be overwritten (defaults to extracting media-type
+     *	from the file-path); [encoding] describes the encoding of a pre-encoded file (warning: no checks against accepted encodings
+     *	performed!); status will be [Ok], [partial-content], [not-modified] or according errors cache aware and etag/last-modified aware;
+     *	automatically adds ClientConfig.fileCacheControl/ClientConfig.immutableCacheControl, if no other cache control is specified */
     tryRespondFile(filePath: string, options?: {
         encoded?: string;
         media?: libBase.MediaType;
         headers?: Record<string, string>;
         checkFreshness?: boolean;
     }): Promise<boolean>;
+    /** [throws] receive the payload of given max length and write it directly to a file; will fail
+     *	if the file already exists and delete the file if it could not be received in full
+     *	automatically responds with given exceptions if the payload cannot be received properly or file operations fail */
     receiveToFile(path: string, maxLength: number | null): Promise<void>;
+    /** [no-throw but errors] receive the payload of given max length as a readable stream
+     *	automatically responds with given exceptions if the payload cannot be received properly
+     *	automatically drained if the readable stream is destroyed before reading all data */
     receiveData(maxLength: number | null): libStream.Readable;
+    /** [throws] receive the payload of given max length as a single complete buffer
+     *	automatically responds with given exceptions if the payload cannot be received properly */
     receiveAllBuffer(maxLength: number | null): Promise<Buffer>;
+    /** [throws] receive the payload of given max length as a single complete decoded string
+     *	automatically responds with given exceptions if the payload cannot be received properly */
     receiveAllText(encoding: string, maxLength: number | null): Promise<string>;
+    /** marks the object as having been handled and returns a web socket or
+     *	automatically responds with a corresponding error and returns null */
     acceptWebSocket(): Promise<ClientSocket | null>;
 }
+/**
+ *	WebSocket with integrated alive checks.
+ *	Structured WebSocket, which takes care of error handling.
+ *	The 'close' event is guaranteed to fire exactly once and no 'data' events will follow.
+ *	Takes ownership of the socket.
+ */
 export declare class ClientSocket extends ClientBase {
     private _ws;
     private _alive;
     private _closing;
     private _emitter;
-    private _extension;
+    private _log;
     private constructor();
     private checkIsAlive;
     private selfIsAlive;
     private handleClosing;
+    private updateLogIdentity;
     static _fromRequest(ws: libWs.WebSocket, source: ClientRequest): ClientSocket;
+    /** send data to the remote (ignored if connection is being closed) */
     send(data: string | Buffer): void;
+    /** close the web socket (promise resolved once the close callback has been fully invoked) */
     close(): Promise<void>;
+    /** tag the logging with the given identifier and return a callback to update the tag */
+    tagLog(identifier: string): SocketLogTag;
     on<K extends keyof ClientSocketEvents>(event: K, listener: ClientSocketEvents[K]): ClientSocket;
     off<K extends keyof ClientSocketEvents>(event: K, listener: ClientSocketEvents[K]): ClientSocket;
     once<K extends keyof ClientSocketEvents>(event: K, listener: ClientSocketEvents[K]): ClientSocket;
     private emitEventSync;
 }
-type ClientSocketEvents = {
-    'data': (data: Buffer) => void;
-    'close': () => void;
-};
 export interface ClientConfig {
+    /** default server name to be used in the http:server header [empty value prevents server header; Default: 'Modular Web Server'] */
     serverName?: string;
+    /** default header values to be added to every http response [Default: { 'X-Content-Type-Options': 'nosniff' }] */
     commonHeaders?: Record<string, string>;
+    /** default web-socket timeout before performing a ping to determine liveness [0 disables the timeout; in milliseconds; Default: 180_000] */
     webSocketTimeout?: number;
+    /** default web-socket timeout to respond to a liveness ping before closing the connection [0 kills the connection without ping test; in milliseconds; Default: 2_000] */
     webSocketAliveTimeout?: number;
+    /** time for a broken connection or socket to receive the response before force-closing it [0 results in immediate close; in milliseconds; Default: 1_000] */
     killGraceTimeout?: number;
+    /** default cache-control value for normal cache reads [empty string does not set any cache-control; Default: 'public, max-age=600, must-revalidate' (10 minutes)] */
     fileCacheControl?: string;
+    /** default cache-control value for immutable cache reads [empty string does not set any cache-control; Default: 'public, max-age=2592000, immutable' (30 days)] */
     immutableCacheControl?: string;
+    /** default cache-control value for any basic responses [empty string does not set any cache-control; Default: 'private, no-cache'] */
     responseCacheControl?: string;
+    /** grace period before the throughput is started to be measured or for busy connections [in milliseconds; Default: 10_000] */
     throughputGrace?: number;
+    /** throughput required for combined sending and receiving bodies of requests [0 disables the throughput check, in bytes/second; Default: 1_000] */
     throughputThreshold?: number;
+    /** length of sliding time window for which the throughput must be above the threshold [in milliseconds; Default: 30_000] */
     throughputWindow?: number;
 }
 export declare class BurntClientConfig {