Skip to main content

Registered endpoints

By default Myelin refuses every non-global address, private networks included. Some applications must still call a service they registered themselves on a private network: a worker on the same Docker Compose network, a GPU box on the LAN, a host reached over Tailscale. Registered endpoints let exactly those calls through Myelin, instead of a second, unguarded HttpClient.

:::warning A narrow, explicit opt-in Nothing changes unless you call AllowRegisteredEndpoints. Even then, only the exact https host and port pairs your IRegisteredEndpoints answers true for gain anything, and they gain only the three private-network ranges below. Never register a host:port that comes from user input. :::

Set up​

Implement IRegisteredEndpoints over wherever your application keeps its registrations, and opt in per client. The handler is long-lived and may ask from several connections at once: the implementation must be thread-safe and must not hold a scoped service (an EF Core context) directly.

public sealed class WorkerRegistry(IDbContextFactory<AppDb> contexts) : IRegisteredEndpoints
{
public async ValueTask<bool> IsRegisteredAsync(string host, int port, CancellationToken ct)
{
// One context per lookup: connections are opened concurrently.
await using var db = await contexts.CreateDbContextAsync(ct);
return await db.Workers.AnyAsync(w => w.Host == host && w.Port == port && !w.Revoked, ct);
}
}

services.AddSingleton<IRegisteredEndpoints, WorkerRegistry>();
services.AddHttpClient("workers")
.UseMyelin(o => o.AllowRegisteredEndpoints(sp => sp.GetRequiredService<IRegisteredEndpoints>()));

AddMyelin(o => o.AllowRegisteredEndpoints(...)) does the same for SafeHttpClient; a handler built by hand takes the set in MyelinHandler.Create(resolver, registeredEndpoints).

The host is passed in its IDN (punycode) form, as the URL gives it; the port is 443 when the URL has none. Match both exactly: no wildcard, no path prefix.

What a registered endpoint may reach​

RangeIANA special-purpose registry entry
10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16IPv4 Private-Use (RFC 1918)
100.64.0.0/10IPv4 Shared Address Space (RFC 6598): carrier-grade NAT, Tailscale
fc00::/7IPv6 Unique-Local (RFC 4193)

Everything else in the address policy stays refused, registered or not: loopback, link-local (169.254.0.0/16, fe80::/10), unspecified, multicast, broadcast, documentation, benchmarking, NAT64 of a private address. Two cloud metadata services that sit inside these ranges are refused too: 100.100.100.200 (Alibaba Cloud) and fd00:ec2::254 (AWS over IPv6).

AddressPolicy.IsAllowedForRegisteredEndpoint(IPAddress) is the check, if you want it elsewhere.

How it is checked​

  • At connect time, on the addresses dialled. The host is resolved again for every new connection, and every answer must be public or in the ranges above: a registered name rebinding to 127.0.0.1 is refused.
  • HTTPS only. An http URL never gets the exemption.
  • Asked per connection. IsRegisteredAsync is called whenever a new connection resolves to a private address, so registering or revoking an endpoint applies without rebuilding the client. Pooled connections of such a handler live one minute at most, so no new request reaches a revoked endpoint after a minute. A request already in progress (a long upload, a streamed response) is not cancelled by a revocation.
  • Redirects are checked again. A redirect is a new request to a new host:port: if that pair is not registered, a private answer is refused (address_refused).

A refusal is the usual OutboundRefusedException with RefusalReasons.AddressRefused, logged with host and reason only.

Client certificates and pinned keys​

A registered worker is usually identified by its key rather than its IP. Configure TLS on the primary handler after UseMyelin(); the Myelin connection check stays in place:

services.AddHttpClient("workers")
.UseMyelin(o => o.AllowRegisteredEndpoints(sp => sp.GetRequiredService<IRegisteredEndpoints>()))
.ConfigurePrimaryHttpMessageHandler((handler, sp) =>
{
var tls = ((SocketsHttpHandler)handler).SslOptions;
tls.ClientCertificates = [clientCertificate];
tls.RemoteCertificateValidationCallback = (_, certificate, _, _) => IsPinned(certificate);
});