Introduction to Middleware

Middleware in Kestrun is a set of pluggable pipeline components that can inspect, transform, short-circuit, or enrich requests and responses before or after your route handlers execute.

Core goals:

  • Composition: Add only what you need (logging, antiforgery, auth, static files, caching, and more).
  • Clarity: PowerShell cmdlets wrap consistent ASP.NET Core middleware concepts.
  • Control: Most features can be tuned globally and, where supported, per route.

Current Status

Area Middleware Available Notes and Links
Security Antiforgery (CSRF), HSTS, HTTPS Redirection Antiforgery, HTTPS Redirection, HSTS
Static Content File Server File Server & Directory Browsing
Responses Caching helpers Responses: Caching & Revalidation
Logging Sinks / enrichment Logging section
AuthN/Z Schemes & policies Authentication section
Sessions Session state Sessions chapter
Event streaming SSE + Broadcast SSE See SSE and SSE Broadcast
Security Host Filtering Tutorial
Security CORS Tutorial
Security Rate Limiting (policy-based) Implemented; see Routing guide
Compression Response Compression Tutorial + Guide
Compression Request Decompression (Content-Encoding) Tutorial

Quick Start: Antiforgery

Add antiforgery middleware and expose a token endpoint:

Add-KrAntiforgeryMiddleware -CookieName '.Kestrun.AntiXSRF' -HeaderName 'X-CSRF-TOKEN'
Add-KrAntiforgeryTokenRoute -Path '/csrf-token' | Out-Null

This protects unsafe verbs (POST, PUT, PATCH, DELETE). Fetch a token first, then send it back in the configured header together with the antiforgery cookie.

See the full tutorial: Antiforgery Protection

Pipeline Order Guidelines

Recommended relative ordering when composing middleware:

  1. Logging / correlation
  2. Forwarded headers / proxy normalization
  3. Static files / file server
  4. Security (antiforgery, authentication, authorization, CORS)
  5. Caching / response manipulation
  6. Routing + handlers (PowerShell / C# / VB)
  7. Post-processing (metrics, custom tail middleware)

Roadmap & Tracking

Planned middleware will appear here as they are implemented. Contributions are welcome; see the contributing docs.

Feature Status Tracking
Antiforgery ✅ Implemented Tutorial + deeper guide planned
HSTS & HTTPS Redirection ✅ Implemented Tutorial + Guide
Rate Limiting ✅ Implemented Policy-based today; dedicated tutorial TBD
Response Compression ✅ Implemented Tutorial + Guide
Request Decompression ✅ Implemented Tutorial
CORS ✅ Implemented Tutorial + Guide
Request Metrics Ideation TBD

Next Steps

Return to the Tutorial index.

Table of contents