init readme
Kim committed
Oct 20, 2025 at 18:48 UTC
81aacb20a176579fd602e04a04dc7e5e49750340
1 file changed
+94
README.md
new
+94
@@ -0,0 +1,94 @@
1
+# RelayDNS
2
+> A lightweight, DNS-driven peer-to-peer proxy layer built on libp2p.
3
+
4
+`relaydns` provides a minimal DNS-entry proxy that routes traffic between arbitrary nodes over **libp2p**.
5
+It lets you expose and discover TCP services (like SSH, API endpoints, etc.) even behind NAT,
6
+without depending on centralized reverse-proxy services.
7
+
8
+## Features
9
+
10
+- 🛰 **Peer-to-peer routing** over libp2p (supports hole punching, relay, pubsub)
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)
15
+
16
+## Architecture Overview
17
+
18
+```
19
+┌──────────────┐ pubsub (GossipSub) ┌──────────────┐
20
+│ relaydns │ <--------------------------> │ client(s) │
21
+│ server │ │ (imported in │
22
+│ (director) │ │ your app) │
23
+└──────────────┘ └──────────────┘
24
+ │ │
25
+ │ TCP stream (e.g. SSH, HTTP, custom) │
26
+ ▼ ▼
27
+ Your users Your local service
28
+```
29
+
30
+## Getting Started
31
+
32
+### 1️⃣ Run the RelayDNS Server
33
+
34
+The **server** acts as a public entrypoint that accepts incoming TCP connections
35
+and forwards them over libp2p to available clients.
36
+
37
+```bash
38
+go build -o relaydns ./cmd/relaydns
39
+
40
+./relaydns \
41
+ --listen-tcp :22 \
42
+ --listen-http :8080 \
43
+ --protocol /relaydns/ssh/1.0 \
44
+ --topic relaydns.backends
45
+```
46
+
47
+### 2️⃣ Embed the RelayDNS Client in Your App
48
+
49
+The client is a small Go library that you can embed in any Go program.
50
+It automatically advertises itself and tunnels incoming streams to your local TCP service.
51
+
52
+Install the module:
53
+```bash
54
+go get github.com/gosuda/relaydns/pkg
55
+```
56
+
57
+Example usage:
58
+```go
59
+package main
60
+
61
+import (
62
+ "context"
63
+ "log"
64
+ "time"
65
+
66
+ "github.com/libp2p/go-libp2p"
67
+ "github.com/gosuda/relaydns/pkg/relaydns"
68
+)
69
+
70
+func main() {
71
+ ctx := context.Background()
72
+ h, err := libp2p.New(
73
+ libp2p.EnableHolePunching(),
74
+ libp2p.EnableNATService(),
75
+ )
76
+ if err != nil {
77
+ log.Fatal(err)
78
+ }
79
+
80
+ client, err := relaydns.NewClient(ctx, h, relaydns.ClientConfig{
81
+ Protocol: "/relaydns/ssh/1.0",
82
+ Topic: "relaydns.backends",
83
+ AdvertiseEvery: 5 * time.Second,
84
+ TargetTCP: "127.0.0.1:22", // your local SSH or app port
85
+ Name: "seoul-node",
86
+ })
87
+ if err != nil {
88
+ log.Fatal(err)
89
+ }
90
+ defer client.Close()
91
+
92
+ select {} // keep running
93
+}
94
+```
\ No newline at end of file