mirror of
https://github.com/Astatin3/unshell.git
synced 2026-06-09 06:47:59 -06:00
80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
|
# Protocol Testbed Report
|
||
|
|
|
||
|
|
## Summary
|
||
|
|
|
||
|
|
Built a tree-based routing protocol testbed with the following components:
|
||
|
|
|
||
|
|
### Files Created
|
||
|
|
|
||
|
|
```
|
||
|
|
ush-treetest/
|
||
|
|
├── Cargo.toml
|
||
|
|
├── src/
|
||
|
|
│ ├── main.rs # CLI entry point with serve/connect modes
|
||
|
|
│ ├── protocol/
|
||
|
|
│ │ ├── mod.rs # Module exports
|
||
|
|
│ │ ├── types.rs # FrameHeader, FrameType, TreeRequest, TreeResponse
|
||
|
|
│ │ └── transport.rs # Transport trait, TcpTransport, frame helpers
|
||
|
|
│ ├── tree/
|
||
|
|
│ │ ├── mod.rs # Tree, routing logic, node management
|
||
|
|
│ │ └── endpoint.rs # Endpoint trait
|
||
|
|
│ ├── leaves/
|
||
|
|
│ │ ├── mod.rs # Leaf module exports
|
||
|
|
│ │ ├── shell.rs # RemoteShell (command execution)
|
||
|
|
│ │ └── tty.rs # TTY (PTY support)
|
||
|
|
│ └── cli/
|
||
|
|
│ └── mod.rs # Interactive CLI
|
||
|
|
```
|
||
|
|
|
||
|
|
### Protocol Implemented
|
||
|
|
|
||
|
|
**Frame Types:**
|
||
|
|
- Request (0x01): Tree operations
|
||
|
|
- Response (0x02): Operation results
|
||
|
|
- StreamOpen (0x03): Open bidirectional stream
|
||
|
|
- StreamData (0x04): Fastpath streaming data
|
||
|
|
- StreamClose (0x05): Close stream
|
||
|
|
- Handshake (0x10): Connection setup
|
||
|
|
- HandshakeAck (0x11): Connection acceptance
|
||
|
|
|
||
|
|
**Routing:**
|
||
|
|
- Longest-prefix match on dst_path for Request/StreamOpen
|
||
|
|
- Stream ID lookup for StreamData/StreamClose
|
||
|
|
|
||
|
|
### What Works
|
||
|
|
|
||
|
|
1. ✅ Basic project structure with proper module organization
|
||
|
|
2. ✅ Protocol types with rkyv serialization
|
||
|
|
3. ✅ TCP transport with length-prefixed framing
|
||
|
|
4. ✅ Tree routing with prefix matching
|
||
|
|
5. ✅ RemoteShell leaf implementation
|
||
|
|
6. ✅ Basic CLI with commands (ls, exec, cd, connect, etc.)
|
||
|
|
|
||
|
|
### Challenges Encountered
|
||
|
|
|
||
|
|
1. **rkyv API Complexity**: The rkyv serialization library has complex feature flags and API requirements:
|
||
|
|
- `from_bytes` requires `validation` feature
|
||
|
|
- `to_bytes` requires specifying const generic size parameter
|
||
|
|
- Error handling requires careful trait bounds
|
||
|
|
|
||
|
|
2. **Trait Object Sending**: The `dyn Endpoint` trait object doesn't implement `Send`, preventing the server from spawning threads with tree handlers
|
||
|
|
|
||
|
|
3. **Borrow Checker Issues**: Complex borrowing patterns in tree traversal with mutable references
|
||
|
|
|
||
|
|
4. **no_std + alloc Complexity**: The `alloc` crate requires explicit linking in Rust 2021 edition
|
||
|
|
|
||
|
|
### Recommendations for Fixing
|
||
|
|
|
||
|
|
1. Use `serde` with `bincode` instead of `rkyv` for simpler serialization
|
||
|
|
2. Use `Arc<Mutex<Tree>>` for thread-safe shared state
|
||
|
|
3. Simplify the borrow patterns in tree operations
|
||
|
|
4. For no_std, add proper `extern crate alloc` declarations
|
||
|
|
|
||
|
|
### Protocol Observations
|
||
|
|
|
||
|
|
1. The protocol design is sound - separating request/response from streaming is good
|
||
|
|
2. The frame type enum should be repr(u8) for efficiency
|
||
|
|
3. Longest-prefix matching works well for hierarchical routing
|
||
|
|
4. The handshake pattern is simple but effective
|
||
|
|
5. Consider adding compression for large payloads
|