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.

KeyRequiredMeaning
Authority or MetadataAddressone of these or SigningKeysOpenID Connect provider whose discovery document and signing keys validate tokens
RequireHttpsMetadatano (default true)Allow an http discovery address; development only
ValidIssuers (or ValidIssuer)yesAccepted 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)yesAccepted aud values
SigningKeysone of these or Authority/MetadataAddressSymmetric keys (Issuer, base64 Value), the format dotnet user-jwts writes; for development and tests
MapInboundClaimsno (default false in this host)When false, claims keep their JWT names (scope, scp, roles), which is what microservices publish

Gateway

KeyDefaultMeaning
Gateway:Node:Region, NodeId, Environment, NeighborRegionslocal, generated, dev, noneNode identity used for routing preference
Gateway:IdentityEnvelope:SigningKeynoneShared 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:ImageResidentAssembliesnoneFurther 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 9100TCP listener; needs STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS=true (Transports)
Gateway:Transports:Tls:*disabled; Port 9443TLS listener; ServerCertificatePath, ServerCertificateKeyPath, ServerCertificatePassword, RequireClientCertificate (Transports)
Gateway:Transports:Udp:*disabled; Port 5102UDP listener; needs STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS=true (Transports)
Gateway:Transports:RabbitMq:*disabled; HostName localhost, Port 5672RabbitMQ; NodeId is required when enabled (Transports)
Gateway:Transports:Messaging:*disabled; valkey:ConnectionString localhost:6379Request 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 100MBTimeouts, 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 5sHeartbeat 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 unsetServe 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_limitingnoneGateway 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.

KeyDefaultMeaning
StellaOps:ComponentLicence:PathnoneLicence file, or a directory whose *.dsse.json files are read
StellaOps:ComponentLicence:KeynoneLicence key: the licence file as one line of standard base64; configure it or Path, not both
StellaOps:ComponentLicence:InstallationIdnoneInstallation 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

PathMethod and accessPurpose
/health, /health/live, /health/ready, /health/startupGET, anonymousLiveness, readiness and startup, with the informational licence object (licensing.md)
/metricsGET, anonymousPrometheus 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/openapiGET, anonymousGenerated OpenAPI document (when Gateway:OpenApi:Enabled)
/api/v1/router/instancesGET, scope router:routing:readConnected service instances (version, region, weight, health)
/api/v1/router/endpointsGET, scope router:routing:readThe distinct Endpoints registered with the gateway, as the licence monitor counts them (licensing.md)
/api/v1/router/routing/weightsGET, scope router:routing:read; POST, scope router:routing:writeRead routing weight overrides and effective weights; set a process-local override
/api/v1/gateway/administration/router/resyncPOST, scope router:routing:writeAsk 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:

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 fieldSource in the validated token
Subjectsub, else the name identifier claim; a caller without either gets no envelope
Tenant, projectstellaops:tenant, stellaops:project, when present
Scopesevery value of scope and scp, split on spaces
Rolesrole, roles and the role claim type
Claimsiss, client_id, name, preferred_username, email, when present
Issuerstellaops-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().