@asenajs/ergenecore 3.2.1 → 5.0.0

package/dist/lib/middlewares/RateLimiterMiddleware.d.ts

@@ -91,10 +91,11 @@ export interface RateLimiterOptions {
     /**
      * Custom key generator function
      *
-     * By default, uses IP address from X-Forwarded-For header or remote address.
+     * By default, identifies the client by the connecting peer, or by the client hop of
+     * `X-Forwarded-For` when `trustProxy` trusts the peer.
      * You can customize this to use user ID, API key, or any other identifier.
      *
-     * @default (ctx) => ctx.req.headers.get('x-forwarded-for') || 'unknown'
+     * @default (ctx) => ctx.getRequestIp() ?? 'unknown'
      *
      * @example
      * ```typescript
@@ -106,6 +107,38 @@ export interface RateLimiterOptions {
      * ```
      */
     keyGenerator?: (context: Context) => string;
+    /**
+     * Which connecting peers are reverse proxies whose `X-Forwarded-For` may be believed.
+     *
+     * - `false` (default): the connecting peer (`getRequestIp()`) is the client; the header is ignored.
+     * - `true`: one proxy layer in front of the server. The header is read and its rightmost entry - the
+     *   one the proxy appended - is the client. Also the right setting when the server listens on a unix
+     *   socket (no peer address to check).
+     * - `string[]`: exact addresses of the trusted proxies. An IPv4 address matches whether it is written
+     *   plain (`'10.0.0.1'`) or IPv4-mapped (`'::ffff:10.0.0.1'`, how Bun reports it on a dual-stack
+     *   listener), in the list, the peer and the forwarded hops alike. Entries are walked from the right;
+     *   the first one not in the list is the client.
+     * - `(address) => boolean`: same walk with a predicate (CIDR checks live here).
+     *
+     * A hop the client wrote itself (`X-Forwarded-For: <forged>, <real>`) is never selected: selection
+     * starts from the right and stops at the first untrusted address.
+     *
+     * Both misconfigurations below fail closed - every client lands in one bucket:
+     * - `true` behind two or more proxy layers keys on the outer proxy (the rightmost hop); list every
+     *   proxy, or use a predicate, instead.
+     * - A trusted peer that sends no usable `X-Forwarded-For` keys on the peer itself; logged once.
+     *
+     * @default false
+     */
+    trustProxy?: boolean | string[] | ((address: string) => boolean);
+    /**
+     * Upper bound on distinct client buckets held in memory. When a new client arrives at the cap, the
+     * least recently seen bucket is evicted - that client starts over with a full bucket.
+     * Must be a positive integer; the constructor throws otherwise.
+     *
+     * @default 10000
+     */
+    maxBuckets?: number;
     /**
      * Custom message for rate limit exceeded response
      *
@@ -232,6 +265,14 @@ export declare class RateLimiterMiddleware extends MiddlewareService {
      * Client key generator function
      */
     private readonly keyGenerator;
+    /**
+     * Trusted reverse proxies whose `X-Forwarded-For` may be believed
+     */
+    private readonly trustProxy;
+    /**
+     * Upper bound on distinct client buckets held in memory
+     */
+    private readonly maxBuckets;
     /**
      * Rate limit exceeded message
      */
@@ -256,6 +297,7 @@ export declare class RateLimiterMiddleware extends MiddlewareService {
      * Bucket TTL in milliseconds
      */
     private readonly bucketTTL;
+    private warnedNoForwardedFor;
     /**
      * Creates a new rate limiter middleware instance
      *
@@ -321,12 +363,40 @@ export declare class RateLimiterMiddleware extends MiddlewareService {
      */
     clearBuckets(): void;
     /**
-     * Default key generator - uses X-Forwarded-For or falls back to 'unknown'
+     * Default key generator - the connecting peer, see `trustProxy`
      *
      * @param context - Ergenecore context
      * @returns Client identifier
      */
     private defaultKeyGenerator;
+    /**
+     * Resolve the client identifier: the connecting peer, or the client hop of `X-Forwarded-For`
+     * when the peer is a trusted proxy
+     *
+     * @param context - Ergenecore context
+     * @returns Client identifier
+     */
+    private resolveClientKey;
+    /**
+     * Warn, once per instance, that a trusted peer forwarded no usable `X-Forwarded-For`
+     *
+     * @param peer - The trusted peer address
+     */
+    private warnNoForwardedFor;
+    /**
+     * Whether an address is a reverse proxy whose forwarded hops may be believed
+     *
+     * @param address - Peer or forwarded hop address
+     * @returns True when the address is trusted
+     */
+    private trusts;
+    /**
+     * Parse `X-Forwarded-For` into its hops, left to right
+     *
+     * @param context - Ergenecore context
+     * @returns The forwarded hops, or an empty list when the header is absent or over-long
+     */
+    private forwardedHops;
     /**
      * Setup automatic cleanup of inactive buckets
      *

package/dist/lib/middlewares/RateLimiterMiddleware.js

@@ -57,6 +57,9 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { MiddlewareService } from '../defaults';
 import { OnStop } from '@asenajs/asena/decorators/ioc';
+const MAX_FORWARDED_HEADER_LENGTH = 1024;
+const IPV4_MAPPED_PREFIX = /^::ffff:(?=\d{1,3}(?:\.\d{1,3}){3}$)/i;
+const unmapIPv4 = (address) => address.replace(IPV4_MAPPED_PREFIX, '');
 /**
  * Rate Limiter Middleware
  *
@@ -122,6 +125,14 @@ export class RateLimiterMiddleware extends MiddlewareService {
      * Client key generator function
      */
     keyGenerator;
+    /**
+     * Trusted reverse proxies whose `X-Forwarded-For` may be believed
+     */
+    trustProxy;
+    /**
+     * Upper bound on distinct client buckets held in memory
+     */
+    maxBuckets;
     /**
      * Rate limit exceeded message
      */
@@ -146,6 +157,7 @@ export class RateLimiterMiddleware extends MiddlewareService {
      * Bucket TTL in milliseconds
      */
     bucketTTL;
+    warnedNoForwardedFor = false;
     /**
      * Creates a new rate limiter middleware instance
      *
@@ -173,6 +185,11 @@ export class RateLimiterMiddleware extends MiddlewareService {
         this.capacity = options.capacity ?? 100;
         this.refillRate = options.refillRate ?? 10;
         this.keyGenerator = options.keyGenerator ?? this.defaultKeyGenerator;
+        this.trustProxy = options.trustProxy ?? false;
+        this.maxBuckets = options.maxBuckets ?? 10_000;
+        if (!Number.isInteger(this.maxBuckets) || this.maxBuckets < 1) {
+            throw new Error(`RateLimiterMiddleware: maxBuckets must be a positive integer, got ${this.maxBuckets}`);
+        }
         this.message = options.message ?? 'Rate limit exceeded. Please try again later.';
         this.statusCode = options.statusCode ?? 429;
         this.cost = options.cost ?? 1;
@@ -208,13 +225,19 @@ export class RateLimiterMiddleware extends MiddlewareService {
         const key = this.keyGenerator(context);
         // Get or create bucket
         let bucket = this.buckets.get(key);
-        if (!bucket) {
+        if (bucket) {
+            this.buckets.delete(key);
+        }
+        else {
             bucket = {
                 tokens: this.capacity,
                 lastRefill: Date.now(),
             };
-            this.buckets.set(key, bucket);
+            if (this.buckets.size >= this.maxBuckets) {
+                this.buckets.delete(this.buckets.keys().next().value);
+            }
         }
+        this.buckets.set(key, bucket);
         // Refill tokens based on elapsed time
         const now = Date.now();
         const elapsedSeconds = (now - bucket.lastRefill) / 1000;
@@ -284,17 +307,82 @@ export class RateLimiterMiddleware extends MiddlewareService {
         this.buckets.clear();
     }
     /**
-     * Default key generator - uses X-Forwarded-For or falls back to 'unknown'
+     * Default key generator - the connecting peer, see `trustProxy`
      *
      * @param context - Ergenecore context
      * @returns Client identifier
      */
     defaultKeyGenerator = (context) => {
-        return (context.req.headers.get('x-forwarded-for') ||
-            context.req.headers.get('cf-connecting-ip') ||
-            context.getRequestIp?.() ||
-            'unknown');
+        return this.resolveClientKey(context);
     };
+    /**
+     * Resolve the client identifier: the connecting peer, or the client hop of `X-Forwarded-For`
+     * when the peer is a trusted proxy
+     *
+     * @param context - Ergenecore context
+     * @returns Client identifier
+     */
+    resolveClientKey(context) {
+        const peer = context.getRequestIp();
+        if (!this.trusts(peer)) {
+            return peer ?? 'unknown';
+        }
+        const hops = this.forwardedHops(context);
+        if (!hops.length) {
+            this.warnNoForwardedFor(peer);
+            return peer ?? 'unknown';
+        }
+        for (let i = hops.length - 1; i >= 0; i--) {
+            if (!this.trusts(hops[i])) {
+                return hops[i];
+            }
+        }
+        return hops.at(-1);
+    }
+    /**
+     * Warn, once per instance, that a trusted peer forwarded no usable `X-Forwarded-For`
+     *
+     * @param peer - The trusted peer address
+     */
+    warnNoForwardedFor(peer) {
+        if (this.warnedNoForwardedFor)
+            return;
+        this.warnedNoForwardedFor = true;
+        console.warn(`RateLimiterMiddleware: trusted proxy ${peer ?? '(no peer address)'} sent no usable X-Forwarded-For; ` +
+            'every client behind it shares one bucket. Make the proxy append X-Forwarded-For or narrow trustProxy.');
+    }
+    /**
+     * Whether an address is a reverse proxy whose forwarded hops may be believed
+     *
+     * @param address - Peer or forwarded hop address
+     * @returns True when the address is trusted
+     */
+    trusts(address) {
+        if (this.trustProxy === true)
+            return true;
+        if (!this.trustProxy || address === null)
+            return false;
+        if (!Array.isArray(this.trustProxy))
+            return this.trustProxy(address);
+        const normalized = unmapIPv4(address);
+        return this.trustProxy.some((entry) => unmapIPv4(entry) === normalized);
+    }
+    /**
+     * Parse `X-Forwarded-For` into its hops, left to right
+     *
+     * @param context - Ergenecore context
+     * @returns The forwarded hops, or an empty list when the header is absent or over-long
+     */
+    forwardedHops(context) {
+        const header = context.req.headers.get('x-forwarded-for');
+        if (!header || header.length > MAX_FORWARDED_HEADER_LENGTH) {
+            return [];
+        }
+        return header
+            .split(',')
+            .map((hop) => hop.trim())
+            .filter(Boolean);
+    }
     /**
      * Setup automatic cleanup of inactive buckets
      *

package/dist/lib/middlewares/RateLimiterMiddleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"RateLimiterMiddleware.js","sourceRoot":"","sources":["../../../lib/middlewares/RateLimiterMiddleware.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RateLimiterMiddleware.js","sourceRoot":"","sources":["../../../lib/middlewares/RateLimiterMiddleware.ts"],"names":[],"mappings":"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"}

package/dist/lib/middlewares/WebSocketOriginMiddleware.d.ts

@@ -0,0 +1,82 @@
+/**
+ * WebSocket Origin Middleware for Ergenecore
+ *
+ * Closes the cross-site WebSocket hijacking hole by:
+ * - Rejecting a handshake whose `Origin` is not allowed, before `server.upgrade()`
+ * - Deciding explicitly what happens when there is no `Origin` at all
+ * - Zero external dependencies (uses Bun's native APIs)
+ *
+ * @module defaults/WebSocketOriginMiddleware
+ *
+ * @example
+ * ```typescript
+ * import { Middleware, WebSocket } from '@asenajs/asena/decorators';
+ * import { WebSocketOriginMiddleware } from '@asenajs/ergenecore';
+ *
+ * @Middleware()
+ * export class ChatOrigin extends WebSocketOriginMiddleware {
+ *   constructor() {
+ *     super({ allowedOrigins: ['https://app.example.com'] });
+ *   }
+ * }
+ *
+ * @WebSocket({ path: 'chat', middlewares: [ChatOrigin, SessionAuth] })
+ * export class ChatSocket { ... }
+ * ```
+ */
+import type { Context } from '../ErgenecoreContextWrapper';
+import { MiddlewareService } from '../defaults';
+/**
+ * WebSocket origin policy options
+ */
+export interface WebSocketOriginOptions {
+    /** Origins allowed to open a WebSocket: exact `Origin` header values, or a predicate. */
+    allowedOrigins: string[] | ((origin: string) => boolean);
+    /**
+     * Accept handshakes that carry no `Origin` header (non-browser clients). Browsers always send one,
+     * so the default rejects: a missing header is not evidence of a first-party page.
+     *
+     * @default false
+     */
+    allowMissingOrigin?: boolean;
+}
+/**
+ * WebSocket Origin Middleware
+ *
+ * Use it as a `@WebSocket({ middlewares: [...] })` middleware, listed **before** any cookie-based
+ * auth middleware: the browser attaches cookies to a cross-site handshake, so a session is already
+ * authenticated by the time an auth middleware looks at it.
+ *
+ * `CorsMiddleware` is not a WebSocket origin policy - it sets response headers a browser applies to
+ * `fetch`/XHR, and a disallowed origin still upgrades.
+ *
+ * The `Origin` header is compared exactly: `'https://app.example.com'`, scheme included, no trailing
+ * slash.
+ *
+ * It is an ordinary middleware, so on an HTTP route it would reject every request without an
+ * `Origin` - which is why the name says WebSocket.
+ *
+ * @example
+ * ```typescript
+ * // A predicate covers wildcard subdomains; there is no '*' special value
+ * new WebSocketOriginMiddleware({ allowedOrigins: (origin) => origin.endsWith('.example.com') });
+ * ```
+ */
+export declare class WebSocketOriginMiddleware extends MiddlewareService {
+    private readonly allowedOrigins;
+    private readonly allowMissingOrigin;
+    /**
+     * Creates a new WebSocket origin middleware instance
+     *
+     * @param options - Origin policy options
+     */
+    constructor(options: WebSocketOriginOptions);
+    /**
+     * Reject the handshake unless its `Origin` is allowed
+     *
+     * @param context - Ergenecore context wrapper
+     * @param next - Function to call next middleware or handler
+     * @returns A 403 response, or the result of next() for an allowed origin
+     */
+    handle(context: Context, next: () => Promise<void>): Promise<any>;
+}

package/dist/lib/middlewares/WebSocketOriginMiddleware.js

@@ -0,0 +1,81 @@
+/**
+ * WebSocket Origin Middleware for Ergenecore
+ *
+ * Closes the cross-site WebSocket hijacking hole by:
+ * - Rejecting a handshake whose `Origin` is not allowed, before `server.upgrade()`
+ * - Deciding explicitly what happens when there is no `Origin` at all
+ * - Zero external dependencies (uses Bun's native APIs)
+ *
+ * @module defaults/WebSocketOriginMiddleware
+ *
+ * @example
+ * ```typescript
+ * import { Middleware, WebSocket } from '@asenajs/asena/decorators';
+ * import { WebSocketOriginMiddleware } from '@asenajs/ergenecore';
+ *
+ * @Middleware()
+ * export class ChatOrigin extends WebSocketOriginMiddleware {
+ *   constructor() {
+ *     super({ allowedOrigins: ['https://app.example.com'] });
+ *   }
+ * }
+ *
+ * @WebSocket({ path: 'chat', middlewares: [ChatOrigin, SessionAuth] })
+ * export class ChatSocket { ... }
+ * ```
+ */
+import { MiddlewareService } from '../defaults';
+/**
+ * WebSocket Origin Middleware
+ *
+ * Use it as a `@WebSocket({ middlewares: [...] })` middleware, listed **before** any cookie-based
+ * auth middleware: the browser attaches cookies to a cross-site handshake, so a session is already
+ * authenticated by the time an auth middleware looks at it.
+ *
+ * `CorsMiddleware` is not a WebSocket origin policy - it sets response headers a browser applies to
+ * `fetch`/XHR, and a disallowed origin still upgrades.
+ *
+ * The `Origin` header is compared exactly: `'https://app.example.com'`, scheme included, no trailing
+ * slash.
+ *
+ * It is an ordinary middleware, so on an HTTP route it would reject every request without an
+ * `Origin` - which is why the name says WebSocket.
+ *
+ * @example
+ * ```typescript
+ * // A predicate covers wildcard subdomains; there is no '*' special value
+ * new WebSocketOriginMiddleware({ allowedOrigins: (origin) => origin.endsWith('.example.com') });
+ * ```
+ */
+export class WebSocketOriginMiddleware extends MiddlewareService {
+    allowedOrigins;
+    allowMissingOrigin;
+    /**
+     * Creates a new WebSocket origin middleware instance
+     *
+     * @param options - Origin policy options
+     */
+    constructor(options) {
+        super();
+        this.allowedOrigins = options.allowedOrigins;
+        this.allowMissingOrigin = options.allowMissingOrigin ?? false;
+    }
+    /**
+     * Reject the handshake unless its `Origin` is allowed
+     *
+     * @param context - Ergenecore context wrapper
+     * @param next - Function to call next middleware or handler
+     * @returns A 403 response, or the result of next() for an allowed origin
+     */
+    async handle(context, next) {
+        const origin = context.req.headers.get('Origin');
+        if (!origin) {
+            return this.allowMissingOrigin ? await next() : new Response('Forbidden', { status: 403 });
+        }
+        const allowed = Array.isArray(this.allowedOrigins)
+            ? this.allowedOrigins.includes(origin)
+            : this.allowedOrigins(origin);
+        return allowed ? await next() : new Response('Forbidden', { status: 403 });
+    }
+}
+//# sourceMappingURL=WebSocketOriginMiddleware.js.map

package/dist/lib/middlewares/WebSocketOriginMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketOriginMiddleware.js","sourceRoot":"","sources":["../../../lib/middlewares/WebSocketOriginMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAkBhD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,yBAA0B,SAAQ,iBAAiB;IAC7C,cAAc,CAA2C;IAEzD,kBAAkB,CAAU;IAE7C;;;;OAIG;IACH,YAAmB,OAA+B;QAChD,KAAK,EAAE,CAAC;QAER,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,IAAI,KAAK,CAAC;IAChE,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,MAAM,CAAC,OAAgB,EAAE,IAAyB;QAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEjD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAC7F,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC;YAChD,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC;YACtC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAEhC,OAAO,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IAC7E,CAAC;CACF"}

package/dist/lib/stream/SSEStreamWriter.js

@@ -5,19 +5,28 @@ import { StreamWriter } from './StreamWriter';
  */
 export class SSEStreamWriter extends StreamWriter {
     async writeSSE(message) {
-        const dataLines = message.data
-            .split(/\r\n|\r|\n/)
-            .map((line) => `data: ${line}`)
-            .join('\n');
-        const sseData = [
-            message.event && `event: ${message.event}`,
-            dataLines,
-            message.id && `id: ${message.id}`,
-            message.retry && `retry: ${message.retry}`,
-        ]
-            .filter(Boolean)
-            .join('\n') + '\n\n';
-        await this.write(sseData);
+        if (message.data === undefined && message.comment === undefined) {
+            throw new Error('writeSSE: message needs data or comment');
+        }
+        const lines = [];
+        for (const line of message.comment?.split(/\r\n|\r|\n/) ?? []) {
+            lines.push(`: ${line}`);
+        }
+        if (message.event) {
+            lines.push(`event: ${message.event}`);
+        }
+        if (message.data !== undefined) {
+            for (const line of message.data.split(/\r\n|\r|\n/)) {
+                lines.push(`data: ${line}`);
+            }
+        }
+        if (message.id) {
+            lines.push(`id: ${message.id}`);
+        }
+        if (message.retry) {
+            lines.push(`retry: ${message.retry}`);
+        }
+        await this.write(lines.join('\n') + '\n\n');
     }
 }
 //# sourceMappingURL=SSEStreamWriter.js.map

package/dist/lib/stream/SSEStreamWriter.js.map

@@ -1 +1 @@
-{"version":3,"file":"SSEStreamWriter.js","sourceRoot":"","sources":["../../../lib/stream/SSEStreamWriter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,YAAY;IACxC,KAAK,CAAC,QAAQ,CAAC,OAAmB;QACvC,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI;aAC3B,KAAK,CAAC,YAAY,CAAC;aACnB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC;aAC9B,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,MAAM,OAAO,GACX;YACE,OAAO,CAAC,KAAK,IAAI,UAAU,OAAO,CAAC,KAAK,EAAE;YAC1C,SAAS;YACT,OAAO,CAAC,EAAE,IAAI,OAAO,OAAO,CAAC,EAAE,EAAE;YACjC,OAAO,CAAC,KAAK,IAAI,UAAU,OAAO,CAAC,KAAK,EAAE;SAC3C;aACE,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;QAEzB,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;CACF"}
+{"version":3,"file":"SSEStreamWriter.js","sourceRoot":"","sources":["../../../lib/stream/SSEStreamWriter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,YAAY;IACxC,KAAK,CAAC,QAAQ,CAAC,OAAmB;QACvC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAChE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC7D,CAAC;QAED,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC;YAC9D,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC1B,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,UAAU,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACxC,CAAC;QAED,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;gBACpD,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,UAAU,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACxC,CAAC;QAED,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;IAC9C,CAAC;CACF"}

package/dist/lib/utils/staticFileReader.d.ts

@@ -0,0 +1,27 @@
+import { type Stats } from 'fs';
+export declare function staticFileHeaders(type: string, etag: string, lastModified: string): Headers;
+export interface StaticFileRead {
+    readonly bytes: Uint8Array<ArrayBuffer> | undefined;
+    readonly type: string;
+    readonly etag: string;
+    readonly lastModified: string;
+}
+export declare function regularFileStats(filePath: string): Stats | undefined;
+/**
+ * Reads small regular files from disk on every call through a bounded set of open descriptors.
+ * Nothing but the descriptor and derived metadata outlives a call; the bytes are always fresh.
+ */
+export declare class StaticFileReader {
+    private readonly maxFileBytes;
+    private readonly maxOpen;
+    private readonly files;
+    constructor(maxFileBytes?: number, maxOpen?: number);
+    read(filePath: string, stats: Stats, withBody: boolean): StaticFileRead;
+    respond(filePath: string, stats: Stats, withBody: boolean): Response;
+    private refresh;
+    release(filePath: string): void;
+    close(): void;
+    private readBytes;
+    private entry;
+    private forget;
+}