Tooark.Http
4.11.0
dotnet add package Tooark.Http --version 4.11.0
NuGet\Install-Package Tooark.Http -Version 4.11.0
<PackageReference Include="Tooark.Http" Version="4.11.0" />
<PackageVersion Include="Tooark.Http" Version="4.11.0" />
<PackageReference Include="Tooark.Http" />
paket add Tooark.Http --version 4.11.0
#r "nuget: Tooark.Http, 4.11.0"
#:package Tooark.Http@4.11.0
#addin nuget:?package=Tooark.Http&version=4.11.0
#tool nuget:?package=Tooark.Http&version=4.11.0
Tooark.Http
Library for outbound HTTP in .NET projects: a thin JSON service over IHttpClientFactory, with resilience, errors mapped to the Tooark exceptions and an outbound guard against SSRF.
The service does not replace HttpClient and does not re-implement its pipeline: the client is created by
IHttpClientFactory, retries, circuit breaker and timeouts come from
Microsoft.Extensions.Http.Resilience, and the
guard is a SocketsHttpHandler.ConnectCallback. The package adds the JSON conventions, the options in the Tooark
pattern and the conversion of every failure into an exception that carries NotificationItems.
π Docs: Tooark.Http on the site Β· All packages Β· API reference
π Languages: πΊπΈ English (this file) Β· π§π· PortuguΓͺs
π Contents
- Overview
- Installation
- Configuration
- Service
- Resilience
- Error Handling
- Outbound Guard
- Observability
- Usage Examples
- Dependencies
- Best Practices
- Error Codes and Solutions
- Contributing
- Help & Security
- Support
- License
π Overview
| Piece | What it does |
|---|---|
IHttpClientService |
GET, POST, PUT, PATCH and DELETE with JSON; SendAsync and SendStreamingAsync for the rest |
AddTooarkHttpClient |
Registers the service and the default client, Tooark, with resilience set up by the options |
AddTooarkNamedHttpClient |
Registers a named client with its own options, and its service as a keyed service |
HttpClientServiceExtension |
The verb methods with a per-call adjustment of the request, such as a header |
AddTooarkOutboundGuard |
Adds the outbound guard to any named or typed client of the application |
OutboundGuard.IsBlocked |
The block list as a pure function, for validations of the application itself |
HttpRequestFailedException |
The error response of the called service, with the original status, its errors and its body |
OutboundBlockedException |
The destination refused by the guard |
- Thin layer: no
new HttpClient(), no pipeline of its own. The client is resolved fromIHttpClientFactoryon every call, so handler rotation and DNS refresh keep working. - Failures in the Tooark standard: an error status, a timeout, an open circuit, a connection failure and a blocked destination each become a Tooark exception with a message key.
- Fails at startup: invalid options are rejected at registration, including the combinations the resilience handler would only reject on the first request.
- No per-call state: the service is a singleton and safe for concurrent use.
π§ Installation
dotnet add package Tooark.Http
The package runs on the base .NET runtime, without ASP.NET Core. It also comes with the Tooark aggregator, but
AddTooarkService does not register the client: call AddTooarkHttpClient in the application.
βοΈ Configuration
appsettings.json
Everything is optional. The example shows every option with its default value, except the base address and the guard lists:
{
"HttpClient": {
"BaseAddress": "https://api.example.com/v1",
"TotalTimeoutSeconds": 30,
"AttemptTimeoutSeconds": 10,
"RetryCount": 3,
"RetryNonIdempotentMethods": true,
"RetryDelayMilliseconds": 2000,
"CircuitBreakerFailureRatio": 0.1,
"CircuitBreakerMinimumThroughput": 100,
"CircuitBreakerSamplingSeconds": 30,
"CircuitBreakerBreakSeconds": 5,
"Resilience": true,
"OutboundGuard": {
"Enabled": false,
"AllowedHosts": [".internal.example.com"],
"AllowedNetworks": ["10.20.0.0/16"]
}
}
}
Program.cs
using Tooark.Http.Injections;
// Reads the HttpClient section
builder.Services.AddTooarkHttpClient(builder.Configuration);
// Or without reading the configuration, only with adjustments in code
builder.Services.AddTooarkHttpClient(options =>
{
options.BaseAddress = "https://api.example.com/v1";
options.RetryCount = 2;
});
With both configuration and code, the code adjustment applies on top of the section. The options are validated at
registration. Only the first registration of the default client counts: the handlers of a client in
IHttpClientFactory accumulate, and a second registration would stack another resilience handler and multiply the
retries. For another destination, with other options, register a named client.
The default client is the IHttpClientFactory client named HttpClientService.ClientName ("Tooark"). Anything
else it needs goes through the standard IHttpClientFactory API, after the registration:
using Tooark.Http;
builder.Services
.AddHttpClient(HttpClientService.ClientName)
.ConfigureHttpClient(client => client.DefaultRequestHeaders.Add("X-Api-Key", apiKey))
.AddHttpMessageHandler<MyAuthenticationHandler>();
A handler added this way sits inside the resilience handler, so it runs once per attempt. A header that changes on every call does not go here: use the methods with a request adjustment.
Client options β HttpClient
| Property | Type | Default | Description |
|---|---|---|---|
BaseAddress |
string |
none | Absolute http or https URL, without credentials, query string or fragment. Required for relative URIs |
TotalTimeoutSeconds |
int |
30 |
Time limit of the call: all attempts and the body read (streaming: up to the headers). From 1 to 3600 |
AttemptTimeoutSeconds |
int |
10 |
Time limit of each attempt, up to the response headers. From 1 to TotalTimeoutSeconds |
RetryCount |
int |
3 |
Retries after the first attempt. From 0 to 10; 0 turns retries off |
RetryNonIdempotentMethods |
bool |
true |
Also retries POST and PATCH; with false, only the other verbs. In v5 the default becomes false |
RetryDelayMilliseconds |
int |
2000 |
Base delay between attempts; it grows exponentially, with jitter. From 0 to 60000 |
CircuitBreakerFailureRatio |
double |
0.1 |
Failure ratio, from 0 to 1, that opens the circuit within the sampling window |
CircuitBreakerMinimumThroughput |
int |
100 |
Minimum number of requests in the window before the ratio is evaluated. At least 2 |
CircuitBreakerSamplingSeconds |
int |
30 |
Sampling window. From twice AttemptTimeoutSeconds to 86400 |
CircuitBreakerBreakSeconds |
int |
5 |
How long the circuit stays open before the service is tried again. From 1 to 86400 |
Resilience |
bool |
true |
Registers the resilience handler. With false, only TotalTimeoutSeconds still applies |
OutboundGuard |
object | β | Options of the outbound guard, below |
RetryNonIdempotentMethods exists since v4.11.0. In v5 its default becomes false: a failure of a POST or of
a PATCH is returned on the first attempt, and the other verbs are still retried. To keep the 4.x behavior after
the migration, set "RetryNonIdempotentMethods": true; to adopt the v5 behavior now, set it to false. The
details are in Resilience.
A named client has the same options, in the section HttpClients:{name}.
Guard options β HttpClient:OutboundGuard
| Property | Type | Default | Description |
|---|---|---|---|
Enabled |
bool |
false |
Turns the guard on for the client. It is off by default because the default client typically calls internal services |
AllowedHosts |
string[] |
none | Host names exempt from the address check: an exact name, or a suffix starting with a dot (.internal.example.com) |
AllowedNetworks |
string[] |
none | CIDR blocks, IPv4 or IPv6, exempt from the block list (10.20.0.0/16, fd00:1::/64) |
For a named client, the guard section is HttpClients:{name}:OutboundGuard.
Named clients
Since v4.11.0, AddTooarkNamedHttpClient registers one client per destination, each with its own options: base
address, timeouts, retries, circuit breaker and outbound guard. The options of each client come from the section
HttpClients:{name} (the constant HttpClientOptions.NamedSection), with the same keys as the HttpClient
section. The HttpClients section, in the plural, sits next to the HttpClient section, not inside it:
{
"HttpClient": {
"BaseAddress": "https://api.example.com/v1"
},
"HttpClients": {
"models": {
"BaseAddress": "https://models.example.com/",
"TotalTimeoutSeconds": 300,
"AttemptTimeoutSeconds": 300,
"CircuitBreakerSamplingSeconds": 600
},
"payments": {
"BaseAddress": "https://payments.example.com/v2",
"RetryNonIdempotentMethods": false
}
}
}
using Tooark.Http.Injections;
// The default client, from the HttpClient section
builder.Services.AddTooarkHttpClient(builder.Configuration);
// Each named client reads its own section: HttpClients:models and HttpClients:payments
builder.Services.AddTooarkNamedHttpClient("models", builder.Configuration);
builder.Services.AddTooarkNamedHttpClient("payments", builder.Configuration, options => options.RetryCount = 1);
// Or without reading the configuration, only with adjustments in code
builder.Services.AddTooarkNamedHttpClient("reports", options =>
{
options.BaseAddress = "https://reports.example.com";
options.RetryCount = 0;
});
The IHttpClientService of each client is a keyed service, and the key is the name:
using Microsoft.Extensions.DependencyInjection;
using Tooark.Http.Interfaces;
public sealed record QuestionDto(string Text);
public sealed record AnswerDto(string Text);
public sealed class ModelGateway([FromKeyedServices("models")] IHttpClientService http)
{
// Goes to https://models.example.com/v1/answers, with the timeouts of the "models" client
public Task<AnswerDto?> AskAsync(QuestionDto question, CancellationToken cancellationToken) =>
http.PostAsync<QuestionDto, AnswerDto>("v1/answers", question, cancellationToken);
}
// Or straight from the service provider
var payments = provider.GetRequiredKeyedService<IHttpClientService>("payments");
- The default client does not change. The
IHttpClientServicewithout a key is still the one of theTooarkclient, and it does not need to be registered for a named client to work. - The name is also the client name in
IHttpClientFactory. A fixed header or an authentication handler goes throughAddHttpClient("models"), after the registration, as with the default client. For that reason, do not use the name of a client the application already registers for another purpose. - Rejected names: the name cannot be empty, contain
:or beTooark. The registration throwsArgumentException. - Only the first registration of each name counts, as with the default client.
- The options are validated at registration, with the same
Options.HttpClient.*messages as the default client, without the client name. - Strict configuration: the
HttpClients:{name}section of each registered client is checked, like theHttpClientsection. With"Tooark": { "StrictConfiguration": true }, an unknown key fails at registration with a message such asOptions.Configuration.UnknownKey;HttpClients:models;TotalTimeout. See strict configuration.
π Service
IHttpClientService is registered as a singleton. Request bodies are serialized and response bodies are read with
System.Text.Json and JsonSerializerDefaults.Web: camelCase names, case-insensitive reading, numbers accepted as
strings.
| Method | Request body | Response body |
|---|---|---|
GetAsync<TResponse>(uri) |
β | JSON |
PostAsync<TRequest, TResponse>(uri, body) |
JSON | JSON |
PostAsync<TRequest>(uri, body) |
JSON | not read |
PutAsync<TRequest, TResponse>(uri, body) |
JSON | JSON |
PutAsync<TRequest>(uri, body) |
JSON | not read |
PatchAsync<TRequest, TResponse>(uri, body) |
JSON | JSON |
PatchAsync<TRequest>(uri, body) |
JSON | not read |
DeleteAsync(uri) |
β | not read |
DeleteAsync<TResponse>(uri) |
β | JSON |
SendAsync(HttpRequestMessage) |
the caller's | raw response |
SendStreamingAsync(HttpRequestMessage) |
the caller's | raw response, body not read yet |
Every method takes an optional CancellationToken as the last parameter. The verb methods also have versions that
take a request adjustment before the token: see Per-call headers.
using Tooark.Http.Interfaces;
public sealed record CustomerDto(int Id, string Name);
public sealed record CreateCustomerDto(string Name);
public sealed record RenameCustomerDto(string Name);
public sealed class CustomerGateway(IHttpClientService http)
{
// GET: null when the response is 204 or has no body
public Task<CustomerDto?> GetAsync(int id, CancellationToken cancellationToken) =>
http.GetAsync<CustomerDto>($"customers/{id}", cancellationToken);
// POST with a response body
public Task<CustomerDto?> CreateAsync(CreateCustomerDto customer, CancellationToken cancellationToken) =>
http.PostAsync<CreateCustomerDto, CustomerDto>("customers", customer, cancellationToken);
// PUT without reading the response
public Task ReplaceAsync(CustomerDto customer, CancellationToken cancellationToken) =>
http.PutAsync($"customers/{customer.Id}", customer, cancellationToken);
// PATCH with a response body
public Task<CustomerDto?> RenameAsync(int id, RenameCustomerDto rename, CancellationToken cancellationToken) =>
http.PatchAsync<RenameCustomerDto, CustomerDto>($"customers/{id}", rename, cancellationToken);
// DELETE
public Task RemoveAsync(int id, CancellationToken cancellationToken) =>
http.DeleteAsync($"customers/{id}", cancellationToken);
}
The rules of the JSON methods:
- Request body: serialized before sending, as
application/json; charset=utf-8withContent-Length, so a retry sends the same bytes again. - Response body: a
204or an empty body returnsdefault(nullfor a reference type). A body that is not valid JSON forTResponsethrowsBadGatewayExceptionwithHttp.InvalidResponse. The methods withoutTResponsedo not read the body. - Error status: any status outside 2xx throws
HttpRequestFailedException.
Request URI and base address
- An absolute URI is used as it is and must be
httporhttps; anything else throwsBadRequestExceptionwithHttp.RequestUriInvalid, because an absolute URI may have come from the user. - A relative URI is combined with
BaseAddress. Without a base address it throwsInternalServerErrorExceptionwithHttp.BaseAddressNotConfigured. - A base address with a path gets the missing trailing slash: with
https://api.example.com/v1,customers/7goes to/v1/customers/7. A relative URI that starts with a slash replaces the whole path:/customers/7goes to/customers/7, without/v1.
Per-call headers
For a header that changes on every call (the user's authorization, an idempotency key, a different Accept), the
verb methods have, since v4.11.0, versions that take an Action<HttpRequestMessage> right before the cancellation
token. They are extension methods in the namespace Tooark.Http.Extensions, for GetAsync, PostAsync,
PutAsync, PatchAsync and DeleteAsync:
using System.Net.Http.Headers;
using Tooark.Http.Extensions;
using Tooark.Http.Interfaces;
public sealed record OrderDto(int ProductId, int Quantity);
public sealed record ReceiptDto(string Protocol);
public sealed class OrderGateway(IHttpClientService http)
{
// The authorization is the one of the user of this call, not a fixed one of the client
public Task<ReceiptDto?> CreateAsync(OrderDto order, string userToken, CancellationToken cancellationToken) =>
http.PostAsync<OrderDto, ReceiptDto>(
"orders",
order,
request => request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", userToken),
cancellationToken);
// The idempotency key lets the called service recognize a retry of the same order
public Task ConfirmAsync(OrderDto order, Guid key, CancellationToken cancellationToken) =>
http.PostAsync(
"orders/confirmations",
order,
request => request.Headers.Add("Idempotency-Key", key.ToString()),
cancellationToken);
}
- Same behavior as the interface methods: JSON both ways,
HttpRequestFailedExceptionon an error status and transport failures as the Tooark exceptions. - The action runs once, before the first attempt, and retries resend the same request. A value that must change on every attempt goes into a handler of the client, which runs once per attempt.
- Same header on every call: configure the client, with the
ConfigureHttpClientshown in the configuration section. - Another implementation of
IHttpClientService(a test fake, a decorator): the call goes through itsSendAsync, with the same JSON and the same error conversion.
SendAsync: the escape hatch
For what the verb methods do not cover (a body that is not JSON, reading the status, another verb), build the
HttpRequestMessage and call SendAsync. The request goes through the same client, with the resilience and the
guard, and the response comes back with its body already loaded in memory. An error status does not throw
here; transport failures (timeout, open circuit, connection, blocked destination) do, as in the other methods. The
caller disposes the response. Just to add a header to a JSON call, prefer the methods of
Per-call headers, which keep the JSON reading and the conversion of the error status.
using var request = new HttpRequestMessage(HttpMethod.Head, $"files/{id}");
request.Headers.Add("X-Request-Source", "billing");
using var response = await http.SendAsync(request, cancellationToken);
var exists = response.StatusCode == HttpStatusCode.OK;
SendStreamingAsync: the streaming response
Since v4.11.0, SendStreamingAsync returns the response as soon as the headers arrive, without loading the body
in memory. It is the send for long or continuous responses: server-sent events (text/event-stream), the chunked
response of a language model, a large file. The request goes through the same client, with the resilience and the
guard, and, as in SendAsync, an error status does not throw.
using System.Net.Http.Headers;
using Tooark.Http.Exceptions;
using var request = new HttpRequestMessage(HttpMethod.Get, "events");
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("text/event-stream"));
// The token applies up to the headers; the caller disposes the response
using var response = await http.SendStreamingAsync(request, cancellationToken);
if (!response.IsSuccessStatusCode)
{
// An error status does not throw: the decision is the caller's
throw new HttpRequestFailedException(response.StatusCode, response.RequestMessage?.RequestUri);
}
// The deadline of the body read is the one of the token passed to it, not the timeout of the call
await using var body = await response.Content.ReadAsStreamAsync(cancellationToken);
using var reader = new StreamReader(body);
while (await reader.ReadLineAsync(cancellationToken) is { } line)
{
// Each line arrives as soon as the called service sends it
}
- Timeout:
TotalTimeoutSecondsand the token passed to the method apply up to the response headers. The body read may last longer than the timeout of the call, and nothing cuts it by itself: control its deadline with your own token, passed toReadAsStreamAsyncand to every read. - Disposal: the caller disposes the response, which releases the connection, also when giving up on the body halfway.
- Failures: up to the headers, the retries and the Tooark exceptions apply (timeout, open circuit, connection,
blocked destination), as in the other methods. A failure while reading the body arrives as the transport
exception (
IOException,HttpRequestException), not as a Tooark exception, and is not retried. - Other implementations: the method has a default implementation in the interface. A hand-written
implementation of
IHttpClientService, written before it existed, keeps compiling and serves it throughSendAsync, with the body already loaded.
π Resilience
With Resilience on (the default), the client gets the standard resilience handler of
Microsoft.Extensions.Http.Resilience, configured from the options. Its strategies, from the outside in:
| Strategy | Default | Option |
|---|---|---|
| Concurrency limiter | 1000 simultaneous requests, no queue | not configurable here |
| Total timeout | 30 s | TotalTimeoutSeconds |
| Retry | 3 retries, exponential from 2 s, jitter | RetryCount, RetryDelayMilliseconds, RetryNonIdempotentMethods |
| Circuit breaker | 10% failures of at least 100 requests in 30 s; open for 5 s | CircuitBreaker* |
| Attempt timeout | 10 s | AttemptTimeoutSeconds |
What you need to know to tune it:
- What is retried: a connection failure, an attempt timeout and the responses
408,429and5xx. ARetry-Afterheader of the response is honored. The other4xxare not retried. - POST and PATCH are retried too, by default. That is the behavior of the standard handler, and of 4.x. The two
verbs are not idempotent: a retry can repeat the effect of a call the called service had already processed (an
order created twice, a charge made twice). Since v4.11.0,
RetryNonIdempotentMethods: falseturns the retry off for those two only: they are repeated neither on a5xxresponse nor on a connection failure. GET, PUT and DELETE are still retried, and the failure of the POST or of the PATCH still counts in the circuit. The option looks at the verb of the request, so it also applies toSendAsync, toSendStreamingAsyncand to the methods with a request adjustment; withRetryCount: 0orResilience: falsenothing is retried, and it has no effect. The alternative is to make the operation idempotent, with an idempotency key sent per call. - In v5, POST and PATCH are no longer retried by default:
RetryNonIdempotentMethodsbecomesfalsewhen not set. To keep the 4.x behavior, set"RetryNonIdempotentMethods": true; to adopt the v5 behavior now, set it tofalse. - Timeouts: the attempt timeout and the handler's total timeout end at the response headers. The service
applies
TotalTimeoutSecondsagain to the whole call, so a body that stops arriving is also cut. Either way the failure isGatewayTimeoutException. The exception isSendStreamingAsync: there the timeout ends at the headers, and the deadline of the body read is the caller's. - One circuit per client. The circuit counts the failures of a client as a whole, not per host. It is the right
grain for a client with a
BaseAddress: register a named client for each known destination, and the failures of one destination do not open the circuit of the others. If the same client calls many unrelated hosts (webhooks of different customers), the failures of one can open the circuit for all: raiseCircuitBreakerFailureRatioandCircuitBreakerMinimumThroughput, and keep that traffic on a named client of its own, apart from the circuit of the internal calls. - Valid combinations:
AttemptTimeoutSecondscannot exceedTotalTimeoutSeconds, andCircuitBreakerSamplingSecondsmust be at least twiceAttemptTimeoutSeconds. Raising the attempt timeout above 15 s therefore requires raising the sampling window too. Both are checked at registration. - Turning it off:
Resilience: falseremoves the handler.TotalTimeoutSecondsstill applies, throughHttpClient.Timeoutand the service.
builder.Services.AddTooarkHttpClient(builder.Configuration, options =>
{
// A slow report endpoint that must not be called twice
options.TotalTimeoutSeconds = 120;
options.AttemptTimeoutSeconds = 120;
options.CircuitBreakerSamplingSeconds = 240;
options.RetryCount = 0;
});
// A payment service: POST and PATCH without a retry, the other verbs with it
builder.Services.AddTooarkNamedHttpClient("payments", builder.Configuration, options =>
{
options.RetryNonIdempotentMethods = false;
});
π¨ Error Handling
Every failure of a call becomes a Tooark exception. With Tooark.AspNetCore, the exception handler turns it into
the Problem Details response of the application with the status below.
| Failure | Exception | Status | Message |
|---|---|---|---|
| The called service answers with an error status | HttpRequestFailedException (BadGatewayException) |
502 | the errors of the called service, or Http.RequestFailed;{status} |
| Timeout of an attempt or of the whole call | GatewayTimeoutException |
504 | Http.RequestTimeout |
| Open circuit | ServiceUnavailableException |
503 | Http.CircuitOpen |
| Concurrency limit of the client reached | ServiceUnavailableException |
503 | Http.ConcurrencyLimitReached |
| Connection failure, no response | BadGatewayException |
502 | Http.ConnectionFailed |
| Success response with invalid JSON | BadGatewayException |
502 | Http.InvalidResponse |
| Destination refused by the outbound guard | OutboundBlockedException (BadRequestException) |
400 | Http.OutboundBlocked;{host} |
Absolute URI that is not http or https |
BadRequestException |
400 | Http.RequestUriInvalid |
Relative URI without BaseAddress |
InternalServerErrorException |
500 | Http.BaseAddressNotConfigured |
| Cancellation by the caller's token | OperationCanceledException, untouched |
β | β |
Body read failure in SendStreamingAsync |
IOException/HttpRequestException, untouched |
β | β |
The original exception (the HttpRequestException, the Polly rejection) is kept in InnerException for the log.
Error responses of the called service
An error status of the called service is not the status of the application: a 404 or a 401 from another
service must not become a 404 or a 401 for whoever called the application. HttpRequestFailedException is
always a 502, and exposes the original status in UpstreamStatusCode, the request URI in RequestUri and the
body of the error response in UpstreamBody.
using System.Net;
using Tooark.Http.Exceptions;
using Tooark.Http.Interfaces;
public sealed class CustomerGateway(IHttpClientService http)
{
public async Task<CustomerDto?> FindAsync(int id, CancellationToken cancellationToken)
{
try
{
return await http.GetAsync<CustomerDto>($"customers/{id}", cancellationToken);
}
catch (HttpRequestFailedException exception) when (exception.UpstreamStatusCode == HttpStatusCode.NotFound)
{
// For this application, a customer that does not exist is not an error
return null;
}
}
}
The notifications of the exception depend on the body of the error response:
Tooark Problem Details β
Content-Type: application/problem+jsonwith theerrorslist ofcode,keyandmessage, which is whatTooark.AspNetCorereturns. Each entry becomes aNotificationItemwith the same code, key and message, so a Tooark service that calls another keeps the original errors:{ "status": 400, "title": "Bad Request", "errors": [ { "code": "T.VLD.STR1", "key": "Email", "message": "Field Email is required" }, { "code": "T.VLD.NUM3", "key": "Age", "message": "Field Age must be greater than 18" } ] }Any other body β a single item with the message
Http.RequestFailed;{status}. The raw body never goes into the message or the notifications: it may carry internal details of the called service.
The error body is read up to 64 KB, in any format; a larger one is ignored. At most 50 errors are used, and each
text is cut at 1024 characters. RequestUri may carry sensitive data in the query string: do not return it in a
response.
Error response body
Since v4.11.0, HttpRequestFailedException exposes the body of the error response in UpstreamBody, as text and
in any format: the error JSON of a provider, plain text, an HTML page. It lets the application read the reason for
the failure and build its own message:
using System.Net;
using Tooark.Exceptions;
using Tooark.Http.Exceptions;
using Tooark.Http.Interfaces;
public sealed record SubscriptionDto(int PlanId);
public sealed class SubscriptionGateway(IHttpClientService http)
{
public async Task SubscribeAsync(SubscriptionDto subscription, CancellationToken cancellationToken)
{
try
{
await http.PostAsync("subscriptions", subscription, cancellationToken);
}
catch (HttpRequestFailedException exception) when (exception.UpstreamStatusCode == HttpStatusCode.PaymentRequired)
{
// The application reads what the provider said and answers with its own key, not with the provider's text
throw new UnprocessableEntityException(
IsOutOfFunds(exception.UpstreamBody) ? "Subscription.OutOfFunds" : "Subscription.PaymentRefused");
}
}
// The body comes from outside: it may be null, not be JSON or not have the expected shape
private static bool IsOutOfFunds(string? body) =>
body is not null && body.Contains("insufficient_funds", StringComparison.Ordinal);
}
- Null when the response has no body, when the body exceeds 64 KB or when reading it fails.
- Outside the message: the message and the notifications of the exception stay the same,
Http.RequestFailed;{status}or the errors of the Tooark Problem Details. The package does not put the body in the message, in the notifications or in the log. - Untrusted: it is what the called service wrote, and it may carry internal data of that service or text controlled by third parties. Do not return it as it is in the response of the application: read what you need and build your own message.
π Outbound Guard
When the application calls a URL provided by the user (a webhook, an avatar to import, a link to preview), the
user chooses where the server connects. Without a check, http://169.254.169.254/ reads the cloud credentials of
the instance and http://localhost:9200/ reaches a service that was never exposed. That is server-side request
forgery (SSRF).
The guard checks the IP address at connection time, not the text of the URL. It is the ConnectCallback of
SocketsHttpHandler: it resolves the name once, checks every address against the block list and connects to the
address it checked. A public name that resolves to an internal address is refused, and so is a name whose DNS
answers differently between the check and the connection (DNS rebinding), because there is no second resolution.
What is blocked
| Range | What it is |
|---|---|
0.0.0.0/8 |
"This network"; 0.0.0.0 reaches the host itself on several systems |
127.0.0.0/8, ::1 |
Loopback |
10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 |
Private networks |
169.254.0.0/16, fe80::/10 |
Link-local, including the metadata address 169.254.169.254 |
100.64.0.0/10 |
Carrier-grade NAT, also used by internal cloud networks |
fc00::/7, fec0::/10 |
IPv6 unique local and site-local |
192.0.0.0/24 |
IETF protocol assignments |
192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32 |
Documentation |
198.18.0.0/15 |
Benchmarking |
224.0.0.0/4, ff00::/8 |
Multicast |
240.0.0.0/4 |
Reserved, including the broadcast 255.255.255.255 |
::/96 |
Unspecified (::) and the deprecated IPv4-compatible addresses |
64:ff9b:1::/48, 100::/64 |
Local-use NAT64 and discard-only |
::ffff:a.b.c.d, 64:ff9b::/96, 2002::/16, 2001::/32 |
IPv4-mapped, NAT64, 6to4 and Teredo: classified by the IPv4 they carry |
The same rule is available as a pure function, OutboundGuard.IsBlocked(IPAddress).
If any address a name resolves to is blocked, the whole host is refused: a name that mixes a public and an
internal address is the shape of a rebinding attack. The refusal is an OutboundBlockedException, a
BadRequestException with Http.OutboundBlocked;{host}. The message carries the host of the URL, never the
address it resolved to.
Webhook example
Turn the guard on for the Tooark client when it sends to user-provided URLs:
using Tooark.Http.Injections;
using Tooark.Http.Interfaces;
builder.Services.AddTooarkHttpClient(builder.Configuration, options => options.OutboundGuard.Enabled = true);
public sealed record OrderPaidEvent(int OrderId, decimal Amount);
public sealed class WebhookSender(IHttpClientService http)
{
// The URL was registered by the customer: the guard refuses it when it leads to the internal network
public Task SendAsync(string webhookUrl, OrderPaidEvent payload, CancellationToken cancellationToken) =>
http.PostAsync(webhookUrl, payload, cancellationToken);
}
Or keep the Tooark client for internal services and give the webhooks a named client, with the
guard on for it alone and its own circuit:
using Microsoft.Extensions.DependencyInjection;
using Tooark.Http.Injections;
using Tooark.Http.Interfaces;
builder.Services.AddTooarkHttpClient(builder.Configuration);
builder.Services.AddTooarkNamedHttpClient("notifications", options => options.OutboundGuard.Enabled = true);
public sealed class WebhookSender([FromKeyedServices("notifications")] IHttpClientService http)
{
public Task SendAsync(string webhookUrl, OrderPaidEvent payload, CancellationToken cancellationToken) =>
http.PostAsync(webhookUrl, payload, cancellationToken);
}
On a client that is not a Tooark one (a named or typed HttpClient of the application itself), the guard goes in
through AddTooarkOutboundGuard, where it is on by default:
using Tooark.Http.Injections;
var webhooks = builder.Services.AddHttpClient("webhooks");
// Resilience first, guard after: the refusal is not retried and does not count in the circuit
webhooks.AddStandardResilienceHandler();
webhooks.AddTooarkOutboundGuard();
On such a client, HttpClient throws the OutboundBlockedException itself. Call AddTooarkOutboundGuard
after the resilience handler and after any configuration of the primary handler: a resilience handler added
later would treat the refusal as a transient failure, and a ConfigurePrimaryHttpMessageHandler that replaces the
handler later removes the connection check. On a client registered by AddTooarkHttpClient or by
AddTooarkNamedHttpClient, turn the guard on with the option OutboundGuard.Enabled, which already places it in
that order.
The guard needs a SocketsHttpHandler as the primary handler. One that the application already configured is kept,
with only its ConnectCallback replaced. A primary handler of another type, such as an HttpClientHandler with
client certificates, is replaced by a new SocketsHttpHandler and its settings are lost: configure the
SocketsHttpHandler directly (SslOptions, Proxy, PooledConnectionLifetime) before adding the guard.
Allow lists
webhooks.AddTooarkOutboundGuard(options =>
{
options.AllowedHosts = ["partner.internal.example.com", ".svc.cluster.local"];
options.AllowedNetworks = ["10.20.0.0/16", "fd00:1::/64"];
});
AllowedHostsβ the name is trusted, whatever it resolves to. An exact name, or a suffix starting with a dot:.internal.example.comallowsapi.internal.example.com, but notinternal.example.comitself norevilinternal.example.com. Case is ignored. Only names: an address goes intoAllowedNetworks.AllowedNetworksβ CIDR blocks exempt from the block list. A single address is written with/32or/128, and the base address must be the network's (10.20.0.1/16is rejected). An allowed IPv4 network also covers the IPv4-mapped form (::ffff:10.20.0.5). NAT64, 6to4 and Teredo addresses are blocked by the IPv4 they carry, but are not allowed by it: allow their own IPv6 block if you need them.
An invalid entry fails at registration.
Redirects
SocketsHttpHandler follows redirects by itself, and each hop to another host opens its own connection, which goes
through the same check. A destination that passes and then redirects to http://169.254.169.254/ is refused at the
second hop.
With an outbound proxy
With a proxy (the HTTP_PROXY/HTTPS_PROXY variables or SocketsHttpHandler.Proxy), the connection is opened
to the proxy, and the proxy resolves the destination name. The connection check then sees only the proxy
address. What happens in that case:
- Covered: an IP literal in the request URL (
http://10.0.0.5/,http://[::1]/,http://2130706433/), which a request handler checks before the connection. - Not covered: a name that resolves to an internal address, and the hops of a redirect. Only the proxy sees
them. Block the internal ranges in the proxy's own rules, and consider turning
AllowAutoRedirectoff. - The proxy itself: an internal proxy is a blocked address. Allow it by name in
AllowedHosts; allowing its network inAllowedNetworkswould also allow IP literals in that network.
What the guard does not protect against
- Calls that do not go through a guarded client: another
HttpClient, a database driver, an SMTP or SDK client. - Public destinations. The guard does not know which public hosts the application should talk to. An allowlist of destinations per customer is the application's rule.
- Hosts in
AllowedHosts: they are not checked at all. - The response. The guard does not limit the size or the content of what the destination returns. The service
buffers a success body in memory (except in
SendStreamingAsync, where the read is the caller's) and up to 64 KB of an error body, inUpstreamBody. Do not return the response of a user-provided URL to the user as it is, nor itsUpstreamBody. - HTTP/3. A QUIC connection does not go through
ConnectCallback, so a guarded client keeps requests on HTTP/1.1 or HTTP/2. - Ports. Any port of an allowed address is reachable.
π‘ Observability
Traces and metrics of the calls come from
Tooark.Observability, with no
code in this package and no reference between the two: AddTooarkObservability registers the OpenTelemetry
HttpClient instrumentation for tracing and for metrics, and that instrumentation covers every HttpClient of the
process, the ones created by IHttpClientFactory included.
Traces: one client span per attempt, so the retries of a call appear as sibling spans. The
traceparentheader is propagated, and a called service that also usesTooark.Observabilitycontinues the same trace. The query string is removed from the span attributes by default.Metrics:
http.client.request.durationand the otherhttp.client.*instruments of .NET.Resilience events (retries, circuit state, timeouts) are published by Polly on the
Pollymeter. To export them, add the meter to the observability options:{ "Observability": { "Metrics": { "AdditionalMeters": ["Polly"] } } }
Without Tooark.Observability the package works the same way, only without telemetry.
π Usage Examples
Calling another Tooark service
The errors of the called service reach the caller of the application with their original codes and keys, inside a
502:
using Tooark.Http.Interfaces;
public sealed record CreateInvoiceDto(int CustomerId, decimal Amount);
public sealed record InvoiceDto(int Id, string Number);
public sealed class BillingGateway(IHttpClientService http)
{
// A validation error of the billing service becomes an HttpRequestFailedException with the same notifications
public Task<InvoiceDto?> CreateAsync(CreateInvoiceDto invoice, CancellationToken cancellationToken) =>
http.PostAsync<CreateInvoiceDto, InvoiceDto>("invoices", invoice, cancellationToken);
}
Reporting a refused webhook URL when it is registered
using System.Net;
using Tooark.Http;
public static bool IsLiteralAllowed(Uri webhookUrl) =>
!IPAddress.TryParse(webhookUrl.IdnHost, out var address) || !OutboundGuard.IsBlocked(address);
This is only an early message for the user. A name is not resolved here: the check that protects the application is the one at connection time.
Without dependency injection
The service has public constructors, for tools and tests: the one of the default client, with
IOptions<HttpClientOptions>, and, since v4.11.0, the one of a named client,
HttpClientService(IHttpClientFactory, HttpClientOptions, string). Both need an IHttpClientFactory, and the
resilience and the guard are those of the client registered in the factory under that name. The shortest path is
to build a service provider:
using Microsoft.Extensions.DependencyInjection;
using Tooark.Http.Injections;
using Tooark.Http.Interfaces;
using var provider = new ServiceCollection()
.AddTooarkHttpClient(options => options.BaseAddress = "https://api.example.com")
.BuildServiceProvider();
var http = provider.GetRequiredService<IHttpClientService>();
In tests of the application, mock IHttpClientService, or replace the primary handler of the client:
services.AddHttpClient(HttpClientService.ClientName).ConfigurePrimaryHttpMessageHandler(() => fakeHandler);
// On a named client, the name is the one of the registration
services.AddHttpClient("models").ConfigurePrimaryHttpMessageHandler(() => fakeHandler);
When faking IHttpClientService:
- Methods with a request adjustment: they are extensions, and they call the
SendAsyncof the fake, not itsPostAsyncorGetAsync. It isSendAsyncthat must return the response, with the status and the JSON body. SendStreamingAsync: a hand-written fake that does not implement it answers through its ownSendAsync, by the default implementation of the interface.- Named client: register the fake under the same key, with
services.AddKeyedSingleton<IHttpClientService>("models", fake).
π Dependencies
| Package | Version | Description |
|---|---|---|
Tooark.Exceptions |
4.x | Exceptions and, through it, NotificationItem |
Microsoft.Extensions.Http.Resilience |
8.x/10.x | Standard resilience handler (Polly), IHttpClientFactory |
Tooark.Observability is not a dependency: see Observability.
π― Best Practices
- Inject
IHttpClientService, never create anHttpClientβ the factory rotates the handlers and keeps the connections; anew HttpClient()per call exhausts sockets, and a static one never sees a DNS change. - Turn the guard on wherever the URL comes from the user β and keep it off, or with allow lists, for the client that calls internal services.
- Prefer
AllowedHostswith exact names β a suffix trusts every name under it, and a network trusts every address in it. - Decide the retries per service β in 4.x, POST and PATCH are retried like the other verbs. Use
RetryNonIdempotentMethods: falsefor a service that is not idempotent, orRetryCount: 0to turn all retries off. In v5 the default ofRetryNonIdempotentMethodsbecomesfalse: set the option now if the application depends on either behavior. - Do not expose the upstream failure β log
UpstreamStatusCodeandRequestUri; the response of the application is the502with the notifications.UpstreamBodyis untrusted: read what you need from it and do not return it as it is. - Pass the
CancellationTokenof the request β the caller's cancellation stops the retries and is not reported as a timeout. - Do not catch
Exceptionaround the calls β the exceptions already carry the right status; catchHttpRequestFailedExceptiononly where an upstream status has a meaning for the application. - Use a named client per destination β each destination gets its own base address, its own timeouts and its own circuit, instead of one default client tuned for the worst case.
- Dispose the response of
SendStreamingAsyncand give the read a deadline β disposing it releases the connection, and the timeout of the call does not cover the body.
β οΈ Error Codes and Solutions
Configuration errors are InternalServerErrorException thrown at registration (AddTooarkHttpClient,
AddTooarkNamedHttpClient, AddTooarkOutboundGuard) or when creating the service without dependency injection. A
named client uses the same messages, without the client name. An invalid client name (empty, with : or Tooark)
is not in the table: it is an ArgumentException.
| Message | Description | Solution |
|---|---|---|
Options.HttpClient.BaseAddressInvalid |
BaseAddress is not an absolute http/https URL, or has credentials, query string or fragment |
Use https://host/path; send credentials in a header |
Options.HttpClient.TotalTimeoutInvalid;{min};{max} |
TotalTimeoutSeconds outside 1 to 3600 |
Use a value in the range |
Options.HttpClient.AttemptTimeoutInvalid;{min};{max} |
AttemptTimeoutSeconds below 1 or above TotalTimeoutSeconds |
Lower the attempt timeout or raise the total |
Options.HttpClient.RetryCountInvalid;{min};{max} |
RetryCount outside 0 to 10 |
Use a value in the range; 0 turns retries off |
Options.HttpClient.RetryDelayInvalid;{min};{max} |
RetryDelayMilliseconds outside 0 to 60000 |
Use a value in the range |
Options.HttpClient.CircuitBreakerFailureRatioInvalid |
CircuitBreakerFailureRatio outside 0 to 1 |
Use a ratio, such as 0.1 for 10% |
Options.HttpClient.CircuitBreakerMinimumThroughputInvalid;{min} |
CircuitBreakerMinimumThroughput below 2 |
Use 2 or more |
Options.HttpClient.CircuitBreakerSamplingInvalid;{min};{max} |
CircuitBreakerSamplingSeconds below twice AttemptTimeoutSeconds, or above 86400 |
Raise the window or lower the attempt timeout |
Options.HttpClient.CircuitBreakerBreakInvalid;{min};{max} |
CircuitBreakerBreakSeconds outside 1 to 86400 |
Use a value in the range |
Options.HttpClient.OutboundGuard.AllowedHostInvalid;{value} |
Entry of AllowedHosts that is not a host name |
Remove scheme, port, path and *; put addresses in AllowedNetworks |
Options.HttpClient.OutboundGuard.AllowedNetworkInvalid;{value} |
Entry of AllowedNetworks that is not a CIDR block with the network address |
Use 10.20.0.0/16; a single address takes /32 or /128 |
Options.Configuration.UnknownKey;{section};{key} |
Unknown key in HttpClient or HttpClients:{name}, with strict configuration on |
Fix the key name, or remove it from the section |
Call errors are thrown by the service:
| Message | Exception | Description | Solution |
|---|---|---|---|
Http.RequestFailed;{status} |
HttpRequestFailedException |
The called service answered with an error status | Check UpstreamStatusCode, UpstreamBody and the called service's log |
Http.RequestTimeout |
GatewayTimeoutException |
No response within the attempt or the total timeout | Check the called service; adjust the timeouts if it is slow by design |
Http.CircuitOpen |
ServiceUnavailableException |
Too many failures: the circuit is open and calls are refused | Wait for CircuitBreakerBreakSeconds; investigate the called service |
Http.ConcurrencyLimitReached |
ServiceUnavailableException |
More than 1000 simultaneous requests on the client | Reduce the concurrency of the calls |
Http.ConnectionFailed |
BadGatewayException |
Connection refused, name not resolved, TLS failure, connection dropped | Check the address, the DNS and the network |
Http.InvalidResponse |
BadGatewayException |
The success body is not valid JSON for the response type | Check the contract and the DTO |
Http.OutboundBlocked;{host} |
OutboundBlockedException |
The guard refused the destination | Fix the URL; for a legitimate internal destination, use the allow lists |
Http.RequestUriInvalid |
BadRequestException |
The request URI is not a valid http or https URI |
Validate the URL before calling |
Http.BaseAddressNotConfigured |
InternalServerErrorException |
Relative URI and no BaseAddress |
Configure the BaseAddress of the client or pass an absolute URI |
π€ Contributing
Contributions are welcome! Start with CONTRIBUTING.md β it covers the development workflow, the coding and commit conventions and the pull request checklist. Bugs and feature requests go through the issue templates of the Tooark repository.
By participating you agree to the Code of Conduct.
π Help & Security
- β Questions, bugs, feature ideas β see SUPPORT.md for the right channel
- π Security vulnerabilities β do not open a public issue; follow SECURITY.md
π Support
If Tooark helps your projects, consider supporting its development:
- π GitHub Sponsors
- β Ko-fi
Every contribution helps keep the project maintained and improving. Thank you! π
π License
This project is licensed under the BSD 3-Clause License.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.DependencyInjection (>= 10.0.15)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.15)
- Microsoft.Extensions.FileProviders.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Http.Resilience (>= 10.11.0)
- Microsoft.Extensions.Options (>= 10.0.15)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.15)
- Tooark.Exceptions (>= 4.11.0)
-
net8.0
- Microsoft.Extensions.DependencyInjection (>= 8.0.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- Microsoft.Extensions.FileProviders.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Http.Resilience (>= 8.10.0)
- Microsoft.Extensions.Options (>= 8.0.2)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 8.0.0)
- Tooark.Exceptions (>= 4.11.0)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Tooark.Http:
| Package | Downloads |
|---|---|
|
Tooark
Package with all Tooark resources for .NET applications. |
GitHub repositories
This package is not used by any popular GitHub repositories.