git.stella-ops.org/docs/modules/router

Router Module

The StellaOps Router is the internal communication infrastructure that enables microservices to communicate through a central gateway using efficient binary protocols.

Why Another Gateway?

StellaOps 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 replaces the Serdica HTTP-to-RabbitMQ pattern with a simpler, generic 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

Component	Project	Purpose
Gateway	StellaOps.Gateway.WebService	HTTP ingress, routing, authorization
Microservice SDK	StellaOps.Microservice	SDK for building microservices
Source Generator	StellaOps.Microservice.SourceGen	Compile-time endpoint discovery
Common	StellaOps.Router.Common	Shared types, frames, interfaces
Config	StellaOps.Router.Config	Configuration models, YAML binding
InMemory Transport	StellaOps.Router.Transport.InMemory	Testing transport
TCP Transport	StellaOps.Router.Transport.Tcp	Production TCP transport
TLS Transport	StellaOps.Router.Transport.Tls	Encrypted TCP transport
UDP Transport	StellaOps.Router.Transport.Udp	Small payload transport
RabbitMQ Transport	StellaOps.Router.Transport.RabbitMQ	Message queue transport
Messaging Transport	StellaOps.Router.Transport.Messaging	Messaging/RPC transport (Valkey-backed via StellaOps.Messaging.Transport.Valkey)

Solution Structure

StellaOps.Router.slnx
├── src/__Libraries/
│   ├── StellaOps.Router.Common/
│   ├── StellaOps.Router.Config/
│   ├── StellaOps.Router.Transport.InMemory/
│   ├── StellaOps.Router.Transport.Tcp/
│   ├── StellaOps.Router.Transport.Tls/
│   ├── StellaOps.Router.Transport.Udp/
│   ├── StellaOps.Router.Transport.RabbitMQ/
│   ├── StellaOps.Microservice/
│   └── StellaOps.Microservice.SourceGen/
├── src/Router/StellaOps.Gateway.WebService/  (moved from src/Gateway/ per Sprint 200)
└── tests/
    └── (test projects)

Key Documents

Module Documentation (this directory)

Document	Purpose
architecture.md	Canonical specification and requirements
schema-validation.md	JSON Schema validation feature
openapi-aggregation.md	OpenAPI document generation
migration-guide.md	WebService to Microservice migration
rate-limiting.md	Centralized router rate limiting (dossier)
aspnet-endpoint-bridge.md	Using ASP.NET endpoint registration as Router endpoint registration
messaging-valkey-transport.md	Messaging transport over Valkey
timelineindexer-microservice-pilot.md	TimelineIndexer Valkey microservice transport pilot mapping and rollback
webservices-valkey-rollout-matrix.md	All-webservices Valkey microservice migration matrix (waves, owners, rollback)
microservice-transport-guardrails.md	Plugin-only transport guardrails and migration PR checklist
authority-gateway-enforcement-runbook.md	Operations runbook for gateway-enforced auth and signed identity envelope trust
rollout-acceptance-20260222.md	Dual-mode rollout acceptance package and evidence index

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

Document	Purpose
README.md	Quick start and feature overview
ARCHITECTURE.md	Detailed architecture walkthrough
GETTING_STARTED.md	Step-by-step setup guide
rate-limiting-config.md	Rate limiting configuration guide
transports.md	Transport plugin documentation

Quick Start

Gateway

var builder = WebApplication.CreateBuilder(args);

// Add router services
builder.Services.AddGatewayServices(builder.Configuration);
builder.Services.AddInMemoryTransport(); // or TCP, TLS, etc.

var app = builder.Build();

// Configure pipeline
app.UseGatewayMiddleware();

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
• Strict semver for version matching
• Region from GatewayNodeConfig (not headers/host)
• No HTTP transport between gateway and microservices
• RequiringClaims (not AllowedRoles) for authorization
• Opaque body handling (router doesn't interpret payloads)

Building

# Build router solution
dotnet build StellaOps.Router.slnx

# Run tests
dotnet test StellaOps.Router.slnx

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