10 KiB
10 KiB
StellaOps Router
Transport-agnostic microservice communication framework with plugin-based transport loading
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
IRouterTransportPlugininterface - 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
Related Modules
- Authority: OAuth/OIDC integration for gateway authentication
- Policy: Route-level authorization policies
- Telemetry: Distributed tracing across microservices
License
AGPL-3.0-or-later