> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Middleware and pipeline

> Add CORS, logging, blocking logic, and route-aware behavior to the request pipeline

## Why middleware matters

Middleware lets you run logic before or after an endpoint without putting that logic inside every controller action. Typical uses:

* CORS
* Request logging
* Route-aware auditing
* Short-circuiting blocked requests
* Adding data to `Context.Items`

## Prefix middleware

Use `RegisterMiddleware(...)` to attach middleware to a route path or path prefix.

```csharp theme={null}
Router.RegisterMiddleware("/projects/*", async (HttpContext Context, Action<HttpContext> Next) =>
{
    RouteFeature? Route = Context.GetFeature<RouteFeature>();

    Context.Items["matchedRoute"] = Route?.Route.ToString() ?? string.Empty;

    if (Context.Request.QueryParameters.Optional("blocked") == "true")
    {
        await Context.Response.Return(new RestApiErrorResponse("Blocked by middleware.", "blocked"));
        return;
    }

    Next(Context);
});
```

If the middleware writes the response and returns early, the endpoint is never called. Do not call `Next(Context)` after short-circuiting.

## A practical CORS pattern

```csharp theme={null}
ControllerEndpointRouter Router = new ControllerEndpointRouter(
    "/api",
    true,
    new CamelCaseParameterNameCodec());
CorsMiddleware Middleware = new CorsMiddleware(
[
    "https://app.example.com",
    "https://admin.example.com"
],
true);

Router.RegisterMiddleware("/users", async (HttpContext Context, Action<HttpContext> Next) =>
{
    await Middleware.Process(Context.Request, Context.Response);
    Next(Context);
});

Router.RegisterControllers(typeof(UsersController).Assembly);
```

## Pipeline stages

Use the overload with `MiddlewareStage` when a middleware depends on data only available later:

1. `Infrastructure`
2. `Routing`
3. `PreAuthorization`
4. `Authorization`
5. `PostAuthorization`
6. `PreHandler`
7. `Handler`
8. `PostHandler`

* Route parameters are available from `Routing` and later
* Authorization state is available from `Authorization` and later
* `Handler` is reserved for the endpoint itself

<Warning>
  You cannot register middleware in the `Handler` stage. That stage is reserved for the endpoint implementation.
</Warning>

## Attribute-based middleware

Attach middleware directly to controllers and methods with `[Middleware]`.

```csharp theme={null}
[Controller]
[Route("/projects")]
[Middleware(typeof(ProjectAuditMiddleware), MiddlewareStage.Infrastructure)]
public sealed class ProjectsController : ControllerBase
{
    [HttpGet("/[projectId]")]
    [Middleware(typeof(ProjectRouteLoggingMiddleware), MiddlewareStage.Routing)]
    public Task<ProjectResponse> Get(string ProjectId)
    {
        return Task.FromResult(new ProjectResponse { ProjectId = ProjectId });
    }
}

public sealed class ProjectAuditMiddleware : MiddlewareBase
{
    public override Task Invoke(HttpContext Context, Action<HttpContext> Next)
    {
        Next(Context);
        return Task.CompletedTask;
    }
}
```

Middleware types declared through `[Middleware]` are constructed through `Router.ServiceProvider`, so constructor injection works for middleware classes too.

## Default middleware behavior

* `RegisterMiddleware("/path", Middleware)` defaults to `PreHandler` for all supported verbs
* `RegisterMiddleware(HttpMethodType.Get, "/path", Middleware)` defaults to `PreHandler` for the exact method and path
* Controller-level `[Middleware]` defaults to `PreHandler`
* Method-level `[Middleware]` defaults to `PreHandler`
* Controller-level middleware runs before method-level middleware

If you need middleware to run before routing, before authorization, or after the handler, choose an explicit `MiddlewareStage` instead of relying on the default.

<Note>
  Middleware types declared in `[Middleware]` must inherit `MiddlewareBase`.
</Note>

## What to read next

[Authorization](/neuron-development/first-party-packages/neuron-http-router/authorization) builds directly on the middleware model and shows how protected endpoints are declared.