Router

Internal communication fabric for Stella Ops — microservices talk through a central gateway over efficient binary transports.

The Stella Ops Router is the internal communication infrastructure that lets microservices communicate through a central gateway using efficient binary protocols, with health-aware routing, claims-based authorization, and centralized admission control.

Why Another Gateway?

Stella Ops already has HTTP-based services. The Router exists because:

1. Performance: Binary framing eliminates HTTP overhead for internal traffic
2. Streaming: First-class support for large payloads (SBOMs, scan results, evidence bundles)
3. Cancellation: Request abortion propagates across service boundaries
4. Health-aware Routing: Automatic failover based on heartbeat and latency
5. Claims-based Auth: Unified authorization via Authority integration
6. Transport Flexibility: UDP for small payloads, TCP/TLS for streams, RabbitMQ for queuing
7. Centralized Rate Limiting: Admission control at the gateway (429 + Retry-After; instance + environment scopes)

The Router generalizes the earlier HTTP-to-RabbitMQ relay pattern into a simpler, transport-agnostic design.

Architecture Overview

                                   ┌─────────────────────────────────┐
                                   │     StellaOps.Gateway.WebService│
  HTTP Clients ────────────────────►  (HTTP ingress)                 │
                                   │                                 │
                                   │  ┌─────────────────────────────┐│
                                   │  │ Endpoint Resolution         ││
                                   │  │ Authorization (Claims)      ││
                                   │  │ Routing Decision            ││
                                   │  │ Transport Dispatch          ││
                                   │  └─────────────────────────────┘│
                                   └──────────────┬──────────────────┘
                                                  │
                        ┌─────────────────────────┼─────────────────────────┐
                        │                         │                         │
                        ▼                         ▼                         ▼
              ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
              │ Billing         │       │ Inventory       │       │ Scanner         │
              │ Microservice    │       │ Microservice    │       │ Microservice    │
              │                 │       │                 │       │                 │
              │ TCP/TLS         │       │ InMemory        │       │ RabbitMQ        │
              └─────────────────┘       └─────────────────┘       └─────────────────┘

Components

Transport selection is driven by the StellaOps.Router.Common.Enums.TransportType enum, whose values are: InMemory, Udp, Tcp, Certificate (TLS/mTLS), RabbitMq, and Messaging. HTTP is explicitly excluded by design (see Invariants).

Gateway Control-Plane Endpoints

Beyond proxying microservice routes, the gateway (StellaOps.Gateway.WebService) hosts its own HTTP control-plane and system endpoints. These are treated as “system paths” so they bypass RouteDispatchMiddleware and resolve directly. Scope constants are declared in the gateway endpoint classes and registered in the canonical scope catalog (StellaOps.Auth.Abstractions/StellaOpsScopes.cs).

Notes:

• operator.verify.* scopes use dotted form (operator.verify.read, operator.verify.admin); the router routing scopes use colon form (router:routing:read, router:routing:write). Both are reflected verbatim in the source and the scope catalog.
• The POST /routing/weights override is process-local (in-memory IRoutingWeightOverrideStore), not persisted cluster-wide.
• The gateway administration group is fail-secure at its route-group boundary with policy router.routing.write. For resync, omitting connectionId intentionally requests all-fleet replay; a non-blank exact value targets one connection, an explicitly blank value returns 400, and a stale value returns 404 without broadening to the fleet.

Solution Structure

The solution file is src/Router/StellaOps.Router.sln. Libraries live under src/Router/__Libraries/ and tests under src/Router/__Tests/.

src/Router/
├── StellaOps.Router.sln
├── StellaOps.Gateway.WebService/      (HTTP ingress / gateway host)
├── StellaOps.Router.Plugin.Unified/   (unified transport plugin adapter)
├── __Libraries/
│   ├── StellaOps.Router.Common/
│   ├── StellaOps.Router.Config/
│   ├── StellaOps.Router.Gateway/
│   ├── StellaOps.Router.AspNet/
│   ├── StellaOps.Router.Transport.InMemory/
│   ├── StellaOps.Router.Transport.Tcp/
│   ├── StellaOps.Router.Transport.Tls/
│   ├── StellaOps.Router.Transport.Udp/
│   ├── StellaOps.Router.Transport.RabbitMq/
│   ├── StellaOps.Router.Transport.Messaging/
│   ├── StellaOps.Microservice/
│   ├── StellaOps.Microservice.AspNetCore/
│   ├── StellaOps.Microservice.SourceGen/
│   ├── StellaOps.Messaging/
│   ├── StellaOps.Messaging.Transport.InMemory/
│   ├── StellaOps.Messaging.Transport.Postgres/
│   └── StellaOps.Messaging.Transport.Valkey/
├── __Tests/
│   └── (test projects)
├── examples/
└── plugins/

Key Documents

Module Documentation (this directory)

Implementation Guides (docs/modules/router/guides/)

Quick Start

Gateway

var builder = WebApplication.CreateBuilder(args);

// Add router services
builder.Services.AddRouterGateway(builder.Configuration);
builder.Services.AddRouterGatewayLocalInMemoryHarness(builder.Environment); // local harness only

var app = builder.Build();

// Configure pipeline
app.UseRouterGateway();

await app.RunAsync();

Microservice

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddStellaMicroservice(options =>
{
    options.ServiceName = "billing";
    options.Version = "1.0.0";
    options.Region = "us-east-1";
});

builder.Services.AddInMemoryTransportClient();

await builder.Build().RunAsync();

Endpoint Definition

[StellaEndpoint("POST", "/invoices")]
[ValidateSchema(Summary = "Create invoice")]
public sealed class CreateInvoiceEndpoint : IStellaEndpoint<CreateInvoiceRequest, CreateInvoiceResponse>
{
    public Task<CreateInvoiceResponse> HandleAsync(
        CreateInvoiceRequest request,
        CancellationToken ct)
    {
        return Task.FromResult(new CreateInvoiceResponse
        {
            InvoiceId = Guid.NewGuid().ToString()
        });
    }
}

Invariants

These are non-negotiable design constraints:

• Method + Path is the endpoint identity (see StellaEndpointAttribute(method, path))
• Strict semver for version matching
• Region from node config — the gateway region comes from RouterNodeConfig.Region (config section GatewayNode, legacy Router:Node); “it is never derived from headers or URLs”
• No HTTP transport between gateway and microservices (HTTP is excluded from the TransportType enum)
• RequiredClaims(the StellaEndpointAttribute.RequiredClaims string array — claims, not roles) for endpoint authorization
• Opaque body handling (router doesn’t interpret payloads)

Building

# Build router solution
dotnet build src/Router/StellaOps.Router.sln

# Run tests
dotnet test src/Router/StellaOps.Router.sln

# Run gateway
dotnet run --project src/Router/StellaOps.Gateway.WebService