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

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/Gateway/
│   └── StellaOps.Gateway.WebService/
└── tests/
    └── (test projects)

Key Documents

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
aspnet-endpoint-bridge.md	Using ASP.NET endpoint registration as Router endpoint registration
messaging-valkey-transport.md	Messaging transport over Valkey

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/Gateway/StellaOps.Gateway.WebService