actor-ts 0.9.1 → 0.11.0

package/dist/http/static/index.d.ts

@@ -0,0 +1,7 @@
+export { getFromFile, getFromDirectory, getFromBrowseableDirectory } from './StaticFiles.js';
+export { StaticFilesOptions, StaticFilesOptionsBuilder, StaticFilesOptionsValidator } from './StaticFilesOptions.js';
+export type { StaticFilesOptionsType } from './StaticFilesOptions.js';
+export { renderDirectoryListing } from './DirectoryListing.js';
+export type { ListingEntry } from './DirectoryListing.js';
+export { resolveStaticPath } from './staticPath.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/http/static/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/static/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACrH,YAAY,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/http/static/index.js

@@ -0,0 +1,5 @@
+export { getFromFile, getFromDirectory, getFromBrowseableDirectory } from './StaticFiles.js';
+export { StaticFilesOptions, StaticFilesOptionsBuilder, StaticFilesOptionsValidator } from './StaticFilesOptions.js';
+export { renderDirectoryListing } from './DirectoryListing.js';
+export { resolveStaticPath } from './staticPath.js';
+//# sourceMappingURL=index.js.map

package/dist/http/static/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/http/static/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAErH,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/http/static/staticPath.d.ts

@@ -0,0 +1,14 @@
+export type StaticPathResult = {
+    readonly ok: true;
+    readonly fsPath: string;
+} | {
+    readonly ok: false;
+};
+/**
+ * Resolve a URL remainder to a filesystem path under `root`, or reject.
+ * Rejections are uniform (the caller answers 404, no existence leak).
+ */
+export declare function resolveStaticPath(root: string, rawRest: string, opts: {
+    readonly dotfiles: 'deny' | 'allow';
+}): StaticPathResult;
+//# sourceMappingURL=staticPath.d.ts.map

package/dist/http/static/staticPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticPath.d.ts","sourceRoot":"","sources":["../../../src/http/static/staticPath.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAyBvG;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAC5C,gBAAgB,CAoBlB"}

package/dist/http/static/staticPath.js

@@ -0,0 +1,67 @@
+/**
+ * Path-traversal defence for the static-file directives — the security
+ * core.  The URL remainder is fully decoded (peeling every encoding layer)
+ * BEFORE validation, every segment is checked, and the joined path is
+ * confined to the root.  Mirrors the rules in
+ * `src/persistence/storage/KeyValidator.ts` (kept local to avoid a
+ * src/http → src/persistence layering dependency).
+ */
+import { join, resolve, sep } from 'node:path';
+const REJECT = { ok: false };
+/** Peel up to a few URL-encoding layers so validation sees the real value. */
+function fullyDecode(input) {
+    let current = input;
+    for (let i = 0; i < 3; i++) {
+        let next;
+        try {
+            next = decodeURIComponent(current);
+        }
+        catch {
+            return current;
+        } // malformed % → keep as-is
+        if (next === current)
+            return current;
+        current = next;
+    }
+    return current;
+}
+function isUnsafeSegment(segment, allowDotfiles) {
+    if (segment === '' || segment === '.' || segment === '..')
+        return true;
+    if (segment.includes('\0'))
+        return true;
+    if (segment.includes('/') || segment.includes('\\'))
+        return true; // defensive (post-split)
+    if (segment.includes(':'))
+        return true; // Windows drive / NTFS alternate data stream
+    if (!allowDotfiles && segment.startsWith('.'))
+        return true;
+    return false;
+}
+/**
+ * Resolve a URL remainder to a filesystem path under `root`, or reject.
+ * Rejections are uniform (the caller answers 404, no existence leak).
+ */
+export function resolveStaticPath(root, rawRest, opts) {
+    const decoded = fullyDecode(rawRest);
+    if (decoded.includes('\0'))
+        return REJECT;
+    // Absolute forms (POSIX root, Windows drive) never come from a rest-path.
+    if (decoded.startsWith('/') || decoded.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(decoded))
+        return REJECT;
+    const trimmed = decoded.replace(/\/+$/, ''); // tolerate one trailing slash (directory marker)
+    const segments = trimmed.length === 0 ? [] : trimmed.split(/[/\\]/);
+    const allowDotfiles = opts.dotfiles === 'allow';
+    for (const segment of segments) {
+        if (isUnsafeSegment(segment, allowDotfiles))
+            return REJECT;
+    }
+    const fsPath = join(root, ...segments);
+    // Confinement: the resolved path must be the root itself or beneath it.
+    const resolvedRoot = resolve(root);
+    const resolvedPath = resolve(fsPath);
+    if (resolvedPath !== resolvedRoot && !resolvedPath.startsWith(resolvedRoot + sep))
+        return REJECT;
+    return { ok: true, fsPath };
+}
+//# sourceMappingURL=staticPath.js.map

