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