GitHub Copilot
7a2a7877c4
PNG screenshots are now the default for dashboard previews, with SVG available by setting WEBTERM_SCREENSHOT_MODE=svg. Documentation and tests updated accordingly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
66 lines
2.5 KiB
Markdown
66 lines
2.5 KiB
Markdown
# Architecture
|
|
|
|
## Overview
|
|
|
|
`webterm` is a Go HTTP/WebSocket server that hosts one or more terminal sessions and renders screenshot/telemetry surfaces for a dashboard UI.
|
|
|
|
```
|
|
Browser (terminal.js + ghostty-vt.wasm)
|
|
│
|
|
│ WS / HTTP / SSE
|
|
▼
|
|
webterm/server.go (LocalServer)
|
|
│
|
|
├── session_manager.go (route/app/session registry)
|
|
├── terminal_session.go (PTY-backed local sessions)
|
|
├── docker_exec_session.go (Docker exec-backed sessions)
|
|
├── docker_watcher.go (container add/remove discovery)
|
|
├── docker_stats.go (CPU sampling + sparkline data)
|
|
├── svg_exporter.go (terminal snapshot -> SVG)
|
|
└── png_exporter.go (terminal snapshot -> PNG via coverage blending)
|
|
```
|
|
|
|
## Packages
|
|
|
|
- `cmd/webterm`: CLI entrypoint
|
|
- `webterm`: server/runtime/domain logic
|
|
- `internal/terminalstate`: Go terminal emulator wrapper (`go-te`) used for screenshots
|
|
- `webterm/coverage_table.go`: coverage map for approximate PNG rendering
|
|
|
|
## Runtime data flow
|
|
|
|
1. Browser connects to `/ws/{route_key}`.
|
|
2. `SessionManager` resolves or creates a session.
|
|
3. Session reads PTY output and updates:
|
|
- live WS stream (`stdout`)
|
|
- replay buffer (reconnect support)
|
|
- terminal-state tracker (`go-te`) for screenshots
|
|
4. Dashboard pulls `/screenshot.png` (default) or `/screenshot.svg` when `WEBTERM_SCREENSHOT_MODE=svg`, and listens on `/events` for activity.
|
|
|
|
## Static assets
|
|
|
|
Assets live in `webterm/static`:
|
|
|
|
- `js/terminal.ts` source
|
|
- `js/terminal.js` bundled client
|
|
- `js/ghostty-vt.wasm`
|
|
- `monospace.css`, icons, `manifest.json`
|
|
|
|
The server resolves static files from:
|
|
|
|
1. `WEBTERM_STATIC_PATH` (if set)
|
|
2. local repository-relative fallbacks rooted at `webterm/static`
|
|
3. embedded assets bundled into the Go binary
|
|
|
|
## Docker integration
|
|
|
|
- **Compose mode** loads services from a compose manifest and creates tiles for services carrying `webterm-command`.
|
|
- **Watch mode** subscribes to Docker events and adds/removes tiles at runtime.
|
|
- `webterm-theme` controls tile theme; default theme applies if unset. Available themes: `tango`, `xterm`, `monokai`, `monokai-pro`, `ristretto`, `dark`, `light`, `dracula`, `catppuccin`, `nord`, `gruvbox`, `solarized`, `tokyo`, `miasma`, `github`, `gotham`.
|
|
|
|
## Reliability notes
|
|
|
|
- WebSocket writes are serialized through a sender queue.
|
|
- Session-manager maps are lock-protected and race-tested.
|
|
- Replay buffers are bounded to avoid unbounded memory growth.
|