Router overview
The Stella Ops Router is a gateway and a microservice SDK for .NET, for teams that want one authenticated HTTP entry point for many services without opening ports on every service host. The services connect out to the gateway and declare their endpoints in code. This page explains the parts; How it differs and the comparison set it beside other gateways, proxies and messaging libraries.
How a request flows
Clients call the gateway over HTTP. The gateway authenticates the caller, checks the claims the target endpoint requires, and forwards the request over a transport to an instance of the microservice that serves the endpoint.
client --HTTP--> gateway --transport--> microservice instance
| |
| routing state <------+ HELLO: name, version, region, endpoints
| claims check | heartbeats
Gateway
The gateway is an ASP.NET Core application. It:
- accepts microservice connections on the server half of one or more transports;
- builds a routing state from what each connected instance announces;
- authenticates callers with JWT bearer tokens from any OpenID Connect provider;
- checks each endpoint’s required claims, applies rate limits, and forwards the request;
- serves health (
/health,/health/live,/health/ready,/health/startup), metrics (/metrics), an OpenAPI document of every connected endpoint, and administration endpoints.
You run it in one of two forms:
| Form | Package | When |
|---|---|---|
The ready-made .NET tool stellaops-router-gateway | StellaOps.Router.Gateway.Host | Configuration only, every transport built in |
| Your own ASP.NET Core host | StellaOps.Router.Gateway.Hosting and the server transports you need | Custom middleware, a chosen transport set, your own deployment |
Both run the same pipeline (Router gateway host).
Microservice
A microservice is any .NET process that uses the microservice SDK, StellaOps.Microservice. It declares endpoints: a method and a path template, such as GET /invoices/{id}, each served by an endpoint class (Microservice SDK). An existing ASP.NET Core application can publish its endpoints through the ASP.NET Core bridge instead.
When the service starts, it connects to the gateway and sends a HELLO: its name, version, region, instance identifier, weight, and the list of endpoints with their timeouts, streaming flag and required claims. While it runs, it sends heartbeats with its health. On shutdown it reports draining, finishes the requests in flight, and disconnects.
Transports
A transport carries frames between gateway and service. Every transport has two halves in two packages: the server half in the gateway (StellaOps.Router.Transport.<Name>.Server) and the client half in the service (StellaOps.Router.Transport.<Name>).
| Transport | Use it for |
|---|---|
| TCP | Development and isolated networks. Unencrypted: both halves refuse it unless STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS=true. |
| TLS | Production over a network: TCP with TLS, optional client certificates (mTLS) and certificate pinning. |
| UDP | Small requests where loss is acceptable. Unencrypted, like TCP. |
| RabbitMQ | Services that already share a RabbitMQ broker with the gateway. |
| Messaging (Valkey) | Request and response queues on a Valkey server. |
| InMemory | Tests and single-process development; gateway and service in one process. |
Transports compares them and shows the configuration of each.
Endpoints and claims
An endpoint is one method and one path template. The gateway matches a request’s method and path against the endpoints of all connected instances. A request that matches none gets 404.
Each endpoint can require claims: a claim type, with or without a value (for example scope = invoices:read). The gateway requires an authenticated caller for every endpoint of an endpoint class (401 without a valid token) and refuses a caller without a required claim (403). An ASP.NET Core endpoint published through the bridge with [AllowAnonymous] is the exception: it is public through the gateway. A write endpoint (POST, PUT, PATCH, DELETE) that publishes no claims of its own takes the claims of the other endpoints on the same path (Security). The service receives only requests that passed these checks.
Instances, versions and regions
Several processes with the same service name are instances of the service. For each request, the gateway:
- takes the instances that serve the endpoint;
- keeps the healthy ones; with none healthy, the degraded ones; never the draining ones;
- prefers instances in its own region (
Gateway:Node:Region), then instances in its neighbour regions (Gateway:Node:NeighborRegions), then the other regions; - picks the instance with the lowest measured ping, then the most recent heartbeat. Only instances tied on both are chosen by weight, then at random.
An instance becomes degraded when its heartbeats are late and unhealthy when they stop; the gateway does not route to an unhealthy instance. Several instances and regions shows a worked example.
Bodies, timeouts and cancellation
- Bodies. The gateway and the service hold each request and response body in memory and send it in one frame, also for an endpoint marked as streaming. A request body may be as large as
Gateway:Routing:MaxRequestBodySize(100 MB by default) and the transport’s frame allow; a response as large as the frame allows: about 12 MiB over TCP and TLS, one datagram over UDP. A larger response is answered502(File uploads and downloads). - Timeouts. Each endpoint has a timeout. When it expires, the gateway answers the caller with
504and stops waiting for the service. - Cancellation. When the caller disconnects or the timeout expires, the gateway sends the service a cancel frame and the endpoint’s
CancellationTokenis cancelled (on Messaging, with frame protection configured) (Long requests and cancellation).
Rate limits
Limits apply in two places: the gateway counts requests per target service, in each gateway process and per environment across gateways, with overrides per service and per route; and an endpoint can limit its own work per key with the C# rate limiter (Rate limiting).
Licence
The client side (the microservice SDK, the bridge and every transport client) is Apache-2.0. The gateway, the server halves of the transports, the C# rate limiter (StellaOps.Messaging.RateLimiting and its backends) and the in-memory test harness are under the Router licence, which allows free production use up to a number of Endpoints (Router licence, Router packages).
