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);