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

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](architecture.md) | Canonical specification and requirements |
| [schema-validation.md](schema-validation.md) | JSON Schema validation feature |
| [openapi-aggregation.md](openapi-aggregation.md) | OpenAPI document generation |
| [migration-guide.md](migration-guide.md) | WebService to Microservice migration |

## Quick Start

### Gateway

```csharp
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

```csharp
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

```csharp
[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

```bash
# 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
```