package/dist/http/static/staticPath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticPath.js","sourceRoot":"","sources":["../../../src/http/static/staticPath.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAI/C,MAAM,MAAM,GAAqB,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AAE/C,8EAA8E;AAC9E,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YAAC,IAAI,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,OAAO,CAAC;QAAC,CAAC,CAAC,2BAA2B;QACjG,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,OAAO,CAAC;QACrC,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,eAAe,CAAC,OAAe,EAAE,aAAsB;IAC9D,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACvE,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,yBAAyB;IAC3F,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,6CAA6C;IACrF,IAAI,CAAC,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,OAAe,EACf,IAA6C;IAE7C,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IAC1C,0EAA0E;IAC1E,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC;IAE1G,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,iDAAiD;IAC9F,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACpE,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC;IAChD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,eAAe,CAAC,OAAO,EAAE,aAAa,CAAC;YAAE,OAAO,MAAM,CAAC;IAC7D,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;IACvC,wEAAwE;IACxE,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,IAAI,YAAY,KAAK,YAAY,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,YAAY,GAAG,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IAEjG,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC"}

package/dist/http/types.d.ts

@@ -13,12 +13,26 @@ export interface HttpRequest {
     readonly params: Readonly<Record<string, string>>;
     /** Raw bytes of the request body (undefined for GET / HEAD). */
     readonly body: Uint8Array | null;
+    /**
+     * Optional remote IP address of the client as the server saw it
+     * (NOT the value of `x-forwarded-for` — that's a header the client
+     * can spoof unless a trusted proxy stripped + replaced it).  Backends
+     * SHOULD populate this from the underlying socket peer; consumers
+     * that need to trust a forwarded header MUST do so explicitly (see
+     * `IpAllowlist`'s `getClientIp` option).
+     */
+    readonly remoteAddress?: string;
 }
 export interface HttpResponse {
     readonly status: number;
     readonly headers?: Readonly<Record<string, string>>;
-    /** Body — if string or JSON object, the marshaller adds Content-Type. */
-    readonly body?: string | Uint8Array | object | null;
+    /**
+     * Body.  A string or plain object is marshalled (JSON) with a
+     * Content-Type; a `Uint8Array` or web `ReadableStream` is sent as raw
+     * bytes (default `application/octet-stream`).  Streams are one-shot, so
+     * the caching middleware must not wrap a streaming response.
+     */
+    readonly body?: string | Uint8Array | ReadableStream<Uint8Array> | object | null;
     /** Forced content-type.  Overrides whatever the marshaller picks. */
     readonly contentType?: string;
 }
