feat: improve connection stability, session lifecycle, file transfer, and encoding robustness

- Fix connection stability: add WebSocket ping/pong heartbeat with
  SetReadDeadline/SetPongHandler on bridge, periodic server-side ping
- Fix Ctrl+C graceful disconnect: signal handler now closes WebSocket
  connection before exiting, sending clean close frame to server
- Fix tab close cleanup: add beforeunload + visibilitychange handlers
  using navigator.sendBeacon to disconnect bridge on tab close
- Fix session expiry: add SESSION_TTL (default 10 min), enforce in
  command handler, expose expires_at/expired in API response
- Fix base64 encoding: support base64url, strip whitespace, remove
  strict roundtrip validation, fallback to Latin-1 for non-UTF-8 data
- Add file upload/download: HTTP multipart upload + stream download,
  WebSocket file_read/file_write protocol, 50MB file size limit
- Add comprehensive tests: 24 server tests, 17 bridge tests all passing

Author: bgwastu

bridge/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"bytes"
+	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -25,6 +26,8 @@ const maxOutputBytes = 128 * 1024
 const (
 	reconnectBaseDelay = 1 * time.Second
 	reconnectMaxDelay  = 30 * time.Second
+	pongWait           = 60 * time.Second
+	maxFileSize        = 50 * 1024 * 1024
 )
 
 var sessionCodePattern = regexp.MustCompile(`^[0-9a-f]{12}$`)
@@ -42,6 +45,32 @@ func printLine(parts ...string) {
 	_, _ = os.Stdout.WriteString(strings.Join(parts, "") + "\n")
 }
 
