Middleware Pipeline Internals

// Middleware pipeline visualization:
// Request →  [M1] → [M2] → [M3] → Handler → Response
//         ↑                              ↓
//         └──────────────────────────────┘
// Each middleware can inspect/mutate both the REQUEST (going in) and RESPONSE (coming out)

// ━━ app.Use — bidirectional middleware (wraps next) ━━
app.Use(async (context, next) =>
{
    // PRE-processing: runs BEFORE the rest of the pipeline
    var sw = System.Diagnostics.Stopwatch.StartNew();
    var path = context.Request.Path;

    await next(context); // call next middleware

    // POST-processing: runs AFTER the rest of the pipeline completes
    sw.Stop();
    Console.WriteLine($"{path} → {context.Response.StatusCode} in {sw.ElapsedMilliseconds}ms");
});

// ━━ app.Run — terminal middleware (does NOT call next) ━━
// Short-circuits the pipeline — nothing after this runs
app.Run(async context =>
{
    await context.Response.WriteAsync("Hello from terminal middleware!");
});

// ━━ app.Map — branch by path ━━
app.Map("/health", healthApp =>
{
    healthApp.Run(async ctx => await ctx.Response.WriteAsync("OK"));
});

// ━━ app.UseWhen — conditional branching ━━
app.UseWhen(
    context => context.Request.Path.StartsWithSegments("/api"),
    apiApp => apiApp.UseRateLimiter());

// ━━ CRITICAL: Order of built-in middleware ━━
// app.UseExceptionHandler("/error")  ← FIRST: catches all downstream exceptions
// app.UseHsts()                       ← HTTPS enforcement
// app.UseHttpsRedirection()           ← redirect HTTP to HTTPS
// app.UseStaticFiles()                ← serve wwwroot before routing overhead
// app.UseRouting()                    ← parse route
// app.UseCors()                       ← CORS (MUST be after routing, before auth)
// app.UseAuthentication()             ← who are you?
// app.UseAuthorization()              ← what can you do?
// app.UseRateLimiter()                ← limit request rate
// app.UseResponseCaching()            ← cache responses
// app.MapControllers()               ← execute endpoints