git.stella-ops.org/docs/modules/router/messaging-valkey-transport.md

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

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

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