HyperExpress

HyperExpress supports two levels of middleware:

• Global Middleware: Registered via webserver.use(callback). These execute on every incoming request and run before any route-specific middlewares.
• Route/Method Specific Middleware: Registered as an options object in route methods (e.g., .get(path, { middlewares: [...] }, callback)). Middlewares in the array are executed in the order specified.

Middleware callbacks receive (request, response, next). Call next() to proceed to the next middleware or route handler.

// Global middleware
webserver.use((request, response, next) => {
    some_asynchronous_call((data) => {
        request.some_data = data;
        next();
    });
});

const specific_middleware1 = (request, response, next) => {
    console.log('route specific middleware 1 ran!');
    return next();
};

const specific_middleware2 = (request, response, next) => {
    console.log('route specific middleware 2 ran!');
    return next();
};

// Route specific middleware
webserver.get('/', {
    middlewares: [specific_middleware1, specific_middleware2]
}, (request, response) => {
    return response.send('Hello World');
});

WebSockets in HyperExpress have specific memory and lifecycle behaviors due to how uWebSockets.js handles upgrades and events:

• Remote Address: During a WebSocket upgrade, the original HTTP socket data is destroyed. While getRemoteAddressAsText() on a native WebSocket might return an empty buffer, HyperExpress snapshots the request-entry IP and port and transfers them through the upgrade process so they are available in the Websocket wrapper.
• Message Data: Inputs for messages, dropped messages, close reasons, pings, pongs, and subscription topics are treated as callback-lifetime native memory.
  • String and Buffer modes copy or consume data synchronously.
  • ArrayBufferSafe creates an owned copy.
  • Warning: The legacy ArrayBuffer mode is zero-copy and must not be retained after the synchronous listener returns.
• Close Lifecycle: To prevent errors when the native core invokes close handlers synchronously, HyperExpress defensively clears its wrapper before close observers run.

A Router acts as a mini-app that holds route information independently of a Server. This allows you to group related routes into branches (e.g., an API version) and then mount that entire branch onto a master Server instance using webserver.use(). A single Router can even be reused across multiple Server instances.

When you mount a router with a pattern like webserver.use('/api/v1', router), all routes defined within that router are automatically prefixed with that pattern. For example, a router route defined as /register becomes /api/v1/register on the server.

const api_v1_router = new HyperExpress.Router();

api_v1_router.post('/register', async (request, response) => {
    const { email, password, captcha } = await request.json();
    const id = await register_account(email, password, captcha);
    return response.json({ id });
});

// Mount the router to the server under the '/api/v1' prefix
webserver.use('/api/v1', api_v1_router);

HyperExpress manages the lifetime of native uWebSockets.js objects to prevent memory errors. When working with HTTP requests and responses, keep the following rules in mind:

• HttpRequest: The native HttpRequest object is only valid during the synchronous route or upgrade callback. HyperExpress copies the Method, URL, query, headers, and path parameters into a JavaScript Request object for safe use. Using Request.raw is an unsafe escape hatch that bypasses these protections.
• HttpResponse: The native HttpResponse is valid until the response is completed via abort(), close(), end(), endWithoutBody(), a successful tryEnd(), or an upgrade(). HyperExpress tracks Response.completed to ensure no native methods are called after completion.
• Peer/Proxy Information: Peer/proxy addresses and ports are captured at request entry and remain stable even after the response is completed.
• Data Chunks (onDataV2): Native memory chunks are detached immediately after the callback. HyperExpress uses buffered/public-stream modes to copy data before retention, or parser mode to consume it synchronously.
• onWritable: This callback only runs while the native response is active. HyperExpress manages a single guarded callback and clears it upon completion.

HyperExpress implements a middleware API similar to ExpressJS, supporting both callback-based and async/promise-based iteration. You can attach middlewares to a Server or a Router using the .use() method.

To trigger the next middleware in the chain, you must either call next() in a callback or resolve the promise in an async function. To trigger the global error handler, you must either pass an Error object to next(error) in a callback or return an Error object from an async function.

// Callback-Based Iteration
router.use('/api', (request, response, next) => {
    some_async_operation(request, response)
    .then(() => next())
    .catch((error) => next(error))
});

// Async/Promise-Based Iteration
server.use(async (request, response) => {
    try {
        await some_async_operation();
    } catch (error) {
        return error; // Triggers global error handler
    }
});

To implement an SSE endpoint, verify response.sse exists, call .open() (or call .send() which opens it automatically), and manage the connection lifecycle by listening for the close event on the response object to clean up resources (like removing the stream from a broadcast pool).

const crypto = require('crypto');
const sse_streams = {};

function broadcast_message(message) {
    Object.keys(sse_streams).forEach((id) => {
        sse_streams[id].send(message);
    });
}

webserver.get('/news/events', (request, response) => {
    if (response.sse) {
        // Open the stream
        response.sse.open();
        
        // Assign a unique ID and store for broadcasting
        response.sse.id = crypto.randomUUID();
        sse_streams[response.sse.id] = response.sse;
        
        // Cleanup on disconnection
        response.once('close', () => {
            delete sse_streams[response.sse.id];
        });
    } else {
        response.send('Server-Sent Events Not Supported!');
    }
});

const crypto = require('crypto');

const sse_streams = {};
function broadcast_message(message) {
    // Send the message to each connection in our connections object
    Object.keys(sse_streams).forEach((id) => {
        sse_streams[id].send(message);
    })
}

webserver.get('/news/events', (request, response) => {
    // You may perform some authentication here as this is just a normal HTTP GET request
    
    // Check to ensure that SSE if available for this request
    if (response.sse) {
        // Looks like we're all good, let's open the stream
        response.sse.open();
        // OR you may also send a message which will open the stream automatically
        response.sse.send('Some initial message');
        
        // Assign a unique identifier to this stream and store it in our broadcast pool
        response.sse.id = crypto.randomUUID();
        sse_streams[response.sse.id] = response.sse;
        
        // Bind a 'close' event handler to cleanup this connection once it disconnects
        response.once('close', () => {
            // Delete the stream from our broadcast pool
            delete sse_streams[response.sse.id]
        });
    } else {
        // End the response with some kind of error message as this request did not support SSE
        response.send('Server-Sent Events Not Supported!');
    }
});