7503c19b8f
- Implemented comprehensive tests for verdict artifact generation to ensure deterministic outputs across various scenarios, including identical inputs, parallel execution, and change ordering. - Created helper methods for generating sample verdict inputs and computing canonical hashes. - Added tests to validate the stability of canonical hashes, proof spine ordering, and summary statistics. - Introduced a new PowerShell script to update SHA256 sums for files, ensuring accurate hash generation and file integrity checks.
76 lines
3.9 KiB
Markdown
76 lines
3.9 KiB
Markdown
# Router · Messaging Transport over Valkey (Draft v0.1)
|
|
|
|
## Status
|
|
- Draft; intended for implementation via a dedicated sprint.
|
|
- Last updated: 2025-12-23 (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.
|
|
|
|
## What Exists Today (Repository Reality)
|
|
- Messaging transport server/client:
|
|
- `src/__Libraries/StellaOps.Router.Transport.Messaging/MessagingTransportServer.cs`
|
|
- `src/__Libraries/StellaOps.Router.Transport.Messaging/MessagingTransportClient.cs`
|
|
- Valkey-backed message queue factory:
|
|
- `src/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyMessageQueueFactory.cs`
|
|
- Gateway WebService currently starts only TCP/TLS transport servers:
|
|
- `src/Gateway/StellaOps.Gateway.WebService/Program.cs`
|
|
- `src/Gateway/StellaOps.Gateway.WebService/Services/GatewayHostedService.cs`
|
|
|
|
## 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 (Draft)
|
|
### Gateway
|
|
- Register Valkey messaging services (`StellaOps.Messaging.Transport.Valkey`)
|
|
- Add messaging transport server (`AddMessagingTransportServer`)
|
|
- Add Gateway config section for messaging transport options:
|
|
- Valkey connection info (host/port/auth)
|
|
- queue naming prefix
|
|
- consumer group / lease duration / dead-letter suffix
|
|
|
|
### 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`.
|
|
|
|
## Gaps / Implementation Work
|
|
1) Wire Messaging transport into Gateway:
|
|
- start/stop `MessagingTransportServer`
|
|
- subscribe to HELLO/HEARTBEAT/RESPONSE events and reuse existing HELLO validation + routing state updates
|
|
2) Extend Gateway transport client to support `TransportType.Messaging` for dispatch.
|
|
3) Add config mapping and deployment examples (compose/helm) for Valkey transport.
|
|
4) Add integration tests covering:
|
|
- microservice HELLO registration via messaging
|
|
- request dispatch + response return
|
|
|