git.stella-ops.org/docs/modules/router/microservice-transport-guardrails.md

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()
• 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.