@@ -49,6 +63,22 @@ export declare const Status: {
 export declare class HttpError extends Error {
     readonly status: number;
     readonly extra?: Readonly<Record<string, unknown>> | undefined;
-    constructor(status: number, message: string, extra?: Readonly<Record<string, unknown>> | undefined);
+    /**
+     * Response headers to emit alongside the error — e.g.
+     * `WWW-Authenticate` on a 401 or `Retry-After` on a 429.  Without
+     * this the value could only reach the body (`extra`), never the
+     * wire as a real header.  Names SHOULD be lower-case; backends emit
+     * them verbatim after the status and before the body.
+     */
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    constructor(status: number, message: string, extra?: Readonly<Record<string, unknown>> | undefined, 
+    /**
+     * Response headers to emit alongside the error — e.g.
+     * `WWW-Authenticate` on a 401 or `Retry-After` on a 429.  Without
+     * this the value could only reach the body (`extra`), never the
+     * wire as a real header.  Names SHOULD be lower-case; backends emit
+     * them verbatim after the status and before the body.
+     */
+    headers?: Readonly<Record<string, string>> | undefined);
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/http/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;IACxE,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IACpD,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,yEAAyE;AACzE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;IAejB,gGAAgG;;;;;;CAMxF,CAAC;AAEX,4EAA4E;AAC5E,qBAAa,SAAU,SAAQ,KAAK;aAEhB,MAAM,EAAE,MAAM;aAEd,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAFzC,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,YAAA;CAK5D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;IACxE,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IACjF,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,yEAAyE;AACzE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;IAejB,gGAAgG;;;;;;CAMxF,CAAC;AAEX,4EAA4E;AAC5E,qBAAa,SAAU,SAAQ,KAAK;aAEhB,MAAM,EAAE,MAAM;aAEd,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzD;;;;;;OAMG;aACa,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAV1C,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,YAAA;IACzD;;;;;;OAMG;IACa,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,YAAA;CAK7D"}

package/dist/http/types.js

@@ -30,10 +30,20 @@ export const Status = {
 export class HttpError extends Error {
     status;
     extra;
-    constructor(status, message, extra) {
+    headers;
+    constructor(status, message, extra, 
+    /**
+     * Response headers to emit alongside the error — e.g.
+     * `WWW-Authenticate` on a 401 or `Retry-After` on a 429.  Without
+     * this the value could only reach the body (`extra`), never the
+     * wire as a real header.  Names SHOULD be lower-case; backends emit
+     * them verbatim after the status and before the body.
+     */
+    headers) {
         super(message);
         this.status = status;
         this.extra = extra;
+        this.headers = headers;
         this.name = 'HttpError';
     }
 }

package/dist/http/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwBH,yEAAyE;AACzE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,EAAE,EAAE,GAAG;IACP,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,SAAS,EAAE,GAAG;IACd,gBAAgB,EAAE,GAAG;IACrB,KAAK,EAAE,GAAG;IACV,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,GAAG;IACf,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,gBAAgB,EAAE,GAAG;IACrB,QAAQ,EAAE,GAAG;IACb,oBAAoB,EAAE,GAAG;IACzB,gGAAgG;IAChG,mBAAmB,EAAE,GAAG;IACxB,eAAe,EAAE,GAAG;IACpB,mBAAmB,EAAE,GAAG;IACxB,UAAU,EAAE,GAAG;IACf,kBAAkB,EAAE,GAAG;CACf,CAAC;AAEX,4EAA4E;AAC5E,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEhB;IAEA;IAHlB,YACkB,MAAc,EAC9B,OAAe,EACC,KAAyC;QAEzD,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAQ;QAEd,UAAK,GAAL,KAAK,CAAoC;QAGzD,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/http/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsCH,yEAAyE;AACzE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,EAAE,EAAE,GAAG;IACP,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,SAAS,EAAE,GAAG;IACd,gBAAgB,EAAE,GAAG;IACrB,KAAK,EAAE,GAAG;IACV,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,GAAG;IACf,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,gBAAgB,EAAE,GAAG;IACrB,QAAQ,EAAE,GAAG;IACb,oBAAoB,EAAE,GAAG;IACzB,gGAAgG;IAChG,mBAAmB,EAAE,GAAG;IACxB,eAAe,EAAE,GAAG;IACpB,mBAAmB,EAAE,GAAG;IACxB,UAAU,EAAE,GAAG;IACf,kBAAkB,EAAE,GAAG;CACf,CAAC;AAEX,4EAA4E;AAC5E,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEhB;IAEA;IAQA;IAXlB,YACkB,MAAc,EAC9B,OAAe,EACC,KAAyC;IACzD;;;;;;OAMG;IACa,OAA0C;QAE1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAZC,WAAM,GAAN,MAAM,CAAQ;QAEd,UAAK,GAAL,KAAK,CAAoC;QAQzC,YAAO,GAAP,OAAO,CAAmC;QAG1D,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/http/websocket/ConnectionWiring.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared connection-wiring layer.  Everything that turns an accepted
+ * upgrade into a live actor-backed connection lives here, so the three
+ * HTTP backends stay thin (they only produce a
+ * {@link WebsocketSocketAdapter}).
+ *
+ * This file grows across the WebSocket work:
+ *   - {@link ConnectionTracker} / {@link trackSocket} — shutdown bookkeeping
+ *     (used by `HttpExtension.bind`'s unbind path).
+ *   - `wireConnection` — spawns the per-connection session actor and
+ *     attaches listeners synchronously (added with the actor layer).
+ */
+import type { ActorSystem } from '../../ActorSystem.js';
+import type { HttpRequest } from '../types.js';
+import type { WebsocketSocketAdapter } from './SocketAdapter.js';
+import { type WebsocketServerRef } from './WebsocketMessages.js';
+import type { WebsocketCodec } from './WebsocketCodec.js';
+import type { ResolvedWebsocketPolicy } from './WebsocketPolicy.js';
+/**
+ * Tracks the live server-side sockets of one binding so `unbind()` can
+ * close them.  Without this a long-lived WebSocket keeps the HTTP
+ * server's `close()` pending forever (the process refuses to exit).
+ */
+export declare class ConnectionTracker {
+    private readonly sockets;
+    add(socket: WebsocketSocketAdapter): void;
+    remove(socket: WebsocketSocketAdapter): void;
+    get size(): number;
+    /** Send a polite close frame to every tracked socket (best-effort). */
+    closeAll(code?: number, reason?: string): void;
+    /** Hard-terminate every tracked socket and forget them all (shutdown). */
+    terminateAll(): void;
+}
+/**
+ * Register `socket` with `tracker` and return a thin wrapper whose
+ * `setListeners` chains tracker removal into `onClose`.  The tracker
+ * always holds the *original* socket, so `closeAll` / `terminateAll`
+ * act on the real thing; the wrapper only ensures we stop tracking a
+ * socket once it closes on its own.
+ */
+export declare function trackSocket(tracker: ConnectionTracker, socket: WebsocketSocketAdapter): WebsocketSocketAdapter;
+/**
+ * Turn one accepted upgrade into a live actor-backed connection.  Called
+ * synchronously from the backend's upgrade callback (via the route's
+ * `connect` handler).
+ *
+ * It does NOT spawn or attach anything itself — instead it tells the hub
+ * a {@link WebsocketAcceptCommand} carrying the per-connection actor's `Props`, so
+ * the hub spawns that actor as its OWN child (`server → conn-N`).  The
+ * child then creates the {@link WebsocketConnection}, reports `connected`, and
+ * attaches the socket listeners in its `preStart`.
+ *
+ * First-frame race: the socket adapter attaches its native listeners
+ * synchronously at upgrade and BUFFERS inbound frames until the child's
+ * `setListeners` runs — so nothing is lost between upgrade and the child
+ * becoming ready.
+ */
+export declare function wireConnection<TOut, TIn, TSelf = never>(_system: ActorSystem, hub: WebsocketServerRef<TOut, TIn, TSelf>, req: HttpRequest, socket: WebsocketSocketAdapter, codec: WebsocketCodec<TOut, TIn>, policy: ResolvedWebsocketPolicy): void;
+//# sourceMappingURL=ConnectionWiring.d.ts.map

package/dist/http/websocket/ConnectionWiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectionWiring.d.ts","sourceRoot":"","sources":["../../../src/http/websocket/ConnectionWiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAA0B,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,GAAG,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAIzC,MAAM,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAI5C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,uEAAuE;IACvE,QAAQ,CAAC,IAAI,SAAO,EAAE,MAAM,SAAK,GAAG,IAAI;IAUxC,0EAA0E;IAC1E,YAAY,IAAI,IAAI;CAWrB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,sBAAsB,GAC7B,sBAAsB,CA2BxB;AAuCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,EACrD,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EACzC,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,EAChC,MAAM,EAAE,uBAAuB,GAC9B,IAAI,CAgCN"}

package/dist/http/websocket/ConnectionWiring.js

@@ -0,0 +1,165 @@
+import { Props } from '../../Props.js';
+import { websocketAcceptCommand } from './WebsocketMessages.js';
+import { WebsocketConnectionActor } from './WebsocketConnectionActor.js';
+/**
+ * Tracks the live server-side sockets of one binding so `unbind()` can
+ * close them.  Without this a long-lived WebSocket keeps the HTTP
+ * server's `close()` pending forever (the process refuses to exit).
+ */
+export class ConnectionTracker {
+    sockets = new Set();
+    add(socket) {
+        this.sockets.add(socket);
+    }
+    remove(socket) {
+        this.sockets.delete(socket);
+    }
+    get size() {
+        return this.sockets.size;
+    }
+    /** Send a polite close frame to every tracked socket (best-effort). */
+    closeAll(code = 1000, reason = '') {
+        for (const socket of this.sockets) {
+            try {
+                socket.close(code, reason);
+            }
+            catch {
+                /* already closing / closed */
+            }
+        }
+    }
+    /** Hard-terminate every tracked socket and forget them all (shutdown). */
+    terminateAll() {
+        for (const socket of this.sockets) {
+            try {
+                if (socket.terminate)
+                    socket.terminate();
+                else
+                    socket.close(1001, 'going away');
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        this.sockets.clear();
+    }
+}
+/**
+ * Register `socket` with `tracker` and return a thin wrapper whose
+ * `setListeners` chains tracker removal into `onClose`.  The tracker
+ * always holds the *original* socket, so `closeAll` / `terminateAll`
+ * act on the real thing; the wrapper only ensures we stop tracking a
+ * socket once it closes on its own.
+ */
+export function trackSocket(tracker, socket) {
+    tracker.add(socket);
+    return {
+        send: (data) => socket.send(data),
+        close: (code, reason) => socket.close(code, reason),
+        terminate: socket.terminate ? () => socket.terminate() : undefined,
+        setListeners: (l) => {
+            socket.setListeners({
+                onMessage: (data) => l.onMessage(data),
+                onClose: (code, reason) => {
+                    tracker.remove(socket);
+                    l.onClose(code, reason);
+                },
+                onError: (err) => l.onError(err),
+            });
+        },
+        get readyState() {
+            return socket.readyState;
+        },
+        bufferedAmount: socket.bufferedAmount ? () => socket.bufferedAmount() : undefined,
+        get remoteAddress() {
+            return socket.remoteAddress;
+        },
+        get protocol() {
+            return socket.protocol;
+        },
+    };
+}
+let connectionCounter = 0;
+/**
+ * Live connection count per hub, for the per-route `maxConnections` cap
+ * (security audit WS-5).  Keyed by the hub ref (one per route); increments
+ * when a connection is admitted and decrements when its socket closes.  A
+ * `WeakMap` so a discarded hub doesn't leak its counter.
+ */
+const liveConnectionsByHub = new WeakMap();
+/**
+ * Wrap `socket` so `onClosed` runs exactly once when it closes — used to
+ * decrement the live-connection count.  Mirrors {@link trackSocket}'s onClose
+ * chaining.
+ */
+function decrementOnClose(socket, onClosed) {
+    let fired = false;
+    const fire = () => { if (!fired) {
+        fired = true;
+        onClosed();
+    } };
+    return {
+        send: (data) => socket.send(data),
+        close: (code, reason) => socket.close(code, reason),
+        terminate: socket.terminate ? () => socket.terminate() : undefined,
+        setListeners: (l) => socket.setListeners({
+            onMessage: (data) => l.onMessage(data),
+            onClose: (code, reason) => { fire(); l.onClose(code, reason); },
+            onError: (err) => l.onError(err),
+        }),
+        get readyState() { return socket.readyState; },
+        bufferedAmount: socket.bufferedAmount ? () => socket.bufferedAmount() : undefined,
+        get remoteAddress() { return socket.remoteAddress; },
+        get protocol() { return socket.protocol; },
+    };
+}
+/**
+ * Turn one accepted upgrade into a live actor-backed connection.  Called
+ * synchronously from the backend's upgrade callback (via the route's
+ * `connect` handler).
+ *
+ * It does NOT spawn or attach anything itself — instead it tells the hub
+ * a {@link WebsocketAcceptCommand} carrying the per-connection actor's `Props`, so
+ * the hub spawns that actor as its OWN child (`server → conn-N`).  The
+ * child then creates the {@link WebsocketConnection}, reports `connected`, and
+ * attaches the socket listeners in its `preStart`.
+ *
+ * First-frame race: the socket adapter attaches its native listeners
+ * synchronously at upgrade and BUFFERS inbound frames until the child's
+ * `setListeners` runs — so nothing is lost between upgrade and the child
+ * becoming ready.
+ */
+export function wireConnection(_system, hub, req, socket, codec, policy) {
+    // Admission cap (security audit WS-5): when the route is at its
+    // connection limit, close the freshly-upgraded socket with 1013 ("try
+    // again later") instead of wiring an actor for it.  Unlimited by default
+    // (`policy.maxConnections === Infinity`).
+    const cap = policy.maxConnections;
+    if (Number.isFinite(cap)) {
+        const hubKey = hub;
+        const live = liveConnectionsByHub.get(hubKey) ?? 0;
+        if (live >= cap) {
+            try {
+                socket.close(1013, 'server at capacity');
+            }
+            catch { /* already closing */ }
+            return;
+        }
+        liveConnectionsByHub.set(hubKey, live + 1);
+        socket = decrementOnClose(socket, () => {
+            liveConnectionsByHub.set(hubKey, Math.max(0, (liveConnectionsByHub.get(hubKey) ?? 1) - 1));
+        });
+    }
+    const id = `ws-${++connectionCounter}`;
+    const upgrade = {
+        path: req.path,
+        params: req.params,
+        query: req.query,
+        headers: req.headers,
+        remoteAddress: req.remoteAddress ?? socket.remoteAddress,
+        subprotocol: socket.protocol,
+    };
+    const props = Props.create(() => new WebsocketConnectionActor({ socket, codec, policy, hub, id, upgrade }));
+    hub.tell(websocketAcceptCommand(props, id), null);
+}
+//# sourceMappingURL=ConnectionWiring.js.map

package/dist/http/websocket/ConnectionWiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectionWiring.js","sourceRoot":"","sources":["../../../src/http/websocket/ConnectionWiring.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,OAAO,EAAE,sBAAsB,EAA2B,MAAM,wBAAwB,CAAC;AACzF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAKzE;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IACX,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE7D,GAAG,CAAC,MAA8B;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,MAA8B;QACnC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,uEAAuE;IACvE,QAAQ,CAAC,IAAI,GAAG,IAAI,EAAE,MAAM,GAAG,EAAE;QAC/B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC7B,CAAC;YAAC,MAAM,CAAC;gBACP,8BAA8B;YAChC,CAAC;QACH,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,YAAY;QACV,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,IAAI,MAAM,CAAC,SAAS;oBAAE,MAAM,CAAC,SAAS,EAAE,CAAC;;oBACpC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;YACxC,CAAC;YAAC,MAAM,CAAC;gBACP,kBAAkB;YACpB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,OAA0B,EAC1B,MAA8B;IAE9B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,OAAO;QACL,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QACjC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC;QACnD,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,SAAU,EAAE,CAAC,CAAC,CAAC,SAAS;QACnE,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE;YAClB,MAAM,CAAC,YAAY,CAAC;gBAClB,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;gBACtC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;oBACxB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBACvB,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBAC1B,CAAC;gBACD,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;aACjC,CAAC,CAAC;QACL,CAAC;QACD,IAAI,UAAU;YACZ,OAAO,MAAM,CAAC,UAAU,CAAC;QAC3B,CAAC;QACD,cAAc,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,cAAe,EAAE,CAAC,CAAC,CAAC,SAAS;QAClF,IAAI,aAAa;YACf,OAAO,MAAM,CAAC,aAAa,CAAC;QAC9B,CAAC;QACD,IAAI,QAAQ;YACV,OAAO,MAAM,CAAC,QAAQ,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,IAAI,iBAAiB,GAAG,CAAC,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAAkB,CAAC;AAE3D;;;;GAIG;AACH,SAAS,gBAAgB,CACvB,MAA8B,EAC9B,QAAoB;IAEpB,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,MAAM,IAAI,GAAG,GAAS,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAAC,KAAK,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,CAAC;IAAC,CAAC,CAAC,CAAC,CAAC;IACvE,OAAO;QACL,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QACjC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC;QACnD,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,SAAU,EAAE,CAAC,CAAC,CAAC,SAAS;QACnE,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC;YACvC,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;YACtC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;YAC/D,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;SACjC,CAAC;QACF,IAAI,UAAU,KAAK,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QAC9C,cAAc,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,cAAe,EAAE,CAAC,CAAC,CAAC,SAAS;QAClF,IAAI,aAAa,KAAK,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;QACpD,IAAI,QAAQ,KAAK,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAoB,EACpB,GAAyC,EACzC,GAAgB,EAChB,MAA8B,EAC9B,KAAgC,EAChC,MAA+B;IAE/B,gEAAgE;IAChE,sEAAsE;IACtE,yEAAyE;IACzE,0CAA0C;IAC1C,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,CAAC;IAClC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,GAAwB,CAAC;QACxC,MAAM,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,IAAI,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC;gBAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;YACjF,OAAO;QACT,CAAC;QACD,oBAAoB,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;QAC3C,MAAM,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE;YACrC,oBAAoB,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC7F,CAAC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACvC,MAAM,OAAO,GAAyB;QACpC,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,MAAM,CAAC,aAAa;QACxD,WAAW,EAAE,MAAM,CAAC,QAAQ;KAC7B,CAAC;IAEF,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CACxB,GAAG,EAAE,CAAC,IAAI,wBAAwB,CAAmB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAClG,CAAC;IACF,GAAG,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAkC,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;AACjF,CAAC"}

package/dist/http/websocket/SocketAdapter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Backend-agnostic socket surface.  Each HTTP backend maps its native
+ * WebSocket (the `ws` package's socket for Fastify/Express, Hono's
+ * `WSContext`) onto a {@link WebsocketSocketAdapter}, and the shared
+ * connection-wiring layer drives everything through this one shape — so
+ * frame decoding, size caps, codec handling and lifecycle live in ONE
+ * place regardless of backend.
+ */
+/**
+ * Listeners the framework attaches to a socket.  The backend adapter
+ * must guarantee that no inbound frame is delivered before
+ * {@link WebsocketSocketAdapter.setListeners} returns (attach natively
+ * in the same synchronous tick, or buffer until then) — this is what
+ * closes the "first frame lost" race by construction.
+ */
+export interface WebsocketListeners {
+    /** One inbound frame, already normalised to text (`string`) or binary (`Uint8Array`). */
+    onMessage(data: string | Uint8Array): void;
+    onClose(code: number, reason: string): void;
+    onError(err: Error): void;
+}
+/** W3C-style readyState values. */
+export declare const WebsocketReadyState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+export interface WebsocketSocketAdapter {
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    /** Hard-kill without a close handshake (shutdown).  Falls back to `close()` if absent. */
+    terminate?(): void;
+    /** Single-shot listener attach — see {@link WebsocketListeners}. */
+    setListeners(l: WebsocketListeners): void;
+    readonly readyState: 0 | 1 | 2 | 3;
+    /** Bytes queued in the peer send buffer, when the backend can report it. */
+    bufferedAmount?(): number;
+    readonly remoteAddress?: string;
+    /** Negotiated `Sec-WebSocket-Protocol`, when known. */
+    readonly protocol?: string;
+}
+/**
+ * The `ws` package socket surface (used by `@fastify/websocket`,
+ * plain `ws.WebSocketServer`, and `@hono/node-ws`).  Only the members
+ * we touch are declared — the peer dep is optional.
+ */
+export interface WebsocketPackageSocket {
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    terminate?(): void;
+    on(event: 'message', cb: (data: unknown, isBinary: boolean) => void): void;
+    on(event: 'close', cb: (code: number, reason: unknown) => void): void;
+    on(event: 'error', cb: (err: unknown) => void): void;
+    readonly bufferedAmount?: number;
+    readonly readyState?: number;
+    readonly protocol?: string;
+}
+/**
+ * Adapt a `ws`-package socket (already upgraded) to a
+ * {@link WebsocketSocketAdapter}.  Native `socket.on(...)` listeners are
+ * attached **immediately** (synchronously at upgrade) and inbound events
+ * are BUFFERED until `setListeners` runs — because the per-connection
+ * actor attaches its listeners a mailbox-tick later, and `ws` would drop
+ * events that arrive with no `'message'` listener.  `isBinary` from `ws`
+ * decides text-vs-binary delivery.
+ */
+export declare function websocketPackageAdapter(socket: WebsocketPackageSocket, opts?: {
+    readonly remoteAddress?: string;
+    readonly protocol?: string;
+}): WebsocketSocketAdapter;
+//# sourceMappingURL=SocketAdapter.d.ts.map

package/dist/http/websocket/SocketAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocketAdapter.d.ts","sourceRoot":"","sources":["../../../src/http/websocket/SocketAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,yFAAyF;IACzF,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAC3C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC;CAC3B;AAED,mCAAmC;AACnC,eAAO,MAAM,mBAAmB;;;;;CAKtB,CAAC;AAEX,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,0FAA0F;IAC1F,SAAS,CAAC,IAAI,IAAI,CAAC;IACnB,oEAAoE;IACpE,YAAY,CAAC,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,4EAA4E;IAC5E,cAAc,CAAC,IAAI,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,SAAS,CAAC,IAAI,IAAI,CAAC;IACnB,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3E,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IACtE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,sBAAsB,EAC9B,IAAI,GAAE;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACzE,sBAAsB,CAwCxB"}

package/dist/http/websocket/SocketAdapter.js

@@ -0,0 +1,97 @@
+/**
+ * Backend-agnostic socket surface.  Each HTTP backend maps its native
+ * WebSocket (the `ws` package's socket for Fastify/Express, Hono's
+ * `WSContext`) onto a {@link WebsocketSocketAdapter}, and the shared
+ * connection-wiring layer drives everything through this one shape — so
+ * frame decoding, size caps, codec handling and lifecycle live in ONE
+ * place regardless of backend.
+ */
+/** W3C-style readyState values. */
+export const WebsocketReadyState = {
+    CONNECTING: 0,
+    OPEN: 1,
+    CLOSING: 2,
+    CLOSED: 3,
+};
+function coerceBinary(data) {
+    if (data instanceof Uint8Array)
+        return data; // Node Buffer is a Uint8Array
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (Array.isArray(data)) {
+        const total = data.reduce((n, b) => n + b.byteLength, 0);
+        const merged = new Uint8Array(total);
+        let off = 0;
+        for (const part of data) {
+            const u8 = new Uint8Array(part);
+            merged.set(u8, off);
+            off += u8.byteLength;
+        }
+        return merged;
+    }
+    return new Uint8Array(0);
+}
+function coerceText(data) {
+    if (typeof data === 'string')
+        return data;
+    const bytes = coerceBinary(data);
+    return new TextDecoder('utf-8', { fatal: false }).decode(bytes);
+}
+/**
+ * Adapt a `ws`-package socket (already upgraded) to a
+ * {@link WebsocketSocketAdapter}.  Native `socket.on(...)` listeners are
+ * attached **immediately** (synchronously at upgrade) and inbound events
+ * are BUFFERED until `setListeners` runs — because the per-connection
+ * actor attaches its listeners a mailbox-tick later, and `ws` would drop
+ * events that arrive with no `'message'` listener.  `isBinary` from `ws`
+ * decides text-vs-binary delivery.
+ */
+export function websocketPackageAdapter(socket, opts = {}) {
+    let listeners = null;
+    const pending = [];
+    socket.on('message', (data, isBinary) => {
+        const norm = isBinary ? coerceBinary(data) : coerceText(data);
+        if (listeners)
+            listeners.onMessage(norm);
+        else
+            pending.push({ t: 'message', data: norm });
+    });
+    socket.on('close', (code, reason) => {
+        const closeCode = typeof code === 'number' ? code : 1005;
+        const reasonText = reason == null ? '' : String(reason);
+        if (listeners)
+            listeners.onClose(closeCode, reasonText);
+        else
+            pending.push({ t: 'close', code: closeCode, reason: reasonText });
+    });
+    socket.on('error', (err) => {
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (listeners)
+            listeners.onError(error);
+        else
+            pending.push({ t: 'error', err: error });
+    });
+    return {
+        send: (data) => socket.send(data),
+        close: (code, reason) => socket.close(code, reason),
+        terminate: socket.terminate ? () => socket.terminate() : undefined,
+        setListeners: (l) => {
+            listeners = l;
+            for (const ev of pending.splice(0)) {
+                if (ev.t === 'message')
+                    l.onMessage(ev.data);
+                else if (ev.t === 'close')
+                    l.onClose(ev.code, ev.reason);
+                else
+                    l.onError(ev.err);
+            }
+        },
+        get readyState() {
+            return (socket.readyState ?? WebsocketReadyState.OPEN);
+        },
+        bufferedAmount: () => socket.bufferedAmount ?? 0,
+        remoteAddress: opts.remoteAddress,
+        protocol: opts.protocol ?? socket.protocol,
+    };
+}
+//# sourceMappingURL=SocketAdapter.js.map

package/dist/http/websocket/SocketAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocketAdapter.js","sourceRoot":"","sources":["../../../src/http/websocket/SocketAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,mCAAmC;AACnC,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,UAAU,EAAE,CAAC;IACb,IAAI,EAAE,CAAC;IACP,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,CAAC;CACD,CAAC;AAkCX,SAAS,YAAY,CAAC,IAAa;IACjC,IAAI,IAAI,YAAY,UAAU;QAAE,OAAO,IAAI,CAAC,CAAC,8BAA8B;IAC3E,IAAI,IAAI,YAAY,WAAW;QAAE,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAC7D,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAS,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAI,CAA4B,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QAC7F,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YACxB,MAAM,EAAE,GAAG,IAAI,UAAU,CAAC,IAAuB,CAAC,CAAC;YACnD,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YACpB,GAAG,IAAI,EAAE,CAAC,UAAU,CAAC;QACvB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,UAAU,CAAC,IAAa;IAC/B,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAOD;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAA8B,EAC9B,OAAwE,EAAE;IAE1E,IAAI,SAAS,GAA8B,IAAI,CAAC;IAChD,MAAM,OAAO,GAAoB,EAAE,CAAC;IAEpC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE;QACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC9D,IAAI,SAAS;YAAE,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;;YACpC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;QAClC,MAAM,SAAS,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACzD,MAAM,UAAU,GAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,SAAS;YAAE,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;;YACnD,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;QACzB,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,IAAI,SAAS;YAAE,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;;YACnC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QACjC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC;QACnD,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,SAAU,EAAE,CAAC,CAAC,CAAC,SAAS;QACnE,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE;YAClB,SAAS,GAAG,CAAC,CAAC;YACd,KAAK,MAAM,EAAE,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnC,IAAI,EAAE,CAAC,CAAC,KAAK,SAAS;oBAAE,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;qBACxC,IAAI,EAAE,CAAC,CAAC,KAAK,OAAO;oBAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;;oBACpD,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QACD,IAAI,UAAU;YACZ,OAAO,CAAC,MAAM,CAAC,UAAU,IAAI,mBAAmB,CAAC,IAAI,CAAkB,CAAC;QAC1E,CAAC;QACD,cAAc,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC;QAChD,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ;KAC3C,CAAC;AACJ,CAAC"}