mirror of
https://github.com/samsonjs/vibetunnel.git
synced 2026-03-25 09:25:50 +00:00
81 lines
No EOL
3.2 KiB
Markdown
81 lines
No EOL
3.2 KiB
Markdown
# Performance Architecture
|
||
|
||
## Session Management Models
|
||
|
||
VibeTunnel supports two distinct session management approaches, each with different performance characteristics:
|
||
|
||
### 1. Server-Managed Sessions (API-initiated)
|
||
|
||
Sessions created via `POST /api/sessions` are spawned directly within the server's Node.js process. These sessions benefit from:
|
||
|
||
- **Direct PTY communication**: Input and resize commands bypass the command pipe system
|
||
- **Reduced latency**: No inter-process communication overhead for terminal interactions
|
||
- **Immediate responsiveness**: Direct memory access to PTY stdout/stdin
|
||
|
||
### 2. External Sessions (vt-initiated)
|
||
|
||
Sessions started via the `vt` command run in a separate Node.js process with:
|
||
|
||
- **File-based communication**: PTY stdout is written to disk files
|
||
- **Command pipe interface**: Resize and input commands are passed through IPC
|
||
- **Additional latency**: File I/O and IPC overhead for all terminal operations
|
||
|
||
## Server Architecture
|
||
|
||
### Session Discovery and Management
|
||
|
||
The server performs two primary management tasks:
|
||
|
||
1. **External Session Monitoring**
|
||
- Watches control directory for new external sessions
|
||
- Automatically registers discovered sessions with the terminal manager
|
||
- Maintains in-memory buffer cache (cols × rows) for text/buffer API endpoints
|
||
|
||
2. **Client Connection Handling**
|
||
- WebSocket connections trigger file watchers on session stdout files
|
||
- File watchers stream new output to connected clients in real-time
|
||
- Multiple clients can connect to the same session simultaneously
|
||
|
||
### Memory Management
|
||
|
||
- **Buffer caching**: Last visible scrollbuffer (terminal dimensions) kept in memory
|
||
- **Efficient retrieval**: Text and buffer API endpoints serve from memory cache
|
||
- **File streaming**: WebSocket clients receive updates via file watchers
|
||
|
||
## Known Performance Issues
|
||
|
||
### Session Creation Blocking
|
||
|
||
**Symptom**: All sessions freeze temporarily when creating a new session
|
||
|
||
**Cause**: Synchronous operations during session creation
|
||
- Session creation endpoint waits for process spawn completion
|
||
- PTY initialization must complete before returning
|
||
- Any synchronous operation blocks the entire Node.js event loop
|
||
|
||
**Impact**: All active sessions become unresponsive during new session initialization
|
||
|
||
### Potential Solutions
|
||
|
||
1. **Async session creation**: Move blocking operations to worker threads
|
||
2. **Pre-spawn PTY pool**: Maintain ready PTYs to reduce creation time
|
||
3. **Event loop monitoring**: Identify and eliminate synchronous operations
|
||
4. **Progressive initialization**: Return session ID immediately, initialize asynchronously
|
||
|
||
## Performance Optimization Strategies
|
||
|
||
### For Server-Managed Sessions
|
||
- Minimize synchronous operations in session creation
|
||
- Use Node.js worker threads for CPU-intensive tasks
|
||
- Implement connection pooling for database operations
|
||
|
||
### For External Sessions
|
||
- Consider memory-mapped files for stdout communication
|
||
- Implement file change batching to reduce watcher overhead
|
||
- Use efficient file formats (binary vs text) where appropriate
|
||
|
||
### General Optimizations
|
||
- Profile event loop blocking with tools like `clinic.js`
|
||
- Implement request queuing for session creation
|
||
- Add performance metrics and monitoring
|
||
- Consider horizontal scaling with session affinity |