# 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