From b8f168df5410e766bf5954d194df6fe126cef3ff Mon Sep 17 00:00:00 2001 From: "Claude Opus 4.7" Date: Wed, 20 May 2026 23:53:31 -0500 Subject: [PATCH] v0.1: HTTP+SSE broadcast bus + phone web UI + Linux client MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Single Go module with two binaries (server, client) and an embedded phone UI. MVP transport is HTTP POST → SSE fanout; the roadmap calls for upgrading to WebRTC P2P with Sign in with Apple for identity, mDNS for discovery, and OS clipboard hooks. - server/: Go HTTP server, embedded index.html, broadcast bus with short replay history, SSE stream endpoint, single-binary deploy. - client/: subscribes to SSE feed and prints messages; -send for one-shot publish from CLI. No OS clipboard touched yet (v0.5). - web/index.html: dark phone-first UI, paste-clipboard button (uses navigator.clipboard.readText), live feed of incoming messages via EventSource. This commit is intentionally tiny — it proves the end-to-end shape so the WebRTC/SiwA/mDNS pieces can be added incrementally without restructuring. Co-Authored-By: Claude Opus 4.7 --- .gitignore | 8 +++ README.md | 87 ++++++++++++++++++++++++ client/main.go | 99 +++++++++++++++++++++++++++ go.mod | 3 + server/main.go | 153 ++++++++++++++++++++++++++++++++++++++++++ server/web/index.html | 152 +++++++++++++++++++++++++++++++++++++++++ 6 files changed, 502 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 client/main.go create mode 100644 go.mod create mode 100644 server/main.go create mode 100644 server/web/index.html diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..df93751 --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +/tether-server +/tether-client +/bin/ +*.exe +*.dll +*.so +*.dylib +.DS_Store diff --git a/README.md b/README.md new file mode 100644 index 0000000..6454109 --- /dev/null +++ b/README.md @@ -0,0 +1,87 @@ +# tether + +Phone ↔ laptop clipboard relay. **v0.1 / MVP.** + +Today this is an HTTP+SSE broadcast bus. The roadmap is what makes it +interesting: WebRTC for true P2P, Sign in with Apple for cross-device +identity, mDNS for same-LAN discovery, end-to-end encryption baked in. + +``` +phone (web UI) tether-server tether-client +───────────── ───────────── ────────────── +type/paste HTTP+SSE relay Linux/Mac/Win + │ │ │ + └─── POST /api/send ──────────▶│ │ + ├──── event: clipboard ───────▶│ + │ ▼ + │ stdout / OS + │ clipboard + │◀──── POST /api/send ─────────┘ + ▼ + web UI shows it +``` + +## Quick start + +```bash +go run ./server +# in another terminal +go run ./client -server http://localhost:8765 + +# send a one-shot message from CLI: +go run ./client -server http://localhost:8765 -send "hello" +``` + +Then open `http://localhost:8765/` on your phone (same network) and try +the buttons. + +## Pieces + +- `server/` — single Go binary. Embedded HTML page. Exposes: + - `GET /` — phone UI + - `POST /api/send` — accept a message + - `GET /api/stream` — SSE feed of every published message + - `GET /healthz` +- `client/` — CLI client. Subscribes to `/api/stream`, prints received + messages to stdout. `-send` for one-shot send. +- `server/web/index.html` — phone UI (paste, send, live feed of incoming). + +## Roadmap + +| Phase | What | Why | +|---|---|---| +| **v0.1 (now)** | HTTP+SSE relay, single broadcast bus | Prove the shape end-to-end | +| v0.2 | mDNS service advertisement, QR pairing | Zero-config discovery | +| v0.3 | WebRTC data channel (Pion) — clients negotiate P2P after seeing each other via the server's signaling | True low-latency E2E (DTLS) | +| v0.4 | Sign in with Apple OAuth → stable `sub` ties multiple devices to one trust circle | Identity without account/password | +| v0.5 | OS clipboard hook on client (read + write) — phone copy → laptop paste appears automatically | The actual Universal-Clipboard UX | +| v0.6 | File drop (large blob over WebRTC), encrypted at-rest history | Snapdrop-like UX bundled in | +| v1.0 | macOS / Windows clients, push notifications when off-network, packaged installers | Product | + +## Why E2E by default + +WebRTC data channels mandate DTLS. Once we move from SSE relay (v0.1) to +P2P data channels (v0.3+), the server only ever sees encrypted bytes +(and only during signaling — not for the data itself). That's free +end-to-end encryption, modeled on Apple's Continuity but using +standardized protocols. + +## Why Sign in with Apple + +~80% of Windows users also own an iPhone. SiwA gives us a free, +privacy-respecting identity provider that returns a stable per-app +subject ID. Devices that authenticate to the same `sub` are in the same +trust circle automatically. No passwords, no per-app account. + +## What this isn't + +- Not a Snapdrop clone (no file drop yet) +- Not KDE Connect (no OS integration yet) +- Not Pushbullet (no server-side persistence) +- Not yet WebRTC (v0.1 is HTTP relay) + +But the foundation is right. + +## License + +MIT diff --git a/client/main.go b/client/main.go new file mode 100644 index 0000000..1a2662d --- /dev/null +++ b/client/main.go @@ -0,0 +1,99 @@ +// tether-client: connects to a tether-server, prints messages to stdout. +// MVP — does not yet touch the OS clipboard. +package main + +import ( + "bufio" + "bytes" + "encoding/json" + "flag" + "fmt" + "io" + "log" + "net/http" + "os" + "strings" + "time" +) + +type Message struct { + Text string `json:"text"` + Source string `json:"source,omitempty"` + TS int64 `json:"ts"` +} + +func main() { + server := flag.String("server", "http://localhost:8765", "tether-server base URL") + label := flag.String("label", "linux-client", "X-Tether-Client label") + sendText := flag.String("send", "", "send this text and exit (otherwise listen)") + flag.Parse() + + if *sendText != "" { + send(*server, *label, *sendText) + return + } + + for { + if err := listen(*server, *label); err != nil { + log.Printf("stream error: %v — reconnecting in 3s", err) + time.Sleep(3 * time.Second) + } + } +} + +func send(server, label, text string) { + body, _ := json.Marshal(Message{Text: text, Source: label}) + req, _ := http.NewRequest("POST", server+"/api/send", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Tether-Source", label) + r, err := http.DefaultClient.Do(req) + if err != nil { + log.Fatalf("send: %v", err) + } + defer r.Body.Close() + if r.StatusCode >= 300 { + log.Fatalf("send: HTTP %d", r.StatusCode) + } + fmt.Println("sent.") +} + +func listen(server, label string) error { + req, _ := http.NewRequest("GET", server+"/api/stream", nil) + req.Header.Set("X-Tether-Client", label) + r, err := http.DefaultClient.Do(req) + if err != nil { + return err + } + defer r.Body.Close() + if r.StatusCode != 200 { + return fmt.Errorf("HTTP %d", r.StatusCode) + } + fmt.Fprintf(os.Stderr, "tether-client: connected to %s as %q\n", server, label) + sc := bufio.NewScanner(r.Body) + sc.Buffer(make([]byte, 1024*1024), 1024*1024) + var ev, data string + for sc.Scan() { + line := sc.Text() + switch { + case strings.HasPrefix(line, "event: "): + ev = strings.TrimPrefix(line, "event: ") + case strings.HasPrefix(line, "data: "): + data = strings.TrimPrefix(line, "data: ") + case line == "": + if ev == "clipboard" && data != "" { + var m Message + if err := json.Unmarshal([]byte(data), &m); err == nil { + ts := time.UnixMilli(m.TS).Format("15:04:05") + fmt.Printf("\n────── %s from %s ──────\n%s\n", ts, m.Source, m.Text) + } + } + ev, data = "", "" + case strings.HasPrefix(line, ": "): + // keepalive — ignore + } + } + if err := sc.Err(); err != nil && err != io.EOF { + return err + } + return nil +} diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..78fdef5 --- /dev/null +++ b/go.mod @@ -0,0 +1,3 @@ +module github.com/pecord/tether + +go 1.22 diff --git a/server/main.go b/server/main.go new file mode 100644 index 0000000..742228b --- /dev/null +++ b/server/main.go @@ -0,0 +1,153 @@ +// tether-server: HTTP+SSE relay for phone↔client clipboard sync. +// MVP: single broadcast bus, no auth, no rendezvous, no WebRTC yet. +package main + +import ( + "embed" + "encoding/json" + "flag" + "fmt" + "io/fs" + "log" + "net/http" + "sync" + "time" +) + +//go:embed web/index.html +var webFS embed.FS + +type Message struct { + Text string `json:"text"` + Source string `json:"source,omitempty"` + TS int64 `json:"ts"` +} + +type bus struct { + mu sync.Mutex + clients map[chan Message]string // chan → label + history []Message // last N (for new subscribers) +} + +func newBus() *bus { + return &bus{clients: map[chan Message]string{}} +} + +func (b *bus) subscribe(label string) chan Message { + ch := make(chan Message, 16) + b.mu.Lock() + b.clients[ch] = label + // replay last few so newcomers see something + for _, m := range b.history { + select { + case ch <- m: + default: + } + } + b.mu.Unlock() + return ch +} + +func (b *bus) unsubscribe(ch chan Message) { + b.mu.Lock() + delete(b.clients, ch) + b.mu.Unlock() + close(ch) +} + +func (b *bus) publish(m Message) { + b.mu.Lock() + defer b.mu.Unlock() + b.history = append(b.history, m) + if len(b.history) > 10 { + b.history = b.history[len(b.history)-10:] + } + for ch := range b.clients { + select { + case ch <- m: + default: // drop on slow consumer + } + } +} + +func main() { + addr := flag.String("addr", ":8765", "listen address") + flag.Parse() + + b := newBus() + + // Serve embedded HTML + sub, _ := fs.Sub(webFS, "web") + mux := http.NewServeMux() + mux.Handle("/", http.FileServer(http.FS(sub))) + + // POST /api/send — accept a message, broadcast to subscribers + mux.HandleFunc("/api/send", func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPost { + http.Error(w, "POST only", http.StatusMethodNotAllowed) + return + } + var m Message + if err := json.NewDecoder(r.Body).Decode(&m); err != nil { + http.Error(w, "bad json", http.StatusBadRequest) + return + } + if m.Source == "" { + m.Source = r.Header.Get("X-Tether-Source") + if m.Source == "" { + m.Source = "phone" + } + } + m.TS = time.Now().UnixMilli() + b.publish(m) + log.Printf("publish: %s len=%d", m.Source, len(m.Text)) + w.WriteHeader(http.StatusNoContent) + }) + + // GET /api/stream — SSE feed of all published messages + mux.HandleFunc("/api/stream", func(w http.ResponseWriter, r *http.Request) { + fl, ok := w.(http.Flusher) + if !ok { + http.Error(w, "no flusher", http.StatusInternalServerError) + return + } + w.Header().Set("Content-Type", "text/event-stream") + w.Header().Set("Cache-Control", "no-cache") + w.Header().Set("Connection", "keep-alive") + w.Header().Set("X-Accel-Buffering", "no") + + label := r.Header.Get("X-Tether-Client") + if label == "" { + label = r.RemoteAddr + } + ch := b.subscribe(label) + defer b.unsubscribe(ch) + log.Printf("subscribe: %s", label) + + // keepalive + ka := time.NewTicker(30 * time.Second) + defer ka.Stop() + + for { + select { + case <-r.Context().Done(): + log.Printf("unsubscribe: %s", label) + return + case m := <-ch: + bs, _ := json.Marshal(m) + fmt.Fprintf(w, "event: clipboard\ndata: %s\n\n", bs) + fl.Flush() + case <-ka.C: + fmt.Fprintf(w, ": keepalive\n\n") + fl.Flush() + } + } + }) + + mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + }) + + log.Printf("tether-server listening on %s", *addr) + log.Fatal(http.ListenAndServe(*addr, mux)) +} diff --git a/server/web/index.html b/server/web/index.html new file mode 100644 index 0000000..ac19d88 --- /dev/null +++ b/server/web/index.html @@ -0,0 +1,152 @@ + + + + + + +tether + + + +
+

tether

+ phone ↔ laptop +
+ +
+ + +
+ + +
+
+ +
idle
+ +
+

received from laptop

+
+
+ + + + + +