Skip to main content

Getting Started

Install​

dotnet add package UnambitiousFx.Myelin

Myelin targets net8.0, net9.0, net10.0 and net11.0. Its only dependencies are Microsoft.Extensions.Http, Microsoft.Extensions.Logging.Abstractions and Microsoft.Extensions.Options. It is trimming- and NativeAOT-compatible.

Register​

using UnambitiousFx.Myelin;

builder.Services.AddMyelin(o =>
{
o.AllowedHosts = ["api.example.com", "*.cdn.example.org"]; // empty: any public host
o.UserAgent = "MyApp/1.0 (+https://example.com)";
o.Timeout = TimeSpan.FromSeconds(10);
o.MaxRedirects = 3;
});

Or bind the options from configuration:

builder.Services.AddMyelin();
builder.Services.Configure<MyelinOptions>(builder.Configuration.GetSection("Myelin"));
appsettings.json
{
"Myelin": {
"AllowedHosts": ["api.example.com", "*.cdn.example.org"],
"UserAgent": "MyApp/1.0"
}
}

Fetch​

public sealed class IconFetcher(SafeHttpClient http)
{
public async Task<byte[]?> FetchAsync(Uri url, CancellationToken ct)
{
try
{
var response = await http.GetAsync(url, maxBytes: 512_000, ct);
return response.Status == HttpStatusCode.OK ? response.Body : null;
}
catch (OutboundRefusedException refused)
{
// refused.Reason: "address_refused", "not_https", "host_not_allowed", "too_large"...
return null;
}
}
}

A 4xx or 5xx is returned in OutboundResponse.Status, not thrown. Only a refusal throws OutboundRefusedException; network failures and the timeout throw as HttpClient would.

Options​

OptionDefaultMeaning
AllowedHosts[]Hosts a request may target. Empty allows any host whose addresses are public. *.example.com matches subdomains, not example.com.
UserAgentnullSent on every request. Some servers refuse a request without one.
Timeout30 sThe whole call: redirects and body included.
MaxRedirects3How many redirects a GET may follow.

Refusal reasons​

ReasonWhen
not_httpsThe URL is relative or not https.
user_infoThe URL carries credentials.
host_not_allowedThe host is not in AllowedHosts.
address_refusedThe host resolves to nothing, or to at least one refused address.
too_many_redirectsMore redirects than MaxRedirects.
redirect_without_locationA 3xx without Location.
redirect_refusedA redirect answered a request that is never redirected.
too_largeThe body is over the limit of the call.

Constants for all of them are in RefusalReasons.