xypriss 9.11.13 → 9.12.0

package/dist/src/server/components/static/XStatic.d.ts

@@ -0,0 +1,218 @@
+/***************************************************************************
+ * XyPriss - Fast And Secure
+ *
+ * XStatic - High-Performance, Sandboxed Static File Serving.
+ * Optimized with Meta-Cache (LRU) and XHSC (Go) Zero-Copy delegation.
+ ***************************************************************************/
+import { XyPrissXHSC } from "../../../xhsc";
+import { XyApp } from "../../../types/XyApp.type";
+import { StaticOptions } from "./types";
+/**
+ * **XStatic** — High-performance, sandboxed static file server for XyPriss.
+ *
+ * XStatic handles static asset delivery through a two-layer architecture:
+ *
+ * 1. **TypeScript layer** — responsible for URI normalization, dotfile/sandbox
+ *    security enforcement, and LRU meta-cache (anti-DDoS I/O shield).
+ * 2. **XHSC (Go) layer** — takes over once the request is validated, streaming
+ *    the file directly from disk to the TCP socket using zero-copy (`sendfile`),
+ *    native ETags, `304 Not Modified`, and `206 Partial Content` (Range requests).
+ *
+ * ### Architectural Flow
+ * ```
+ * Request
+ *   → URI Normalization
+ *   → Dotfile / Restricted File Check
+ *   → Sandbox Enforcement (Project Root + Directory Jail)
+ *   → LRU Meta-Cache (negative cache — blocks repeated 404 storms)
+ *   → Filesystem Existence Check
+ *   → XHSC Zero-Copy Delegation (Go)
+ *   → Response
+ * ```
+ *
+ * ### Basic Usage
+ * ```typescript
+ * import { XStatic } from "xypriss";
+ *
+ * const app  = createServer(options);
+ * const xs   = new XStatic(app, __sys__);
+ *
+ * xs.define("/assets", "./public");
+ * xs.define("/docs",   "./documentation");
+ *
+ * // Explicit opt-out of sandbox (e.g. user-upload directory)
+ * xs.define("/avatars", "/var/www/uploads/avatars", {
+ *   allowOutsideRoot: true,
+ *   unsafe: true,
+ * });
+ * ```
+ *
+ * ### Global Configuration (via `createServer`)
+ * ```typescript
+ * const app = createServer({
+ *   static: {
+ *     zeroCopy:       true,   // Enable sendfile() syscall in XHSC
+ *     ConcurrencyPool: 1024,  // Max goroutines for disk I/O
+ *     lruCacheSize:   5000,   // Entries kept in negative meta-cache
+ *     dotfiles:       "deny", // Block .env, .git, etc.
+ *     defaultMaxAge:  86400,  // Default Cache-Control max-age (seconds)
+ *   },
+ * });
+ * ```
+ *
+ * @remarks
+ * XStatic is **instance-scoped** by design. Avoid singleton patterns when
+ * running under XMS (XyPriss MultiServer) to prevent cross-instance route
+ * leakage and memory pressure.
+ *
+ * @see {@link StaticOptions}  for per-route configuration.
+ * @see {@link IXStatic}       for global configuration shape.
+ * @see {@link XStaticMetaCache} for LRU cache implementation details.
+ */
+export declare class XStatic {
+    private app;
+    private sys;
+    private metaCache;
+    private pendingStats;
+    private logger;
+    private qLog;
+    private globalConfig;
+    /**
+     * Creates a new `XStatic` instance bound to the given server and system API.
+     *
+     * Reads the `"static"` key from the application config (`Configs.get`),
+     * initialises the LRU meta-cache with the configured size (default: **5 000**
+     * entries), and wires up internal loggers.
+     *
+     * @param app - The XyPriss application instance to register middleware on.
+     * @param sys - The XHSC system handle (`__sys__`), which exposes the sandboxed
+     *   `fs` and `path` APIs as well as the project root (`__root__`).
+     *
+     * @throws {Error} If the global `"static"` configuration block fails Zod schema
+     *   validation (see {@link validateConfigs}).
+     *
+     * @example
+     * ```typescript
+     * const xs = new XStatic(app, __sys__);
+     * ```
+     */
+    constructor(app: XyApp, sys: XyPrissXHSC);
+    /**
+     * Validates the global static configuration block at startup.
+     *
+     * Performs two sequential checks:
+     *
+     * 1. **Dotfiles type guard** — ensures `dotfiles` is either `"allow"` or
+     *    `"deny"` when provided as a plain string.
+     * 2. **Zod schema validation** — runs `IXStaticSchem.safeParse` against the
+     *    full config object to catch unknown or malformed fields.
+     *
+     * @throws {Error} `"Invalid configuration for 'dotfiles'"` — if `dotfiles` is
+     *   present but not a string.
+     * @throws {Error} `"Invalid dotfiles mode. Expected one of 'allow' or 'deny',
+     *   but got: '<value>'"` — if the dotfiles string is not a recognised mode.
+     * @throws {Error} Zod validation message — if the config object fails the
+     *   `IXStaticSchem` schema.
+     *
+     * @internal
+     */
+    private validateConfigs;
+    /**
+     * Registers a static file route on the application.
+     *
+     * Mounts an async middleware on `route` that handles the full request
+     * lifecycle: URI normalization → dotfile/restricted-file protection →
+     * sandbox enforcement → LRU cache lookup → filesystem check →
+     * XHSC zero-copy delegation.
+     *
+     * ---
+     *
+     * ### Security Layers
+     *
+     * **1 — Dotfile & Restricted File Protection**
+     *
+     * Controlled by `globalConfig.dotfiles` (default: `"deny"`). When in deny
+     * mode, any file whose name starts with `"."` (e.g. `.env`, `.git`) or
+     * appears in a custom restricted list is rejected with `403 Forbidden` before
+     * any disk access occurs.
+     *
+     * **2 — Sandbox Enforcement** *(skipped when `options.unsafe` or
+     * `options.allowOutsideRoot` is `true`)*
+     *
+     * - **Project Root Check** — the resolved `dir` must be inside the project
+     *   root (`sys.__root__`). Prevents accidentally serving system directories.
+     * - **Directory Jail** — the resolved request path must be strictly inside
+     *   `dir`. Blocks path-traversal attacks (`../../etc/passwd`).
+     *
+     * **3 — LRU Meta-Cache (Anti-DDoS I/O Shield)**
+     *
+     * Paths that have previously resolved to `"not found"` are cached in memory.
+     * Subsequent requests for the same missing path are rejected at the cache
+     * layer — zero disk I/O, pure RAM response — protecting against flood
+     * attacks that enumerate non-existent files.
+     *
+     * ---
+     *
+     * ### Zero-Copy Delegation to XHSC (Go)
+     *
+     * Once a request passes all validation steps, TypeScript sends a single IPC
+     * signal to the XHSC worker: `"request #<id> may read <absolutePath>"`.
+     * XHSC then streams the file directly from disk to the client TCP socket
+     * using `sendfile()`, bypassing the V8/Node.js heap entirely. HTTP-level
+     * concerns (ETag generation, `304 Not Modified`, `206 Partial Content` for
+     * Range requests) are all handled natively by Go's `http.ServeContent`.
+     *
+     * ---
+     *
+     * @param route - The URL prefix to mount (e.g. `"/assets"`). Automatically
+     *   normalised via {@link UriNormalizer.normalizePath}.
+     * @param dir   - The filesystem directory to serve from (e.g. `"./public"`).
+     *   Relative paths are resolved against the process working directory.
+     * @param options - Optional per-route overrides. See {@link StaticOptions}.
+     *
+     * @returns `void` — the middleware is registered as a side effect.
+     *
+     * @throws This method does not throw. Internal errors are caught, logged via
+     *   the application logger, and forwarded to `next()` so the request chain
+     *   can continue (or fall through to a global error handler).
+     *
+     * @example
+     * ```typescript
+     * // Serve ./public under /assets (fully sandboxed, dotfiles denied)
+     * xs.define("/assets", "./public");
+     *
+     * // Custom Cache-Control for long-lived build artefacts (1 week)
+     * xs.define("/dist", "./build", { maxAge: 604800 });
+     *
+     * // User-uploaded content outside the project root (explicit opt-out)
+     * xs.define("/uploads", "/var/www/uploads", {
+     *   allowOutsideRoot: true,
+     *   unsafe: true,
+     * });
+     * ```
+     *
+     * @see {@link StaticOptions} for the full list of per-route options.
+     * @see {@link serve} for the deprecated alias.
+     */
+    define(route: string, dir: string, options?: StaticOptions): void;
+    /**
+     * @deprecated Use {@link define} instead. Will be removed in a future release.
+     *
+     * Alias for {@link define} — kept for beta compatibility only.
+     *
+     * @param route   - The URL prefix to mount (e.g. `"/assets"`).
+     * @param dir     - The filesystem directory to serve from.
+     * @param options - Optional per-route overrides. See {@link StaticOptions}.
+     *
+     * @example
+     * ```typescript
+     * // ❌ Deprecated — avoid in new code
+     * xs.serve("/assets", "./public");
+     *
+     * // ✅ Preferred
+     * xs.define("/assets", "./public");
+     * ```
+     */
+    serve(_route: string, _dir: string, _options?: StaticOptions): void;
+}
+//# sourceMappingURL=XStatic.d.ts.map

