RepletoryLib.Api.Middleware 1.0.0

RepletoryLib.Api.Middleware

ASP.NET Core middleware for exception handling, correlation IDs, request logging, timing, tenant resolution, and IP filtering.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.Api.Middleware provides a comprehensive middleware suite for ASP.NET Core applications. A single call to UseRepletoryMiddleware() adds exception handling, correlation ID tracking, request/response logging, timing, tenant resolution, and optional IP filtering to your pipeline.

Key Features

• Global exception handling -- Catches unhandled exceptions and returns standardized ErrorResponse JSON
• Correlation ID -- Generates or propagates X-Correlation-ID across the request lifecycle
• Request timing -- Adds X-Response-Time-Ms header to every response
• Request logging -- Logs HTTP method, path, status code, and duration
• Tenant resolution -- Extracts tenant context from JWT claims
• IP filtering -- Allow/block lists for IP-based access control
• ICurrentTenantService -- Injectable service populated by tenant resolution middleware

Installation

dotnet add package RepletoryLib.Api.Middleware

Dependencies

Quick Start

using RepletoryLib.Api.Middleware;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRepletoryMiddleware();

var app = builder.Build();
app.UseRepletoryMiddleware();

{
  "Middleware": {
    "EnableRequestLogging": true,
    "EnableTiming": true,
    "EnableIpFilter": false,
    "AllowedIps": [],
    "BlockedIps": [],
    "ExcludedPaths": ["/health", "/metrics"]
  }
}

Configuration

MiddlewareOptions

Usage Examples

Middleware Pipeline Order

UseRepletoryMiddleware() registers middleware in this order:

1. CorrelationIdMiddleware -- Sets X-Correlation-ID
2. RequestTimingMiddleware -- Measures elapsed time
3. RequestLoggingMiddleware -- Logs request details
4. TenantResolutionMiddleware -- Extracts tenant from JWT
5. IpFilterMiddleware -- Applies IP filtering (if enabled)
6. GlobalExceptionMiddleware -- Catches and formats exceptions

Correlation ID Propagation

Incoming requests with an X-Correlation-ID header will propagate it; otherwise, a new GUID is generated:

Request: GET /api/orders
X-Correlation-ID: abc-123

Response: 200 OK
X-Correlation-ID: abc-123
X-Response-Time-Ms: 42

Global Exception Handling

Unhandled exceptions are caught and returned as standardized JSON:

{
  "statusCode": 500,
  "message": "An unexpected error occurred",
  "errors": [],
  "traceId": "00-abc123...",
  "timestamp": "2025-01-15T10:30:00Z"
}

AppException and ValidationException from RepletoryLib.Common are handled with their specific status codes.

Tenant Resolution

The middleware extracts tenant_id and tenant_name from JWT claims and populates ICurrentTenantService:

using RepletoryLib.Common.Interfaces;

public class OrderService
{
    private readonly ICurrentTenantService _tenant;

    public OrderService(ICurrentTenantService tenant) => _tenant = tenant;

    public async Task<Order> CreateOrderAsync(Order order)
    {
        order.TenantId = _tenant.TenantId;
        // ...
    }
}

IP Filtering

{
  "Middleware": {
    "EnableIpFilter": true,
    "AllowedIps": ["10.0.0.0/24", "192.168.1.100"],
    "BlockedIps": ["203.0.113.50"]
  }
}

Integration with Other RepletoryLib Packages

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.