Router Microservice Transport Guardrails

This document defines mandatory guardrails for migrating StellaOps.*.WebService services to Router microservice transport over Valkey messaging.

Required Contract

• Service startup must use AddRouterMicroservice(...) from StellaOps.Router.AspNet.
• Router transport activation must be configuration-driven from environment/compose keys.
• Transport implementation loading must remain plugin-based:
• Router transport plugins from Router:TransportPlugins:*.
• Messaging backend plugin from Router:Messaging:PluginDirectory and Router:Messaging:SearchPattern.
• Messaging transport selection must be explicit (Router:Messaging:Transport=valkey for this rollout).
• Services must keep rollback-compatible toggles so routing can return to reverse proxy without code edits.

Required Configuration Keys

• <Service>:Router:Enabled
• <Service>:Router:Gateways:*:TransportType
• <Service>:Router:TransportPlugins:Directory
• <Service>:Router:TransportPlugins:SearchPattern
• <Service>:Router:Messaging:Transport
• <Service>:Router:Messaging:PluginDirectory
• <Service>:Router:Messaging:SearchPattern
• <Service>:Router:Messaging:RequestQueueTemplate
• <Service>:Router:Messaging:ResponseQueueName
• <Service>:Router:Messaging:ConsumerGroup
• <Service>:Router:Messaging:valkey:ConnectionString
• <Service>:Router:Messaging:valkey:Database

Forbidden Patterns

• Direct service-level DI calls to concrete transport registration methods such as:
• AddMessagingTransportClient()
• AddTcpTransportClient()
• AddUdpTransportClient()
• AddRabbitMqTransportClient()
• AddTlsTransportClient()
• Legacy gateway startup paths must not call AddInMemoryTransport() to satisfy default gateway transport binding. AddRouterGateway(...) is fail-closed by default; process-local in-memory transport is only available through the explicit AddRouterGatewayLocalInMemoryHarness(...) API and only in Development, Testing, or Local host environments.
• Compile-time coupling from webservice projects to transport assemblies solely to enable default behavior.
• Hardcoded transport selection in code paths that bypass environment/compose configuration.

Required Test Coverage

• Router enabled with missing gateway endpoints must fail fast.
• Missing/invalid router options section input must fail fast.
• Missing transport plugin for configured TransportType must fail fast with explicit error text.
• Messaging transport binding must verify queue/timeouts and Valkey options from configuration.

Migration PR Checklist

• [ ] Service startup uses AddRouterMicroservice(...) and retains TryUseStellaRouter(...) behavior.
• [ ] No direct concrete transport registration calls are added in service DI.
• [ ] Compose/environment keys are added for router enablement, plugin directories, and Valkey settings.
• [ ] Gateway route plan updated (ReverseProxy -> Microservice) with rollback instructions.
• [ ] OpenAPI preview (/openapi.json) shows migrated endpoint paths plus schema components.
• [ ] Targeted tests include plugin-missing and section-validation failure cases.
• [ ] Sprint execution log and decisions/risks updated with doc links and evidence.