package/dist/src/server/components/static/XStatic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XStatic.d.ts","sourceRoot":"","sources":["../../../../../src/server/components/static/XStatic.ts"],"names":[],"mappings":"AAAA;;;;;6EAK6E;AAG7E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAIlD,OAAO,EAA0B,aAAa,EAAE,MAAM,SAAS,CAAC;AAMhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,qBAAa,OAAO;IA4BZ,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,GAAG;IA5Bf,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,YAAY,CAAwC;IAC5D,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,IAAI,CAAqC;IAEjD,OAAO,CAAC,YAAY,CAAW;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;gBAES,GAAG,EAAE,KAAK,EACV,GAAG,EAAE,WAAW;IAgB5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,eAAe;IA4BvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4EG;IACI,MAAM,CACT,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,aAAkB,GAC5B,IAAI;IAqLP;;;;;;;;;;;;;;;;;OAiBG;IACI,KAAK,CACR,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,aAAkB,GAC7B,IAAI;CAUV"}

package/dist/src/server/components/static/XStatic.js

@@ -0,0 +1,388 @@
+/***************************************************************************
+ * XyPriss - Fast And Secure
+ *
+ * XStatic - High-Performance, Sandboxed Static File Serving.
+ * Optimized with Meta-Cache (LRU) and XHSC (Go) Zero-Copy delegation.
+ ***************************************************************************/
+import { Logger } from "../../../shared/logger/Logger";
+import { UriNormalizer } from "../../../middleware/built-in/security/UriNormalizer";
+import { Configs } from "../../..";
+import { IXStaticSchem } from "./IXStaticSchem";
+import { QuickLogger } from "../../../shared/logger/quickLogger";
+import { XStaticMetaCache } from "./MetaCache";
+import { stat } from "node:fs/promises";
+/**
+ * **XStatic** — High-performance, sandboxed static file server for XyPriss.
+ *
+ * XStatic handles static asset delivery through a two-layer architecture:
+ *
+ * 1. **TypeScript layer** — responsible for URI normalization, dotfile/sandbox
+ *    security enforcement, and LRU meta-cache (anti-DDoS I/O shield).
+ * 2. **XHSC (Go) layer** — takes over once the request is validated, streaming
+ *    the file directly from disk to the TCP socket using zero-copy (`sendfile`),
+ *    native ETags, `304 Not Modified`, and `206 Partial Content` (Range requests).
+ *
+ * ### Architectural Flow
+ * ```
+ * Request
+ *   → URI Normalization
+ *   → Dotfile / Restricted File Check
+ *   → Sandbox Enforcement (Project Root + Directory Jail)
+ *   → LRU Meta-Cache (negative cache — blocks repeated 404 storms)
+ *   → Filesystem Existence Check
+ *   → XHSC Zero-Copy Delegation (Go)
+ *   → Response
+ * ```
+ *
+ * ### Basic Usage
+ * ```typescript
+ * import { XStatic } from "xypriss";
+ *
+ * const app  = createServer(options);
+ * const xs   = new XStatic(app, __sys__);
+ *
+ * xs.define("/assets", "./public");
+ * xs.define("/docs",   "./documentation");
+ *
+ * // Explicit opt-out of sandbox (e.g. user-upload directory)
+ * xs.define("/avatars", "/var/www/uploads/avatars", {
+ *   allowOutsideRoot: true,
+ *   unsafe: true,
+ * });
+ * ```
+ *
+ * ### Global Configuration (via `createServer`)
+ * ```typescript
+ * const app = createServer({
+ *   static: {
+ *     zeroCopy:       true,   // Enable sendfile() syscall in XHSC
+ *     ConcurrencyPool: 1024,  // Max goroutines for disk I/O
+ *     lruCacheSize:   5000,   // Entries kept in negative meta-cache
+ *     dotfiles:       "deny", // Block .env, .git, etc.
+ *     defaultMaxAge:  86400,  // Default Cache-Control max-age (seconds)
+ *   },
+ * });
+ * ```
+ *
+ * @remarks
+ * XStatic is **instance-scoped** by design. Avoid singleton patterns when
+ * running under XMS (XyPriss MultiServer) to prevent cross-instance route
+ * leakage and memory pressure.
+ *
+ * @see {@link StaticOptions}  for per-route configuration.
+ * @see {@link IXStatic}       for global configuration shape.
+ * @see {@link XStaticMetaCache} for LRU cache implementation details.
+ */
+export class XStatic {
+    /**
+     * Creates a new `XStatic` instance bound to the given server and system API.
+     *
+     * Reads the `"static"` key from the application config (`Configs.get`),
+     * initialises the LRU meta-cache with the configured size (default: **5 000**
+     * entries), and wires up internal loggers.
+     *
+     * @param app - The XyPriss application instance to register middleware on.
+     * @param sys - The XHSC system handle (`__sys__`), which exposes the sandboxed
+     *   `fs` and `path` APIs as well as the project root (`__root__`).
+     *
+     * @throws {Error} If the global `"static"` configuration block fails Zod schema
+     *   validation (see {@link validateConfigs}).
+     *
+     * @example
+     * ```typescript
+     * const xs = new XStatic(app, __sys__);
+     * ```
+     */
+    constructor(app, sys) {
+        this.app = app;
+        this.sys = sys;
+        this.pendingStats = new Map();
+        this.globalConfig = Configs.get("static") || {};
+        this.metaCache = new XStaticMetaCache(this.globalConfig.lruCacheSize || 5000);
+        this.logger = app.logger || Logger.getInstance();
+        this.qLog = QuickLogger.for("XStatic");
+        this.logger.debug("server", "XStatic initialized with Zero-Copy delegation support.");
+        this.validateConfigs();
+    }
+    /**
+     * Validates the global static configuration block at startup.
+     *
+     * Performs two sequential checks:
+     *
+     * 1. **Dotfiles type guard** — ensures `dotfiles` is either `"allow"` or
+     *    `"deny"` when provided as a plain string.
+     * 2. **Zod schema validation** — runs `IXStaticSchem.safeParse` against the
+     *    full config object to catch unknown or malformed fields.
+     *
+     * @throws {Error} `"Invalid configuration for 'dotfiles'"` — if `dotfiles` is
+     *   present but not a string.
+     * @throws {Error} `"Invalid dotfiles mode. Expected one of 'allow' or 'deny',
+     *   but got: '<value>'"` — if the dotfiles string is not a recognised mode.
+     * @throws {Error} Zod validation message — if the config object fails the
+     *   `IXStaticSchem` schema.
+     *
+     * @internal
+     */
+    validateConfigs() {
+        const c = this.globalConfig;
+        const sdc = ["allow", "deny"];
+        if (c.dotfiles != null &&
+            !["string", "string"].includes(typeof c.dotfiles)) {
+            throw new Error("Invalid configuration for 'dotfiles'");
+        }
+        if (c.dotfiles &&
+            typeof c.dotfiles === "string" &&
+            !sdc.includes(c.dotfiles)) {
+            throw new Error(`Invalid dotfiles mode. Expected one of ${sdc.map((s) => `'${s}'`).join(" or ")}, but got: '${c.dotfiles}'`);
+        }
+        const validatedConfigs = IXStaticSchem.safeParse(this.globalConfig);
+        if (!validatedConfigs.success) {
+            throw new Error(validatedConfigs.errors[0].message);
+        }
+    }
+    /**
+     * Registers a static file route on the application.
+     *
+     * Mounts an async middleware on `route` that handles the full request
+     * lifecycle: URI normalization → dotfile/restricted-file protection →
+     * sandbox enforcement → LRU cache lookup → filesystem check →
+     * XHSC zero-copy delegation.
+     *
+     * ---
+     *
+     * ### Security Layers
+     *
+     * **1 — Dotfile & Restricted File Protection**
+     *
+     * Controlled by `globalConfig.dotfiles` (default: `"deny"`). When in deny
+     * mode, any file whose name starts with `"."` (e.g. `.env`, `.git`) or
+     * appears in a custom restricted list is rejected with `403 Forbidden` before
+     * any disk access occurs.
+     *
+     * **2 — Sandbox Enforcement** *(skipped when `options.unsafe` or
+     * `options.allowOutsideRoot` is `true`)*
+     *
+     * - **Project Root Check** — the resolved `dir` must be inside the project
+     *   root (`sys.__root__`). Prevents accidentally serving system directories.
+     * - **Directory Jail** — the resolved request path must be strictly inside
+     *   `dir`. Blocks path-traversal attacks (`../../etc/passwd`).
+     *
+     * **3 — LRU Meta-Cache (Anti-DDoS I/O Shield)**
+     *
+     * Paths that have previously resolved to `"not found"` are cached in memory.
+     * Subsequent requests for the same missing path are rejected at the cache
+     * layer — zero disk I/O, pure RAM response — protecting against flood
+     * attacks that enumerate non-existent files.
+     *
+     * ---
+     *
+     * ### Zero-Copy Delegation to XHSC (Go)
+     *
+     * Once a request passes all validation steps, TypeScript sends a single IPC
+     * signal to the XHSC worker: `"request #<id> may read <absolutePath>"`.
+     * XHSC then streams the file directly from disk to the client TCP socket
+     * using `sendfile()`, bypassing the V8/Node.js heap entirely. HTTP-level
+     * concerns (ETag generation, `304 Not Modified`, `206 Partial Content` for
+     * Range requests) are all handled natively by Go's `http.ServeContent`.
+     *
+     * ---
+     *
+     * @param route - The URL prefix to mount (e.g. `"/assets"`). Automatically
+     *   normalised via {@link UriNormalizer.normalizePath}.
+     * @param dir   - The filesystem directory to serve from (e.g. `"./public"`).
+     *   Relative paths are resolved against the process working directory.
+     * @param options - Optional per-route overrides. See {@link StaticOptions}.
+     *
+     * @returns `void` — the middleware is registered as a side effect.
+     *
+     * @throws This method does not throw. Internal errors are caught, logged via
+     *   the application logger, and forwarded to `next()` so the request chain
+     *   can continue (or fall through to a global error handler).
+     *
+     * @example
+     * ```typescript
+     * // Serve ./public under /assets (fully sandboxed, dotfiles denied)
+     * xs.define("/assets", "./public");
+     *
+     * // Custom Cache-Control for long-lived build artefacts (1 week)
+     * xs.define("/dist", "./build", { maxAge: 604800 });
+     *
+     * // User-uploaded content outside the project root (explicit opt-out)
+     * xs.define("/uploads", "/var/www/uploads", {
+     *   allowOutsideRoot: true,
+     *   unsafe: true,
+     * });
+     * ```
+     *
+     * @see {@link StaticOptions} for the full list of per-route options.
+     * @see {@link serve} for the deprecated alias.
+     */
+    define(route, dir, options = {}) {
+        const normalizedRoute = UriNormalizer.normalizePath(route);
+        const resolvedDir = this.sys.path.resolve(dir);
+        const projectRoot = this.sys.__root__;
+        // Synchronous Sandbox Check (Project Root Violation)
+        if (!options.allowOutsideRoot && !options.unsafe && projectRoot) {
+            if (!resolvedDir.startsWith(projectRoot)) {
+                this.qLog.warn(`Blocked attempt to mount static directory outside project root: ${resolvedDir}`);
+                throw new Error(`Forbidden: Project Root Violation for path ${resolvedDir}`);
+            }
+        }
+        // XHSC Fast Path: Queue route for Go native interception before Node.js execution
+        const goRoutePath = normalizedRoute === "/" ? "/*filepath" : `${normalizedRoute}/*filepath`;
+        XStatic._routesToSync = XStatic._routesToSync || [];
+        XStatic._routesToSync.push({
+            goRoutePath,
+            resolvedDir
+        });
+        // Middleware registration (Fallback / Node.js standard path)
+        this.app.use(normalizedRoute, async (req, res, next) => {
+            try {
+                // 1. Path Calculation (Strip mount point)
+                let relativePath = req.path;
+                if (req.path === normalizedRoute) {
+                    relativePath = "/";
+                }
+                else {
+                    const prefix = normalizedRoute.endsWith("/")
+                        ? normalizedRoute
+                        : `${normalizedRoute}/`;
+                    if (req.path.startsWith(prefix)) {
+                        relativePath = req.path.substring(normalizedRoute.length);
+                    }
+                }
+                // Remove leading slash for join/basename operations
+                const cleanRelative = relativePath.startsWith("/")
+                    ? relativePath.substring(1)
+                    : relativePath;
+                const fileName = cleanRelative.split("/").pop() || "";
+                // 2. Dotfile & Restricted File Protection (Global Policy)
+                const dotfileConfig = this.globalConfig.dotfiles || "deny";
+                const dotfileMode = typeof dotfileConfig === "object"
+                    ? dotfileConfig.mode
+                    : dotfileConfig;
+                const customRestricted = typeof dotfileConfig === "object"
+                    ? dotfileConfig.custom || []
+                    : [];
+                if (dotfileMode === "deny") {
+                    const isRestricted = fileName.startsWith(".") ||
+                        customRestricted.includes(fileName);
+                    if (isRestricted) {
+                        this.qLog.warn(
+                        // "security",
+                        `Blocked attempt to access restricted file: ${fileName}`);
+                        res.status(403).end("Forbidden: Access Denied");
+                        return next();
+                    }
+                }
+                const fullPath = this.sys.path.join(dir, relativePath);
+                // 3. Path Normalization & Security Check (Sandbox)
+                const resolvedPath = this.sys.path.resolve(fullPath);
+                const rootDir = this.sys.path.resolve(dir);
+                const projectRoot = this.sys.__root__;
+                if (!options.allowOutsideRoot &&
+                    !options.unsafe &&
+                    projectRoot) {
+                    // Check 1: Is the defined directory inside the project root?
+                    if (!rootDir.startsWith(projectRoot)) {
+                        this.qLog.warn(
+                        //    "security",
+                        `Blocked attempt to serve directory outside project root: ${rootDir}`);
+                        res.status(403).end("Forbidden: Project Root Violation");
+                        return next();
+                    }
+                    // Check 2: Is the requested file inside the defined directory? (Standard Jail)
+                    if (!resolvedPath.startsWith(rootDir)) {
+                        this.qLog.warn(
+                        // "security",
+                        `Blocked attempt to access file outside static root: ${resolvedPath}`);
+                        res.status(403).end("Forbidden: Sandbox Violation");
+                        return next();
+                    }
+                }
+                // 4 & 5. LRU Meta-Cache & Existence Check (Anti-DDoS and Libuv Starvation Shield)
+                const cacheHit = this.metaCache.get(resolvedPath);
+                if (cacheHit) {
+                    if (!cacheHit.exists) {
+                        return next();
+                    }
+                    // If it exists, we can skip the stat call and proceed to delegation
+                }
+                else {
+                    let fileStats;
+                    try {
+                        if (this.pendingStats.has(resolvedPath)) {
+                            fileStats = await this.pendingStats.get(resolvedPath);
+                        }
+                        else {
+                            const statPromise = stat(resolvedPath);
+                            this.pendingStats.set(resolvedPath, statPromise);
+                            fileStats = await statPromise;
+                            this.pendingStats.delete(resolvedPath);
+                        }
+                    }
+                    catch (e) {
+                        this.pendingStats.delete(resolvedPath);
+                        this.metaCache.set(resolvedPath, false);
+                        return next();
+                    }
+                    // Skip if it's a directory (cache as false so it falls through to next)
+                    if (fileStats.isDirectory()) {
+                        this.metaCache.set(resolvedPath, false);
+                        return next();
+                    }
+                    // Valid file, cache as true
+                    this.metaCache.set(resolvedPath, true);
+                }
+                // 6. Delegation to XHSC (Go)
+                const worker = this.app._xhscWorker;
+                if (worker) {
+                    res.status(0);
+                    // Handle Cache-Control (Local option > Global config)
+                    const maxAge = options.maxAge ?? this.globalConfig.defaultMaxAge;
+                    if (maxAge !== undefined) {
+                        res.setHeader("Cache-Control", `public, max-age=${maxAge}`);
+                    }
+                    worker.delegateStatic(req.id, resolvedPath);
+                    res.end();
+                    return;
+                }
+                else {
+                    res.status(500).send("[XStatic] High-performance static serving requires XHSC Clustering mode.");
+                }
+            }
+            catch (err) {
+                this.logger.error("server", `XStatic failure: ${err}`);
+                next();
+            }
+        });
+        this.logger.debug("server", `Static route defined: ${normalizedRoute} -> ${dir}`);
+    }
+    /**
+     * @deprecated Use {@link define} instead. Will be removed in a future release.
+     *
+     * Alias for {@link define} — kept for beta compatibility only.
+     *
+     * @param route   - The URL prefix to mount (e.g. `"/assets"`).
+     * @param dir     - The filesystem directory to serve from.
+     * @param options - Optional per-route overrides. See {@link StaticOptions}.
+     *
+     * @example
+     * ```typescript
+     * // ❌ Deprecated — avoid in new code
+     * xs.serve("/assets", "./public");
+     *
+     * // ✅ Preferred
+     * xs.define("/assets", "./public");
+     * ```
+     */
+    serve(_route, _dir, _options = {}) {
+        const msg = "XStatic.serve() is deprecated. Please use XStatic.define().";
+        this.qLog.error(
+        // "server",
+        msg);
+        // this.define(route, dir, options);
+        throw new Error(msg);
+    }
+}
+//# sourceMappingURL=XStatic.js.map

