unshell/ush-treetest/PROTOCOL.md

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