Architektūra

Bendra veikimo eiga

Numatytasis režimas (vietinis tmux + tunelis):

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

Tiesioginis smėliadėžės režimas (Daytona, be tunelio):

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

Nustačius --no-tunnel, Termbridge praleidžia Cloudflare ir naudoja jūsų pateiktą viešą URL.

Komponentai

CLI procesas

• Paleidžia HTTP serverį, teikiantį UI išteklius.
• Paleidžia WebSocket serverį terminalo įvesties ir išvesties srautams.
• Sukuria vieną ar kelias tmux sesijas (arba Daytona PTY).
• Išduoda vienkartinius išpirkimo žetonus.
• Paleidžia ir stebi tunelį, jei jis įjungtas (šiuo metu Cloudflare).
• Tiesioginiu smėliadėžės režimu paleidžia Termbridge smėliadėžėje ir laukia bendrinimo URL.

Terminalo posistemė

• tmux posistemė: naudoja node-pty, kad prisijungtų prie tmux ir perduotų tikrus klavišų paspaudimus bei išvestį.
• Daytona posistemė: naudoja Daytona PTY smėliadėžėje.
• Nustato TERM=xterm-256color ir COLORTERM=truecolor, kad būtų palaikomos visos spalvos.
• Naudojant tmux, išjungia būsenos juostą tmux, kad UI liktų tvarkingas.

Terminalų registras

• Stebi pasiekiamas terminalo sesijas.
• Pateikia sąrašą UI ir patikrina pasirinktų terminalų ID.

Autentifikavimas ir sesija

• Vienkartinis žetonas išvedamas kaip URL ir užkoduojamas QR kode.
• GET /__tb/s/:token išperka žetoną ir nustato slapuko sesiją.
• WebSocket ryšiams būtinas galiojantis sesijos slapukas ir CSRF žetonas.
• CSRF žetonas gaunamas per GET /__tb/api/csrf ir perduodamas WebSocket užklausos parametru.

Tarpinio serverio režimas

Kai perduodamas --proxy <port>:

• Visi termbridge maršrutai pateikiami po /__tb/ prefiksu
• Užklausos, kurios nėra /__tb/, persiunčiamos tikslinei programai
• UI peržiūrų parinkiklyje pateikia Terminalo ir Peržiūros rodinius
• Peržiūros rodinyje įkeliamas iframe, nukreipiantis į /
• HMR WebSocket ryšiai persiunčiami tikslinei programai

Sauga

• CSRF apsauga: WebSocket ryšio atnaujinimui būtinas CSRF žetonas, apsaugantis nuo užgrobimo iš kitos svetainės.
• Įvesties apribojimai: 64KB HTTP turinio, 1MB WebSocket pranešimas, 64KB terminalo įvestis vienam pranešimui.
• Užklausų dažnio ribojimas: apribojimai pagal IP taikomi žetonų išpirkimui ir WebSocket ryšiams.

API galiniai taškai

Visi maršrutai pateikiami po prefiksu /__tb/, kad nekiltų konfliktų su persiunčiamomis programomis:

• GET /__tb/healthz – būsenos patikra
• GET /__tb/s/:token – žetono išpirkimas → slapukas → peradresavimas
• GET /__tb/api/terminals – terminalų sąrašo gavimas
• GET /__tb/api/csrf – CSRF žetono gavimas WebSocket ryšiui
• GET /__tb/api/config – konfigūracijos gavimas (proxyPort, devProxyUrl)
• POST /__tb/api/terminals – naujos tmux sesijos kūrimas
• GET /__tb/app/* – SPA atsarginis maršrutas
• WS /__tb/ws/terminal/:terminalId?csrf=<token> – terminalo įvesties ir išvesties srautas

Įjungus tarpinio serverio režimą:

• GET / – peradresuoja į persiunčiamą programą (arba į /__tb/app, jei išjungta)
• * /* – persiunčiama tikslinei programai

WebSocket protokolas

Klientas -> serveris:

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

Serveris -> klientas:

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

UI stekas

• Vite + TanStack Router
• xterm.js + Fit priedas + WebGL vaizduoklis
• Pirmiausia mobiliesiems pritaikytas išdėstymas su fiksuota įvesties juosta
• Automatinis pakartotinis prisijungimas su eksponentiniu laukimo laiku (iki 10 bandymų)
• Ryšio būsenos indikatorius