NinjaVault.Http 100.42.1

<p align="center"> <img src="https://raw.githubusercontent.com/alisaivi786/NinjaVault/main/assets/icon-512.png" width="112" alt="NinjaVault" /> </p>

<h1 align="center">NinjaVault.Http</h1>

<p align="center"> Typed <code>HttpClient</code> registration for third-party APIs with <b>automatic request/response logging</b>, a pluggable log sink, and <b>correlation-id propagation</b>. </p>

<p align="center"> <a href="https://www.nuget.org/packages/NinjaVault.Http"><img src="https://img.shields.io/nuget/v/NinjaVault.Http.svg?label=NinjaVault.Http" alt="NuGet version" /></a> <a href="https://www.nuget.org/packages/NinjaVault.Http"><img src="https://img.shields.io/nuget/dt/NinjaVault.Http.svg" alt="NuGet downloads" /></a> <a href="https://github.com/alisaivi786/NinjaVault/actions/workflows/ci.yml"><img src="https://github.com/alisaivi786/NinjaVault/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <img src="https://img.shields.io/badge/.NET-8%20%7C%209%20%7C%2010-512BD4" alt=".NET 8, 9, 10" /> <a href="https://github.com/alisaivi786/NinjaVault/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT" /></a> </p>

Why NinjaVault.Http

• See every outbound call. Method, URL, status, elapsed time, headers and bodies for every request your app makes to an external API.
• Safe by default. Secret headers are redacted. Binary, multipart and oversized bodies are recorded as a small placeholder and never decoded or buffered.
• Store logs anywhere. By default each call is one ILogger entry, so it flows into Serilog, the console, Seq, Application Insights or OpenSearch with no extra setup. Implement one interface (IExternalApiCallLogSink) to keep full records in SQL or a queue.
• One correlation id end to end. An AsyncLocal accessor stamps the same X-Correlation-Id on every outgoing call made while handling one incoming request.
• Never breaks your call. A failing sink is caught and logged as a warning; the real HTTP call always completes.
• Standard building blocks. A plain DelegatingHandler on IHttpClientFactory, so it composes with resilience handlers and anything else.

Works with any typed or named HttpClient, including NinjaVault.Cdn: services.AddNinjaVaultCdn(configuration).AddNinjaVaultHttpLogging("NinjaVaultCdn");

Quick start

1. Install

dotnet add package NinjaVault.Http

2. Register shared infrastructure, then each API client

builder.Services.AddNinjaVaultHttp(builder.Configuration);

builder.Services.AddNinjaVaultHttpClient<IPaymentsApi, PaymentsApi>("PaymentsApi", (_, client) =>
{
    client.BaseAddress = new Uri("https://payments.example.com/");
});

3. Write the typed client as usual

public sealed class PaymentsApi(HttpClient http) : IPaymentsApi
{
    public Task<HttpResponseMessage> ChargeAsync(ChargeRequest request, CancellationToken ct)
        => http.PostAsJsonAsync("charges", request, ct);
}

Every call made by PaymentsApi is now logged and carries an X-Correlation-Id header.

Add logging to a client registered elsewhere

Already have an IHttpClientBuilder (from AddHttpClient, an SDK, or AddNinjaVaultCdn)? Attach logging with one line:

builder.Services.AddNinjaVaultHttp(builder.Configuration);   // binds options (optional; defaults otherwise)

builder.Services.AddHttpClient<IWeatherApi, WeatherApi>()
    .AddNinjaVaultHttpLogging("WeatherApi");

builder.Services.AddNinjaVaultCdn(builder.Configuration)
    .AddNinjaVaultHttpLogging("NinjaVaultCdn");

Configuration reference

{
  "NinjaVault": {
    "ExternalApiLogging": {
      "Enabled": true,
      "CaptureRequestBody": true,
      "CaptureResponseBody": true,
      "MaxBodyLength": 8192,
      "SensitiveHeaders": [ "X-Tenant-Secret" ]
    }
  }
}

Every key is optional. With no section at all you get the defaults above. Options are read through IOptionsMonitor, so changes made while the app is running apply to the next call.

Configure in code instead:

builder.Services.AddNinjaVaultHttp();
builder.Services.Configure<ExternalApiLoggingOptions>(o =>
{
    o.CaptureResponseBody = false;
    o.SensitiveHeaders.Add("X-Tenant-Secret");
});

What is never captured as text

Neither is read or buffered by the handler, so large downloads still stream straight to your code.

Where the logs go

If you filter logs by category or level (for example with Serilog MinimumLevel.Override), keep NinjaVault.Http at Information or lower, or the default entries are dropped.

Persist logs with a custom sink

public sealed class DbApiLogSink(AppDbContext db) : IExternalApiCallLogSink
{
    public async Task WriteAsync(ExternalApiCallLog log, CancellationToken cancellationToken)
    {
        db.ApiLogs.Add(new ApiLogRow
        {
            ServiceName = log.ServiceName,         // "PaymentsApi", "NinjaVaultCdn", ...
            EndpointId = log.EndpointId,
            CorrelationId = log.CorrelationId,
            TraceId = log.TraceId,
            Method = log.Method,
            RequestUrl = log.RequestUrl,
            RequestHeaders = log.RequestHeaders,   // JSON, secrets already [REDACTED]
            RequestBody = log.RequestBody,
            StatusCode = log.StatusCode,           // 0 = failed before a response (DNS, timeout...)
            ResponseHeaders = log.ResponseHeaders,
            ResponseBody = log.ResponseBody,
            ElapsedMs = log.ElapsedMs,
            Error = log.Error,
            StartedOnUtc = log.StartedOnUtc,
            CompletedOnUtc = log.CompletedOnUtc
        });
        await db.SaveChangesAsync(cancellationToken);
    }
}

builder.Services.AddNinjaVaultHttp(builder.Configuration);
builder.Services.AddScoped<IExternalApiCallLogSink, DbApiLogSink>(); // register after AddNinjaVaultHttp

Each write runs in its own DI scope, so scoped services such as a DbContext are safe to use.

Correlation across services

Set the context once per incoming request, and every outgoing call reuses it:

app.Use(async (context, next) =>
{
    ICorrelationContextAccessor accessor = context.RequestServices.GetRequiredService<ICorrelationContextAccessor>();
    string correlationId = context.Request.Headers[CorrelationConstants.HeaderName].FirstOrDefault()
        ?? Guid.NewGuid().ToString("N");

    accessor.Current = new CorrelationContext(correlationId, context.TraceIdentifier);
    context.Response.Headers[CorrelationConstants.HeaderName] = correlationId;

    await next();
});

If no context is set (in background jobs, for example), a new id is generated per logical operation.

Tag calls per endpoint (optional)

using HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "charges")
    .WithEndpointId((int)PaymentsEndpoint.CreateCharge);

// the log's EndpointId is set, so you can group, count and alert per endpoint

Troubleshooting

Compatibility

NinjaVault SDKs

The same CDN client in every language, with the same features and the same version number (for example 100.42.1 everywhere):

Links

• Source, issues and release notes: https://github.com/alisaivi786/NinjaVault
• Change-sets: https://github.com/alisaivi786/NinjaVault/tree/main/changesets/NinjaVault.Http
• License: MIT