Server-only HTTP client library for .NET with authentication, caching, logging, and structured error handling. Uses DelegatingHandler pipeline with IHttpClientFactory.
Server-only HTTP client library for .NET with authentication, caching, logging, and structured error handling. Uses DelegatingHandler pipeline with IHttpClientFactory.
Features
Authentication — OAuth 2.1 token refresh with proactive (before expiry) and reactive (on 401) strategies, concurrent refresh queue, exponential backoff
The underlying HttpRequestMessage.Options keys are also available in AcdcRequestOptions for advanced usage.
Named Clients
Register multiple independent ACDC clients for different downstream services:
services.AddAcdcHttpClient("service-a", b => b
.WithBaseAddress(new Uri("https://service-a.example.com"))
.WithAuth(auth => { auth.RefreshEndpoint = "..."; auth.ClientId = "a"; }));
services.AddAcdcHttpClient("service-b", b => b
.WithBaseAddress(new Uri("https://service-b.example.com"))
.WithCache(cache => cache.Duration = TimeSpan.FromMinutes(10)));
// Resolve by key
var clientA = sp.GetRequiredKeyedService<AcdcHttpClient>("service-a");
Custom Handlers
Register custom DelegatingHandler types that run between the Cache and Deduplication handlers in the pipeline:
public class CorrelationIdHandler : DelegatingHandler
{
protected override async Task<HttpResponseMessage> SendAsync(
HttpRequestMessage request,
CancellationToken cancellationToken)
{
request.Headers.Add("X-Correlation-Id", Guid.NewGuid().ToString());
return await base.SendAsync(request, cancellationToken);
}
}
// Register with the builder
builder.Services.AddTransient<CorrelationIdHandler>();
builder.Services.AddAcdcHttpClient(b => b
.WithCustomHandler<CorrelationIdHandler>());
Custom handlers must be registered in DI (AddTransient or AddScoped) and must not store per-request state in instance fields since handlers are pooled by IHttpClientFactory.
Token Lifecycle
ACDC handles refreshing tokens, not obtaining them. Your application's login flow provides the initial tokens, and ACDC keeps them alive:
Your login flow authenticates the user and obtains initial access + refresh tokens
You seed the tokens via ITokenProvider.SaveTokensAsync()
ACDC takes over — the AuthHandler injects the Bearer token on every request and refreshes automatically:
Proactive refresh: When the access token is within RefreshThreshold of expiry (default 60s), ACDC refreshes in the background without blocking the current request
Reactive refresh: On a 401 response, ACDC refreshes and retries the request once
Concurrent coordination: Multiple simultaneous 401s share a single refresh call via leader/follower election
The default InMemoryTokenProvider stores tokens in memory — tokens are lost on process restart. For persistent storage, implement ITokenProvider backed by Redis or a database:
public class RedisTokenProvider : ITokenProvider
{
private readonly IDistributedCache _cache;
public RedisTokenProvider(IDistributedCache cache) => _cache = cache;
// Implement GetAccessTokenAsync, SaveTokensAsync, etc.
// using _cache.GetStringAsync / _cache.SetStringAsync
}
// Register before AddAcdcHttpClient
builder.Services.AddSingleton<ITokenProvider, RedisTokenProvider>();
Debugging and Observability
Enable Debug Logging
ACDC uses ILogger<T> for all handler logging. Set the log level to Debug to see handler internals:
Headers matching SensitiveFields are replaced with [REDACTED] in logs. The default list includes Authorization, Cookie, X-Api-Key, and common credential field names. Add custom fields:
Enable debug logging for CSharpAcdc (see above) to see refresh attempts and error details
Check that RefreshEndpoint is a valid, reachable URL
Verify ClientId and ClientSecret match your OAuth provider configuration
After repeated failures, ACDC applies exponential backoff (1s → 2s → 4s → ... → 30s max). The backoff resets after a successful refresh
Cache not working
Verify cache is configured: .WithCache(cache => ...) — without this, no CacheHandler is registered
Check that requests are GET or HEAD — other methods bypass the cache
Confirm you haven't set request.SkipCache() on the request
For UserIsolated cache keys, the Authorization header must be present. Without auth, all requests share the same cache key
InvalidOperationException from CancelAll()
ActiveRequestTracker.CancelAll() cancels all in-flight requests tracked at call time. This is expected behavior — callers should catch OperationCanceledException:
try
{
var response = await client.GetAsync("/api/data");
}
catch (OperationCanceledException)
{
// Expected after CancelAll() — request was intentionally cancelled
}
Requests fail silently
If requests complete without errors but return unexpected data:
Check for AcdcCacheException — stale cache entries may be served when the MaxStaleAge fail-safe is enabled
Enable debug logging to see if cache is returning stale data
Verify the handler pipeline is registered: AddAcdcHttpClient() must be called in DI setup
AcdcAuthException on startup
ACDC doesn't obtain initial tokens. You must seed them before making authenticated requests:
var tokenProvider = app.Services.GetRequiredService<ITokenProvider>();
await tokenProvider.SaveTokensAsync(accessToken, refreshToken, expiresAt, CancellationToken.None);
Security Best Practices
Always use HTTPS — ACDC does not enforce TLS but all RefreshEndpoint and BaseAddress URLs should use https://
Never hardcode secrets — Use IConfiguration, environment variables, or a secrets manager (Azure Key Vault, AWS Secrets Manager) for ClientId and ClientSecret:
builder.Services.AddAcdcHttpClient(b => b
.WithAuth(auth =>
{
auth.RefreshEndpoint = builder.Configuration["Auth:TokenEndpoint"]!;
auth.ClientId = builder.Configuration["Auth:ClientId"]!;
auth.ClientSecret = builder.Configuration["Auth:ClientSecret"];
}));
Token storage — The default InMemoryTokenProvider is suitable for development. In production, implement ITokenProvider backed by Redis or a database to survive restarts and share tokens across instances
Sensitive data redaction — The LoggingHandler redacts Authorization, Cookie, X-Api-Key, and other credential headers by default. Review AcdcLoggingOptions.DefaultSensitiveFields and add any application-specific headers
Request URL redaction — Query string parameters matching sensitive field names are also redacted in logs (?token=abc becomes ?token=[REDACTED])
Performance Tuning
Cache Duration
Low-latency APIs (< 100ms): Duration of 1-5 minutes reduces upstream load without stale data risk
Expensive queries (> 500ms): Duration of 10-30 minutes with StaleWhileRevalidateTimeout of 1-2 seconds gives fast responses while refreshing in the background
Rarely-changing data (config, feature flags): Duration of 1 hour+ with MaxStaleAge set even higher for fail-safe
Stale-While-Revalidate
StaleWhileRevalidateTimeout and MaxStaleAge work together:
.WithCache(cache =>
{
cache.Duration = TimeSpan.FromMinutes(5); // Fresh for 5 min
cache.MaxStaleAge = TimeSpan.FromHours(1); // Stale-but-usable for 1 hour
cache.StaleWhileRevalidateTimeout = TimeSpan.FromSeconds(1); // Return stale after 1s
cache.BackgroundRefreshOnTimeout = true; // Refresh continues in background
})
If the downstream API takes 3 seconds and the StaleWhileRevalidateTimeout is 1 second, the caller gets the stale value after 1 second while the fresh response is fetched and cached in the background.
Auth Refresh Threshold
RefreshThreshold (default 60s) controls how early proactive refresh starts. For high-traffic services, increase to 120-300s to ensure tokens are always fresh under load. For low-traffic services, the default 60s is sufficient.
Timeouts
Set WithTimeout() based on your downstream SLAs. The default is inherited from HttpClient (100 seconds). For microservice-to-microservice calls, 5-10 seconds is typical.
Deduplication
Deduplication applies only to GET and HEAD requests with identical URL and headers. It's most effective for:
Dashboard pages that fire multiple identical API calls
Service meshes where retries create duplicate requests
Disable per-request with request.SkipDeduplication() when you need guaranteed fresh responses.
Architecture
graph LR
A[Your Code] --> B[AcdcHttpClient]
B --> C[LoggingHandler]
C --> D[ErrorHandler]
D --> E[CancellationHandler]
E --> F[AuthHandler]
F --> G[CacheHandler]
G --> H[Custom Handlers]
H --> I[DeduplicationHandler]
I --> J[HttpClient]
J --> K[Server]
F -- "proactive refresh" --> L[ITokenRefreshStrategy]
F -- "token storage" --> M[ITokenProvider]
G -- "L1 + L2 cache" --> N[FusionCache]
style A fill:#e1f5fe
style K fill:#e8f5e9
style L fill:#fff3e0
style M fill:#fff3e0
style N fill:#fff3e0
Each handler wraps the next, processing requests left-to-right and responses right-to-left. The AuthHandler coordinates with ITokenProvider for storage and ITokenRefreshStrategy for refresh logic. The CacheHandler delegates to FusionCache which manages L1 (in-memory) and optional L2 (Redis) tiers.
