# 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:

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

Palvelin → asiakas:

```json
{ "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