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:

You run it in one of two forms:

FormPackageWhen
The ready-made .NET tool stellaops-router-gatewayStellaOps.Router.Gateway.HostConfiguration only, every transport built in
Your own ASP.NET Core hostStellaOps.Router.Gateway.Hosting and the server transports you needCustom 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>).

TransportUse it for
TCPDevelopment and isolated networks. Unencrypted: both halves refuse it unless STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS=true.
TLSProduction over a network: TCP with TLS, optional client certificates (mTLS) and certificate pinning.
UDPSmall requests where loss is acceptable. Unencrypted, like TCP.
RabbitMQServices that already share a RabbitMQ broker with the gateway.
Messaging (Valkey)Request and response queues on a Valkey server.
InMemoryTests 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:

  1. takes the instances that serve the endpoint;
  2. keeps the healthy ones; with none healthy, the degraded ones; never the draining ones;
  3. prefers instances in its own region (Gateway:Node:Region), then instances in its neighbour regions (Gateway:Node:NeighborRegions), then the other regions;
  4. 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

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).