HttpLens 1.1.0

HttpLens

Install one NuGet package, add two lines of code, and see every outbound HTTP call your app makes — in a browser dashboard.

Features

• Automatic interception — captures all HttpClient requests/responses via IHttpClientFactory
• Embedded dashboard — dark/light theme SPA served at /_httplens
• Sensitive header masking — Authorization, Cookie, X-Api-Key and custom headers masked before storage
• Request/response body capture — with configurable size limits and truncation
• Polly retry detection — groups retry attempts visually in the dashboard
• Export — one-click copy as cURL or C# HttpClient code; download HAR 1.2 files
• Correlation — W3C Trace ID, inbound request path, HttpClient name
• In-memory ring buffer — configurable max records, thread-safe
• Real-time updates — polling fallback (SignalR planned)

Installation

dotnet add package HttpLens

Quick Start

var builder = WebApplication.CreateBuilder(args);

// 1. Register HttpLens services
builder.Services.AddHttpLens();

var app = builder.Build();

// 2. Mount the dashboard
app.MapHttpLensDashboard();

app.Run();

Then open https://localhost:5001/_httplens in your browser.

Configuration

builder.Services.AddHttpLens(options =>
{
    options.MaxStoredRecords = 1000;
    options.SensitiveHeaders.Add("X-Custom-Secret");
    options.CaptureRequestBody = true;
});

Security

By default HttpLens applies no security — the dashboard is publicly accessible. This preserves the zero-config developer experience. Each security layer is opt-in.

Security Layers

Configuration Examples

Restrict to development only:

// Automatically skips registration in Production
builder.Services.AddHttpLens(builder.Environment, options =>
{
    options.AllowedEnvironments.AddRange(["Development", "Staging"]);
});

Protect with an API key:

builder.Services.AddHttpLens(options =>
{
    options.ApiKey = "my-secret-key";
});

Then access the dashboard at /_httplens?key=my-secret-key. The key is stored in sessionStorage so subsequent API calls include it automatically via the X-HttpLens-Key header.

Restrict by IP:

builder.Services.AddHttpLens(options =>
{
    options.AllowedIpRanges.AddRange(["127.0.0.1", "10.0.0.0/8", "::1"]);
});

Disable in production via appsettings.json:

appsettings.Development.json:

{ "HttpLens": { "IsEnabled": true } }

appsettings.Production.json:

{ "HttpLens": { "IsEnabled": false } }

Then bind in Program.cs:

builder.Services.AddHttpLens(options =>
    builder.Configuration.GetSection("HttpLens").Bind(options));

Combined example (recommended for shared/staging environments):

builder.Services.AddHttpLens(builder.Environment, options =>
{
    builder.Configuration.GetSection("HttpLens").Bind(options);

    // Override: force-disable in production regardless of config
    if (builder.Environment.IsProduction())
        options.IsEnabled = false;
});

Middleware Order

Security checks are applied automatically inside MapHttpLensDashboard() in this order:

1. EnabledGuard — returns 404 if IsEnabled = false
2. IpAllowlist — returns 403 if client IP is not in AllowedIpRanges
3. ApiKey — returns 401 if X-HttpLens-Key / ?key= is missing or wrong
4. Authorization policy — evaluated by ASP.NET Core auth middleware
5. Endpoint handler

No UseMiddleware calls are needed in your Program.cs.

Note: MapHttpLensDashboard() automatically applies all security checks (enabled guard, IP allowlist, API key, and authorization policy) to both the SPA and API routes. If you call MapHttpLensApi() directly, only the authorizationPolicy parameter (if provided) is applied — IP allowlist and API key checks are skipped.

Polly Retry Detection

To group Polly retry attempts in the dashboard:

builder.Services
    .AddHttpClient("MyClient")
    .AddStandardResilienceHandler()   // Polly resilience
    .Services
    .AddHttpClient("MyClient")
    .AddRetryDetection();             // HttpLens retry tracking

Retried requests are grouped visually — the first attempt appears as a normal row, subsequent retries appear indented beneath it.

Export Features

• cURL — Click "📋 Copy" on the Export tab to copy a ready-to-paste cURL command
• C# — Copy a complete HttpClient / HttpRequestMessage code snippet
• HAR — Click "📦 HAR" to download all filtered traffic as a HAR 1.2 file (importable in Chrome DevTools)

Dark / Light Theme

Toggle between dark and light themes using the 🌙/☀️ button in the header. Preference is saved to localStorage.

API Endpoints

License

MIT