Architektúra

Magas szintű folyamat

Alapértelmezett mód (helyi tmux + alagút):

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

Közvetlen sandbox mód (Daytona, alagút nélkül):

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

Ha be van állítva a --no-tunnel, a Termbridge kihagyja a Cloudflare-t, és a megadott nyilvános URL-t használja.

Komponensek

CLI folyamat

• Elindítja a HTTP szervert, amely kiszolgálja a UI eszközöket.
• Elindítja a terminál I/O-hoz szükséges WebSocket-szervert.
• Létrehoz egy vagy több tmux munkamenetet (vagy Daytona PTY-t).
• Egyszer felhasználható beváltási tokeneket bocsát ki.
• Engedélyezés esetén elindítja és felügyeli az alagutat (jelenleg: Cloudflare).
• Közvetlen sandbox módban elindítja a Termbridge-t a sandboxban, majd megvárja a megosztási URL-t.

Terminálháttér

• tmux háttér: A node-pty használatával csatlakozik a tmux-hoz, hogy a valódi billentyűleütéseket és kimenetet kezelje.
• Daytona háttér: Sandboxon belüli Daytona PTY-ket használ.
• Beállítja a TERM=xterm-256color és a COLORTERM=truecolor értékét a teljes színtámogatáshoz.
• tmux esetén letiltja a tmux állapotsorát, hogy a UI tiszta maradjon.

Terminál-nyilvántartás

• Nyomon követi az elérhető terminál-munkameneteket.
• Listát biztosít a UI számára, és ellenőrzi a kiválasztott terminálazonosítókat.

Hitelesítés és munkamenet

• Az egyszer használatos token URL formájában jelenik meg, és QR kóddá van kódolva.
• A GET /__tb/s/:token beváltja a tokent, és cookie-alapú munkamenetet állít be.
• A WebSocket-kapcsolatokhoz érvényes munkamenet-cookie és CSRF-token szükséges.
• A CSRF-token lekérése a GET /__tb/api/csrf használatával történik, és WebSocket-lekérdezési paraméterként kerül továbbításra.

Proxy mód

A --proxy <port> megadásakor:

• Minden termbridge-útvonal a /__tb/ előtag alatt érhető el
• A nem /__tb/ kérések a célalkalmazáshoz kerülnek továbbításra
• A UI a Terminal/Preview nézeteket jeleníti meg a Nézetváltóban
• A Preview nézet a / címre mutató iframe-et tölt be
• A HMR-hez tartozó WebSocket-kapcsolatok továbbítódnak a célhoz

Biztonság

• CSRF-védelem: A WebSocket-frissítésekhez CSRF-token szükséges a webhelyek közötti eltérítés megakadályozásához.
• Bemeneti korlátok: 64KB-os HTTP törzs, 1MB-os WebSocket-üzenet, üzenetenként 64KB terminálbemenet.
• Sebességkorlátozás: Tokenbeváltási és WebSocket-kapcsolati korlátok IP szerint.

API végpontok

Az összes útvonal a /__tb/ előtag alatt érhető el, hogy ne ütközzön a proxyn továbbított alkalmazásokkal:

• GET /__tb/healthz – állapotellenőrzés
• GET /__tb/s/:token – token beváltása → cookie → átirányítás
• GET /__tb/api/terminals – terminálok listázása
• GET /__tb/api/csrf – CSRF-token lekérése WebSockethez
• GET /__tb/api/config – konfiguráció lekérése (proxyPort, devProxyUrl)
• POST /__tb/api/terminals – új tmux munkamenet létrehozása
• GET /__tb/app/* – SPA tartalékútvonal
• WS /__tb/ws/terminal/:terminalId?csrf=<token> – terminál I/O-adatfolyam

Proxy mód engedélyezésekor:

• GET / – átirányítás a proxyn elérhető alkalmazáshoz (vagy /__tb/app-hez, ha le van tiltva)
• * /* – továbbítás a célalkalmazáshoz

WebSocket-protokoll

Kliens -> szerver:

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

Szerver -> kliens:

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

UI-verem

• Vite + TanStack Router
• xterm.js + Fit-kiegészítő + WebGL-megjelenítő
• Elsősorban mobilra szabott elrendezés rögzített beviteli sávval
• Automatikus újracsatlakozás exponenciális várakozással (legfeljebb 10 próbálkozás)
• Kapcsolatállapot-jelző