52 lines
2.8 KiB
Markdown
52 lines
2.8 KiB
Markdown
# 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.
|