The StellaOps Router is a high-performance, production-grade framework for building distributed microservice architectures. It provides a unified API for service-to-service communication across multiple transport protocols, with automatic service discovery, OpenAPI aggregation, compile-time endpoint validation, and runtime transport plugin loading.

Key Features

Multi-Transport Support: InMemory, TCP, TLS/mTLS, RabbitMQ, UDP, Valkey/Redis, PostgreSQL
Plugin-Based Transports: Transports loaded at runtime via IRouterTransportPlugin interface
Compile-Time Code Generation: Source generators create endpoint descriptors and schema providers at build time
Gateway Pattern: HTTP ingress with automatic routing to backend microservices
OpenAPI Aggregation: Unified Swagger documentation from all connected services
Streaming Support: First-class support for large payloads and server-sent events
JSON Schema Validation: Optional request/response validation with [ValidateSchema]
Zero-Configuration Discovery: Services auto-register with the gateway on startup

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         HTTP Clients                                 │
│                    (Browser, CLI, Mobile)                            │
└─────────────────────────────┬───────────────────────────────────────┘
                              │ HTTPS
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      Router Gateway                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ OpenAPI Agg  │  │ Auth/AuthZ   │  │ Route Resolution         │  │
│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │
└─────────────────────────────┬───────────────────────────────────────┘
                              │ Binary Transport (TCP/TLS/RabbitMQ)
           ┌──────────────────┼──────────────────┐
           ▼                  ▼                  ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│   Billing         │ │   Inventory       │ │   Notification    │
│   Microservice    │ │   Microservice    │ │   Microservice    │
│                   │ │                   │ │                   │
│  [StellaEndpoint] │ │  [StellaEndpoint] │ │  [StellaEndpoint] │
└───────────────────┘ └───────────────────┘ └───────────────────┘

Quick Start

1. Create a Microservice

using StellaOps.Microservice;
using StellaOps.Router.Transport.InMemory;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddStellaMicroservice(options =>
{
    options.ServiceName = "my-service";
    options.Version = "1.0.0";
    options.ConfigFilePath = "microservice.yaml";
});

builder.Services.AddInMemoryTransport();
builder.Services.AddScoped<MyEndpoint>();

var host = builder.Build();
await host.RunAsync();

2. Define Endpoints

using StellaOps.Microservice;

// Typed endpoint with automatic JSON serialization
[StellaEndpoint("POST", "/orders", TimeoutSeconds = 30)]
public sealed class CreateOrderEndpoint : IStellaEndpoint<CreateOrderRequest, CreateOrderResponse>
{
    public Task<CreateOrderResponse> HandleAsync(
        CreateOrderRequest request,
        CancellationToken cancellationToken)
    {
        return Task.FromResult(new CreateOrderResponse
        {
            OrderId = $"ORD-{Guid.NewGuid():N}"[..16]
        });
    }
}

// Raw endpoint for streaming
[StellaEndpoint("POST", "/files/{id}", SupportsStreaming = true)]
public sealed class UploadFileEndpoint : IRawStellaEndpoint
{
    public async Task<RawResponse> HandleAsync(
        RawRequestContext context,
        CancellationToken cancellationToken)
    {
        var fileId = context.PathParameters["id"];
        await using var stream = context.Body;
        // Process stream...

        var headers = new HeaderCollection();
        headers.Set("Content-Type", "application/json");
        return new RawResponse
        {
            StatusCode = 201,
            Headers = headers,
            Body = new MemoryStream("""{"status":"uploaded"}"""u8.ToArray())
        };
    }
}

3. Configure the Gateway

using StellaOps.Router.Gateway;
using StellaOps.Router.Gateway.DependencyInjection;
using StellaOps.Router.Transport.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRouterGateway(builder.Configuration);
builder.Services.AddInMemoryTransport();
builder.Services.AddAuthentication();

var app = builder.Build();

app.UseAuthentication();
app.UseClaimsAuthorization();
app.MapRouterOpenApi();
app.UseRouterGateway();

app.Run();

Transport Plugins

