HTTP Server

Native Binary Streaming (sendFile)

Enterprise-standard utility for serving physical assets using XHSC Zero-Copy architecture with full HTTP Range support.

res.sendFile(filePath) leverages the XHSC (Hyper-System Core) native engine to stream binary data directly from the filesystem to the network socket, bypassing the Node.js/V8 heap to ensure minimal memory footprint and maximum throughput.

Advanced Architecture

Unlike conventional frameworks that buffer file content into the JavaScript heap — leading to latency and GC pressure — XyPriss implements a Zero-Copy Ranged Streaming architecture:

Native Resolution

The path is rigorously validated using __sys__.fs, protecting against directory traversal attacks.

MIME-Type Intelligence

Headers are automatically calculated based on the internal MIME_MAP, ensuring browser-compliant delivery.

Ranged Delivery

Full support for HTTP Range headers via native lseek(2) and copy_file_range(2). Essential for video seek and large asset delivery.

Low Memory Impact

Even with multi-gigabyte files, the Node.js process RSS remains stable as data flows through a dedicated native IPC bridge.

Zero-Copy Guarantee

Data never touches the Node.js heap. The XHSC engine reads from disk and writes to the TCP socket directly, keeping your application memory footprint flat regardless of file size.

Implementation Examples

Standard Asset Delivery

Serve documents or images with automatic MIME-type resolution and caching headers. Conditional requests (ETags/Last-Modified) are handled automatically.

typescript

import { XyPrisRequest, XyPrisResponse } from "xypriss";

export const getReport = (req: XyPrisRequest, res: XyPrisResponse) => {
    const storageRoot = __sys__.vars.get("__root__");
    const reportPath = __sys__.path.join(
        storageRoot,
        "storage",
        "reports",
        "annual.pdf",
    );

    // Serve with Content-Type: application/pdf
    // Handles conditional requests (ETags/Last-Modified) automatically
    res.sendFile(reportPath);
};

Media Streaming with Seek Support

Because res.sendFile supports Range requests natively, it is the ideal choice for streaming video content to modern browsers.

typescript

app.get("/media/video/:id", (req, res) => {
    const videoPath = __sys__.path.resolve("./assets/media/demo.mp4");

    // Automatically handles byte-range requests
    // (e.g., Range: bytes=1024-2048)
    // allowing users to seek without downloading the whole file.
    res.sendFile(videoPath);
});

Advanced Download Logic

Secure download route with custom headers, MIME enforcement, and forced attachment disposition.

typescript

app.get("/download/report/:id", async (req, res) => {
    const reportName = `report-${req.params.id}.pdf`;

    await res.sendFile(reportName, {
        // Base directory for resolution
        root: __sys__.path.join(__sys__.__root__, "storage/vault"),

        // Force browser to download instead of rendering
        disposition: "attachment",

        // Custom security headers
        headers: {
            "X-Report-Id": req.params.id,
            "Cache-Control": "private, no-store, must-revalidate"
        },

        // Ensure the browser treats it as PDF
        mimeOverrides: {
            ".pdf": "application/pdf"
        },

        // Cache for 1 hour unless overridden by headers
        maxAge: 3600000
    });
});

Configuration Options

The sendFile method accepts an optional second argument to fine-tune delivery behaviour:

Property	Type	Description
root	string	Base directory for relative file path resolution.
maxAge	number	Cache-Control max-age in milliseconds.
headers	Record<string, string>	Custom HTTP headers to serve with the file.
disposition	string	Content-Disposition value. Use 'inline', 'attachment', or a custom filename.
mimeOverrides	Record<string, string>	Map of file extensions to MIME types to override system defaults.

Security & Reliability

Path Sanitization

res.sendFile automatically normalises paths to prevent ../ traversal exploits.

Error Resilience

If the file is inaccessible or corrupted, the framework dispatches a 404 or 500 before headers are flushed, ensuring client-side consistency.

MIME Coverage

Natively handles 50+ extensions including .webp, .mp4, .zip, .svg, .jsonc.

Always Use Absolute Paths

Provide an absolute path to res.sendFile. Use __sys__.path.resolve or __sys__.path.join to ensure platform-independent path construction and avoid security issues.

Benchmarks: Mixed Workload (Auth + 500 KB File)

This benchmark validates res.sendFile() on a realistic production workload: authentication middleware (2 ms overhead) followed by a 500 KB binary file transfer. The fixed IPC bridge cost (~15 ms) is fully amortised by the transfer, so XyPriss leads on latency at every load level.

Mixed Avg Latency (50 conn)

837.5 ms

Lowest among Express, Fastify, and XyPriss — auth + 500 KB file.

Total Data (10s window)

~328 MB

Highest data transferred at 10 connections — Zero-Copy advantage.

p99 Tail Latency (100 conn)

4 182 ms

Lowest tail latency at 100 connections — Fastify reaches 8 411 ms.

Average Latency — Auth + 500 KB File

Concurrent connections

Lower is better (ms)

Tail Latency p99 — Auth + 500 KB File

Lower is better (ms)

Full Benchmarks: routing, static delivery, synthesis table and takeaways

Structured Responses

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