30 KiB

Raw Blame History

Terminal Tool Feature Specification

Executive Summary

This specification details the implementation of an interactive tmux terminal interface integrated into the canvas dashboard. Users will be able to connect to their DigitalOcean droplets, manage tmux sessions, and collaborate on terminal sessions directly from the collaborative whiteboard.

1. Architecture Overview

1.1 High-Level Flow

User → Canvas UI → TerminalShape (xterm.js)
                        ↓
                  WebSocket
                        ↓
            Cloudflare Worker (SSH Proxy)
                        ↓
                  SSH Connection
                        ↓
            DigitalOcean Droplet → tmux

1.2 Technology Stack

Frontend

xterm.js ^5.3.0 - Terminal emulator
xterm-addon-fit ^0.8.0 - Responsive sizing
xterm-addon-web-links ^0.9.0 - Clickable URLs
React 18.2.0 (existing)
TLDraw 3.15.4 (existing)

Backend

ssh2 ^1.15.0 - SSH client for Cloudflare Worker
Cloudflare Workers (existing)
Cloudflare Durable Objects (existing)

Server

DigitalOcean Droplet (existing)
tmux (user-installed)
SSH daemon (standard)

2. Frontend Implementation

2.1 TerminalShape Definition

File: src/shapes/TerminalShapeUtil.tsx

export type ITerminalShape = TLBaseShape<"Terminal", {
  w: number                    // width (default: 800)
  h: number                    // height (default: 600)
  sessionId: string            // current tmux session name
  collaborationMode: boolean   // enable shared input (default: false)
  ownerId: string             // shape creator's user ID
  pinnedToView: boolean       // pin to viewport
  tags: string[]              // organization tags
  fontFamily: string          // terminal font (default: "Monaco")
  fontSize: number            // terminal font size (default: 13)
  terminalTheme: "dark" | "light"
}>

export class TerminalShape extends BaseBoxShapeUtil<ITerminalShape> {
  static override type = "Terminal"
  static readonly PRIMARY_COLOR = "#10b981"  // Green

  getDefaultProps(): ITerminalShape["props"] {
    return {
      w: 800,
      h: 600,
      sessionId: "",
      collaborationMode: false,
      ownerId: "",
      pinnedToView: false,
      tags: ['terminal'],
      fontFamily: "Monaco, Menlo, 'Courier New', monospace",
      fontSize: 13,
      terminalTheme: "dark"
    }
  }

  component(shape: ITerminalShape) {
    // Uses StandardizedToolWrapper pattern
    // Renders TerminalContent component
  }
}

2.2 TerminalTool

File: src/tools/TerminalTool.ts

export class TerminalTool extends BaseBoxShapeTool {
  static override id = "Terminal"
  shapeType = "Terminal"

  // Creates terminal shape when user drags on canvas
}

2.3 TerminalContent Component

File: src/components/TerminalContent.tsx

Features:

xterm.js instance management
WebSocket connection to backend
Session browser UI (when no session selected)
Collaboration mode toggle
Input handling (keyboard, paste)
Auto-resize on shape dimension changes

States:

Loading: Connecting to backend
Session Browser: List available tmux sessions
Connected: Active terminal session
Error: Connection failed or SSH error

UI Layout:

┌──────────────────────────────────────┐
│ Terminal (header from StandardizedToolWrapper)
├──────────────────────────────────────┤
│ [Session Browser Mode]               │
│                                      │
│ Available tmux sessions:             │
│ ┌──────────────────────────────┐    │
│ │ ○ session-1    [Attach]      │    │
│ │ ○ canvas-main  [Attach]      │    │
│ └──────────────────────────────┘    │
│                                      │
│ [+ Create New Session]               │
│                                      │
│ [OR: Terminal Output when connected] │
│                                      │
└──────────────────────────────────────┘
│ [🔒 Read-only] [👥 Collaboration: Off]│
└──────────────────────────────────────┘

2.4 SessionBrowser Component

File: src/components/SessionBrowser.tsx

Features:

Fetch list of tmux sessions from backend
Display session metadata (name, windows, creation time)
"Attach" button per session
"Create New Session" button with name input
Refresh button for session list

Props:

interface SessionBrowserProps {
  onSelectSession: (sessionId: string) => void
  onCreateSession: (sessionName: string) => void
}

3. Backend Implementation

3.1 SSH Proxy Architecture