Transport implementations are loaded at runtime via the plugin system. See Transport Plugins for full documentation.

Transport	Plugin Assembly	Use Case	Performance
InMemory	`StellaOps.Router.Transport.InMemory.dll`	Development, testing	Sub-microsecond
TCP	`StellaOps.Router.Transport.Tcp.dll`	Internal services	< 1ms latency
TLS	`StellaOps.Router.Transport.Tls.dll`	Cross-datacenter, mTLS	< 2ms latency
RabbitMQ	`StellaOps.Router.Transport.RabbitMq.dll`	Async processing	Queue-based
UDP	`StellaOps.Router.Transport.Udp.dll`	Fire-and-forget	Best effort
Valkey	`StellaOps.Messaging.Transport.Valkey.dll`	Distributed, pub/sub	Memory-fast
PostgreSQL	`StellaOps.Messaging.Transport.Postgres.dll`	Transactional	Persistent

Loading Transport Plugins

using StellaOps.Router.Common.Plugins;

// Load transport plugins from directory
var pluginLoader = new RouterTransportPluginLoader(logger);
pluginLoader.LoadFromDirectory("plugins/router/transports");

// Register the configured transport (reads Router:Transport:Type from config)
pluginLoader.RegisterConfiguredTransport(services, configuration);

Configuring Transport

# router.yaml
Router:
  Transport:
    Type: tls                      # Which transport plugin to use
    Tls:
      Port: 5101
      CertificatePath: /certs/server.pfx
      RequireClientCertificate: true

Project Structure

src/Router/
├── StellaOps.Gateway.WebService/     # Gateway HTTP entrypoint
├── __Libraries/
│   ├── StellaOps.Router.Gateway/     # Gateway core logic
│   ├── StellaOps.Router.Common/      # Shared models and enums
│   ├── StellaOps.Router.Config/      # YAML configuration
│   ├── StellaOps.Router.AspNet/      # ASP.NET Core integration
│   ├── StellaOps.Microservice/       # Microservice SDK
│   ├── StellaOps.Microservice.SourceGen/  # Compile-time generator
│   ├── StellaOps.Messaging/          # Queue abstractions
│   └── StellaOps.Router.Transport.*/ # Transport implementations
├── __Tests/                          # Unit and integration tests
└── examples/                         # Working examples
    ├── Examples.OrderService/
    ├── Examples.NotificationService/
    └── Examples.MultiTransport.Gateway/

Configuration

microservice.yaml

service:
  name: billing-service
  version: 1.0.0
  region: us-east-1
  instanceId: billing-001

endpoints:
  - path: /invoices
    method: POST
    timeoutSeconds: 30
  - path: /invoices/{id}
    method: GET
    timeoutSeconds: 10

routers:
  - host: gateway.internal
    port: 5100
    transportType: Tcp
    priority: 1
  - host: gateway-backup.internal
    port: 5100
    transportType: Tcp
    priority: 2

heartbeat:
  intervalSeconds: 30
  reconnect:
    initialDelayMs: 1000
    maxDelayMs: 60000

router.yaml (Gateway)

gateway:
  name: api-gateway
  region: us-east-1

transports:
  tcp:
    port: 5100
    maxConnections: 1000
  tls:
    port: 5101
    certificatePath: /certs/server.pfx
    requireClientCertificate: true

routing:
  defaultTimeout: 30
  maxRequestBodyBytes: 10485760

services:
  billing:
    routes:
      - path: /invoices
        methods: [GET, POST]
      - path: /invoices/{id}
        methods: [GET, PUT, DELETE]
  inventory:
    routes:
      - path: /items
        methods: [GET]

Building

# Build the Router solution
dotnet build src/Router/StellaOps.Router.sln

# Run tests
dotnet test src/Router/StellaOps.Router.sln

# Build specific example
dotnet run --project src/Router/examples/Examples.OrderService

Documentation

Authority: OAuth/OIDC integration for gateway authentication
Policy: Route-level authorization policies
Telemetry: Distributed tracing across microservices

License

AGPL-3.0-or-later

README.md

StellaOps Router