Arkkitehtuuri

Yleiskuva toiminnasta

Oletus (paikallinen tmux + tunneli):

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

Suora hiekkalaatikkotila (Daytona, ei tunnelia):

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

Kun --no-tunnel on asetettu, Termbridge ohittaa kohteen Cloudflare ja käyttää antamaasi julkista URL-osoitetta.

Komponentit

CLI-prosessi

• Käynnistää HTTP-palvelimen, joka tarjoaa UI-resurssit.
• Käynnistää WebSocket-palvelimen päätteen syötettä ja tulostetta varten.
• Luo yhden tai useamman tmux-istunnon (tai Daytona-pseudo­päätteen).
• Luo kertakäyttöiset lunastustunnukset.
• Käynnistää tunnelin, jos se on käytössä, ja valvoo sitä (tällä hetkellä Cloudflare).
• Suorassa hiekkalaatikkotilassa käynnistää Termbridge-ohjelman hiekkalaatikossa ja odottaa jaon URL-osoitetta.

Päätteen taustajärjestelmä

• tmux-taustajärjestelmä: Käyttää node-pty:tä yhteyden muodostamiseen kohteeseen tmux oikeita näppäinpainalluksia ja tulostetta varten.
• Daytona-taustajärjestelmä: Käyttää Daytona-pseudopäätteitä hiekkalaatikossa.
• Asettaa TERM=xterm-256color ja COLORTERM=truecolor täydellistä väritukea varten.
• Kohteessa tmux poistaa tmux-tilapalkin käytöstä, jotta UI pysyy siistinä.

Pääterekisteri

• Seuraa käytettävissä olevia pääteistuntoja.
• Tarjoaa listan kohteelle UI ja vahvistaa valitut pääte-ID:t.

Todennus ja istunto

• Kertakäyttöinen tunnus tulostetaan muodossa URL ja koodataan QR-koodiin.
• GET /__tb/s/:token lunastaa tunnuksen ja asettaa istuntoevästeen.
• WebSocket-yhteydet edellyttävät kelvollista istuntoevästettä ja CSRF-tunnusta.
• CSRF-tunnus haetaan kohteesta GET /__tb/api/csrf ja välitetään WebSocket-kyselyparametrina.

Välityspalvelintila

Kun --proxy <port> annetaan:

• Kaikki termbridge-reitit ovat etuliitteen /__tb/ alla
• Pyynnöt, jotka eivät koske kohdetta /__tb/, välitetään kohdesovellukselle
• UI tuo Terminal- ja Preview-näkymät esiin Views-valitsimessa
• Preview-näkymä lataa iframe-kehyksen, joka osoittaa kohteeseen /
• HMR:n WebSocket-yhteydet välitetään eteenpäin kohteelle

Tietoturva

• CSRF-suojaus: WebSocket-yhteyden päivitys edellyttää CSRF-tunnusta, joka estää sivustojen välisen kaappauksen.
• Syöterajat: 64KB HTTP-runko, 1MB WebSocket-viesti, 64KB päätteen syöte viestiä kohti.
• Nopeusrajoitukset: IP-kohtaiset rajat tunnusten lunastukselle ja WebSocket-yhteyksille.

API-päätepisteet

Kaikki reitit ovat etuliitteen /__tb/ alla, jotta välitettäviin sovelluksiin ei synny ristiriitoja:

• GET /__tb/healthz – tilatarkistus
• GET /__tb/s/:token – tunnuksen lunastus → eväste → uudelleenohjaus
• GET /__tb/api/terminals – päätelista
• GET /__tb/api/csrf – hae CSRF-tunnus WebSocketia varten
• GET /__tb/api/config – hae asetukset (proxyPort, devProxyUrl)
• POST /__tb/api/terminals – luo uusi tmux-istunto
• GET /__tb/app/* – SPA-varareitti
• WS /__tb/ws/terminal/:terminalId?csrf=<token> – päätteen syötteen ja tulosteen suoratoisto

Kun välityspalvelintila on käytössä:

• GET / – uudelleenohjaa välitettyyn sovellukseen (tai kohteeseen /__tb/app, jos pois käytöstä)
• * /* – välitetään kohdesovellukselle

WebSocket-protokolla

Asiakas → palvelin:

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

Palvelin → asiakas:

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

UI-pino

• Vite + TanStack Router
• xterm.js + Fit-lisäosa + WebGL-renderöijä
• Mobiililähtöinen asettelu, jossa on kiinteä syöttöpalkki
• Automaattinen uudelleenyhdistäminen eksponentiaalisella viiveellä (enintään 10 yritystä)
• Yhteyden tilan ilmaisin