Router

Verified against commit 942a18727c (2026-09-26, DOC-2 of SPRINT_20260926_001). Re-verify by reading the evidence paths listed in the Evidence section of architecture.md.

Service wiring (image, database and role, compose profile, bundle presence) is generated in the service inventory; this dossier does not restate it.

Internal communication fabric for Stella Ops: the single HTTP front door (router-gateway) and the binary transports that connect it to the platform microservices.

The Stella Ops Router is the HTTP ingress and internal routing layer. The gateway (StellaOps.Gateway.WebService) terminates HTTPS, validates tokens, signs an identity envelope, serves the Angular console, and dispatches API requests to microservices over binary transports with health-aware routing, claims-based authorization and centralized admission control. It owns no database.

Why a dedicated router

1. One routing authority: services publish their endpoints in a HELLO frame; the gateway routes to them without a per-service route-table entry.
2. Streaming: first-class support for large payloads (SBOMs, scan results, evidence bundles).
3. Cancellation: request abortion propagates across service boundaries (Cancel frames).
4. Health-aware routing: instance selection uses heartbeat recency and latency.
5. Claims-based authorization: unified enforcement at the gateway, with Authority overrides.
6. Transport flexibility: Messaging over Valkey in the deployed estate, TLS for certificate-based streams, RabbitMQ; TCP and UDP are development-only.
7. Centralized rate limiting: admission control at the gateway (429 + Retry-After).

Architecture Overview

                                   ┌─────────────────────────────────┐
                                   │ router-gateway                  │
  HTTP Clients ────────────────────►  (StellaOps.Gateway.WebService) │
                                   │                                 │
                                   │  ┌─────────────────────────────┐│
                                   │  │ Endpoint Resolution         ││
                                   │  │ Authorization (Claims)      ││
                                   │  │ Routing Decision            ││
                                   │  │ Transport Dispatch          ││
                                   │  └─────────────────────────────┘│
                                   └──────────────┬──────────────────┘
                                                  │ binary frames
                        ┌─────────────────────────┼─────────────────────────┐
                        ▼                         ▼                         ▼
              ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
              │ Microservice A  │       │ Microservice B  │       │ Microservice C  │
              │ Messaging/Valkey│       │ Messaging/Valkey│       │ TLS             │
              └─────────────────┘       └─────────────────┘       └─────────────────┘

Deployment

Components

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

Gateway-owned endpoints

Beyond proxying microservice routes, the gateway hosts health, metrics, OpenAPI and build-info aggregation, product-security metadata, Doctor checks, plugin diagnostics, routing administration (router:routing:read / router:routing:write) and the operator verify surface (operator.verify.read / operator.verify.admin). The complete table with scopes and sources is in architecture.md, Gateway-owned HTTP endpoints.

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.Gateway.LocalInMemoryHarness/
│   ├── 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/

Key Documents

Module Documentation (this directory)

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

Runbooks

• add-router-transport.md - build and deploy a signed transport plugin
• local-runtime-replay.md - replay and verify the local runtime route boundary

Quick Start

Gateway (library composition)

The deployable gateway is StellaOps.Gateway.WebService. A custom host composes the gateway library like this; the in-memory harness is registered only for Development, Testing or Local environments:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();
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; the gateway host maps Gateway:Node onto it); it is never derived from headers or URLs
• No HTTP transport between gateway and microservices (HTTP is excluded from the TransportType enum)
• Claims, not roles, for endpoint authorization at the gateway: a microservice declares StellaEndpointAttribute.RequiredClaims (string array), which is published as EndpointDescriptor.RequiringClaims
• Opaque body handling (the router does not 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