mirror of
https://github.com/UNITRONIX/BetterDesk.git
synced 2026-09-10 17:45:42 +00:00
UNITRONIX
dd0889e3d6
Introduce a SessionManager for relay-based remote sessions in the Tauri MGMT client: new SessionCommand API, start/stop/session input routing, clipboard/recording/quality controls, and notification read/dismiss state. Wire AppState with new mutexes and show main window on startup. CI: add SBOM generation (anchore) and Trivy vulnerability scan steps. Misc: change console Docker DB path, large README/CHANGELOG updates (chat E2E, unattended access/WOL, i18n expansion, CDAP/SDK docs), and many web-nodejs assets/locales/routes/views/services and server-side changes.
84 lines
5.2 KiB
Markdown
84 lines
5.2 KiB
Markdown
# CDAP — Connected Device Access Protocol
|
|
|
|
## Overview
|
|
|
|
CDAP (Connected Device Access Protocol) is BetterDesk's unified WebSocket-based protocol for
|
|
bidirectional communication between the management server and endpoint agents. It enables:
|
|
|
|
- **Real-time telemetry** — CPU, memory, disk, and custom metrics streamed continuously
|
|
- **Widget-based dashboards** — Agents declare UI widgets (gauges, toggles, buttons, charts) that render in the web console
|
|
- **Remote commands** — Operators send structured commands to agents (restart service, run script, toggle relay)
|
|
- **File transfer** — Browse, read, write, and delete files on agent endpoints
|
|
- **Terminal access** — Full PTY terminal sessions over WebSocket
|
|
- **Clipboard sync** — Bidirectional clipboard exchange between browser and device
|
|
- **Audio streaming** — PCM/Opus audio relay for voice communication
|
|
- **Multi-monitor desktop** — Resolution detection, selective monitor control
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌────────────────────┐ WebSocket ┌──────────────────────┐
|
|
│ CDAP Agent │ ◄═══════════════════════► │ Go Server (:21122) │
|
|
│ (Go / Python / │ /cdap │ cdap/gateway.go │
|
|
│ Node.js binary) │ │ cdap/handler.go │
|
|
└────────────────────┘ └──────────┬───────────┘
|
|
│
|
|
REST API │ + WS proxy
|
|
│
|
|
┌──────────▼───────────┐
|
|
│ Node.js Console │
|
|
│ (:5000) │
|
|
│ routes/cdap.routes │
|
|
│ cdapMediaProxy.js │
|
|
└──────────┬───────────┘
|
|
│
|
|
Browser │ WS
|
|
│
|
|
┌──────────▼───────────┐
|
|
│ Web Console UI │
|
|
│ cdap-widgets.js │
|
|
│ cdap-desktop.js │
|
|
│ cdap-audio.js │
|
|
└──────────────────────┘
|
|
```
|
|
|
|
## Message Flow
|
|
|
|
1. **Agent connects** via WebSocket to `ws://server:21122/cdap`
|
|
2. **Authentication** — agent sends `auth` message with API key or device token
|
|
3. **Manifest registration** — agent sends `manifest` with device descriptor, capabilities, and widget definitions
|
|
4. **Heartbeat loop** — agent sends `heartbeat` every N seconds with system metrics
|
|
5. **Widget state** — agent sends `state_update` or `bulk_update` with current widget values
|
|
6. **Commands** — server sends `command` messages, agent executes and responds with `command_response`
|
|
7. **Events** — server pushes `alert_ack`, `config_update`, `state_request` to agents
|
|
|
|
## Capability Model
|
|
|
|
Each agent declares its capabilities in the manifest:
|
|
|
|
| Capability | Description |
|
|
|-------------------|------------------------------------------------|
|
|
| `telemetry` | System metrics (CPU, RAM, disk, network) |
|
|
| `commands` | Execute structured commands |
|
|
| `remote_desktop` | Screen capture, input injection |
|
|
| `file_transfer` | File browse, read, write, delete |
|
|
| `clipboard` | Bidirectional clipboard sync |
|
|
| `terminal` | PTY terminal sessions |
|
|
| `audio` | Audio streaming (PCM/Opus) |
|
|
| `screenshot` | On-demand screenshot capture |
|
|
|
|
## Key Files
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| `betterdesk-server/cdap/gateway.go` | WebSocket gateway, connection management |
|
|
| `betterdesk-server/cdap/handler.go` | Message dispatch, command routing |
|
|
| `betterdesk-server/cdap/audio.go` | Audio session management |
|
|
| `betterdesk-server/cdap/clipboard.go` | Clipboard sync logic |
|
|
| `betterdesk-server/cdap/media_control.go` | Cursor, quality, codec, multi-monitor |
|
|
| `betterdesk-server/api/cdap_handlers.go` | REST + WS HTTP handlers |
|
|
| `web-nodejs/routes/cdap.routes.js` | Node.js proxy routes |
|
|
| `web-nodejs/services/cdapMediaProxy.js` | WebSocket proxy factory |
|
|
|
|
See also: [PROTOCOL.md](PROTOCOL.md), [AGENT_GUIDE.md](AGENT_GUIDE.md), [BRIDGE_GUIDE.md](BRIDGE_GUIDE.md)
|