readme: add chatting client
Kim committed
Oct 21, 2025 at 17:55 UTC
dc6b0fc0d8c17aeb659f5cc471e7837eef082344
2 files changed
+65
-21
Makefile
+27
-9
@@ -1,5 +1,5 @@
1
SHELL := /bin/sh
2
-.PHONY: help server-up server-down server-build client-run client-build fmt tidy
2
+.PHONY: help server-up server-down server-build client-run client-build chat-run chat-build fmt tidy
3
4
# Detect docker compose command (override with `make DC="docker-compose"` if needed)
5
DC ?= docker compose
@@ -33,6 +33,22 @@ client-run:
33
client-build:
34
go build -trimpath -o bin/relaydns-client ./cmd/example_http_client
35
36
+# ---------- Chat (local go) ----------
37
+CHAT_ADDR ?= :8091
38
+CHAT_NAME ?= demo-chat
39
+
40
+CHAT_FLAGS := \
41
+ --server-url $(SERVER_URL) \
42
+ --addr $(CHAT_ADDR) \
43
+ --name $(CHAT_NAME) \
44
+ $(CLIENT_BOOTSTRAPS_FLAGS)
45
+
46
+chat-run:
47
+ go run ./cmd/example_chat $(CHAT_FLAGS)
48
+
49
+chat-build:
50
+ go build -trimpath -o bin/relaydns-chat ./cmd/example_chat
51
+
52
# ---------- Dev helpers ----------
53
fmt:
54
go fmt ./...
@@ -41,11 +57,13 @@ tidy:
57
go mod tidy
58
59
help:
44
- @echo "Server:"
45
- @echo " make server-up # build and start relayserver (docker compose)"
46
- @echo " make server-down # stop and remove containers"
47
- @echo "\nClient:"
48
- @echo " make client-run # run example_http_client locally with minimal flags"
49
- @echo " make client-build # build example_http_client to ./bin/relaydns-client"
50
- @echo "\nFlags (override with make VAR=value):"
51
- @echo " SERVER_URL BACKEND_HTTP BOOTSTRAPS"
60
+ @echo "Server:"
61
+ @echo " make server-up # build and start relayserver (docker compose)"
62
+ @echo " make server-down # stop and remove containers"
63
+ @echo "\nClients (optional):"
64
+ @echo " make client-run # run example_http_client locally"
65
+ @echo " make client-build # build example_http_client to ./bin/relaydns-client"
66
+ @echo " make chat-run # run example_chat locally (WS UI + advertiser)"
67
+ @echo " make chat-build # build example_chat to ./bin/relaydns-chat"
68
+ @echo "\nFlags (override with make VAR=value):"
69
+ @echo " SERVER_URL BACKEND_HTTP BOOTSTRAPS CHAT_ADDR CHAT_NAME"
README.md
+38
-12
@@ -11,7 +11,6 @@ without depending on centralized reverse-proxy services.
11
- 🧩 **DNS-driven entrypoint** (server acts as a lightweight coordinator)
12
- 🔄 **Automatic peer advertisement** via GossipSub
13
- 🔌 **Pluggable client SDK** — embed the relaydns client directly into your Go applications
14
-- 🪶 **Lightweight** and dependency-minimal (Cobra CLI + Go libp2p only)
14
15
## Architecture Overview
16
@@ -39,18 +38,29 @@ Published ports:
38
- Admin/UI + HTTP proxy: `8080`
39
- libp2p TCP/QUIC: `4001/tcp`, `4001/udp`
40
42
-### 2️⃣ Run the Example Client (Makefile)
41
+### 2️⃣ (Optional) Run Example Clients
42
44
-The example client runs a tiny local HTTP backend and advertises it over libp2p.
43
+Clients are NOT required to run the server. They are provided for testing/demo.
44
46
-```bash
47
-make client-run
48
-# Optional (override on demand):
49
-# make client-run BACKEND_HTTP=:8081 SERVER_URL=http://localhost:8080 \
50
-# BOOTSTRAPS="/dnsaddr/your.bootstrap/p2p/12D3Koo..."
51
-```
45
+- HTTP client (optional): exposes a tiny local HTTP backend and advertises it.
46
+ ```bash
47
+ make client-run
48
+ # Optional overrides:
49
+ # make client-run BACKEND_HTTP=:8081 SERVER_URL=http://localhost:8080 \
50
+ # BOOTSTRAPS="/dnsaddr/your.bootstrap/p2p/12D3Koo..."
51
+ ```
52
+
53
+- Chat client (optional): WebSocket chat UI (local) + advertiser (libp2p). Uses coder/websocket.
54
+ ```bash
55
+ make chat-run
56
+ # Optional overrides:
57
+ # make chat-run CHAT_ADDR=:8091 CHAT_NAME=demo-chat SERVER_URL=http://localhost:8080 \
58
+ # BOOTSTRAPS="/ip4/1.2.3.4/tcp/4001/p2p/12D3Koo..."
59
+ ```
60
53
-The client exposes a tiny local HTTP server and tunnels traffic to it via libp2p streams.
61
+If you run the chat client:
62
+- Open locally: `http://localhost:8091`
63
+- Open via server proxy: Admin → your peer → Open (routes to `/peer/<peerID>/` then `/peer/<peerID>/ws`).
64
65
### 3️⃣ Embed the Client SDK in Your App
66
@@ -90,7 +100,23 @@ Server flags (see `docker-compose.yml`):
100
- `--http` Unified admin UI + HTTP proxy listen address (default `:8080`)
101
- `--bootstrap` Repeatable multiaddr with `/p2p/`
102
93
-Example client flags (see `make client-run`):
103
+HTTP client flags (see `make client-run`):
104
+- `--server-url` Admin base URL to fetch `/health` (default `http://localhost:8080`)
105
+- `--bootstrap` Repeatable multiaddr with `/p2p/`
106
+- `--backend-http` Local backend HTTP listen address (default `:8081`)
107
+
108
+Chat client flags (see `make chat-run`):
109
- `--server-url` Admin base URL to fetch `/health` (default `http://localhost:8080`)
110
- `--bootstrap` Repeatable multiaddr with `/p2p/`
96
-- `--backend-http` Local backend HTTP listen address (default `:8081`)
\ No newline at end of file
111
+- `--addr` Local chat HTTP listen address (default `:8091`)
112
+- `--name` Display name (shown on server UI)
113
+
114
+## Deploying the Server (public)
115
+
116
+- Expose ports:
117
+ - `8080/tcp` Admin UI + HTTP/WS proxy (`/peer/<peerID>/`)
118
+ - `4001/tcp` and `4001/udp` libp2p (GossipSub/streams)
119
+- Cloudflare DNS:
120
+ - Web UI/proxy (8080): can be proxied (orange cloud) if using HTTP/HTTPS
121
+ - libp2p (4001 tcp/udp): must be DNS only (gray cloud). Cloudflare proxy doesn’t support arbitrary TCP/UDP ports.
122
+- WebSocket: server proxies 101 and tunnels bytes; the chat backend allows any HTTP(S) Origin for demo. Restrict in production.