Router gateway host
StellaOps.Router.Gateway.Host is a ready-to-run Router gateway, installed as the .NET tool stellaops-router-gateway. StellaOps.Router.Gateway.Hosting is the same gateway as a library, for an ASP.NET Core host of your own. Both run one pipeline: the transport host that accepts microservice connections, the routing state built from their HELLO frames, the endpoint claims check, rate limiting, health and readiness, metrics, the generated OpenAPI document, the router administration endpoints and the licence monitor. Callers authenticate with standard JWT bearer tokens from any OpenID Connect provider. The gateway needs no database; Valkey is used only when environment rate limits or the Messaging transport are configured.
Run the host
export STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS=true # only for the TCP or UDP transport
stellaops-router-gateway --urls http://127.0.0.1:8080
The command is installed as described under Install the host as a .NET tool.
The host offers the TCP, TLS, UDP, RabbitMQ and Messaging transports; each one starts only when its Enabled setting is true. It reads appsettings.json from the content root (the current directory unless --contentRoot is given), environment variables (__ separates sections, for example Gateway__Transports__Tcp__Enabled=true) and command-line arguments, as any ASP.NET Core application does. A minimal configuration with TCP and an OpenID Connect provider:
{
"Authentication": {
"Schemes": {
"Bearer": {
"Authority": "https://idp.example/realms/apps",
"ValidIssuers": [ "https://idp.example/realms/apps" ],
"ValidAudiences": [ "router-gateway" ]
}
}
},
"Gateway": {
"Node": { "Region": "eu-1" },
"Transports": {
"Tcp": { "Enabled": true, "BindAddress": "0.0.0.0", "Port": 9100 }
}
}
}
The host refuses to start when JWT bearer authentication is incomplete, when an enabled transport has no loaded plugin, or when a setting that this host does not use is present (see Settings the host refuses).
Install the host as a .NET tool
The host is also packed as a .NET tool: the package StellaOps.Router.Gateway.Host installs the command stellaops-router-gateway. The package carries the host and every assembly it runs (the Router libraries, the five server transports and the Valkey backend of the Messaging transport), so it has no NuGet dependency. The machine needs the .NET 10 runtime with ASP.NET Core.
dotnet tool install StellaOps.Router.Gateway.Host --version <x.y.z-yyyyMMddTHHmmssZ> \
--tool-path /opt/router/tools --add-source <feed URL or folder holding the package>
--tool-path installs the command into that folder, which suits a service; --global installs it for the current user instead. The command reads its configuration as described under Run the host: appsettings.json in the working directory, environment variables and command-line arguments. A Messaging deployment of the tool sets Gateway:Transports:Messaging:valkey:ConnectionString.
A .NET tool redistributes the third-party assemblies it embeds, so the package carries their licence texts in third-party-licenses/, one text per NuGet package, listed with its version and licence in third-party-licenses/index.tsv. After an install with --tool-path, they are under <tool path>/.store/stellaops.router.gateway.host/<version>/stellaops.router.gateway.host/<version>/, beside the package’s own licence files.
Run the tool as a systemd service
The tool runs in the foreground and stops on SIGTERM, so a Type=simple unit fits. The working directory holds appsettings.json (and, for the TLS transport, the server certificate):
[Unit]
Description=Router gateway
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=router-gateway
WorkingDirectory=/etc/router-gateway
ExecStart=/opt/router/tools/stellaops-router-gateway --urls http://0.0.0.0:8080
Environment=DOTNET_ROOT=/usr/lib/dotnet
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
Set DOTNET_ROOT to the folder that holds the dotnet runtime when it is not in the default location. The command is an application host that finds the runtime through DOTNET_ROOT.
Windows service
The tool does not register with the Windows Service Control Manager, so sc.exe cannot run the command as a service directly. Run it under a service wrapper that starts a console process, or compose the gateway in your own host (below), call builder.Host.UseWindowsService() from the Microsoft.Extensions.Hosting.WindowsServices package, and register that executable with sc.exe create.
Compose the gateway in your own host
StellaOps.Router.Gateway.Hosting exposes the composition of the tool, so an application can host the gateway itself and add its own middleware and services. The gateway of Getting started is composed this way, with the TCP transport, forwarded headers and, as optional hardening, the removal of every X-StellaOps-* request header:
var builder = WebApplication.CreateBuilder(args);
// The gateway pipeline: the TCP server transport (Gateway:Transports:Tcp), the routing state built
// from the microservices' HELLO frames, JWT bearer authentication (Authentication:Schemes:Bearer),
// the endpoint claims check, health, metrics, the router administration endpoints and the licence
// monitor. The host stops at startup when JWT bearer authentication is not configured.
builder.AddRouterGatewayHost(typeof(TcpTransportServerPlugin).Assembly);
// Behind a reverse proxy: take the caller's address and scheme from X-Forwarded-For and
// X-Forwarded-Proto, but only from the proxies listed in ReverseProxy:KnownProxies (loopback by default).
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
foreach (var proxy in builder.Configuration.GetSection("ReverseProxy:KnownProxies").Get<string[]>() ?? [])
{
options.KnownProxies.Add(IPAddress.Parse(proxy));
}
});
var app = builder.Build();
app.UseForwardedHeaders();
// Optional hardening: the gateway host already removes the identity headers (X-StellaOps-Tenant,
// X-StellaOps-Scopes, the identity envelope and the rest) from every routed request. This middleware
// also removes every other X-StellaOps-* request header, so no caller-supplied one reaches a service.
app.Use((context, next) =>
{
foreach (var name in context.Request.Headers.Keys
.Where(key => key.StartsWith("X-StellaOps-", StringComparison.OrdinalIgnoreCase))
.ToList())
{
context.Request.Headers.Remove(name);
}
return next(context);
});
app.UseRouterGatewayHost();
await app.RunAsync();
The gateway registers the server side of each transport, so the application references the server packages it offers (StellaOps.Router.Transport.<Name>.Server, each of which brings its client package) and passes their assemblies to AddRouterGatewayHost. A gateway that offers TLS only:
// A gateway that offers TLS only: pass the server assembly of each transport it offers.
var builder = WebApplication.CreateBuilder(args);
builder.AddRouterGatewayHost(typeof(TlsTransportServerPlugin).Assembly);
var app = builder.Build();
app.UseRouterGatewayHost();
A transport assembly deployed without a reference can be named under Gateway:TransportPlugins:ImageResidentAssemblies instead. A client assembly alone is not enough: the host stops with “no server-side transport plugin for it is loaded”. The host starts only the TCP, TLS, UDP, RabbitMQ and Messaging transports; a transport of another name in an assembly passed to AddRouterGatewayHost is not started.
To add a section of your own to the health output (/health and the other health paths), register an IGatewayHealthContributor. Its Name is the property name, unique and different from the built-in ones (status, started, ready, transportReady, requiredMicroservices, missingMicroservices, traceId, licence); Describe() returns the value, called for every health request. A contributor never changes the status code.
The Messaging transport also needs a Messaging backend registered for its section before AddRouterGatewayHost registers the transport. This registers the Valkey backend when the transport is enabled, as the tool does:
// The Messaging transport also needs a backend registered for its section, before
// AddRouterGatewayHost registers the transport. This registers the Valkey backend.
var builder = WebApplication.CreateBuilder(args);
if (builder.Configuration.GetValue<bool>("Gateway:Transports:Messaging:Enabled"))
{
builder.Services.AddMessagingTransport<ValkeyTransportPlugin>(
builder.Configuration, "Gateway:Transports:Messaging");
}
builder.AddRouterGatewayHost(typeof(MessagingTransportServerPlugin).Assembly);
var app = builder.Build();
app.UseRouterGatewayHost();
Configuration
Authentication
The host registers the ASP.NET Core JWT bearer handler, which binds Authentication:Schemes:Bearer.
| Key | Required | Meaning |
|---|---|---|
Authority or MetadataAddress | one of these or SigningKeys | OpenID Connect provider whose discovery document and signing keys validate tokens |
RequireHttpsMetadata | no (default true) | Allow an http discovery address; development only |
ValidIssuers (or ValidIssuer) | yes | Accepted iss values. The handler validates the issuer only when it is configured, and providers that serve several tenants share signing keys, so the host requires it |
ValidAudiences (or ValidAudience) | yes | Accepted aud values |
SigningKeys | one of these or Authority/MetadataAddress | Symmetric keys (Issuer, base64 Value), the format dotnet user-jwts writes; for development and tests |
MapInboundClaims | no (default false in this host) | When false, claims keep their JWT names (scope, scp, roles), which is what microservices publish |
Gateway
| Key | Default | Meaning |
|---|---|---|
Gateway:Node:Region, NodeId, Environment, NeighborRegions | local, generated, dev, none | Node identity used for routing preference |
Gateway:IdentityEnvelope:SigningKey | none | Shared key that signs the caller identity sent to microservices (Caller identity for microservices). At least 32 characters; a shorter or empty value stops the host |
Gateway:TransportPlugins:ImageResidentAssemblies | none | Further transport assemblies to load at startup, beside those passed to AddRouterGatewayHost and the StellaOps.Router.Transport.* assemblies already loaded. A listed assembly that cannot be loaded stops the host |
Gateway:Transports:Tcp:* | disabled; BindAddress 0.0.0.0; Port 9100 | TCP listener; needs STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS=true (Transports) |
Gateway:Transports:Tls:* | disabled; Port 9443 | TLS listener; ServerCertificatePath, ServerCertificateKeyPath, ServerCertificatePassword, RequireClientCertificate (Transports) |
Gateway:Transports:Udp:* | disabled; Port 5102 | UDP listener; needs STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS=true (Transports) |
Gateway:Transports:RabbitMq:* | disabled; HostName localhost, Port 5672 | RabbitMQ; NodeId is required when enabled (Transports) |
Gateway:Transports:Messaging:* | disabled; valkey:ConnectionString localhost:6379 | Request and response queues on a Valkey server: valkey:ConnectionString and valkey:Database of the server; transport may be left out, and when set it must be valkey; queue names RequestQueueTemplate (router:requests:{service}), CancelControlQueueTemplate (router:cancels:{service}:{connection}) and ResponseQueueName (router:responses), which the microservices must use too; ConsumerGroup (router-gateway), RequestTimeout, LeaseDuration, HeartbeatInterval (Transports) |
Gateway:Routing:* | DefaultTimeout 30s, GlobalTimeoutCap 120s, MaxRequestBodySize 100MB | Timeouts, payload limit and instance selection (PreferLocalRegion, AllowDegradedInstances) |
Gateway:Health:* | StaleThreshold 30s, DegradedThreshold 15s (20 seconds in effect: at least twice the Messaging heartbeat, 10s), CheckInterval 5s | Heartbeat health; RequiredMicroservices keeps /health/ready at 503 until each named service is connected. A required name matches a connected service name ignoring case and a :port part; ServiceNameSuffixes (empty by default) lists endings removed from both names first, each once and in order, for example a DNS domain |
Gateway:OpenApi:* | Enabled true, Title Gateway API, TokenUrl unset | Serve the OpenAPI document generated from the connected microservices. Without TokenUrl the document declares the bearer scheme only; with it, an OAuth2 client-credentials scheme lists the scopes the endpoints require. The document states no licence |
rate_limiting | none | Gateway rate limits (Rate limiting); environment rules count in Valkey through the store the host registers (AddRouterValkeyRateLimitStore) |
The Valkey backend connects with Gateway:Transports:Messaging:valkey:ConnectionString; the Gateway:Transports:Messaging section has no connection key of its own. A transport value that names another backend stops the host with Messaging transport 'valkey' is registered in code for 'Gateway:Transports:Messaging', but 'Gateway:Transports:Messaging:transport' names '<name>'. Gateway:MessagingBackendPlugins is refused, see below.
Licence monitor
The host counts the Endpoints (method group and path template) that the connected microservices register, and reads an optional licence record offline, from a file or a licence key. The status is informational: it never changes readiness or liveness and never refuses or stops routing, and nothing is sent outside the installation. The log and the health output also carry a licence notice, which names the licensee of a licence record that covers the running version. The licence monitor guide describes the counting, the record, the statuses and the notice.
| Key | Default | Meaning |
|---|---|---|
StellaOps:ComponentLicence:Path | none | Licence file, or a directory whose *.dsse.json files are read |
StellaOps:ComponentLicence:Key | none | Licence key: the licence file as one line of standard base64; configure it or Path, not both |
StellaOps:ComponentLicence:InstallationId | none | Installation identifier the licence record names (lowercase UUID) |
Settings the host refuses
These keys are not used by this host. So that a setting never looks applied when it is not, the host stops at startup and names every one that is present:
Gateway:Auth, Gateway:Routes, Gateway:HttpsRedirect, Gateway:HttpClient, Gateway:TransportPlugins:AllowedSignerThumbprints, Gateway:TransportPlugins:RequireSignedManifest, Gateway:MessagingBackendPlugins.
Configure authentication under Authentication:Schemes:Bearer (Authentication), and the transports with the NuGet transport packages (Transports).
Endpoints
| Path | Method and access | Purpose |
|---|---|---|
/health, /health/live, /health/ready, /health/startup | GET, anonymous | Liveness, readiness and startup, with the informational licence object (licensing.md) |
/metrics | GET, anonymous | Prometheus metrics, including the licence Endpoint gauge; the connection and routing-weight gauges are on the meter StellaOps.Router.Gateway.Hosting |
/openapi.json, /openapi.yaml, /.well-known/openapi | GET, anonymous | Generated OpenAPI document (when Gateway:OpenApi:Enabled) |
/api/v1/router/instances | GET, scope router:routing:read | Connected service instances (version, region, weight, health) |
/api/v1/router/endpoints | GET, scope router:routing:read | The distinct Endpoints registered with the gateway, as the licence monitor counts them (licensing.md) |
/api/v1/router/routing/weights | GET, scope router:routing:read; POST, scope router:routing:write | Read routing weight overrides and effective weights; set a process-local override |
/api/v1/gateway/administration/router/resync | POST, scope router:routing:write | Ask one connection, or every connection, to send its endpoints again |
The scopes are read from the scope or scp claim, as one value or a space-separated list. Every other request goes to the microservice pipeline. Gateway HTTP API gives the parameters and answers of each.
Endpoint authorization
A microservice publishes each endpoint’s authorization in its HELLO frame; the gateway enforces it before it dispatches the request:
- an endpoint marked
AllowAnonymousaccepts any caller; - an endpoint that requires authentication answers
401to a request without a valid token; - an endpoint with
RequiringClaimsanswers403when the caller lacks a claim. Ascopeorscprequirement matches one value of a space-separated list; - an endpoint that declares a named authorization policy without publishing the claims it maps to answers
403, because the gateway cannot enforce the policy; - a
POST,PUT,PATCHorDELETEendpoint, or one for any method, that publishes no claims takes the claims of the other endpoints of the same service on the same path (Security).
Caller identity for microservices
A microservice never receives a caller identity that the client wrote. For every request routed to a microservice the host removes these request headers: X-StellaOps-TenantId, X-StellaOps-Tenant, X-StellaOps-Project, X-StellaOps-Actor, X-StellaOps-Scopes, X-StellaOps-Roles, X-StellaOps-Session, X-StellaOps-Client, X-Stella-Tenant, X-Stella-Project, X-Stella-Actor, X-Stella-Scopes, X-Scopes, X-Tenant-Id, the identity envelope headers (X-StellaOps-Identity-Envelope, -Signature, -Algorithm) and the raw claim names sub, tid, scope, scp, cnf, cnf.jkt, iss and client_id. The Authorization header is forwarded unchanged.
The authenticated caller travels in a signed identity envelope (the request headers X-StellaOps-Identity-Envelope, -Signature and -Algorithm), when Gateway:IdentityEnvelope:SigningKey is set (environment Gateway__IdentityEnvelope__SigningKey). Generate a random key of at least 32 characters, keep it out of source control, and give each microservice the same value: on the ASP.NET Core bridge, StellaRouterBridgeOptions.IdentityEnvelopeSigningKey. The host signs an envelope for each authenticated request, valid for two minutes, with:
| Envelope field | Source in the validated token |
|---|---|
| Subject | sub, else the name identifier claim; a caller without either gets no envelope |
| Tenant, project | stellaops:tenant, stellaops:project, when present |
| Scopes | every value of scope and scp, split on spaces |
| Roles | role, roles and the role claim type |
| Claims | iss, client_id, name, preferred_username, email, when present |
| Issuer | stellaops-router-gateway (the signer, not the token issuer) |
An anonymous request gets no envelope. Without the key the host signs nothing and logs so once at startup; microservices then see no caller identity. On the bridge, Hybrid (the default) runs such a request without a caller identity and GatewayEnforced answers 403 (ASP.NET Core bridge). The endpoint claims check above does not depend on the key.
UseRouterGatewayHost() adds this step. A host composed with the lower-level UseGatewayRequestPipeline() instead does not get it, so compose your host with UseRouterGatewayHost().
Related
- Deployment: systemd, Windows service, container, health and metrics.
- Configuration reference
- Security
- Router licence
