Developer
77 lines
1.9 KiB
Markdown
77 lines
1.9 KiB
Markdown
# Web Terminal Specification
|
|
|
|
## Purpose
|
|
|
|
Provide browser-based terminal access to running tool containers.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: WebSocket Terminal
|
|
|
|
The system SHALL provide terminal sessions via WebSocket.
|
|
|
|
#### Scenario: Open terminal
|
|
- GIVEN a running tool instance
|
|
- WHEN the user opens the terminal
|
|
- THEN a WebSocket connection is established
|
|
- AND a shell is spawned in the container via `docker exec`
|
|
|
|
### Requirement: Terminal I/O
|
|
|
|
The system SHALL stream terminal I/O via WebSocket.
|
|
|
|
#### Scenario: Command execution
|
|
- GIVEN an active terminal session
|
|
- WHEN the user types a command
|
|
- THEN stdin is forwarded to the container shell
|
|
- AND stdout/stderr is streamed back to the browser
|
|
|
|
### Requirement: Terminal Resize
|
|
|
|
The system SHALL support terminal resize events.
|
|
|
|
#### Scenario: Resize terminal
|
|
- GIVEN an active terminal session
|
|
- WHEN the browser window is resized
|
|
- THEN the terminal dimensions (COLS, ROWS) are updated
|
|
- AND the shell receives the new size
|
|
|
|
### Requirement: Session Management
|
|
|
|
The system SHALL manage terminal sessions.
|
|
|
|
#### Scenario: Multiple sessions
|
|
- GIVEN a running tool instance
|
|
- WHEN multiple terminals are opened
|
|
- THEN each has an independent session
|
|
|
|
#### Scenario: Cleanup
|
|
- GIVEN an active terminal session
|
|
- WHEN the user disconnects
|
|
- THEN the session is cleaned up
|
|
- AND the shell process is terminated
|
|
|
|
### Requirement: Access Control
|
|
|
|
The system SHALL restrict terminal access.
|
|
|
|
#### Scenario: Unauthorized access
|
|
- GIVEN a tool instance owned by user A
|
|
- WHEN user B tries to access the terminal
|
|
- THEN the connection is rejected with 403
|
|
|
|
## Dependencies
|
|
|
|
- tool-instances (running containers)
|
|
- auth-oauth (authentication)
|
|
- xterm.js frontend library
|
|
- ptyprocess for pseudo-TTY
|
|
|
|
## Quality Gates
|
|
|
|
- `pytest` must pass
|
|
- `mypy .` must pass
|
|
- `ruff check .` must pass
|
|
- `npm run typecheck` must pass
|
|
- `npm run lint` must pass
|