Fix build and code structure improvements. New but essential UI functionality. CI improvements. Documentation improvements. AI module improvements.
This commit is contained in:
StellaOps Bot
294
docs/router/README.md
Normal file
294
docs/router/README.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# 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 `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
|
||||
|
||||
```csharp
|
||||
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
|
||||
|
||||
```csharp
|
||||
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
|
||||
|
||||
```csharp
|
||||
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](./transports/README.md) 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
|
||||
|
||||
```csharp
|
||||
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
|
||||
|
||||
```yaml
|
||||
# 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
|
||||
|
||||
```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)
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
- [Architecture Overview](./ARCHITECTURE.md)
|
||||
- [Getting Started Guide](./GETTING_STARTED.md)
|
||||
- [Transport Configuration](./transports/)
|
||||
- [Rate Limiting](./rate-limiting.md)
|
||||
- [Examples](./examples/README.md)
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user