HTTP Server

XStatic: High-Performance Static Delegation

Zero-copy architecture that offloads static file delivery to the native Go engine (XHSC) via a secure IPC bridge — bypassing Node.js entirely during request handling.

In traditional Node.js web frameworks, serving static files involves reading data from disk into memory buffers, processing them through the JavaScript event loop, and writing to the network socket. XStatic eliminates these bottlenecks by synchronising routing tables and security policies to the native Go engine at startup, which then intercepts requests at the TCP level.

Traditional Bottlenecks

Memory Overhead

Every file read creates temporary buffers increasing GC pressure.

Event Loop Blocking

High-concurrency static requests saturate the event loop, delaying business logic execution.

Context Switching

Constant data movement between kernel and user space incurs significant CPU overhead.

XHSC Fast Path Architecture

XStatic solves these issues through Native XHSC Fast Path Interception. Node.js is completely bypassed during the request lifecycle. Routes and security configurations are synced to the Go engine at startup, which then serves files natively via efficient OS-level primitives.

Startup Sync

All routes and security policies (allowOutsideRoot, dotfiles) are serialised and transmitted to the Go engine when the server starts. No runtime overhead from this sync.

Zero-Copy Transfer

Data moves from disk to TCP socket via kernel-level primitives (sendfile, copy_file_range). Node.js memory stays completely flat regardless of file size.

Design Principle: Single Source of Truth

Routing and security are defined once in TypeScript via xs.define(). XyPriss validates the configuration and pushes it to Go. You never write Go configuration — the TypeScript API is the single source of truth.

Basic Usage

To enable XStatic, instantiate the component and define your routes:

typescript

import { XStatic, createServer } from "xypriss";

const app = createServer();
const xs = new XStatic(app, __sys__);

// Define a static route (URI path -> physical directory)
xs.define("/static", "public");

app.start();

Configuration Examples

Case 1: Secure Sandbox (Default)

Enforces strict sandboxing. Node.js synchronously verifies the target directory at startup. Malicious URLs (/static/../../.env) are blocked instantly by Go's native path-cleaning before the filesystem is accessed.

typescript

xs.define("/assets", "./public", {
    allowOutsideRoot: false, // Default security boundary
    maxAge: "1d"             // Cache-Control: max-age=86400
});

Case 2: Shared Assets (Cross-Root)

Serve files from shared mounts or global folders outside the project root. Go still normalises the URI to prevent directory traversal relative to the target directory.

typescript

xs.define("/global", "/mnt/shared/images", {
    allowOutsideRoot: true,
    maxAge: 3600 // 1 hour
});

Global Configuration

Settings in createServer define the default security and performance policy for all static instances. These are passed to the Go engine as startup flags.

dotfilesControls access to hidden files (.env, .git)

Since Node.js is bypassed, this rule is strictly enforced by the Go engine. Go inspects the base filename and halts the request immediately if it matches the policy.

typescript

static: {
    dotfiles: {
        mode: "deny",               // "deny" | "ignore" | "allow"
        custom: ["config.json", "private.key"] // Block specific sensitive files
    }
}

deny

Returns 403 Forbidden for any dotfile (recommended).

ignore

Returns 404 Not Found (stealth mode) for dotfiles.

allow

Serves the file — not recommended for production.

zeroCopyNative sendfile(2) optimisation

Data is transferred directly from disk to network without intermediate memory copies. Node.js memory stays flat even for multi-gigabyte files transferred concurrently.

typescript

static: { zeroCopy: true }

lruCacheSizeMeta-Cache size for negative lookups

Stores the state of non-existent files. Subsequent requests for unknown files are served directly from RAM, saving disk I/O.

typescript

static: { lruCacheSize: 10000 }

concurrencyPool

Limits concurrent I/O goroutines in the native engine to prevent resource exhaustion (default: 2048).

defaultMaxAge

Sets a default Cache-Control policy for all served assets.

Performance Benchmarks

Real-World Data

All benchmarks use autocannon on Kali GNU/Linux Rolling (localhost). XyPriss runs via Bun/XFPM with the XHSC native orchestrator. Baselines (Express, Fastify) run in Node.js single-process mode for fair comparison.

Static Delivery Peak

~13 100

req/s with Cluster ×10 — throughput leader against Express & Fastify.

0% Event Loop Blocked

Node.js is fully bypassed during file delivery.

Single-Worker Lead

×5 - ×8

Throughput advantage over Express/Fastify without cluster scaling.

Throughput (req/s) — Static Files

Concurrent connections

Higher is better

Full benchmarks: routing, mixed workload, latency and error rates

Cluster Scaling

With --cluster-workers 10, XStatic throughput more than doubles (~13,000 req/s), confirming that the Go fast-path gains and horizontal scaling are cumulative.

File Delegation vs Streaming

XStatic represents a shift from "File Streaming" to File Delegation. By offloading data transfer to a compiled native engine, XyPriss provides an enterprise-grade solution for serving assets at scale.

Send Response Utility

Standardise every API response with the structured Send utility and IResTemplate contract.