package/dist/src/server/components/static/XStatic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XStatic.js","sourceRoot":"","sources":["../../../../../src/server/components/static/XStatic.ts"],"names":[],"mappings":"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"}

package/dist/src/server/components/static/types.d.ts

@@ -0,0 +1,34 @@
+import { IXStaticSchem } from "./IXStaticSchem";
+export type DotfileModeT = "deny" | "allow";
+/**
+ * How to handle files starting with a dot (e.g. .env, .git).
+ * - "allow": Serves the file (Security Risk)
+ * - Object: Custom restricted file patterns.
+ * @default "deny"
+ */
+type dotfiles = DotfileModeT | {
+    mode: DotfileModeT;
+    /** Custom file patterns to always restrict regardless of dot prefix */
+    custom?: string[];
+};
+/**
+ * Static file serving configuration (XStatic).
+ *
+ * Configures the high-performance XStatic engine, including
+ * meta-caching and delegation behaviors.
+ */
+export type IXStatic = typeof IXStaticSchem.types & {
+    dotfiles?: dotfiles;
+};
+export interface StaticOptions {
+    /** Allow serving files outside of the project root (Security Risk) */
+    allowOutsideRoot?: boolean;
+    /** Disable path validation safety checks */
+    unsafe?: boolean;
+    /** Cache-Control max-age header */
+    maxAge?: string | number;
+    /** Fallback to standard TS streaming if delegation fails */
+    fallback?: boolean;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/server/components/static/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/server/components/static/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;AAE5C;;;;;GAKG;AACH,KAAK,QAAQ,GACP,YAAY,GACZ;IACI,IAAI,EAAE,YAAY,CAAC;IACnB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAER;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,aAAa,CAAC,KAAK,GAAG;IAChD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACvB,CAAC;AAGF,MAAM,WAAW,aAAa;IAC1B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB"}

package/dist/src/server/components/static/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/server/components/static/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/server/components/static/types.ts"],"names":[],"mappings":""}