Add unit tests for RabbitMq and Udp transport servers and clients

- Implemented comprehensive unit tests for RabbitMqTransportServer, covering constructor, disposal, connection management, event handlers, and exception handling. - Added configuration tests for RabbitMqTransportServer to validate SSL, durable queues, auto-recovery, and custom virtual host options. - Created unit tests for UdpFrameProtocol, including frame parsing and serialization, header size validation, and round-trip data preservation. - Developed tests for UdpTransportClient, focusing on connection handling, event subscriptions, and exception scenarios. - Established tests for UdpTransportServer, ensuring proper start/stop behavior, connection state management, and event handling. - Included tests for UdpTransportOptions to verify default values and modification capabilities. - Enhanced service registration tests for Udp transport services in the dependency injection container.
2025-12-05 19:01:12 +02:00
parent 53508ceccb
commit cc69d332e3
245 changed files with 22440 additions and 27719 deletions
--- a/docs/modules/router/README.md
+++ b/docs/modules/router/README.md
@@ -0,0 +1,165 @@
+# 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
+```