Router features
This page walks through the features a gateway offers, one section each: what it does, when you use it, an example, its configuration in JSON and as environment variables, the cases you meet, and the pitfalls. Each section links to the page with the full detail. The features that set the Router apart are on Unique features.
Configuration keys are shown in appsettings.json form; as environment variables, : becomes __ (Gateway__Routing__GlobalTimeoutCap=10m). A list entry takes its index (Gateway__Node__NeighborRegions__0=eu-central).
Routing
What. The gateway matches each HTTP request’s method and path to an endpoint that a connected service announced, and sends the request to an instance of that service.
When. Always: a service publishes its endpoints by declaring them, and needs no route configuration in the gateway.
Example. A path parameter, which the SDK copies into the request object:
[StellaEndpoint("GET", "/invoices/{id}", TimeoutSeconds = 10)]
public sealed class GetInvoiceEndpoint : IStellaEndpoint<GetInvoiceRequest, GetInvoiceResponse>
{
private readonly ILogger<GetInvoiceEndpoint> _logger;
public GetInvoiceEndpoint(ILogger<GetInvoiceEndpoint> logger)
{
_logger = logger;
}
public Task<GetInvoiceResponse> HandleAsync(
GetInvoiceRequest request,
CancellationToken cancellationToken)
{
_logger.LogInformation("Fetching invoice {InvoiceId}", request.Id);
// Simulate invoice lookup
return Task.FromResult(new GetInvoiceResponse
{
InvoiceId = request.Id,
CustomerId = "CUST-001",
Amount = 199.99m,
Status = "paid",
CreatedAt = DateTime.UtcNow.AddDays(-7),
PaidAt = DateTime.UtcNow.AddDays(-1)
});
}
}
Configuration. None in the gateway. The service may override an endpoint’s timeout and claims in microservice.yaml (Microservice SDK).
Cases.
| Request | Answer |
|---|---|
GET /invoices/INV-001, a connected instance serves GET /invoices/{id} | Routed; Id is INV-001 |
| A path no connected service registers | 404, problem type urn:stellaops:router:endpoint-not-found |
| The path exists, but every instance is unhealthy or draining | 503 No instances available |
Pitfalls. An endpoint exists only while an instance that announces it is connected: a stopped service makes its paths 404. Paths are matched as templates, so /invoices/{id} and /invoices/{number} are the same Endpoint.
Versions and pinning
What. Each instance announces a service version. A caller can pin one with the header X-Api-Version: 1.0.0 or the media type Accept: application/vnd.stellaops.v1.0.0+json; a request that names no version reaches any version.
When. During an upgrade that changes a service’s contract, so that old callers keep the old version while new callers use the new one.
Example.
curl -i http://localhost:5080/invoices/INV-001 -H "Authorization: Bearer $TOKEN" -H "X-Api-Version: 2.0.0"
Configuration. The service sets Version in AddStellaMicroservice (a semantic version). The gateway needs nothing.
Cases. With versions 1.0.0 and 2.0.0 connected, a request pinned to 2.0.0 reaches only 2.0.0 instances, with that version’s timeout; a request pinned to 3.0.0 gets 503 No instances available, naming 3.0.0. Each version keeps its own claims: a request is authorized against the claims of the version it is routed to, so 2.0.0 may add or drop a claim that 1.0.0 requires. Claim overrides from Authority apply to every version.
Pitfalls. Versions match exactly: 1.0.0 does not match 1 or 1.0. Keep at least one instance of every version callers still pin (Several instances and regions).
Instances, health and load distribution
What. Several processes of one service are instances. Each sends heartbeats; the gateway routes to healthy instances, prefers its own region, then its neighbour regions, then the rest, and within that group picks the instance with the lowest measured ping.
When. To share load and to keep serving when an instance, a host or a site stops.
Example. A service that reads its instance id and region from configuration, so one build runs as several instances:
builder.Services.AddStellaMicroservice(options =>
{
options.ServiceName = "inventory";
options.Version = "1.0.0";
// The region of this instance (Router:Region); the gateway prefers instances in its own region.
options.Region = builder.Configuration["Router:Region"] ?? "demo";
options.InstanceId = builder.Configuration["Router:InstanceId"] ?? $"inventory-{Environment.MachineName}";
// Below the gateway's degraded threshold (Gateway:Health:DegradedThreshold; 20 s in effect by default).
options.HeartbeatInterval = TimeSpan.FromSeconds(10);
options.Routers =
[
new RouterEndpointConfig { Host = gatewayHost, Port = gatewayPort, TransportType = TransportType.Tcp }
];
});
Configuration.
{
"Gateway": {
"Node": { "Region": "eu-west", "NeighborRegions": [ "eu-central" ] },
"Health": { "DegradedThreshold": "15s", "StaleThreshold": "30s", "RequiredMicroservices": [ "billing" ] },
"Routing": { "PreferLocalRegion": true, "AllowDegradedInstances": true }
}
}
Cases. An instance whose heartbeat is late is degraded and gets requests only when no instance is healthy; one whose heartbeats stopped is not routed to. A draining instance finishes its requests and takes no new ones. Weights decide only between instances that tie on ping and heartbeat; operators override them at run time (Gateway HTTP API).
Pitfalls. A heartbeat interval above the gateway’s thresholds makes instances flap; keep the SDK default of 10 seconds. A remote region serves only when the local one has no routable instance: regions give failover, not load sharing (Several instances and regions).
Timeouts and cancellation
What. Each endpoint declares its timeout. When it expires, or the caller disconnects, the gateway answers or stops, and cancels the endpoint’s CancellationToken.
When. For every endpoint: a short timeout for quick reads, a longer one for reports and imports.
Example.
/// <summary>
/// A long request. It passes the cancellation token to every await, so it stops when the caller
/// disconnects or the gateway's timeout for the endpoint expires.
/// </summary>
[StellaEndpoint("POST", "/reports", TimeoutSeconds = 60)]
public sealed class GenerateReportEndpoint(ReportActivity activity, ILogger<GenerateReportEndpoint> logger)
: IStellaEndpoint<GenerateReportRequest, GenerateReportResponse>
{
public async Task<GenerateReportResponse> HandleAsync(GenerateReportRequest request, CancellationToken cancellationToken)
{
try
{
var report = await ReportBuilder.BuildAsync(request, cancellationToken);
activity.RecordCompleted();
return report;
}
catch (OperationCanceledException)
{
activity.RecordCancelled();
logger.LogInformation("Report of {Rows} rows cancelled", request.Rows);
throw;
}
}
}
Configuration. The endpoint: TimeoutSeconds, or defaultTimeout in microservice.yaml. The gateway caps every timeout:
{ "Gateway": { "Routing": { "GlobalTimeoutCap": "10m" } } }
Cases. A timeout gives 504 (Upstream timeout); a caller disconnect gives no answer. The service sees the cancellation on TCP, TLS, UDP and RabbitMQ, and on Messaging with frame protection (Long requests and cancellation).
Pitfalls. An endpoint that does not pass the token to its awaits keeps working after the caller is gone. A timeout above GlobalTimeoutCap (120 seconds by default) is cut to the cap.
Rate limiting
What. The gateway limits requests per target service, in each gateway process and per environment across gateways, with overrides per service and per route; an endpoint limits its own work per key.
When. Gateway limits protect the system; endpoint limits express business rules such as “10 uploads per report per minute”.
Example.
foreach (var policy in Policies)
{
var permit = await _limiter.TryAcquireAsync(reportId, policy, cancellationToken);
if (!permit.IsAllowed)
{
var deniedHeaders = new HeaderCollection();
deniedHeaders.Set("Content-Type", "text/plain; charset=utf-8");
deniedHeaders.Set(
"Retry-After",
Math.Ceiling(permit.RetryAfter?.TotalSeconds ?? 1).ToString(CultureInfo.InvariantCulture));
return new RawResponse
{
StatusCode = 429,
Headers = deniedHeaders,
Body = new MemoryStream(Encoding.UTF8.GetBytes("Too many attachments for this report."))
};
}
}
Configuration.
{
"rate_limiting": {
"for_instance": { "rules": [ { "per_seconds": 60, "max_requests": 600 } ] }
}
}
As environment variables: rate_limiting__for_instance__rules__0__per_seconds=60 and rate_limiting__for_instance__rules__0__max_requests=600.
Cases. A denied request gets 429 with Retry-After; callers with a stellaops:tenant claim are counted per tenant (Rate limiting).
Pitfalls. The in-memory endpoint limiter counts per service instance; use the PostgreSQL or Valkey backend for a limit shared by instances.
Authentication and claims
What. The gateway validates JWT bearer tokens from your OpenID Connect provider and checks the claims each endpoint publishes before it sends the request.
When. For every service endpoint; a bridged endpoint with [AllowAnonymous] is public.
Example. Claims published from microservice.yaml:
# Endpoint overrides for the billing service (keys: method, path, defaultTimeout, supportsStreaming,
# requiringClaims). The gateway enforces the claims the service publishes: a caller without a valid
# token gets 401, a caller without the scope 403.
endpoints:
- method: POST
path: /invoices
defaultTimeout: 45s
requiringClaims:
- type: "scope"
value: "invoices:write"
- method: GET
path: /invoices/{id}
requiringClaims:
- type: "scope"
value: "invoices:read"
Configuration.
{
"Authentication": {
"Schemes": {
"Bearer": {
"Authority": "https://idp.contoso.example/realms/apps",
"ValidIssuers": [ "https://idp.contoso.example/realms/apps" ],
"ValidAudiences": [ "router-gateway" ]
}
}
}
}
As environment variables: Authentication__Schemes__Bearer__Authority=..., Authentication__Schemes__Bearer__ValidIssuers__0=..., Authentication__Schemes__Bearer__ValidAudiences__0=router-gateway.
Cases. No valid token: 401. A token without a required claim: 403. A write endpoint without claims of its own takes the claims of the other endpoints on its path (Security).
Pitfalls. The gateway stops at start-up without a key source, an issuer and an audience. RequiredClaims on the attribute names claim types, not scope values; put scopes in microservice.yaml.
TLS and mutual TLS
What. The TLS transport encrypts the connection between gateway and service, can require a client certificate (mTLS), and can pin the gateway certificate in the service.
When. Whenever gateway and services talk across a network.
Example.
// TLS with a client certificate (mTLS) and the gateway certificate pinned by SHA-256 thumbprint.
services.AddTlsTransportClient(options =>
{
options.Host = "gateway.contoso.example";
options.Port = 9443;
options.ExpectedServerHostname = "gateway.contoso.example";
options.ClientCertificatePath = "/etc/contoso/billing/client.pfx";
options.ClientCertificatePassword = Environment.GetEnvironmentVariable("BILLING_CLIENT_CERT_PASSWORD");
options.EnabledProtocols = SslProtocols.Tls13;
options.CertificatePinning = new CertificatePinningOptions
{
ThumbprintsSha256 = ["9F2D6C4E7A1B3D5F8E0A2C4B6D8F1A3C5E7B9D0F2A4C6E8B1D3F5A7C9E0B2D4F"]
};
});
Configuration.
{
"Gateway": {
"Transports": {
"Tls": {
"Enabled": true,
"ServerCertificatePath": "/etc/router/tls/gateway.crt",
"ServerCertificateKeyPath": "/etc/router/tls/gateway.key",
"RequireClientCertificate": true
}
}
}
}
As environment variables: Gateway__Transports__Tls__Enabled=true and the same pattern for the other keys.
Cases. A service without a valid client certificate cannot connect; a gateway certificate that matches no pin is refused by the service (Transports).
Pitfalls. A PEM certificate needs ServerCertificateKeyPath. AllowSelfSigned without a pin stops start-up.
Size limits
What. The gateway refuses a request body above Gateway:Routing:MaxRequestBodySize and holds each body in memory; each transport carries a request or response in one frame.
When. Size the limits before you send files through the gateway.
Example. A download capped below the frame limit:
/// <summary>
/// A CSV download. The Router holds a whole response in memory and sends it in one frame, so the
/// endpoint caps the file: at most 500,000 rows, about 5.3 MB, below the 16 MiB frame of the TCP and
/// TLS transports. The query parameter rows sets the number of rows.
/// </summary>
[StellaEndpoint("GET", "/reports/{id}/download", SupportsStreaming = true, TimeoutSeconds = 60)]
public sealed class DownloadReportEndpoint : IRawStellaEndpoint
{
private const int MaxRows = 500_000;
public Task<RawResponse> HandleAsync(RawRequestContext context, CancellationToken cancellationToken)
{
var reportId = context.PathParameters["id"];
var rows = context.QueryParameters.TryGetValue("rows", out var value)
&& int.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out var parsed)
? Math.Clamp(parsed, 1, MaxRows)
: 10_000;
var csv = new StringBuilder("row,value\n");
for (var row = 1; row <= rows; row++)
{
cancellationToken.ThrowIfCancellationRequested();
csv.Append(CultureInfo.InvariantCulture, $"{row},{row * 7 % 1000}\n");
}
var headers = new HeaderCollection();
headers.Set("Content-Type", "text/csv; charset=utf-8");
headers.Set("Content-Disposition", "attachment; filename=" + reportId + ".csv");
return Task.FromResult(new RawResponse
{
StatusCode = 200,
Headers = headers,
Body = new MemoryStream(Encoding.UTF8.GetBytes(csv.ToString()))
});
}
}
Configuration.
{ "Gateway": { "Routing": { "MaxRequestBodySize": "50MB" } } }
Cases. A larger request gets 413 with maxBytes; a response above the frame gets 502 Response too large; over TCP and TLS a body may be about 12 MiB (File uploads and downloads).
Pitfalls. The frame limit applies whatever MaxRequestBodySize says.
Schema validation and OpenAPI
What. The source generator derives a JSON Schema from each typed endpoint; [ValidateSchema] refuses a body that does not match with 422, and the gateway serves one OpenAPI document of every connected endpoint.
When. For public endpoints whose callers need a precise contract and early errors.
Example.
/// <summary>A stock adjustment: a whole number of units and a reason in the body.</summary>
public sealed record AdjustStockRequest
{
/// <summary>
/// Set by the SDK from {sku} in the path, after validation. Nullable, so the schema does not
/// require it in the body.
/// </summary>
public string? Sku { get; init; }
public required int Quantity { get; init; }
public required string Reason { get; init; }
}
/// <summary>The stock after the adjustment.</summary>
public sealed record AdjustStockResponse(string Sku, int QuantityOnHand);
/// <summary>
/// Adjusts the stock of an item. [ValidateSchema] checks the JSON body against the schema the
/// source generator derives from AdjustStockRequest, so a body without the quantity or the reason, or
/// with a value of the wrong type, is answered 422 before the handler runs.
/// </summary>
[StellaEndpoint("POST", "/items/{sku}/adjustments", TimeoutSeconds = 10)]
[ValidateSchema(Summary = "Adjust the stock of an item", Tags = ["inventory"])]
public sealed class AdjustStockEndpoint : IStellaEndpoint<AdjustStockRequest, AdjustStockResponse>
{
public Task<AdjustStockResponse> HandleAsync(AdjustStockRequest request, CancellationToken cancellationToken) =>
Task.FromResult(new AdjustStockResponse(request.Sku ?? string.Empty, 100 + request.Quantity));
}
Configuration.
{ "Gateway": { "OpenApi": { "Enabled": true, "Title": "Contoso API", "CacheTtlSeconds": 300 } } }
Cases. A body with a wrong type or a missing required property: 422 with errors[]. The document: /openapi.json, /openapi.yaml (Schema validation and OpenAPI).
Pitfalls. A property the path fills must be nullable and not required, or the schema requires it in the body. The OpenAPI paths answer without a token.
Metrics, logs and traces
What. /metrics serves Prometheus metrics; the gateway logs one line per routed request (not for health, metrics, OpenAPI or administration requests); every request carries a trace identifier to the service.
When. In every deployment, scraped and collected centrally.
Example. The request log line, at Information, has this message template; each placeholder is also a structured log property:
HTTP {Method} {Path} -> {StatusCode} in {ElapsedMs}ms TraceId={TraceId} TargetService={TargetService}
Configuration. Logging levels in the standard Logging section; .NET meters for an OpenTelemetry exporter:
| Meter | Instruments |
|---|---|
StellaOps.Router.Gateway | stella_router_requests_total, stella_router_request_duration_seconds |
StellaOps.Router.Gateway.Hosting | Connections and routing weights |
StellaOps.Router.Gateway.RateLimit | stellaops.router.ratelimit.allowed, .rejected, .check_latency and the circuit breaker |
StellaOps.Router.Licence | The licence Endpoint count |
StellaOps.Router.Transport.Tls | router_tls_validate_rejected_total |
Cases. The gateway’s trace identifier reaches the service as the request’s correlation id (RawRequestContext.CorrelationId), so service logs can name it (Gateway HTTP API).
Pitfalls. /metrics has no token check; keep it on an internal interface.
Deployment
What. The gateway runs as the .NET tool or in your own host, under systemd, as a Windows service through a host of your own, or in a container; services run beside it.
When. For every production gateway.
Example.
dotnet tool install StellaOps.Router.Gateway.Host --version <x.y.z-yyyyMMddTHHmmssZ> --tool-path /opt/router/tools
Configuration. ASPNETCORE_URLS or --urls for the HTTP address, ASPNETCORE_ENVIRONMENT, and the sections above (Deployment).
Cases. Readiness probes use /health/ready, which waits for Gateway:Health:RequiredMicroservices. The gateway needs no database: it keeps its routing state in memory, built from what the connected services announce, and after a restart the state returns as the services connect again. Valkey is needed only for environment-wide rate limits or the Messaging transport, RabbitMQ only for its transport.
Pitfalls. STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS must not be set in production; give each service a stop timeout above its DrainDeadline.
Testing
What. The local in-memory harness runs a gateway inside a test process, so tests call endpoints over HTTP the way callers do, without a network or a token issuer.
When. For endpoint tests: binding, status codes, JSON, routing.
Example.
// The gateway: the core gateway pipeline with the local in-memory harness. The harness runs only
// in the Development, Testing or Local environment.
var gatewayBuilder = WebApplication.CreateBuilder(new WebApplicationOptions { EnvironmentName = "Testing" });
gatewayBuilder.WebHost.UseUrls("http://127.0.0.1:0");
gatewayBuilder.Configuration["GatewayNode:Region"] = "test";
gatewayBuilder.Services.AddSingleton(_registry);
gatewayBuilder.Services.AddRouterGateway(gatewayBuilder.Configuration);
gatewayBuilder.Services.AddRouterGatewayLocalInMemoryHarness(gatewayBuilder.Environment);
_gateway = gatewayBuilder.Build();
_gateway.UseRouterGateway();
await _gateway.StartAsync();
_http = new HttpClient { BaseAddress = new Uri(_gateway.Urls.Single()) };
Configuration. The test environment must be Development, Testing or Local.
Cases. The tests reach the endpoint classes through the gateway pipeline; authentication and transports are not exercised (Testing with the in-memory harness).
Pitfalls. The service connects in the background: wait until the gateway lists the endpoint before the first request.
