Composable Middleware Examples

This guide provides battle-tested middleware implementations for real-world scenarios: request timing, correlation tracking, security headers, and structured state sharing.


1. Request Execution Timing Middleware

Measures the elapsed execution time of the entire request lifecycle and sets the standard X-Response-Time header:

import type { MiddlewareHandler } from "katal";

export const timingMiddleware: MiddlewareHandler = async (ctx, next) => {
    const start = performance.now();

    // Delegate down the onion pipeline to downstream middleware and controller
    const response = await next();

    const duration = (performance.now() - start).toFixed(2);
    response.headers.set("X-Response-Time", `${duration}ms`);
    return response;
};

// Register globally
app.use(timingMiddleware);

2. Security Headers Middleware (OWASP Recommendations)

Injects industry-standard HTTP security headers onto every outgoing response:

import type { MiddlewareHandler } from "katal";

export const securityHeadersMiddleware: MiddlewareHandler = async (ctx, next) => {
    const response = await next();

    response.headers.set("X-Content-Type-Options", "nosniff");
    response.headers.set("X-Frame-Options", "DENY");
    response.headers.set("X-XSS-Protection", "1; mode=block");
    response.headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
    response.headers.set("Strict-Transport-Security", "max-age=31536000; includeSubDomains; preload");
    response.headers.set(
        "Content-Security-Policy",
        "default-src 'self'; img-src 'self' data: https:; script-src 'self' 'unsafe-inline';"
    );

    return response;
};

app.use(securityHeadersMiddleware);

3. Correlation ID & Audit Stamping Middleware

Preserves incoming correlation IDs or generates a cryptographically random UUID, making it accessible to controllers and response headers:

import type { MiddlewareHandler } from "katal";

export const correlationIdMiddleware: MiddlewareHandler = async (ctx, next) => {
    // 1. Inward Pass: Resolve or generate correlation ID
    const correlationId = ctx.request.headers.get("x-request-id") ?? crypto.randomUUID();

    // 2. Attach to context state for access in controllers and logs
    ctx.state.correlationId = correlationId;

    // 3. Delegate to controller
    const response = await next();

    // 4. Outward Pass: Attach correlation ID to response headers
    response.headers.set("X-Request-ID", correlationId);
    return response;
};

app.use(correlationIdMiddleware);

4. State Sharing Between Middleware and Controllers

Use ctx.state as a strongly-typed shared bag of data across the request lifecycle:

// Define custom context state interface
declare module "katal" {
    interface RequestContextState {
        userGeo?: { country: string; city: string };
        requestId?: string;
    }
}

// Middleware populates geo data
app.use(async (ctx, next) => {
    ctx.state.userGeo = {
        country: ctx.request.headers.get("cf-ipcountry") ?? "US",
        city: ctx.request.headers.get("cf-ipcity") ?? "Unknown",
    };
    return await next();
});

// Controller reads geo data
class LocalizedFeedController extends Controller {
    async handle(ctx: RequestContext) {
        const geo = ctx.state.userGeo;
        return this.success({ country: geo?.country });
    }
}

5. Legacy Katal v2 { before, after } Middleware Pattern

If you prefer explicit object hooks or have existing v2 middleware, Katal supports { before, after } objects natively:

import type { Middleware, MiddlewareContext } from "katal";

export const auditHookMiddleware: Middleware = {
    async before(ctx: MiddlewareContext) {
        ctx.state.startedAt = Date.now();
        console.log(`[Audit] Incoming ${ctx.request.method} ${ctx.request.url}`);
        return null; // Return null to continue, or a Response to short-circuit
    },

    async after(ctx: MiddlewareContext) {
        const elapsed = Date.now() - (ctx.state.startedAt as number);
        console.log(`[Audit] Finished with status ${ctx.response?.status} in ${elapsed}ms`);
        return ctx.response!;
    },
};

app.use(auditHookMiddleware);

See Also