Αρχιτεκτονική

Ροή υψηλού επιπέδου

Προεπιλογή (τοπικό tmux + σήραγγα):

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

Άμεση λειτουργία sandbox (Daytona, χωρίς σήραγγα):

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

Όταν οριστεί το --no-tunnel, το Termbridge παραλείπει το Cloudflare και χρησιμοποιεί το δημόσιο URL που δώσατε.

Στοιχεία

Διαδικασία CLI

• Εκκινεί τον διακομιστή HTTP που εξυπηρετεί τα στοιχεία UI.
• Εκκινεί τον διακομιστή WebSocket για είσοδο/έξοδο τερματικού.
• Δημιουργεί μία ή περισσότερες συνεδρίες tmux (ή PTY Daytona).
• Εκδίδει διακριτικά μίας χρήσης για εξαργύρωση.
• Εκκινεί και παρακολουθεί τη σήραγγα όταν είναι ενεργοποιημένη (Cloudflare προς το παρόν).
• Στην άμεση λειτουργία sandbox, εκκινεί το Termbridge μέσα στο sandbox και περιμένει το κοινόχρηστο URL.

Backend τερματικού

• Backend tmux: Χρησιμοποιεί το node-pty για σύνδεση στο tmux και υποστηρίζει πραγματικές πληκτρολογήσεις και έξοδο.
• Backend Daytona: Χρησιμοποιεί PTY Daytona μέσα σε sandbox.
• Ορίζει τα TERM=xterm-256color και COLORTERM=truecolor για πλήρη υποστήριξη χρωμάτων.
• Για tmux, απενεργοποιεί τη γραμμή κατάστασης tmux ώστε να διατηρεί καθαρό το UI.

Μητρώο τερματικών

• Παρακολουθεί τις διαθέσιμες συνεδρίες τερματικού.
• Παρέχει λίστα για το UI και επικυρώνει τα επιλεγμένα αναγνωριστικά τερματικών.

Έλεγχος ταυτότητας και συνεδρία

• Το διακριτικό μίας χρήσης εμφανίζεται ως URL και κωδικοποιείται σε κώδικα QR.
• Το GET /__tb/s/:token εξαργυρώνει το διακριτικό και ορίζει μια συνεδρία cookie.
• Οι συνδέσεις WebSocket απαιτούν έγκυρο cookie συνεδρίας και διακριτικό CSRF.
• Το διακριτικό CSRF ανακτάται μέσω του GET /__tb/api/csrf και περνά ως παράμετρος query του WebSocket.

Λειτουργία διακομιστή μεσολάβησης

Όταν περνά το --proxy <port>:

• Όλες οι διαδρομές του termbridge βρίσκονται κάτω από το πρόθεμα /__tb/
• Τα αιτήματα που δεν είναι /__tb/ προωθούνται στην εφαρμογή-στόχο
• Το UI εμφανίζει τις προβολές Terminal/Preview μέσω του εναλλάκτη Views
• Η προβολή Preview φορτώνει ένα iframe που δείχνει στο /
• Οι συνδέσεις WebSocket για HMR προωθούνται στον στόχο

Ασφάλεια

• Προστασία CSRF: Οι αναβαθμίσεις WebSocket απαιτούν διακριτικό CSRF για την αποτροπή παραβίασης από άλλη προέλευση.
• Όρια εισόδου: σώμα HTTP 64KB, μήνυμα WebSocket 1MB, είσοδος τερματικού 64KB ανά μήνυμα.
• Περιορισμός ρυθμού: Όρια ανά IP για την εξαργύρωση διακριτικών και τις συνδέσεις WebSocket.

Καταληκτικά σημεία API

Όλες οι διαδρομές βρίσκονται κάτω από το πρόθεμα /__tb/ για την αποφυγή διενέξεων με εφαρμογές που προωθούνται μέσω διακομιστή μεσολάβησης:

• GET /__tb/healthz - έλεγχος υγείας
• GET /__tb/s/:token - εξαργύρωση διακριτικού → cookie → ανακατεύθυνση
• GET /__tb/api/terminals - λίστα τερματικών
• GET /__tb/api/csrf - λήψη διακριτικού CSRF για WebSocket
• GET /__tb/api/config - λήψη ρυθμίσεων (proxyPort, devProxyUrl)
• POST /__tb/api/terminals - δημιουργία νέας συνεδρίας tmux
• GET /__tb/app/* - εφεδρική διαδρομή SPA
• WS /__tb/ws/terminal/:terminalId?csrf=<token> - ροή εισόδου/εξόδου τερματικού

Όταν είναι ενεργοποιημένη η λειτουργία διακομιστή μεσολάβησης:

• GET / - ανακατεύθυνση στην εφαρμογή μέσω διακομιστή μεσολάβησης (ή /__tb/app αν είναι απενεργοποιημένη)
• * /* - προώθηση στην εφαρμογή-στόχο μέσω διακομιστή μεσολάβησης

Πρωτόκολλο WebSocket

Πελάτης -> διακομιστής:

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

Διακομιστής -> πελάτης:

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

Στοίβα UI

• Vite + TanStack Router
• xterm.js + πρόσθετο Fit + μηχανή απόδοσης WebGL
• Διάταξη πρώτα για κινητά, με σταθερή γραμμή εισόδου
• Αυτόματη επανασύνδεση με εκθετική καθυστέρηση (έως 10 προσπάθειες)
• Ένδειξη κατάστασης σύνδεσης