File: worker/TerminalProxy.ts

Responsibilities:

Establish SSH connections to DigitalOcean droplet
Pool SSH connections per user (reuse across terminals)
Execute tmux commands over SSH
Stream terminal I/O via WebSocket
Handle SSH authentication (private key)

Key Methods:

class TerminalProxy {
  // Connection management
  async connect(config: SSHConfig): Promise<SSHConnection>
  async disconnect(connectionId: string): Promise<void>

  // tmux operations
  async listSessions(): Promise<TmuxSession[]>
  async createSession(name: string): Promise<string>
  async attachSession(sessionId: string): Promise<void>
  async sendInput(sessionId: string, data: string): Promise<void>

  // Stream management
  async streamOutput(sessionId: string): AsyncIterator<Buffer>
  async resize(sessionId: string, cols: number, rows: number): Promise<void>
}

3.2 Worker Routes

Extend: worker/AutomergeDurableObject.ts

New Routes:

// WebSocket upgrade for terminal I/O
GET /terminal/ws/:sessionId

// tmux session management
GET /terminal/sessions          // List all tmux sessions
POST /terminal/sessions         // Create new session
GET /terminal/sessions/:id      // Get session details
DELETE /terminal/sessions/:id   // Kill session

// Terminal I/O (used by WebSocket)
POST /terminal/:sessionId/input    // Send input
POST /terminal/:sessionId/resize   // Resize terminal

3.3 WebSocket Protocol

Message Types (Client → Server):

// Initialize terminal connection
{
  type: "init",
  sessionId: string,
  cols: number,
  rows: number
}

// Send user input
{
  type: "input",
  data: string  // keyboard input, paste, etc.
}

// Resize terminal
{
  type: "resize",
  cols: number,
  rows: number
}

// List tmux sessions (for browser)
{
  type: "list_sessions"
}

// Create new tmux session
{
  type: "create_session",
  name: string
}

// Detach from current session
{
  type: "detach"
}

Message Types (Server → Client):

// Terminal output (binary)
{
  type: "output",
  data: Uint8Array  // raw terminal output
}

// Session list response
{
  type: "sessions",
  sessions: [
    {
      name: string,
      windows: number,
      created: string,
      attached: boolean
    }
  ]
}

// Error messages
{
  type: "error",
  message: string
}

// Status updates
{
  type: "status",
  status: "connected" | "disconnected" | "attached"
}

4. Configuration System

4.1 Config File Structure

File: terminal-config.json (gitignored) Example: terminal-config.example.json (committed)

{
  "version": "1.0",
  "default_connection": "primary",
  "connections": {
    "primary": {
      "name": "Primary Droplet",
      "host": "165.227.xxx.xxx",
      "port": 22,
      "user": "root",
      "auth": {
        "type": "privateKey",
        "keyPath": "~/.ssh/id_ed25519"
      },
      "tmux": {
        "default_session": "canvas-main",
        "socket_name": null
      }
    },
    "staging": {
      "name": "Staging Droplet",
      "host": "192.168.xxx.xxx",
      "port": 22,
      "user": "deploy",
      "auth": {
        "type": "privateKey",
        "keyPath": "~/.ssh/staging_key"
      }
    }
  },
  "terminal": {
    "default_font_family": "Monaco, Menlo, monospace",
    "default_font_size": 13,
    "default_theme": "dark",
    "themes": {
      "dark": {
        "background": "#1e1e1e",
        "foreground": "#d4d4d4",
        "cursor": "#ffffff",
        "selection": "#264f78"
      },
      "light": {
        "background": "#ffffff",
        "foreground": "#333333",
        "cursor": "#000000",
        "selection": "#add6ff"
      }
    }
  },
  "security": {
    "allowed_users": [],
    "read_only_default": true,
    "collaboration_requires_permission": true
  }
}

4.2 Config Loading

File: src/config/terminalConfig.ts

export async function loadTerminalConfig(): Promise<TerminalConfig> {
  // Load from local file or environment variables
  // Validate schema
  // Return parsed config
}

export function getDefaultConnection(): ConnectionConfig {
  // Return default connection from config
}

4.3 Environment Variables (Alternative)

For production deployment:

TERMINAL_SSH_HOST=165.227.xxx.xxx
TERMINAL_SSH_PORT=22
TERMINAL_SSH_USER=root
TERMINAL_SSH_KEY_PATH=/path/to/private_key
TERMINAL_DEFAULT_SESSION=canvas-main

