Arhitektura

Potek na visoki ravni

Privzeto (lokalni tmux + tunel):

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

Neposredni način peskovnika (Daytona, brez tunela):

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

Ko je nastavljena spremenljivka --no-tunnel, Termbridge preskoči Cloudflare in uporabi vaš javni URL.

Komponente

Proces CLI

• Zažene strežnik HTTP, ki streže sredstva UI.
• Zažene strežnik WebSocket za V/I terminala.
• Ustvari eno ali več sej tmux (ali PTY-jev Daytona).
• Izdaja enkratne žetone za dostop.
• Zažene in nadzira tunel, če je omogočen (trenutno Cloudflare).
• V neposrednem načinu peskovnika zažene Termbridge v peskovniku in počaka na deljeni URL.

Zaledje terminala

• Zaledje tmux: Uporablja node-pty za povezavo s tmux, da omogoči prave pritiske tipk in izhod.
• Zaledje Daytona: Uporablja PTY-je Daytona v peskovniku.
• Nastavi TERM=xterm-256color in COLORTERM=truecolor za polno podporo barvam.
• Za tmux onemogoči vrstico stanja tmux, da UI ostane čist.

Register terminalov

• Spremlja razpoložljive terminalske seje.
• Ponuja seznam za UI in preverja izbrane ID-je terminalov.

Preverjanje pristnosti in seja

• Enkratni žeton se izpiše kot URL in kodira v kodo QR.
• GET /__tb/s/:token unovči žeton in nastavi sejo s piškotkom.
• Za povezave WebSocket sta potrebna veljaven sejni piškotek in žeton CSRF.
• Žeton CSRF se pridobi prek GET /__tb/api/csrf in posreduje kot parameter v poizvedbi WebSocket.

Način posredovanja

Ko je podan --proxy <port>:

• Vse poti termbridge so pod predpono /__tb/
• Zahteve, ki niso /__tb/, se posredujejo ciljni aplikaciji
• UI prek preklopnika Views prikaže poglede Terminal/Preview
• Pogled Preview naloži okvir iframe, ki kaže na /
• Povezave WebSocket za HMR se posredujejo cilju

Varnost

• Zaščita CSRF: Za nadgradnjo povezav WebSocket je potreben žeton CSRF, ki preprečuje ugrabitev z drugega spletnega mesta.
• Omejitve vnosa: Telo HTTP do 64KB, sporočilo WebSocket do 1MB, vhod terminala do 64KB na sporočilo.
• Omejevanje hitrosti: Omejitve na IP za unovčenje žetonov in povezave WebSocket.

Končne točke API

Vse poti so pod predpono /__tb/, da se preprečijo konflikti s posredovanimi aplikacijami:

• GET /__tb/healthz – preverjanje stanja
• GET /__tb/s/:token – unovčenje žetona → piškotek → preusmeritev
• GET /__tb/api/terminals – seznam terminalov
• GET /__tb/api/csrf – pridobitev žetona CSRF za WebSocket
• GET /__tb/api/config – pridobitev konfiguracije (proxyPort, devProxyUrl)
• POST /__tb/api/terminals – ustvarjanje nove seje tmux
• GET /__tb/app/* – rezervni prikaz SPA
• WS /__tb/ws/terminal/:terminalId?csrf=<token> – pretakanje V/I terminala

Ko je omogočen način posredovanja:

• GET / – preusmeri na posredovano aplikacijo (ali na /__tb/app, če je onemogočena)
• * /* – posredovano ciljni aplikaciji

Protokol WebSocket

Odjemalec -> strežnik:

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

Strežnik -> odjemalec:

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

Sklad UI

• Vite + TanStack Router
• xterm.js + dodatek Fit + izrisovalnik WebGL
• Postavitev, prilagojena najprej mobilnim napravam, s fiksno vrstico za vnos
• Samodejna ponovna povezava z eksponentnim podaljševanjem čakanja (do 10 poskusov)
• Kazalnik stanja povezave