# 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).