5. Multiplayer & Collaboration

5.1 Permission Model

Owner (Shape Creator):

Full control: input, resize, session switching
Can toggle collaboration mode
Can close terminal

Viewer (Other Users):

Read-only mode (default):
- See terminal output
- Cannot send input
- Cannot resize or change session
Collaboration mode (enabled by owner):
- Can send input to terminal
- Shared cursor visibility (optional)
- Input from any user broadcasts to all viewers

5.2 State Synchronization

Via Automerge (shape metadata):

Position, size, pinned status
Current session ID
Collaboration mode flag
Owner ID

Via WebSocket (terminal output):

Terminal output streams to all connected clients
Input messages sent to backend, broadcast to collaborators
Not persisted (ephemeral)

5.3 Collaboration UI

Indicators:

Collaboration mode toggle (owner only)
User count badge (e.g., "3 viewers")
Input lock icon when read-only
Color-coded user cursors (when collaboration enabled)

Implementation:

// In TerminalContent component
const isOwner = shape.props.ownerId === currentUserId
const canInput = isOwner || shape.props.collaborationMode

// Disable input handling if read-only
term.onData((data) => {
  if (!canInput) {
    showNotification("Terminal is read-only. Owner must enable collaboration.")
    return
  }
  ws.send(JSON.stringify({ type: 'input', data }))
})

6. Security Considerations

6.1 SSH Key Management

Storage:

SSH private keys stored in secure location (not in repo)
Path reference in config file
Worker reads key from environment or secure storage

Best Practices:

Use dedicated SSH keys for canvas terminal (not personal keys)
Restrict key permissions on droplet (authorized_keys)
Consider using SSH certificates with short TTLs
Rotate keys periodically

6.2 User Authentication

Requirements:

Users must be authenticated to canvas dashboard (existing auth)
Terminal access tied to user session
Worker validates user token before SSH connection

Implementation:

// In worker route handler
const userId = await validateUserToken(request.headers.get('Authorization'))
if (!userId) {
  return new Response('Unauthorized', { status: 401 })
}

6.3 Command Restrictions

Considerations:

Terminal gives full shell access to droplet
No command filtering by default (tmux limitation)
Rely on droplet-level user permissions

Recommendations:

Create dedicated canvas-terminal user on droplet
Use sudo for privileged operations
Consider shell restrictions (rbash, restricted commands)

6.4 Rate Limiting

Protection:

Limit SSH connections per user
Throttle WebSocket message rate
Connection timeout after inactivity

Implementation:

// In Durable Object
private readonly MAX_CONNECTIONS_PER_USER = 5
private readonly MESSAGE_RATE_LIMIT = 1000  // messages per minute
private readonly IDLE_TIMEOUT = 30 * 60 * 1000  // 30 minutes

7. Error Handling

7.1 Connection Failures

Scenarios:

SSH connection refused
Authentication failed
Network timeout
Droplet unreachable

UI Response:

┌────────────────────────────────┐
│ Terminal                       │
├────────────────────────────────┤
│                                │
│  ⚠️ Connection Failed          │
│                                │
│  Could not connect to droplet  │
│  165.227.xxx.xxx               │
│                                │
│  Error: Connection timeout     │
│                                │
│  [Retry]  [Check Config]       │
│                                │
└────────────────────────────────┘

7.2 Session Errors

Scenarios:

tmux session not found
Session killed externally
Permission denied

Handling:

Return to session browser
Show error notification
Auto-refresh session list

7.3 WebSocket Disconnection

Reconnection Strategy:

Detect disconnect (onclose event)
Show "Reconnecting..." overlay
Exponential backoff retry (1s, 2s, 4s, 8s, 16s)
Max 5 attempts
Show error if all attempts fail

Implementation:

private reconnect(attempt: number = 0) {
  if (attempt >= 5) {
    this.showError("Connection lost. Please refresh.")
    return
  }

  const delay = Math.min(1000 * Math.pow(2, attempt), 16000)
  setTimeout(() => {
    this.connect()
  }, delay)
}

8. UI/UX Details

8.1 Terminal Appearance

Default Theme (Dark):