+// Global reference for signal handler to gracefully close the connection
+var (
+	currentBridge   *wsConn
+	currentBridgeMu sync.Mutex
+)
+
+func setCurrentBridge(w *wsConn) {
+	currentBridgeMu.Lock()
+	currentBridge = w
+	currentBridgeMu.Unlock()
+}
+
+func clearCurrentBridge() {
+	currentBridgeMu.Lock()
+	currentBridge = nil
+	currentBridgeMu.Unlock()
+}
+
+func closeCurrentBridge() {
+	currentBridgeMu.Lock()
+	if currentBridge != nil {
+		currentBridge.close()
+	}
+	currentBridgeMu.Unlock()
+}
+
 func main() {
 	wsURL := os.Getenv("BRIDGE_WS_URL")
 	if wsURL == "" {
@@ -60,6 +89,9 @@ func main() {
 	signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
 	go func() {
 		<-sig
+		// Gracefully close the bridge WebSocket connection so the server
+		// gets a clean close frame. This also unblocks ReadMessage().
+		closeCurrentBridge()
 		close(quit)
 	}()
 
@@ -217,6 +249,16 @@ func (w *wsConn) close() {
 	_ = w.conn.Close()
 }
 
+func (w *wsConn) closeUnderlying() {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if w.closed {
+		return
+	}
+	w.closed = true
+	_ = w.conn.Close()
+}
+
 func readCommands(wsc *wsConn, dot string) bool {
 	defer func() {
 		printLine("\n", dot, " Connection closed.", ansiReset)
@@ -269,13 +311,133 @@ func readCommands(wsc *wsConn, dot string) bool {
 				"exit_code": code,
 				"truncated": truncated,
 			})
+		case "file_read":
+			var msg struct {
+				ID       string `json:"id"`
+				Path     string `json:"path"`
+				Encoding string `json:"encoding"`
+			}
+			_ = json.Unmarshal(data, &msg)
+			if msg.ID == "" {
+				continue
+			}
+			handleFileRead(wsc, msg.ID, msg.Path)
+		case "file_write":
+			var msg struct {
+				ID       string `json:"id"`
+				Path     string `json:"path"`
+				Data     string `json:"data"`
+				Encoding string `json:"encoding"`
+			}
+			_ = json.Unmarshal(data, &msg)
+			if msg.ID == "" {
+				continue
+			}
+			handleFileWrite(wsc, msg.ID, msg.Path, msg.Data, msg.Encoding)
 		case "bye":
 			wsc.close()
 			return false
 		}
 	}
 }
 
+func handleFileRead(wsc *wsConn, id, path string) {
+	printLine(ansiCyan+"📖"+ansiReset, " ", ansiBold, "File read:", ansiReset, " ", path)
+	data, size, err := readFile(path)
+	if err != nil {
+		wsc.sendJSON(map[string]any{
+			"type":    "file_read_result",
+			"id":      id,
+			"path":    path,
+			"error":   err.Error(),
+			"size":    0,
+			"data":    "",
+			"encoding": "base64",
+		})
+		return
+	}
+	wsc.sendJSON(map[string]any{
+		"type":     "file_read_result",
+		"id":       id,
+		"path":     path,
+		"data":     data,
+		"size":     size,
+		"encoding": "base64",
+	})
+}
+
+func handleFileWrite(wsc *wsConn, id, path, data, encoding string) {
+	printLine(ansiCyan+"📝"+ansiReset, " ", ansiBold, "File write:", ansiReset, " ", path)
+	bytesWritten, err := writeFile(path, data, encoding)
+	if err != nil {
+		wsc.sendJSON(map[string]any{
+			"type":         "file_write_result",
+			"id":           id,
+			"path":         path,
+			"error":        err.Error(),
+			"bytes_written": 0,
+		})
+		return
+	}
+	wsc.sendJSON(map[string]any{
+		"type":          "file_write_result",
+		"id":            id,
+		"path":          path,
+		"bytes_written": bytesWritten,
+	})
+}
+
+func readFile(path string) (string, int64, error) {
+	fi, err := os.Stat(path)
+	if err != nil {
+		return "", 0, fmt.Errorf("cannot access %s: %w", path, err)
+	}
+	if fi.Size() > maxFileSize {
+		return "", 0, fmt.Errorf("file too large: %d bytes (max %d)", fi.Size(), maxFileSize)
+	}
+
+	f, err := os.Open(path)
+	if err != nil {
+		return "", 0, fmt.Errorf("cannot open %s: %w", path, err)
+	}
+	defer f.Close()
+
+	data, err := io.ReadAll(f)
+	if err != nil {
+		return "", 0, fmt.Errorf("cannot read %s: %w", path, err)
+	}
+
+	encoded := base64.StdEncoding.EncodeToString(data)
+	return encoded, fi.Size(), nil
+}
+
+func writeFile(path, data, encoding string) (int, error) {
+	var raw []byte
+	switch encoding {
+	case "base64", "":
+		var err error
+		raw, err = base64.StdEncoding.DecodeString(data)
+		if err != nil {
+			// Try base64url
+			raw, err = base64.URLEncoding.DecodeString(data)
+			if err != nil {
+				return 0, fmt.Errorf("invalid base64 data: %w", err)
+			}
+		}
+	default:
+		return 0, fmt.Errorf("unsupported encoding: %s", encoding)
+	}
+
+	if len(raw) > maxFileSize {
+		return 0, fmt.Errorf("data too large: %d bytes (max %d)", len(raw), maxFileSize)
+	}
+
+	if err := os.WriteFile(path, raw, 0644); err != nil {
+		return 0, fmt.Errorf("cannot write %s: %w", path, err)
+	}
+	return len(raw), nil
+}
+
 func dialAndRun(wsURL, code string, quit <-chan struct{}) (string, bool) {
 	dialer := websocket.Dialer{HandshakeTimeout: 15 * time.Second}
 	conn, resp, err := dialer.Dial(wsURL, http.Header{})
@@ -294,9 +456,18 @@ func dialAndRun(wsURL, code string, quit <-chan struct{}) (string, bool) {
 	}
 
 	bridge := &wsConn{conn: conn}
+	setCurrentBridge(bridge)
+
 	dot := ansiCyan + "●" + ansiReset
 	printLine(dot, " ", ansiBold, code, ansiReset, "  —  Ctrl+C to disconnect")
 
+	// Set up heartbeat: expect pong within pongWait
+	conn.SetReadDeadline(time.Now().Add(pongWait))
+	conn.SetPongHandler(func(string) error {
+		conn.SetReadDeadline(time.Now().Add(pongWait))
+		return nil
+	})
+
 	if !bridge.sendJSON(map[string]any{
 		"type":    "join",
 		"session": code,
@@ -313,15 +484,18 @@ func dialAndRun(wsURL, code string, quit <-chan struct{}) (string, bool) {
 	}) {
 		select {
 		case <-quit:
+			clearCurrentBridge()
 			return "", false
 		default:
 		}
 		printLine(dot, " ", ansiRed, "Join failed, reconnecting...", ansiReset)
 		bridge.close()
+		clearCurrentBridge()
 		return "", true
 	}
 
 	reconnect := readCommands(bridge, dot)
+	clearCurrentBridge()
 	return dot, reconnect
 }