Unique features
These are the parts of the Router that work differently from a reverse proxy or an API gateway configured by files. Each section says what the feature is, when it helps, how it looks in code or configuration, the cases you meet and the pitfalls. Router features covers the features gateways have in common, and the comparison sets the Router beside other products.
Services connect out to the gateway
What. A service opens the connection to the gateway; the gateway never connects to the service. The service host needs no listening port, no load balancer entry and no inbound firewall rule.
When. Services on hosts where opening ports is slow or forbidden, behind NAT, or in many small sites; and whenever you want the list of instances to follow the processes that run.
Example. The service names the gateway it connects to:
builder.Services.AddTcpTransportClient(options =>
{
options.Host = gatewayHost;
options.Port = gatewayPort;
});
Configuration. In the service, Host and Port of the transport client (here from Router:Host and Router:Port, so Router__Host=gateway.contoso.example sets it). In the gateway, the listener:
{ "Gateway": { "Transports": { "Tls": { "Enabled": true, "Port": 9443 } } } }
Cases. A new instance is routable once its HELLO arrives; a stopped one leaves the routing state when its connection closes. After a gateway outage the services connect again on their own (Transports).
Pitfalls. The transport port is privileged: whoever connects to it can announce endpoints. Keep it on the services’ network and require client certificates (Security).
Endpoints declared in code and announced
What. An endpoint is a class with [StellaEndpoint]; the source generator finds it at compile time, and the service announces it, with its timeout and claims, when it connects.
When. When the code should be the one place that defines routes and their rules, without a gateway configuration to keep in step.
Example.
[StellaEndpoint("POST", "/invoices", TimeoutSeconds = 30)]
public sealed class CreateInvoiceEndpoint : IStellaEndpoint<CreateInvoiceRequest, CreateInvoiceResponse>
{
private readonly ILogger<CreateInvoiceEndpoint> _logger;
public CreateInvoiceEndpoint(ILogger<CreateInvoiceEndpoint> logger)
{
_logger = logger;
}
public Task<CreateInvoiceResponse> HandleAsync(
CreateInvoiceRequest request,
CancellationToken cancellationToken)
{
_logger.LogInformation(
"Creating invoice for customer {CustomerId} with amount {Amount}",
request.CustomerId,
request.Amount);
// Simulate invoice creation
var invoiceId = $"INV-{Guid.NewGuid():N}".ToUpperInvariant()[..16];
return Task.FromResult(new CreateInvoiceResponse
{
InvoiceId = invoiceId,
CreatedAt = DateTime.UtcNow,
Status = "draft"
});
}
}
Configuration. microservice.yaml overrides a timeout or the claims without a rebuild:
endpoints:
- method: POST
path: /invoices
defaultTimeout: 45s
Cases. The gateway’s Endpoint list shows what the connected services announced (Gateway HTTP API); the build reports STELLA001 to STELLA006 for endpoint mistakes (Microservice SDK).
Pitfalls. An endpoint class that is not registered in dependency injection is still announced, and answers 500. microservice.yaml cannot add an endpoint.
Claims and timeouts travel with the endpoint
What. The claims a caller needs and the endpoint’s timeout are part of what the service announces; the gateway enforces them for each request.
When. When the team that owns a service also owns who may call it and how long it may take.
Example.
# 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. In the service only. The gateway adds a cap for every timeout (Gateway:Routing:GlobalTimeoutCap, Gateway__Routing__GlobalTimeoutCap).
Cases. A caller without invoices:read gets 403 for GET /invoices/{id}; a slow call gets 504 after the endpoint’s own timeout.
Pitfalls. A write endpoint without claims takes those of the other endpoints on its path (Security).
The ASP.NET Core bridge
What. An existing ASP.NET Core application publishes its minimal API or controller endpoints to the gateway, with the claims of their authorization policies, without being rewritten.
When. To move an existing API behind the gateway, one caller at a time, while it keeps its own port.
Example.
// Publish the minimal API endpoints below to the gateway as the service "orders". The bridge
// routes the gateway's requests to the ASP.NET Core endpoints they match.
builder.Services.AddStellaRouterBridge(options =>
{
options.ServiceName = "orders";
options.Version = "1.0.0";
options.Region = "demo";
options.InstanceId = builder.Configuration["Router:InstanceId"];
options.Routers =
[
new RouterEndpointConfig { Host = gatewayHost, Port = gatewayPort, TransportType = TransportType.Tcp }
];
});
// Keep the heartbeat below the gateway's degraded threshold.
builder.Services.Configure<StellaMicroserviceOptions>(options =>
options.HeartbeatInterval = TimeSpan.FromSeconds(10));
builder.Services.AddTcpTransportClient(options =>
{
options.Host = gatewayHost;
options.Port = gatewayPort;
});
Configuration. The bridge options in code; the identity envelope key from configuration (Gateway:IdentityEnvelope:SigningKey in the gateway, the same value in the application).
Cases. A policy built with RequireClaim or a scope requirement becomes a gateway claim; an endpoint with [AllowAnonymous] is public through the gateway (ASP.NET Core bridge).
Pitfalls. Bridged requests do not run the application’s middleware. With the default OnMissingAuthorization, an endpoint without authorization metadata stops the application at start-up.
Cancellation across transports
What. A gateway timeout or a caller disconnect reaches the endpoint as a cancelled CancellationToken, on TCP, TLS, UDP and RabbitMQ, and on Messaging with frame protection.
When. For long work that should stop when nobody waits for it.
Example. The long request of Router features passes the token to every await; the gateway does the rest.
Configuration. Nothing for TCP, TLS, UDP and RabbitMQ. For Messaging, frame protection on both sides:
{ "Router": { "Frame": { "Envelope": { "ActiveKeyId": "k1", "Keys": { "k1": "<secret from your store>" } } } } }
Cases. The caller closes the connection at second 5 of a 60-second report: the service stops at the next await (Long requests and cancellation).
Pitfalls. Work that ignores the token goes on. The in-memory test harness sends no cancel.
Transports beyond HTTP
What. Gateway and services talk over TCP, TLS (with mTLS and pinning), UDP, RabbitMQ or a Valkey message queue; each request is answered on the same transport.
When. TLS across a network; RabbitMQ or Valkey where services already share a broker, or must not open connections to the gateway’s host at all.
Example.
// Messaging over Valkey: the Valkey backend reads Router:Transport:Messaging:valkey:ConnectionString,
// and the queue names must equal the gateway's (the defaults below are the gateway's defaults).
services.AddMessagingTransport<ValkeyTransportPlugin>(configuration, "Router:Transport:Messaging");
services.AddMessagingTransportClient(options =>
{
options.RequestQueueTemplate = "router:requests:{service}";
options.ResponseQueueName = "router:responses";
});
Configuration. One section per transport under Gateway:Transports (Transports).
Cases. A Messaging service and a TCP service serve the same gateway side by side.
Pitfalls. Messaging runs a request once, but a Valkey failure during the run can run it again: keep Messaging endpoints that change data idempotent. TCP and UDP are unencrypted and refuse to start without STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS.
Region preference and weights
What. Each instance announces its region and weight; the gateway prefers its own region, then named neighbour regions, then the rest, and operators override weights at run time.
When. Several sites, each with a gateway, that should keep traffic local and fail over.
Example. options.Region in the registration of Router features.
Configuration.
{ "Gateway": { "Node": { "Region": "eu-west", "NeighborRegions": [ "eu-central" ] } } }
Cases. With every eu-west instance gone, requests go to eu-central before any other region (Several instances and regions).
Pitfalls. Weights decide only between instances that tie on ping and heartbeat.
The identity envelope
What. The gateway removes the identity headers a caller sends and signs the authenticated caller into an envelope; a bridged application reads the caller from it, verified with a shared key.
When. When services behind the gateway need the caller’s identity without validating tokens themselves.
Example. The bridge options of The ASP.NET Core bridge take the key as IdentityEnvelopeSigningKey.
Configuration.
{ "Gateway": { "IdentityEnvelope": { "SigningKey": "<at least 32 characters from your secret store>" } } }
As an environment variable: Gateway__IdentityEnvelope__SigningKey.
Cases. A caller who sends X-StellaOps-Actor reaches no service with it; an authenticated caller reaches the application as HttpContext.User (ASP.NET Core bridge).
Pitfalls. Without the key on both sides the application sees no caller.
Schema validation with one OpenAPI document
What. The schemas the generator derives are both the validation rules of [ValidateSchema] and the gateway’s OpenAPI document of every connected service.
When. When the contract callers read should be the one the services enforce.
Example. The validated endpoint of Router features.
Configuration. Gateway:OpenApi:* (Schema validation and OpenAPI).
Cases. A body with "quantity": "five" gets 422 from the service, and the document shows quantity as an integer.
Pitfalls. Raw endpoints have no schema.
The in-memory test harness
What. A gateway in the test process, connected to the service over the InMemory transport.
When. Endpoint tests that should see what callers see, without a network.
Example.
// The service: the billing endpoint classes on the InMemory transport client.
var serviceBuilder = Host.CreateApplicationBuilder(new HostApplicationBuilderSettings { DisableDefaults = true });
serviceBuilder.Services.AddLogging();
serviceBuilder.Services.AddSingleton(_registry);
serviceBuilder.Services.AddStellaMicroservice(options =>
{
options.ServiceName = "billing";
options.Version = "1.0.0";
options.Region = "test";
options.InstanceId = "billing-test";
options.Routers = [new RouterEndpointConfig { Host = "localhost", Port = 1, TransportType = TransportType.InMemory }];
});
serviceBuilder.Services.AddInMemoryTransportClient();
serviceBuilder.Services.AddScoped<CreateInvoiceEndpoint>();
serviceBuilder.Services.AddScoped<GetInvoiceEndpoint>();
_service = serviceBuilder.Build();
await _service.StartAsync();
await WaitForEndpointAsync("GET", "/invoices/{id}");
Configuration. The test environment Testing, Development or Local.
Cases. POST /invoices in a test returns the endpoint’s JSON through the gateway pipeline (Testing with the in-memory harness).
Pitfalls. The harness is under the Router licence, and it runs no JWT authentication.
