Архитектура

Общ преглед на потока

По подразбиране (локален tmux + тунел):

Browser (phone)
  |
  | HTTPS
  v
Cloudflare Quick Tunnel
  |
  | HTTP/WS
  v
Local Termbridge server
  |
  | PTY
  v
Tmux session

Директен режим на sandbox (Daytona, без тунел):

Browser (phone)
  |
  | HTTPS
  v
Daytona preview link
  |
  | HTTP/WS
  v
Termbridge server (sandbox)
  |
  | PTY
  v
Tmux session (sandbox)

Когато е зададен --no-tunnel, Termbridge пропуска Cloudflare и използва предоставения от вас публичен URL.

Компоненти

Процес CLI

• Стартира сървъра HTTP, който предоставя активите на UI.
• Стартира WebSocket сървъра за входно-изходните операции на терминала.
• Създава една или повече сесии tmux (или Daytona PTY).
• Издава еднократни токени за достъп.
• Стартира и следи тунела, когато е активиран (Cloudflare към момента).
• В директен режим на sandbox стартира Termbridge вътре в sandbox и изчаква споделения URL.

Терминален бекенд

• Бекенд tmux: Използва node-pty за свързване към tmux и обработка на реалните натискания на клавиши и изхода.
• Бекенд Daytona: Използва PTY Daytona вътре в sandbox.
• Задава TERM=xterm-256color и COLORTERM=truecolor за пълна поддръжка на цветовете.
• За tmux изключва лентата на състоянието tmux, за да остави UI изчистен.

Регистър на терминалите

• Следи наличните терминални сесии.
• Предоставя списък на UI и проверява избраните идентификатори на терминали.

Удостоверяване и сесия

• Еднократният токен се отпечатва като URL и се кодира в код QR.
• GET /__tb/s/:token използва токена и задава сесийна бисквитка.
• WebSocket връзките изискват валидна сесийна бисквитка и CSRF токен.
• CSRF токенът се извлича чрез GET /__tb/api/csrf и се предава като параметър на заявката WebSocket.

Режим на прокси

Когато се подаде --proxy <port>:

• Всички маршрути на termbridge са с префикс /__tb/
• Заявките, които не са /__tb/, се препращат към целевото приложение
• UI показва изгледите Terminal/Preview чрез превключвателя Views
• Изгледът Preview зарежда iframe, насочен към /
• WebSocket връзките за HMR се препращат към целевото приложение

Сигурност

• CSRF защита: WebSocket надстройките изискват CSRF токен, за да се предотврати отвличане от друг сайт.
• Ограничения на входа: тяло на HTTP от 64KB, WebSocket съобщение от 1MB, входни данни за терминала до 64KB на съобщение.
• Ограничаване на честотата: ограничения за всяко IP при използване на токени и WebSocket връзки.

Крайни точки API

Всички маршрути са с префикс /__tb/, за да се избегнат конфликти с проксираните приложения:

• GET /__tb/healthz - проверка на изправността
• GET /__tb/s/:token - използване на токен → бисквитка → пренасочване
• GET /__tb/api/terminals - списък на терминалите
• GET /__tb/api/csrf - получаване на CSRF токен за WebSocket
• GET /__tb/api/config - получаване на конфигурация (proxyPort, devProxyUrl)
• POST /__tb/api/terminals - създаване на нова сесия tmux
• GET /__tb/app/* - резервен маршрут на SPA
• WS /__tb/ws/terminal/:terminalId?csrf=<token> - поточно предаване на входно-изходните операции на терминала

Когато режимът на прокси е активиран:

• GET / - пренасочва към проксираното приложение (или /__tb/app, ако е изключено)
• * /* - препраща към целевото приложение

Протокол WebSocket

Клиент -> сървър:

{ "type": "input", "data": "ls -la" }
{ "type": "resize", "cols": 120, "rows": 32 }
{ "type": "control", "key": "ctrl_c" }

Сървър -> клиент:

{ "type": "output", "data": "..." }
{ "type": "status", "state": "connected" }

Стек UI

• Vite + TanStack Router
• xterm.js + добавката Fit + рендериране чрез WebGL
• Подредба за мобилни устройства с фиксирана лента за въвеждане
• Автоматично повторно свързване с експоненциално увеличаване на интервала (до 10 опита)
• Индикатор за състоянието на връзката