50 lines
2.3 KiB
Markdown
50 lines
2.3 KiB
Markdown
---
|
|
id: server/control-channel
|
|
name: Implement wraith-control reserved channel for pubsub event bus bridging (ADR-018)
|
|
status: pending
|
|
depends_on:
|
|
- server/handler
|
|
- auth/error-types
|
|
scope: narrow
|
|
risk: medium
|
|
impact: component
|
|
level: implementation
|
|
---
|
|
|
|
## Description
|
|
|
|
Implement the control channel routing per ADR-018. When the server receives a `channel_open_direct_tcpip` request for `wraith-control:0`:
|
|
|
|
1. The handler detects the reserved `wraith-` prefix destination
|
|
2. Instead of making a TCP connection, it bridges the SSH channel to an internal event bus handle
|
|
3. `EventEnvelope` JSON flows bidirectionally over the SSH channel
|
|
|
|
The entire `wraith-` prefix is reserved — no TCP connections should be attempted for `wraith-*` destinations. The control channel is optional; servers without pubsub configured should accept the channel and provide a configurable behavior (reject or provide a loopback pipe).
|
|
|
|
At this stage, implement the routing logic and a `ControlChannel` trait that consumers can implement. The actual pubsub bridge implementation would be in a separate crate or behind a feature flag.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `crates/wraith-core/src/server/control_channel.rs` exports `ControlChannelHandler` trait and routing logic
|
|
- [ ] `WRAITH_CONTROL_DESTINATION` constant defined as `"wraith-control"` (ADR-018)
|
|
- [ ] `WRAITH_PREFIX` constant defined as `"wraith-"` for namespace reservation
|
|
- [ ] `ControlChannelHandler` trait: `async fn handle_channel(stream: Box<dyn AsyncRead + AsyncWrite + Unpin + Send>)`
|
|
- [ ] Server handler detects `wraith-*` prefix and routes to `ControlChannelHandler` instead of TCP proxy
|
|
- [ ] If no `ControlChannelHandler` configured, reject the channel open request (SSH channel open failure)
|
|
- [ ] Non-reserved destinations continue through normal TCP proxy path
|
|
- [ ] Server constraint enforced: no TCP connections to `wraith-*` destinations
|
|
- [ ] Unit tests: reserved destination detected, non-reserved passes through, prefix matching works
|
|
|
|
## References
|
|
|
|
- docs/architecture/server.md — Channel Handling section (reserved destinations), Constraints section
|
|
- docs/architecture/decisions/018-control-channel-for-pubsub.md — control channel rationale
|
|
- docs/architecture/napi-and-pubsub.md — server-side control channel behavior
|
|
|
|
## Notes
|
|
|
|
> To be filled by implementation agent
|
|
|
|
## Summary
|
|
|
|
> To be filled on completion |