Arhitektūra

Kopējā darbplūsma

Noklusējums (lokālais tmux + tunelis):

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

Tiešais smilškastes režīms (Daytona, bez tuneļa):

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

Ja ir iestatīts --no-tunnel, Termbridge izlaiž Cloudflare un izmanto jūsu norādīto publisko URL.

Komponenti

CLI process

• Palaiž HTTP serveri, kas apkalpo UI resursus.
• Palaiž WebSocket serveri termināļa ievadei un izvadei.
• Izveido vienu vai vairākas tmux sesijas (vai Daytona PTY).
• Izsniedz vienreizējus izpirkšanas tokenus.
• Palaiž un uzrauga tuneli, ja tas ir iespējots (pašlaik Cloudflare).
• Tiešajā smilškastes režīmā palaiž Termbridge smilškastē un gaida koplietošanas URL.

Termināļa aizmugursistēma

• tmux aizmugursistēma: izmanto node-pty, lai izveidotu savienojumu ar tmux un saņemtu īstas taustiņu ievades un izvadi.
• Daytona aizmugursistēma: izmanto Daytona PTY smilškastē.
• Pilnam krāsu atbalstam iestata TERM=xterm-256color un COLORTERM=truecolor.
• tmux gadījumā atspējo tmux statusa joslu, lai UI būtu pārskatāma.

Termināļu reģistrs

• Uzskaita pieejamās termināļa sesijas.
• Nodrošina sarakstu priekš UI un validē atlasītos termināļa ID.

Autentifikācija un sesija

• Vienreizējais tokens tiek izdrukāts kā URL un iekodēts QR kodā.
• GET /__tb/s/:token izpērk tokenu un iestata sīkdatnes sesiju.
• WebSocket savienojumiem vajadzīga derīga sesijas sīkdatne un CSRF tokens.
• CSRF tokens tiek iegūts, izmantojot GET /__tb/api/csrf, un nodots WebSocket vaicājuma parametrā.

Starpniekservera režīms

Kad tiek nodots --proxy <port>:

• Visi termbridge maršruti atrodas zem prefiksa /__tb/
• Pieprasījumi, kas nav /__tb/, tiek pārsūtīti mērķa lietotnei
• UI ar skatu pārslēgu parāda termināļa un priekšskatījuma skatus
• Priekšskatījuma skats ielādē iframe, kas norāda uz /
• HMR WebSocket savienojumi tiek pārsūtīti mērķim

Drošība

• CSRF aizsardzība: WebSocket savienojuma izveidei vajadzīgs CSRF tokens, lai novērstu starpvietņu pārtveršanu.
• Ievades ierobežojumi: 64KB HTTP pamatdaļa, 1MB WebSocket ziņojums, 64KB termināļa ievade katrā ziņojumā.
• Pieprasījumu ātruma ierobežošana: katram IP tiek noteikti tokenu izpirkšanas un WebSocket savienojumu ierobežojumi.

API galapunkti

Visi maršruti atrodas zem prefiksa /__tb/, lai izvairītos no konfliktiem ar starpniekservera pārsūtītām lietotnēm:

• GET /__tb/healthz - darbspējas pārbaude
• GET /__tb/s/:token - tokena izpirkšana → sīkdatne → novirzīšana
• GET /__tb/api/terminals - termināļu saraksts
• GET /__tb/api/csrf - CSRF tokena iegūšana WebSocket savienojumam
• GET /__tb/api/config - konfigurācijas iegūšana (proxyPort, devProxyUrl)
• POST /__tb/api/terminals - jaunas tmux sesijas izveide
• GET /__tb/app/* - SPA rezerves maršruts
• WS /__tb/ws/terminal/:terminalId?csrf=<token> - termināļa I/O straumēšana

Kad ir iespējots starpniekservera režīms:

• GET / - novirza uz starpniekservera lietotni (vai /__tb/app, ja tā ir atspējota)
• * /* - novirza uz mērķa lietotni

WebSocket protokols

Klients -> serveris:

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

Serveris -> klients:

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

UI steks

• Vite + TanStack Router
• xterm.js + Fit papildinājums + WebGL renderētājs
• Mobilajām ierīcēm vispirms pielāgots izkārtojums ar fiksētu ievades joslu
• Automātiska atkārtota savienojuma izveide ar eksponenciālu aizturi (līdz 10 mēģinājumiem)
• Savienojuma statusa indikators