@bjoernboss/mws 1.0.0 → 1.1.0

package/dist/client.js

@@ -1,26 +1,24 @@
 /* SPDX-License-Identifier: BSD-3-Clause */
 /* Copyright (c) 2024-2026 Bjoern Boss Henrichsen */
 import * as libLog from "./log.js";
-import * as libCache from "./cache.js";
 import * as libHelper from "./helper.js";
 import * as libBase from "./base.js";
 import * as libEvents from "events";
 import * as libFs from "fs";
 import * as libStream from "stream";
 import * as libUrl from "url";
-import * as libWs from "ws";
 import * as libHttp from "http";
 const BAD_HTTP_STRING_REGEX = /[\x00-\x1f\x7f]/;
 const BAD_HTTP_HEADER_NAME_REGEX = /[\x00-\x1f\x7f\(\)<>@,;:\\"/\[\]\?=\{\} \t]/;
 class ClientContext {
-    dropLogTag;
     path;
+    identity;
     translationCount;
     busyCount;
     headerPatchCount;
     htmlPatchCount;
-    constructor(path, translationCount, busyCount, headerPatchCount, htmlPatchCount) {
-        this.dropLogTag = () => { };
+    constructor(path, identity, translationCount, busyCount, headerPatchCount, htmlPatchCount) {
+        this.identity = identity;
         this.path = path;
         this.translationCount = translationCount;
         this.busyCount = busyCount;
@@ -46,25 +44,25 @@ class ClientBase extends libLog.Logger {
         }
         this._config = config;
     }
-    /* raw request origin (no host will result in '_'; host will be lower-case) */
+    /** raw request origin (no host will result in '_'; host will be lower-case) */
     url;
-    /* path relative to current module */
+    /** path relative to current module */
     get path() {
         return this._path;
     }
-    /* configuration used by this client */
+    /** configuration used by this client */
     get config() {
         return this._config;
     }
-    /* check if the path relative to the current module is a sub path of the given test base path */
+    /** 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) {
         return libHelper.isSubPath(base, this._path);
     }
-    /* check if the path relative to the current module is inside of the given test base path */
+    /** check if the path relative to the current module is inside of the given test base path (must be truly inside; /base/...) */
     isInsideOf(base) {
         return libHelper.isInside(base, this._path);
     }
-    /* create a path relative from the current module into the clients traversed server space */
+    /** create a path relative from the current module into the clients traversed server space */
     makePath(path) {
         path = libHelper.sanitize(path, false);
         let output = path;
@@ -146,38 +144,38 @@ class HttpRequestResponse extends libStream.Writable {
         this.responseCompleted = false;
     }
 }
-/*
-*	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.
-*/
+/**
+ *	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 class ClientRequest extends ClientBase {
     _headerPatcher;
     _htmlPatcher;
@@ -185,8 +183,8 @@ export class ClientRequest extends ClientBase {
     _throughput;
     _native;
     _request;
-    _cache;
-    constructor(cache, config, protocol, request, response) {
+    _server;
+    constructor(server, config, protocol, request, response) {
         super(new libUrl.URL(`${protocol}://${request.headers.host?.toLowerCase() ?? '_'}${request.url}`), 'request', config);
         this._headerPatcher = [];
         this._htmlPatcher = [];
@@ -207,7 +205,7 @@ export class ClientRequest extends ClientBase {
         this._state.completedResolve = completedResolve;
         this._state.breakResolve = breakResolve;
         this._request = request;
-        this._cache = cache;
+        this._server = server;
         /* setup the throughput measurement to detect any stalling connections */
         this._throughput = { timer: null, deadline: 0, start: 0, active: true, busyCheck: [] };
         if (this.config.throughputThreshold > 0) {
@@ -440,7 +438,8 @@ export class ClientRequest extends ClientBase {
         });
     }
     markAsBroken(reason, graceful) {
-        this.error(`Connection broken: [${reason}]`);
+        if (reason != '')
+            this.error(`Connection broken: [${reason}]`);
         this._state.response = ResponseState.broken;
         if (this._state.breaking != null) {
             if (!graceful)
@@ -799,7 +798,7 @@ export class ClientRequest extends ClientBase {
         let sanitized = null;
         let match = null;
         /* check if this is only an identity map, in which case nothing complex needs to be evaluated */
-        if (Object.keys(map).length == 1 && map['/'] == '/')
+        if (map == null || Object.keys(map).length == 1 && map['/'] == '/')
             match = ['/', '/'];
         /* create the merged reverse map and check if the map applies to the current translation */
         else {
@@ -815,38 +814,30 @@ export class ClientRequest extends ClientBase {
             if (match == null || match[1] == null)
                 return null;
         }
-        const current = new ClientContext(this._path, this._translation.length, this._throughput.busyCheck.length, this._headerPatcher.length, this._htmlPatcher.length);
+        const current = new ClientContext(this._path, this.identity, this._translation.length, this._throughput.busyCheck.length, this._headerPatcher.length, this._htmlPatcher.length);
         /* setup the new path, all path translations, and the tagged logging identity */
         this._path = libHelper.rebasePath(match[0], match[1], this._path);
         if (sanitized != null)
             this._translation.push(sanitized);
-        if (identity != '') {
-            const update = this.tagLog(identity);
-            current.dropLogTag = () => update();
-        }
+        if (identity != '')
+            this.logSetIdentity(`${this.identity}.${identity}`);
         return current;
     }
     _restoreSnapshot(snapshot) {
         this._path = snapshot.path;
+        this.logSetIdentity(snapshot.identity);
         this._translation.splice(snapshot.translationCount);
         this._throughput.busyCheck.splice(snapshot.busyCount);
         this._headerPatcher.splice(snapshot.headerPatchCount);
         this._htmlPatcher.splice(snapshot.htmlPatchCount);
-        snapshot.dropLogTag();
     }
-    /* instantiate a request client from a web request structure (must be followed by one finalizeConnection call under all circumstances) */
-    static fromRequest(protocol, request, response, options) {
-        const cache = (options?.cache instanceof libCache.CacheHost ? options.cache : libCache.createCache(options?.cache));
-        return new ClientRequest(cache, BurntClientConfig.from(options?.config), protocol, request, response);
+    static _fromRequest(protocol, request, response, config, server) {
+        return new ClientRequest(server, config, protocol, request, response);
     }
-    /* instantiate a request client from a web socket upgrade structure (instantiates a new no-server wss if none is provided; must be followed by one finalizeConnection call under all circumstances) */
-    static fromUpgrade(protocol, request, socket, head, options) {
-        const cache = (options?.cache instanceof libCache.CacheHost ? options.cache : libCache.createCache(options?.cache));
-        return new ClientRequest(cache, BurntClientConfig.from(options?.config), protocol, request, { socket, head, wss: options?.wss });
+    static _fromUpgrade(protocol, request, socket, head, config, server, wss) {
+        return new ClientRequest(server, config, protocol, request, { socket, head, wss });
     }
-    /* finalize the connection by ensuring the response is completed and pontentially also closed (must be called once at
-    *	the end; must have been fully processed and responded to; default responds with not-found for unhandled requests) */
-    async finalizeConnection() {
+    async _finalizeConnection() {
         /* ensure the connection is default replied with not-found */
         if (this._state.response == ResponseState.none)
             this.respondNotFound();
@@ -890,7 +881,7 @@ export class ClientRequest extends ClientBase {
             this._request.socket.setTimeout(this._native.timeout ?? 0);
         this._state.completedResolve();
     }
-    /* respond with an internal error and kill the connection */
+    /** respond with an internal error and kill the connection */
     killConnection(reason) {
         const description = `Connection killed: ${reason}`;
         const closing = (this._state.response == ResponseState.none || this._state.response == ResponseState.acknowledged);
@@ -898,44 +889,48 @@ export class ClientRequest extends ClientBase {
             this.respondInternalError(description, { headers: { 'Connection': 'close' } });
         this.markAsBroken((closing ? '' : description), closing);
     }
-    /* cache host to be used with this client */
+    /** server the client originates from */
+    get server() {
+        return this._server;
+    }
+    /** cache host used by this server and client */
     get cache() {
-        return this._cache;
+        return this._server.cache;
     }
-    /* request has not yet been acknowledged in any way */
+    /** request has not yet been acknowledged in any way */
     get unhandled() {
         return (this._state.response == ResponseState.none);
     }
-    /* request has been acknowledged or already processed */
+    /** request has been acknowledged or already processed */
     get claimed() {
         return (this._state.response != ResponseState.none);
     }
-    /* resolves whenever the response has been determined (is broken or a response header has been sent) */
+    /** resolves whenever the response has been determined (is broken or a response header has been sent) */
     get responded() {
         return this._state.respondedPromise;
     }
-    /* resolves whenever the request has been fully processed */
+    /** resolves whenever the request has been fully processed */
     get completed() {
         return this._state.completedPromise;
     }
-    /* http request headers */
+    /** http request headers */
     get headers() {
         return this._request.headers;
     }
-    /* http request method */
+    /** http request method */
     get method() {
         return this._request.method ?? '';
     }
-    /* was the http request a head request */
+    /** was the http request a head request */
     get isHead() {
         return (this._request.method == 'HEAD');
     }
-    /* return the string formatted media-type (or empty string for no media type) */
+    /** return the string formatted media-type (or empty string for no media type) */
     getMediaType() {
         const type = libHelper.splitAndTrimList(this.headers['content-type'] ?? null, ';', true)[0] ?? '';
         return type.toLowerCase();
     }
-    /* check the content-type for a media-type and otherwise return the default type */
+    /** check the content-type for a media-type and otherwise return the default type */
     getMediaTypeCharset(defEncoding) {
         const type = this.headers['content-type'];
         if (type == null)
@@ -957,7 +952,7 @@ export class ClientRequest extends ClientBase {
         }
         return defEncoding;
     }
-    /* 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]) */
+    /** 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, options) {
         if (!Array.isArray(types))
             types = [types];
@@ -971,8 +966,8 @@ export class ClientRequest extends ClientBase {
         this.respondUnsupported(type, types.map(t => t.mediaType).join(','), options);
         return 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 */
+    /** 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, options) {
         if (!Array.isArray(methods))
             methods = [methods];
@@ -986,35 +981,35 @@ export class ClientRequest extends ClientBase {
         this.respondMethodNotAllowed(this.method, allowed, options);
         return 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) */
+    /** 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) {
         this._throughput.busyCheck.push(cb);
     }
-    /* 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) */
+    /** 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) {
         this._headerPatcher.push(cb);
     }
-    /* 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) */
+    /** 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) {
         this._htmlPatcher.push(cb);
     }
-    /* respond with [internal-error] and a default text response (always considered an error; reason is logged server-side only) */
+    /** respond with [internal-error] and a default text response (always considered an error; reason is logged server-side only) */
     respondInternalError(reason, options) {
         this.constructQuickResponse(libBase.Status.InternalError, `Failure Reason (not sent): ${reason}`, options?.headers, {
             media: libBase.Media.Text, body: Buffer.from(`An internal server error occurred while processing the request for [${this.url.pathname}].`, 'utf-8')
         });
     }
-    /* respond with [forbidden] and a default text response (reason is logged server-side only) */
+    /** respond with [forbidden] and a default text response (reason is logged server-side only) */
     respondForbidden(reason, options) {
         this.constructQuickResponse(libBase.Status.Forbidden, `Forbidden Reason (not sent): ${reason}`, options?.headers, {
             media: libBase.Media.Text, body: Buffer.from(`Access to [${this.url.pathname}] denied.`, 'utf-8')
         });
     }
-    /* 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 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, options) {
         const status = options?.status ?? libBase.Status.Ok;
         if (content == null)
@@ -1028,13 +1023,13 @@ export class ClientRequest extends ClientBase {
             media, body: (options?.lightResponse && this.isHead ? undefined : content)
         });
     }
-    /* respond with [ok] and either a message or a default response */
+    /** respond with [ok] and either a message or a default response */
     respondOk(options) {
         this.constructQuickResponse(libBase.Status.Ok, options?.message ?? null, options?.headers, {
             media: libBase.Media.Text, body: Buffer.from(options?.message ?? `${this.method} was successful for [${this.url.pathname}].`, 'utf-8')
         });
     }
-    /* respond with [created] and either a message or a default response (ensure target is properly URI encoded) */
+    /** respond with [created] and either a message or a default response (ensure target is properly URI encoded) */
     respondCreated(target, options) {
         const header = (options?.headers ?? {});
         header['Location'] = target;
@@ -1042,7 +1037,7 @@ export class ClientRequest extends ClientBase {
             media: libBase.Media.Text, body: Buffer.from(`Resource [${this.url.pathname}] successfully created:\n${target}`, 'utf-8')
         });
     }
-    /* respond with [not-modified] and no body (ensure the etag and/or last-modified is set) */
+    /** respond with [not-modified] and no body (ensure the etag and/or last-modified is set) */
     respondNotModified(options) {
         const header = (options?.headers ?? {});
         if (options?.etag != null && !('ETag' in header))
@@ -1051,7 +1046,7 @@ export class ClientRequest extends ClientBase {
             header['Last-Modified'] = options.lastModified;
         this.constructQuickResponse(libBase.Status.NotModified, null, header, null);
     }
-    /* respond with [precondition-failed] and a default text response (ensure the etag and/or last-modified is set) */
+    /** respond with [precondition-failed] and a default text response (ensure the etag and/or last-modified is set) */
     respondPreconditionFailed(reason, options) {
         const header = (options?.headers ?? {});
         if (options?.etag != null && !('ETag' in header))
@@ -1062,13 +1057,13 @@ export class ClientRequest extends ClientBase {
             media: libBase.Media.Text, body: Buffer.from(`Precondition for resource [${this.url.pathname}] failed:\n${reason}`, 'utf-8')
         });
     }
-    /* respond with [bad-request] and a default text response */
+    /** respond with [bad-request] and a default text response */
     respondBadRequest(reason, options) {
         this.constructQuickResponse(libBase.Status.BadRequest, reason, options?.headers, {
             media: libBase.Media.Text, body: Buffer.from(`Request for [${this.url.pathname}] is perceived as malformed:\n${reason}`, 'utf-8')
         });
     }
-    /* respond with [range-not-satisfiable] and a default text response */
+    /** respond with [range-not-satisfiable] and a default text response */
     respondRangeIssue(range, size, options) {
         const header = (options?.headers ?? {});
         header['Content-Range'] = `bytes */${size}`;
@@ -1076,25 +1071,25 @@ export class ClientRequest extends ClientBase {
             media: libBase.Media.Text, body: Buffer.from(`Range [${range}] cannot be satisfied for [${this.url.pathname}] of size ${size}.`, 'utf-8')
         });
     }
-    /* respond with [conflict] and a default text response */
+    /** respond with [conflict] and a default text response */
     respondConflict(conflict, options) {
         this.constructQuickResponse(libBase.Status.Conflict, conflict, options?.headers, {
             media: libBase.Media.Text, body: Buffer.from(`Conflict for resource [${this.url.pathname}]:\n${conflict}`, 'utf-8')
         });
     }
-    /* respond with [not-found] and a default text response */
+    /** respond with [not-found] and a default text response */
     respondNotFound(options) {
         this.constructQuickResponse(libBase.Status.NotFound, null, options?.headers, {
             media: libBase.Media.Text, body: Buffer.from(`Resource [${this.url.pathname}] could not be found.`, 'utf-8')
         });
     }
-    /* respond with [unsupported-media-type] and a default text response */
+    /** respond with [unsupported-media-type] and a default text response */
     respondUnsupported(used, allowed, options) {
         this.constructQuickResponse(libBase.Status.UnsupportedMediaType, `Allowed was [${allowed}] but [${used}] was used`, options?.headers, {
             media: libBase.Media.Text, body: Buffer.from(`Media type [${used}] not supported for [${this.url.pathname}].\nAllowed: ${allowed}`, 'utf-8')
         });
     }
-    /* respond with [invalid-method] and a default text response */
+    /** respond with [method-not-allowed] and a default text response */
     respondMethodNotAllowed(method, allowed, options) {
         const header = (options?.headers ?? {});
         header['Allow'] = allowed;
@@ -1102,7 +1097,7 @@ export class ClientRequest extends ClientBase {
             media: libBase.Media.Text, body: Buffer.from(`Method ${method} not allowed for [${this.url.pathname}].\nAllowed: ${allowed}.`, 'utf-8')
         });
     }
-    /* respond with [request-timeout] and a default text response */
+    /** respond with [request-timeout] and a default text response */
     respondRequestTimeout(reason, options) {
         const header = (options?.headers ?? {});
         header['Connection'] = 'close';
@@ -1110,13 +1105,13 @@ export class ClientRequest extends ClientBase {
             media: libBase.Media.Text, body: Buffer.from(`Request processing of [${this.url.pathname}] timed out:\n${reason}`, 'utf-8')
         });
     }
-    /* respond with [content-too-large] and a default text response */
+    /** respond with [content-too-large] and a default text response */
     respondContentTooLarge(allowed, atLeastProvided, options) {
         this.constructQuickResponse(libBase.Status.ContentTooLarge, `[${atLeastProvided}] > [${allowed}]`, options?.headers, {
             media: libBase.Media.Text, body: Buffer.from(`Content of at least size ${atLeastProvided} too large for [${this.url.pathname}].\nAt most ${allowed} bytes are allowed.`, 'utf-8')
         });
     }
-    /* respond with [update-required] and a default text response */
+    /** respond with [update-required] and a default text response */
     respondUpdateRequired(upgrade, options) {
         const header = (options?.headers ?? {});
         if (!('Connection' in header))
@@ -1126,7 +1121,7 @@ export class ClientRequest extends ClientBase {
             media: libBase.Media.Text, body: Buffer.from(`Endpoint [${this.url.pathname}] requires an upgrade.\nRequired: ${upgrade}`, 'utf-8')
         });
     }
-    /* respond with [see-other] to the given target and a default text response (forces method GET; ensure target is properly URI encoded) */
+    /** respond with [see-other] to the given target and a default text response (forces method GET; ensure target is properly URI encoded) */
     respondSeeOther(target, options) {
         const header = (options?.headers ?? {});
         header['Location'] = target;
@@ -1134,7 +1129,7 @@ export class ClientRequest extends ClientBase {
             media: libBase.Media.Text, body: Buffer.from(`Continue at: ${target}`, 'utf-8')
         });
     }
-    /* respond with [temporary-redirect] to the given target and a default text response (preserves method; ensure target is properly URI encoded) */
+    /** respond with [temporary-redirect] to the given target and a default text response (preserves method; ensure target is properly URI encoded) */
     respondTemporaryRedirect(target, options) {
         const header = (options?.headers ?? {});
         header['Location'] = target;
@@ -1142,7 +1137,7 @@ export class ClientRequest extends ClientBase {
             media: libBase.Media.Text, body: Buffer.from(`Resource [${this.url.pathname}] temporarily redirects to:\n${target}`, 'utf-8')
         });
     }
-    /* respond with [permanent-redirect] to the given target and a default text response (preserves method; ensure target is properly URI encoded)  */
+    /** respond with [permanent-redirect] to the given target and a default text response (preserves method; ensure target is properly URI encoded) */
     respondPermanentRedirect(target, options) {
         const header = (options?.headers ?? {});
         header['Location'] = target;
@@ -1150,9 +1145,9 @@ export class ClientRequest extends ClientBase {
             media: libBase.Media.Text, body: Buffer.from(`Resource [${this.url.pathname}] permanently redirects to:\n${target}`, 'utf-8')
         });
     }
-    /* 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 */
+    /** 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 */
     async respondHtml(page, options) {
         if (this._state.response != ResponseState.none)
             return this.badClientUsage('HTML response on already claimed connection', false);
@@ -1179,10 +1174,10 @@ export class ClientRequest extends ClientBase {
         this.log(`Responding with HTML content and status [${status.msg}]${this.isHead ? ' as light-build' : ''}`);
         this.sendFullResponse(status, headers, { media: libBase.Media.Html, body: content });
     }
-    /* [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 */
+    /** [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) {
         const status = options?.status ?? libBase.Status.Ok;
         const headers = (options?.headers ?? {});
@@ -1191,11 +1186,11 @@ export class ClientRequest extends ClientBase {
         this.log(`Responding with data and status [${status.msg}]`);
         return this.sendClientData(status, options?.media ?? libBase.Media.Unknown, headers, options?.dynamicEncode ?? true, options?.contentSize ?? null);
     }
-    /* 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 */
+    /** 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 */
     async tryRespondFile(filePath, options) {
         if (options == null)
             options = {};
@@ -1211,7 +1206,7 @@ export class ClientRequest extends ClientBase {
                 return false;
         }
         catch (err) {
-            this.respondInternalError(`Failed to read file: ${err.message}`);
+            this.respondInternalError(`Failed to read file [${filePath}]: ${err.message}`);
             return true;
         }
         if (typeof cached == 'string') {
@@ -1315,7 +1310,7 @@ export class ClientRequest extends ClientBase {
                 if (settled)
                     return;
                 settled = true;
-                this.respondInternalError(`Failed to stream file: ${err.message}`);
+                this.respondInternalError(`Failed to stream file [${filePath}]: ${err.message}`);
                 stream.destroy(err);
             });
             stream.once('error', (err) => {
@@ -1330,9 +1325,9 @@ export class ClientRequest extends ClientBase {
             });
         });
     }
-    /* [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 */
+    /** [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 */
     async receiveToFile(path, maxLength) {
         this.trace(`Collecting data from [${this.url.pathname}] to: [${path}]`);
         return new Promise((resolve, reject) => {
@@ -1373,14 +1368,14 @@ export class ClientRequest extends ClientBase {
             });
         });
     }
-    /* [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 */
+    /** [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) {
         return this.receiveClientData(maxLength);
     }
-    /* [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 */
+    /** [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 */
     async receiveAllBuffer(maxLength) {
         return new Promise((resolve, reject) => {
             let stream = this.receiveClientData(maxLength);
@@ -1390,8 +1385,8 @@ export class ClientRequest extends ClientBase {
             stream.once('error', (err) => reject(err));
         });
     }
-    /* [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 */
+    /** [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 */
     async receiveAllText(encoding, maxLength) {
         /* wait for the buffer (let all errors propagate out) */
         const buffer = await this.receiveAllBuffer(maxLength);
@@ -1403,8 +1398,8 @@ export class ClientRequest extends ClientBase {
             throw err;
         }
     }
-    /* marks the object as having been handled and returns a web socket or
-    *	automatically responds with a corresponding error and returns null */
+    /** marks the object as having been handled and returns a web socket or
+     *	automatically responds with a corresponding error and returns null */
     async acceptWebSocket() {
         if (this._state.response != ResponseState.none) {
             this.badClientUsage('WebSocket upgrade on already claimed connection', false);
@@ -1438,8 +1433,7 @@ export class ClientRequest extends ClientBase {
                 resolve(null);
             });
             /* start the upgrade process (web-socket upgrade handler will automatically send error messages) */
-            const wss = (native.wss ?? new libWs.WebSocketServer({ noServer: true, clientTracking: false }));
-            wss.handleUpgrade(this._request, native.socket, native.head, (ws, _) => {
+            native.wss.handleUpgrade(this._request, native.socket, native.head, (ws, _) => {
                 if (!settled && this._state.response == ResponseState.headerSent) {
                     settled = true, this._state.response = ResponseState.completed;
                     /* ensure that the socket is valid as otherwise proper cleanup might not be guaranteed (no
@@ -1459,18 +1453,18 @@ export class ClientRequest extends ClientBase {
         return ws;
     }
 }
-/*
-*	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.
-*/
+/**
+ *	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 class ClientSocket extends ClientBase {
     _ws;
     _alive;
     _closing;
     _emitter;
-    _extension;
+    _log;
     constructor(ws, source) {
         super(source, 'socket', source.config);
         this._ws = ws;
@@ -1478,7 +1472,7 @@ export class ClientSocket extends ClientBase {
         this._closing = { promise: null, closed: null, defer: 0 };
         this._emitter = new libEvents.EventEmitter();
         this._ws.on('pong', () => {
-            this.trace(`Alive check pong received`, { extension: this._extension });
+            this.trace(`Alive check pong received`, { identity: this._log.identity });
             this.selfIsAlive();
         });
         this._ws.on('message', (data) => {
@@ -1504,12 +1498,14 @@ export class ClientSocket extends ClientBase {
         this._ws.once('error', (err) => {
             this.handleClosing(`WebSocket error: ${err.message}`);
         });
+        /* perserve the log extension of the base and preserve it to be re-used for internal logs */
+        const extIndex = source.identity.indexOf('.');
+        if (extIndex > 0)
+            this.logSetIdentity(`${this.identity}${source.identity.substring(extIndex)}`);
+        source.log(`WebSocket accepted: [${this.identity}]`);
+        this._log = { identity: this.identity, tagList: [] };
         /* start the first alive check (no need to consider the socket timeout, as it will have been cleared already) */
         this.selfIsAlive();
-        /* perserve the log extension of the base and preserve it to be re-used for internal logs */
-        source.log(`WebSocket accepted: [${this.logIdentity}]`);
-        this.tagLog(source.logExtension);
-        this._extension = source.logExtension;
     }
     checkIsAlive() {
         if (this._closing.promise != null)
@@ -1524,7 +1520,7 @@ export class ClientSocket extends ClientBase {
         this._alive.timer = setTimeout(() => this.checkIsAlive(), this.config.webSocketAliveTimeout);
         /* try to ping the remote to check the liveliness */
         try {
-            this.trace(`Sending ping to determine if connection is alive`, { extension: this._extension });
+            this.trace(`Sending ping to determine if connection is alive`, { identity: this._log.identity });
             this._ws.ping();
         }
         catch (err) {
@@ -1549,14 +1545,14 @@ export class ClientSocket extends ClientBase {
             this._alive.timer = null;
             /* check if a termination should be triggered and otherwise start the grace termination timer */
             if (terminate != null) {
-                this.error(terminate, { extension: this._extension });
+                this.error(terminate, { identity: this._log.identity });
                 this._ws.terminate();
             }
             else {
                 this._alive.timer = setTimeout(() => {
                     this._alive.timer = null;
                     if (this._closing.closed != null) {
-                        this.error('Closing connection', { extension: this._extension });
+                        this.error('Closing connection', { identity: this._log.identity });
                         this._ws.terminate();
                     }
                 }, this.config.killGraceTimeout);
@@ -1567,13 +1563,21 @@ export class ClientSocket extends ClientBase {
         const closed = this._closing.closed;
         this._closing.closed = null;
         this.emitEventSync('close');
-        this.trace('Socket connection closed', { extension: this._extension });
+        this.trace('Socket connection closed', { identity: this._log.identity });
         closed();
     }
+    updateLogIdentity() {
+        let identity = this._log.identity;
+        for (const tag of this._log.tagList) {
+            if (tag.value != '')
+                identity += `.${tag.value}`;
+        }
+        this.logSetIdentity(identity);
+    }
     static _fromRequest(ws, source) {
         return new ClientSocket(ws, source);
     }
-    /* send data to the remote (ignored if connection is being closed) */
+    /** send data to the remote (ignored if connection is being closed) */
     send(data) {
         if (this._closing.promise != null)
             return;
@@ -1584,7 +1588,7 @@ export class ClientSocket extends ClientBase {
             this.handleClosing(`WebSocket error while sending data: ${err.message}`);
         }
     }
-    /* close the web socket (promise resolved once the close callback has been fully invoked) */
+    /** close the web socket (promise resolved once the close callback has been fully invoked) */
     close() {
         if (this._closing.promise == null) {
             this._ws.close();
@@ -1592,6 +1596,26 @@ export class ClientSocket extends ClientBase {
         }
         return this._closing.promise;
     }
+    /** tag the logging with the given identifier and return a callback to update the tag */
+    tagLog(identifier) {
+        let tag = { value: identifier };
+        this._log.tagList.push(tag);
+        if (tag.value != '')
+            this.updateLogIdentity();
+        /* setup the handler responsible to update the logging */
+        return (value) => {
+            if (tag == null)
+                return;
+            /* check if the tag should be removed or if the value should just be updated */
+            if (value == null) {
+                this._log.tagList = this._log.tagList.filter((v) => v != tag);
+                tag = null;
+            }
+            else if (value != tag.value)
+                tag.value = value;
+            this.updateLogIdentity();
+        };
+    }
     /* -------- event handler interfaces -------- */
     on(event, listener) {
         this._emitter.on(event, listener);
@@ -1610,7 +1634,7 @@ export class ClientSocket extends ClientBase {
             this._emitter.emit(event, ...args);
         }
         catch (err) {
-            this.error(`Unhandled exception in ${event} listener: ${err.message}`, { extension: this._extension });
+            this.error(`Unhandled exception in ${event} listener: ${err.message}`, { identity: this._log.identity });
         }
     }
 }