108 lines
4.7 KiB
Markdown
108 lines
4.7 KiB
Markdown
# Router · Messaging Transport over Valkey
|
|
|
|
## Status
|
|
- **Implemented** in Sprint 8100.0011.0003.
|
|
- Core components: Gateway DI wiring, GatewayHostedService integration, GatewayTransportClient dispatch.
|
|
- Last updated: 2025-12-24 (UTC).
|
|
|
|
## Purpose
|
|
Enable Gateway ↔ microservice Router traffic over an offline-friendly, Redis-compatible transport (Valkey) by using the existing **Messaging** transport layer:
|
|
- Router transport: `StellaOps.Router.Transport.Messaging`
|
|
- Messaging backend: `StellaOps.Messaging.Transport.Valkey`
|
|
|
|
This supports environments where direct TCP/TLS microservice connections are undesirable, and where an internal message bus is the preferred control plane.
|
|
|
|
## Implementation Summary
|
|
|
|
### Libraries
|
|
- `StellaOps.Router.Transport.Messaging` — Router transport layer over messaging
|
|
- `StellaOps.Messaging.Transport.Valkey` — Valkey/Redis backend for messaging
|
|
- `StellaOps.Messaging` — Core messaging abstractions and DI
|
|
|
|
### Gateway Integration
|
|
- **Program.cs** — Conditional registration of `ValkeyTransportPlugin` and `AddMessagingTransportServer()`
|
|
- **GatewayOptions.cs** — `GatewayMessagingTransportOptions` for Valkey connection and queue configuration
|
|
- **GatewayHostedService.cs** — Start/stop `MessagingTransportServer`, subscribe to events
|
|
- **GatewayTransportClient.cs** — Dispatch to `TransportType.Messaging` connections
|
|
|
|
## High-Level Flow
|
|
1) Microservice connects via messaging transport:
|
|
- publishes a HELLO message to the gateway request queue
|
|
2) Gateway processes HELLO:
|
|
- registers instance + endpoints into routing state
|
|
3) Gateway routes an HTTP request to a microservice:
|
|
- publishes a REQUEST message to the service request queue
|
|
4) Microservice handles request:
|
|
- executes handler (or ASP.NET bridge) and publishes a RESPONSE message
|
|
5) Gateway returns response to the client.
|
|
|
|
## Queue Topology (Conceptual)
|
|
The Messaging transport uses a small set of queues (names are configurable):
|
|
- **Gateway request queue**: receives HELLO / HEARTBEAT / REQUEST frames from services
|
|
- **Gateway response queue**: receives RESPONSE frames from services
|
|
- **Per-service request queues**: gateway publishes REQUEST frames targeted to a service
|
|
- **Dead letter queues** (optional): for messages that exceed retries/leases
|
|
|
|
## Configuration
|
|
|
|
### Gateway YAML Configuration
|
|
```yaml
|
|
Gateway:
|
|
Transports:
|
|
Messaging:
|
|
Enabled: true
|
|
ConnectionString: "valkey:6379"
|
|
Database: 0
|
|
RequestQueueTemplate: "router:requests:{service}"
|
|
ResponseQueueName: "router:responses"
|
|
ConsumerGroup: "router-gateway"
|
|
RequestTimeout: "30s"
|
|
LeaseDuration: "5m"
|
|
BatchSize: 10
|
|
HeartbeatInterval: "10s"
|
|
```
|
|
|
|
### Gateway DI Registration
|
|
```csharp
|
|
// In Program.cs (already implemented)
|
|
if (bootstrapOptions.Transports.Messaging.Enabled)
|
|
{
|
|
builder.Services.AddMessagingTransport<ValkeyTransportPlugin>(
|
|
builder.Configuration, "Gateway:Transports:Messaging");
|
|
builder.Services.AddMessagingTransportServer();
|
|
}
|
|
```
|
|
|
|
### Microservice
|
|
- Register Valkey messaging services (`StellaOps.Messaging.Transport.Valkey`)
|
|
- Add messaging transport client (`AddMessagingTransportClient`)
|
|
- Ensure Microservice Router SDK connects via `IMicroserviceTransport`
|
|
|
|
## Operational Semantics (Draft)
|
|
- **At-least-once** delivery: message queues and leases imply retries are possible; handlers should be idempotent where feasible.
|
|
- **Lease timeouts**: must be tuned to max handler execution time; long-running tasks should respond with 202 + job id rather than blocking.
|
|
- **Determinism**: message ordering may vary; Router must not depend on arrival order for correctness (only for freshness/telemetry).
|
|
|
|
## Security Notes
|
|
- Messaging transport is internal. External identity must still be enforced at the Gateway.
|
|
- The Gateway must not trust client-supplied identity headers; it must overwrite reserved headers before dispatch.
|
|
- See `docs/modules/gateway/identity-header-policy.md`.
|
|
|
|
## Implementation Status
|
|
|
|
### Completed (Sprint 8100.0011.0003)
|
|
1. ✅ Wire Messaging transport into Gateway:
|
|
- start/stop `MessagingTransportServer` in `GatewayHostedService`
|
|
- subscribe to `OnHelloReceived`, `OnHeartbeatReceived`, `OnResponseReceived`, `OnConnectionClosed` events
|
|
- reuse routing state updates and claims store updates
|
|
2. ✅ Extend Gateway transport client to support `TransportType.Messaging` for dispatch.
|
|
3. ✅ Add config options (`GatewayMessagingTransportOptions`) and DI mappings.
|
|
|
|
### Remaining Work
|
|
1. Add deployment examples (compose/helm) for Valkey transport.
|
|
2. Add integration tests using ValkeyFixture:
|
|
- microservice HELLO registration via messaging
|
|
- request dispatch + response return
|
|
3. Validate streaming support (or document as out-of-scope).
|
|
|