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:

Performance: Binary framing eliminates HTTP overhead for internal traffic
Streaming: First-class support for large payloads (SBOMs, scan results, evidence bundles)
Cancellation: Request abortion propagates across service boundaries
Health-aware Routing: Automatic failover based on heartbeat and latency
Claims-based Auth: Unified authorization via Authority integration
Transport Flexibility: UDP for small payloads, TCP/TLS for streams, RabbitMQ for queuing
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

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

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

6.9 KiB Raw Blame History