.terminal-container {
  background: #1e1e1e;
  color: #d4d4d4;
  font-family: Monaco, Menlo, 'Courier New', monospace;
  font-size: 13px;
  line-height: 1.4;
  padding: 8px;
}

xterm.js Configuration:

const term = new Terminal({
  theme: {
    background: '#1e1e1e',
    foreground: '#d4d4d4',
    cursor: '#ffffff',
    cursorAccent: '#1e1e1e',
    selection: '#264f78',
    black: '#000000',
    red: '#cd3131',
    green: '#0dbc79',
    yellow: '#e5e510',
    blue: '#2472c8',
    magenta: '#bc3fbc',
    cyan: '#11a8cd',
    white: '#e5e5e5',
    brightBlack: '#666666',
    brightRed: '#f14c4c',
    brightGreen: '#23d18b',
    brightYellow: '#f5f543',
    brightBlue: '#3b8eea',
    brightMagenta: '#d670d6',
    brightCyan: '#29b8db',
    brightWhite: '#e5e5e5'
  },
  fontFamily: "Monaco, Menlo, 'Courier New', monospace",
  fontSize: 13,
  lineHeight: 1.4,
  cursorBlink: true,
  cursorStyle: 'block',
  scrollback: 10000,
  tabStopWidth: 4
})

Location: src/ui/CustomToolbar.tsx

Button Config:

<ToolbarButton
  icon="terminal"  // or custom SVG icon
  label="Terminal"
  onClick={() => setActiveTool('Terminal')}
  isActive={activeTool === 'Terminal'}
  tooltip="Create terminal window (Ctrl+`)"
/>

Icon (SVG):

<svg width="24" height="24" viewBox="0 0 24 24" fill="none">
  <rect x="2" y="4" width="20" height="16" rx="2" stroke="currentColor" stroke-width="2"/>
  <path d="M6 8L10 12L6 16" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
  <line x1="12" y1="16" x2="18" y2="16" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
</svg>

8.3 Keyboard Shortcuts

Global:

`Ctrl/Cmd + `` - Create new terminal
Ctrl/Cmd + Shift + T - Focus terminal (if exists)

Within Terminal:

Ctrl + C - Send SIGINT (normal terminal behavior)
Ctrl + D - Send EOF / exit shell
Ctrl + L - Clear screen
Ctrl + Shift + C - Copy selection
Ctrl + Shift + V - Paste

Shape Controls:

Escape - Deselect terminal
Delete - Close terminal (prompt for confirmation)

Right-click on Terminal Shape:

┌───────────────────────────┐
│ Copy                      │
│ Paste                     │
├───────────────────────────┤
│ Clear Terminal            │
│ Reset Terminal            │
├───────────────────────────┤
│ Switch Session...         │
│ Detach from Session       │
├───────────────────────────┤
│ Toggle Collaboration Mode │
│ Pin to View               │
├───────────────────────────┤
│ Settings                  │
│ Close                     │
└───────────────────────────┘

9. Performance Optimizations

9.1 Connection Pooling

Strategy:

Maintain persistent SSH connections per user
Reuse connections across terminal shapes
Close connections after idle timeout (30 min)

Benefits:

Faster terminal creation (no SSH handshake delay)
Reduced load on droplet
Better resource utilization

9.2 Output Buffering

Implementation:

Buffer terminal output on backend
Send batched updates every 16ms (60 FPS)
Avoid overwhelming WebSocket with rapid output

// In TerminalProxy
private outputBuffer: Buffer[] = []
private flushInterval: NodeJS.Timer

constructor() {
  this.flushInterval = setInterval(() => {
    if (this.outputBuffer.length > 0) {
      const combined = Buffer.concat(this.outputBuffer)
      this.ws.send(combined)
      this.outputBuffer = []
    }
  }, 16)  // 60 FPS
}

9.3 Lazy Loading

Strategy:

Load xterm.js dynamically when first terminal created
Preload terminal config on dashboard load
Cache session list with 5-second TTL

9.4 Viewport Optimization

When Minimized:

Pause xterm.js rendering
Buffer output in memory
Resume rendering when expanded

When Off-screen:

Reduce render rate to 10 FPS
Full rate when terminal visible

10. Testing Strategy

10.1 Unit Tests

Components:

TerminalShape.test.tsx - Shape creation, props
SessionBrowser.test.tsx - Session list rendering
TerminalContent.test.tsx - xterm.js integration
TerminalProxy.test.ts - SSH connection logic

Coverage Goals:

Core functionality: 90%+
Edge cases: 80%+
Error handling: 100%

10.2 Integration Tests

Scenarios:

Create terminal → Session browser appears
Select session → Terminal connects and displays output
Send input → Appears in terminal
Resize shape → Terminal resizes
Close terminal → SSH connection cleaned up
Multiplayer: Owner enables collaboration → Viewer can send input

10.3 Manual Testing Checklist

SSH connection to droplet succeeds
Session browser lists tmux sessions
Can attach to existing session
Can create new session with custom name
Terminal displays output correctly (colors, formatting)
Keyboard input works (typing, special keys)
Copy/paste works
Resize terminal updates dimensions
Minimize/expand preserves state
Pin to view works during pan/zoom
Collaboration mode toggle works
Read-only mode blocks input
WebSocket reconnects after disconnect
Multiple terminals can be open simultaneously
Terminal state syncs across multiplayer clients
SSH connection pools work (reuse connections)
Error messages display correctly
Config file loads properly
Toolbar button creates terminal

11. Deployment Guide

11.1 Prerequisites

Droplet Setup:

# On DigitalOcean droplet
apt update && apt install tmux

# Create dedicated user (optional)
adduser canvas-terminal
usermod -aG sudo canvas-terminal

# Add SSH public key to authorized_keys
mkdir -p /home/canvas-terminal/.ssh
echo "ssh-ed25519 AAAA..." >> /home/canvas-terminal/.ssh/authorized_keys
chmod 700 /home/canvas-terminal/.ssh
chmod 600 /home/canvas-terminal/.ssh/authorized_keys

Local Setup:

# Generate SSH key pair (if needed)
ssh-keygen -t ed25519 -f ~/.ssh/canvas_terminal -C "canvas-terminal"

# Copy terminal-config.example.json to terminal-config.json
cp terminal-config.example.json terminal-config.json

# Edit config with your droplet details
nano terminal-config.json

11.2 Installation

# Install dependencies
npm install xterm xterm-addon-fit xterm-addon-web-links ssh2

# Build project
npm run build

# Deploy worker
npm run deploy

11.3 Configuration

Update terminal-config.json:

{
  "connections": {
    "primary": {
      "host": "YOUR_DROPLET_IP",
      "user": "canvas-terminal",
      "auth": {
        "keyPath": "~/.ssh/canvas_terminal"
      }
    }
  }
}

Environment Variables (for Cloudflare Worker):

# Set via Cloudflare dashboard or CLI
wrangler secret put TERMINAL_SSH_KEY < ~/.ssh/canvas_terminal
wrangler secret put TERMINAL_SSH_HOST
wrangler secret put TERMINAL_SSH_USER

11.4 Verification

Test Checklist:

SSH to droplet manually: ssh -i ~/.ssh/canvas_terminal canvas-terminal@YOUR_IP
Start tmux: tmux new-session -d -s test
Open canvas dashboard
Create terminal shape
Verify session browser shows "test" session
Attach to session
Type commands and verify output

12. Future Enhancements

12.1 Phase 2 Features

Terminal History:

Save terminal session snapshots
Replay terminal sessions
Export terminal output

Custom Themes:

Theme builder UI
Import/export themes
Community theme gallery

Split Panes:

tmux pane support in UI
Visual pane management
Keyboard shortcuts for splits

12.2 Phase 3 Features

File Transfer:

Drag-and-drop file upload to droplet
Download files from terminal
Integration with FileSystemContext

Command Palette:

Quick command execution
Command history search
Saved command snippets

Terminal Templates:

Predefined terminal layouts
Auto-run commands on session start
Environment variable presets

12.3 Advanced Features

AI Integration:

Command suggestions
Error explanation
Code generation in terminal

Monitoring:

Resource usage graphs (CPU, memory)
Network traffic visualization
Log tailing with filtering

Team Features:

Shared tmux sessions per project
Session recording for training
Permission groups (read/write/admin)

13. Maintenance & Support

13.1 Monitoring

Metrics to Track:

SSH connection success rate
WebSocket disconnect frequency
Average terminal response time
Active terminal count
Error rate by type

Logging:

SSH connection events
Session creation/destruction
WebSocket errors
Input/output volume

13.2 Known Limitations

Cloudflare Worker Timeout: Workers have 30-second CPU time limit
- Mitigation: Use Durable Objects for persistent connections
SSH Key Storage: Securely storing private keys in Worker
- Mitigation: Use Cloudflare Secrets or external key management
Terminal Output Size: Large output can overwhelm WebSocket
- Mitigation: Output buffering and rate limiting
tmux Version: Feature compatibility depends on tmux version
- Requirement: tmux 2.0+ recommended

13.3 Troubleshooting

Common Issues:

"Connection timeout":

Check droplet firewall (allow port 22)
Verify SSH daemon running: systemctl status sshd
Test SSH manually from local machine

"Authentication failed":

Verify SSH key permissions (600 for private key)
Check authorized_keys on droplet
Confirm username matches config

"No tmux sessions found":

Create test session: tmux new-session -d -s test
Check tmux socket: ls /tmp/tmux-*
Verify user has tmux installed

"Terminal output garbled":

Check terminal encoding (UTF-8)
Verify TERM environment variable: echo $TERM
Reset terminal: Ctrl+C then reset

14. Documentation Files

14.1 Files to Create

TERMINAL_SPEC.md (this document)
terminal-config.example.json - Example configuration
README_TERMINAL.md - User-facing documentation
TERMINAL_SETUP.md - Deployment guide
API.md - Backend API documentation

14.2 Code Comments

Required Comments:

Function/class JSDoc comments
Complex algorithm explanations
Security considerations
Performance optimization notes

15. Acceptance Criteria

15.1 Functional Requirements

Users can create terminal shapes on canvas
Terminal displays session browser when no session selected
Users can attach to existing tmux sessions
Users can create new tmux sessions with custom names
Terminal renders output with correct colors and formatting
Users can send input to terminal (keyboard, paste)
Terminal resizes correctly when shape dimensions change
Read-only mode prevents non-owners from sending input
Collaboration mode allows multiple users to send input
Terminal reconnects automatically after disconnect
SSH connections are pooled and reused
Config file system works for droplet credentials
Toolbar button creates new terminal

15.2 Non-Functional Requirements

Terminal response time < 100ms (local network)
WebSocket reconnection < 5 seconds
SSH connection pool reduces latency by 50%+
Terminal handles 10+ simultaneous users
No memory leaks after 1 hour of usage
Code coverage > 80%
Documentation complete and accurate

15.3 Security Requirements

SSH private keys not exposed in client code
User authentication validated on every request
Rate limiting prevents abuse
Collaboration mode requires owner permission
SSH connections closed after idle timeout
No command injection vulnerabilities

16. Timeline Estimate

Phase 1: Foundation (3-4 days)

Day 1: Dependencies, config system, TerminalShape/Tool
Day 2: TerminalContent component, xterm.js integration
Day 3: SessionBrowser component, UI polish
Day 4: Testing, bug fixes

Phase 2: Backend (3-4 days)

Day 1: SSH proxy setup, connection pooling
Day 2: Worker routes, WebSocket protocol
Day 3: tmux integration, session management
Day 4: Testing, error handling

Phase 3: Integration (2-3 days)

Day 1: Register shape/tool, toolbar button
Day 2: Multiplayer, collaboration mode
Day 3: Testing, documentation

Phase 4: Polish (2-3 days)

Day 1: Performance optimization
Day 2: Error handling, edge cases
Day 3: Final testing, deployment

Total: 10-14 days (2-3 weeks)

17. Success Metrics

Adoption:

50% of active users create at least one terminal
Average 2-3 terminals per canvas
80% session success rate (no connection errors)

Performance:

< 100ms terminal response time
< 5% WebSocket disconnect rate
95% SSH connection success rate

Engagement:

Average 10+ minutes per terminal session
30% of terminals use collaboration mode
5+ commands per terminal session

18. Risks & Mitigations

18.1 Technical Risks

Risk: Cloudflare Worker CPU timeout

Mitigation: Use Durable Objects for long-running connections

Risk: SSH connection overhead

Mitigation: Connection pooling, keep-alive

Risk: WebSocket scalability

Mitigation: Load testing, rate limiting

18.2 Security Risks

Risk: SSH key compromise

Mitigation: Use dedicated keys, rotate regularly, monitor access

Risk: Unauthorized terminal access

Mitigation: User authentication, permission checks

Risk: Command injection

Mitigation: Input sanitization, no shell interpolation

18.3 UX Risks

Risk: Confusing session browser

Mitigation: Clear UI, tooltips, onboarding

Risk: Collaboration conflicts (multiple users typing)

Mitigation: Input queueing, visual feedback, cursor indicators

Risk: Terminal performance degradation

Mitigation: Output buffering, viewport optimization

19. Appendix

19.1 tmux Commands Reference

# List sessions
tmux ls

# Create new session
tmux new-session -s session_name

# Attach to session
tmux attach -t session_name

# Detach from session
tmux detach

# Kill session
tmux kill-session -t session_name

# Resize pane
tmux resize-pane -x 100 -y 30

# Capture pane output
tmux capture-pane -t session_name:window.pane -p

19.2 SSH Connection Example

import { Client } from 'ssh2'

const conn = new Client()
conn.on('ready', () => {
  console.log('SSH connected')

  conn.exec('tmux ls', (err, stream) => {
    if (err) throw err

    stream.on('data', (data: Buffer) => {
      console.log('Sessions:', data.toString())
    })
  })
})

conn.connect({
  host: '165.227.xxx.xxx',
  port: 22,
  username: 'canvas-terminal',
  privateKey: fs.readFileSync('/path/to/private_key')
})

19.3 xterm.js Integration Example

import { Terminal } from 'xterm'
import { FitAddon } from 'xterm-addon-fit'

const term = new Terminal()
const fitAddon = new FitAddon()

term.loadAddon(fitAddon)
term.open(document.getElementById('terminal'))
fitAddon.fit()

// Connect to WebSocket
const ws = new WebSocket('wss://worker.url/terminal/ws/session-123')

ws.onmessage = (event) => {
  term.write(event.data)
}

term.onData((data) => {
  ws.send(JSON.stringify({ type: 'input', data }))
})

Revision History

Version	Date	Author	Changes
1.0	2025-01-19	Initial	Complete specification document

Contact & Support

For questions or issues with the terminal feature:

GitHub Issues: https://github.com/yourusername/canvas-website/issues
Documentation: /docs/terminal-tool.md
Slack: #canvas-terminal

End of Specification

30 KiB Raw Blame History

Terminal Tool Feature Specification

Executive Summary

1. Architecture Overview

1.1 High-Level Flow

1.2 Technology Stack

2. Frontend Implementation

2.1 TerminalShape Definition

2.2 TerminalTool

2.3 TerminalContent Component

2.4 SessionBrowser Component

3. Backend Implementation

3.1 SSH Proxy Architecture

3.2 Worker Routes

3.3 WebSocket Protocol

4. Configuration System

4.1 Config File Structure

4.2 Config Loading

4.3 Environment Variables (Alternative)

5. Multiplayer & Collaboration

5.1 Permission Model

5.2 State Synchronization

5.3 Collaboration UI

6. Security Considerations

6.1 SSH Key Management

6.2 User Authentication

6.3 Command Restrictions

6.4 Rate Limiting

7. Error Handling

7.1 Connection Failures

7.2 Session Errors

7.3 WebSocket Disconnection

8. UI/UX Details

8.1 Terminal Appearance

8.2 Toolbar Button

8.3 Keyboard Shortcuts

8.4 Context Menu

9. Performance Optimizations

9.1 Connection Pooling

9.2 Output Buffering

9.3 Lazy Loading

9.4 Viewport Optimization

10. Testing Strategy

10.1 Unit Tests

10.2 Integration Tests

10.3 Manual Testing Checklist

11. Deployment Guide

11.1 Prerequisites

11.2 Installation

11.3 Configuration

11.4 Verification

12. Future Enhancements

12.1 Phase 2 Features

12.2 Phase 3 Features

12.3 Advanced Features

13. Maintenance & Support

13.1 Monitoring

13.2 Known Limitations

13.3 Troubleshooting

14. Documentation Files

14.1 Files to Create

14.2 Code Comments

15. Acceptance Criteria

15.1 Functional Requirements

15.2 Non-Functional Requirements

15.3 Security Requirements

16. Timeline Estimate

17. Success Metrics

18. Risks & Mitigations

18.1 Technical Risks

18.2 Security Risks

18.3 UX Risks

19. Appendix

19.1 tmux Commands Reference

19.2 SSH Connection Example

19.3 xterm.js Integration Example

Revision History

Contact & Support

30 KiB

Raw Blame History