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

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

Serveris -> klientas:

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