docs: Add docs on rest of the subsystems

pojntfx · pojntfx · commit b24ab8c390c9 · 2022-05-06T23:18:36.000+02:00
diff --git a/README.md b/README.md
@@ -16,7 +16,12 @@ Overlay networks based on WebRTC.
 
 weron provides lean, fast & secure overlay networks based on WebRTC.
 
-🚧 This project is a work-in-progress! Instructions will be added as soon as it is usable. 🚧
+It enables you too ...
+
+- **Access to nodes behind NAT**: Because weron uses WebRTC to establish connections between nodes, it can easily traverse corporate firewalls and NATs using STUN, or even use a TURN server to tunnel traffic. This can be very useful to i.e. SSH into your homelab without forwarding any ports on your router.
+- **Secure your home network**: By using the inbuilt interactive TLS verification and running the signaling server locally, weron can be used to secure traffic between nodes in a LAN without depending on any external infrastructure.
+- **Join local nodes into a cloud network**: If you run e.g. a Kubernetes cluster with nodes based on cloud instances but also want to join your on-prem nodes into it, you can use weron to create a trusted network for it.
+- **Write your own peer-to-peer protocols**: The simple API makes writing distributed applications with automatic reconnects, multiple datachannels etc. approachable and fun!
 
 ## Installation
 
@@ -83,9 +88,9 @@ $ sudo podman run -d --name weron-signaler --network weron -p 1337:1337 -e DATAB
 
 It should now be reachable on `ws://localhost:1337/`.
 
-To use it in production, put this signaling server behind a TLS-enabled reverse proxy such as [Caddy](https://caddyserver.com/) or [Traefik](https://traefik.io/). You may also either want to keep `API_PASSWORD` empty to disable the management API completely or use OpenID Connect to authenticate instead; for more information, see the [signaling server reference](#signaling-server). You can also embed the signaling server in your own application using it's [Go API](https://pkg.go.dev/github.com/pojntfx/weron@v0.0.0-20220505182851-8eabe8595f05/pkg/wrtcsgl).
+To use it in production, put this signaling server behind a TLS-enabled reverse proxy such as [Caddy](https://caddyserver.com/) or [Traefik](https://traefik.io/). You may also either want to keep `API_PASSWORD` empty to disable the management API completely or use OpenID Connect to authenticate instead; for more information, see the [signaling server reference](#signaling-server). You can also embed the signaling server in your own application using it's [Go API](https://pkg.go.dev/github.com/pojntfx/weron@main/pkg/wrtcsgl).
 
-### Manage Communities with `weron manager`
+### 2. Manage Communities with `weron manager`
 
 While it is possible to create ephermal communities on a signaling server without any kind of authorization, you probably want to create a persistent community for most applications. Ephermal communities get created and deleted automatically as clients join or leave, persistent communities will never get deleted automatically. You can manage these communities using the manager CLI.
 
@@ -129,7 +134,203 @@ It is also possible to delete communities using `weron delete`, which will also
 $ weron manager delete --community mycommunity
 ```
 
-For more information, see the [manager reference](#manager). You can also embed the manager in your own application using it's [Go API](https://pkg.go.dev/github.com/pojntfx/weron@v0.0.0-20220505182851-8eabe8595f05/pkg/wrtcmgr).
+For more information, see the [manager reference](#manager). You can also embed the manager in your own application using it's [Go API](https://pkg.go.dev/github.com/pojntfx/weron@main/pkg/wrtcmgr).
+
+### 3. Test the System with `weron chat`
+
+The chat is an easy way to test if everything is working correctly. To join a chatroom, run the following:
+
+```shell
+$ weron chat --community mycommunity --password mypassword --key mykey --names user1,user2,user3 --channels one,two,three
+```
+
+On another peer, run the following (if your signaling server is public, you can run this anywhere on the planet):
+
+```shell
+$ weron chat --community mycommunity --password mypassword --key mykey --names user1,user2,user3 --channels one,two,three
+.wss://weron.herokuapp.com/
+user2!
++user1@one
++user1@two
++user1@three
+user2>
+```
+
+You can now start sending and receiving messages or add new peers to your chatroom to test the network.
+
+For more information, see the [chat reference](#chat). You can also embed the chat in your own application using it's [Go API](https://pkg.go.dev/github.com/pojntfx/weron@main/pkg/wrtcchat).
+
+### 4. Measure Latency with `weron utility latency`
+
+An insightful metric of your network is it's latency, which you can measure with this utility; think of this as `ping`, but for WebRTC. First, start the latency measurement server like so:
+
+```shell
+$ weron utility latency --community mycommunity --password mypassword --key mykey --server
+```
+
+On another peer, launch the client, which should start measuring the latency immediately; press <kbd>CTRL</kbd> <kbd>C</kbd> to stop it and get the total statistics:
+
+```shell
+$ weron utility latency --community mycommunity --password mypassword --key mykey
+# ...
+128 B written and acknowledged in 110.111µs
+128 B written and acknowledged in 386.12µs
+128 B written and acknowledged in 310.458µs
+128 B written and acknowledged in 335.341µs
+128 B written and acknowledged in 264.149µs
+^CAverage latency: 281.235µs (5 packets written) Min: 110.111µs Max: 386.12µs
+```
+
+For more information, see the [latency measurement utility reference](#latency-measurement-utility). You can also embed the utility in your own application using it's [Go API](https://pkg.go.dev/github.com/pojntfx/weron@main/pkg/wrtcltc).
+
+### 5. Measure Throughput with `weron utility throughput`
+
+If you want to transfer large amounts of data, your network's throughput is a key characteristic. This utility allows you to measure this metric between two nodes; think of it as `iperf`, but for WebRTC. First, start the throughput measurement server like so:
+
+```shell
+$ weron utility throughput --community mycommunity --password mypassword --key mykey --server
+```
+
+On another peer, launch the client, which should start measuring the throughput immediately; press <kbd>CTRL</kbd> <kbd>C</kbd> to stop it and get the total statistics:
+
+```shell
+$ weron utility throughput --community mycommunity --password mypassword --key mykey
+# ...
+97.907 MB/s (783.253 Mb/s) (50 MB read in 510.690403ms)
+64.844 MB/s (518.755 Mb/s) (50 MB read in 771.076908ms)
+103.360 MB/s (826.881 Mb/s) (50 MB read in 483.745832ms)
+89.335 MB/s (714.678 Mb/s) (50 MB read in 559.692495ms)
+85.582 MB/s (684.657 Mb/s) (50 MB read in 584.233931ms)
+^CAverage throughput: 74.295 MB/s (594.359 Mb/s) (250 MB written in 3.364971672s) Min: 64.844 MB/s Max: 103.360 MB/s
+```
+
+For more information, see the [throughput measurement utility reference](#throughput-measurement-utility). You can also embed the utility in your own application using it's [Go API](https://pkg.go.dev/github.com/pojntfx/weron@main/pkg/wrtcthr).
+
+### 6. Create a Layer 3 (IP) Overlay Network with `weron vpn ip`
+
+If you want to join multiple nodes into a overlay network, the IP VPN is the best choice. It works in a similar way to i.e. Tailscale/WireGuard and can either dynamically allocate an IP address from a CIDR notation or statically assign one for you. On Windows, make sure to install [TAP-Windows](https://duckduckgo.com/?q=TAP-Windows&t=h_&ia=web) first. To get started, launch the VPN on the first peer:
+
+```shell
+$ sudo weron vpn ip --community mycommunity --password mypassword --key mykey --ips 2001:db8::1/64,192.0.2.1/24
+{"level":"info","addr":"wss://weron.herokuapp.com/","time":"2022-05-06T22:20:51+02:00","message":"Connecting to signaler"}
+{"level":"info","id":"[\"2001:db8::6a/64\",\"192.0.2.107/24\"]","time":"2022-05-06T22:20:56+02:00","message":"Connected to signaler"}
+```
+
+On another peer, launch the VPN as well:
+
+```shell
+$ sudo weron vpn ip --community mycommunity --password mypassword --key mykey --ips 2001:db8::1/64,192.0.2.1/24
+{"level":"info","addr":"wss://weron.herokuapp.com/","time":"2022-05-06T22:22:30+02:00","message":"Connecting to signaler"}
+{"level":"info","id":"[\"2001:db8::b9/64\",\"192.0.2.186/24\"]","time":"2022-05-06T22:22:36+02:00","message":"Connected to signaler"}
+{"level":"info","id":"[\"2001:db8::6a/64\",\"192.0.2.107/24\"]","time":"2022-05-06T22:22:36+02:00","message":"Connected to peer"}
+```
+
+You can now communicate between the peers:
+
+```shell
+$ ping 2001:db8::b9
+PING 2001:db8::b9(2001:db8::b9) 56 data bytes
+64 bytes from 2001:db8::b9: icmp_seq=1 ttl=64 time=1.07 ms
+64 bytes from 2001:db8::b9: icmp_seq=2 ttl=64 time=1.36 ms
+64 bytes from 2001:db8::b9: icmp_seq=3 ttl=64 time=1.20 ms
+64 bytes from 2001:db8::b9: icmp_seq=4 ttl=64 time=1.10 ms
+^C
+--- 2001:db8::b9 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3002ms
+rtt min/avg/max/mdev = 1.066/1.180/1.361/0.114 ms
+```
+
+If you temporarly loose the network connection, the network topology changes etc. it will automatically reconnect. For more information and limitations on proprietary operating systems like macOS, see the [IP VPN reference](#layer-3-ip-overlay-networks). You can also embed the utility in your own application using it's [Go API](https://pkg.go.dev/github.com/pojntfx/weron@main/pkg/wrtcip).
+
+### 7. Create a Layer 2 (Ethernet) Overlay Network with `weron vpn ethernet`
+
+If you want more flexibility or work on non-IP networks, the ethernet VPN is a good choice. It works in a similar way to `n2n` or ZeroTier. Due to API restrictions, this VPN type [is not available on macOS](https://support.apple.com/guide/deployment/system-and-kernel-extensions-in-macos-depa5fb8376f/web); use [Asahi Linux](https://asahilinux.org/), a computer that respects your freedoms or the layer 3 (IP) VPN instead. To get started, launch the VPN on the first peer:
+
+```shell
+$ sudo weron vpn ethernet --community mycommunity --password mypassword --key mykey
+{"level":"info","addr":"wss://weron.herokuapp.com/","time":"2022-05-06T22:42:10+02:00","message":"Connecting to signaler"}
+{"level":"info","id":"fe:60:a5:8b:81:36","time":"2022-05-06T22:42:11+02:00","message":"Connected to signaler"}
+```
+
+If you want to add an IP address to the TAP interface, do so with `iproute2` or your OS tools:
+
+```shell
+$ sudo ip addr add 192.0.2.1/24 dev tap0
+$ sudo ip addr add 2001:db8::1/32 dev tap0
+```
+
+On another peer, launch the VPN as well:
+
+```shell
+$ sudo weron vpn ethernet --community mycommunity --password mypassword --key mykey
+{"level":"info","addr":"wss://weron.herokuapp.com/","time":"2022-05-06T22:52:56+02:00","message":"Connecting to signaler"}
+{"level":"info","id":"b2:ac:ae:b6:32:8c","time":"2022-05-06T22:52:57+02:00","message":"Connected to signaler"}
+{"level":"info","id":"fe:60:a5:8b:81:36","time":"2022-05-06T22:52:57+02:00","message":"Connected to peer"}
+```
+
+And add the IP addresses:
+
+```shell
+$ sudo ip addr add 192.0.2.2/24 dev tap0
+$ sudo ip addr add 2001:db8::2/32 dev tap0
+```
+
+You can now communicate between the peers:
+
+```shell
+$ ping 2001:db8::2
+PING 2001:db8::2(2001:db8::2) 56 data bytes
+64 bytes from 2001:db8::2: icmp_seq=1 ttl=64 time=1.20 ms
+64 bytes from 2001:db8::2: icmp_seq=2 ttl=64 time=1.14 ms
+64 bytes from 2001:db8::2: icmp_seq=3 ttl=64 time=1.24 ms
+^C
+--- 2001:db8::2 ping statistics ---
+3 packets transmitted, 3 received, 0% packet loss, time 2002ms
+rtt min/avg/max/mdev = 1.136/1.193/1.239/0.042 ms
+```
+
+If you temporarly loose the network connection, the network topology changes etc. it will automatically reconnect. You can also embed the utility in your own application using it's [Go API](https://pkg.go.dev/github.com/pojntfx/weron@main/pkg/wrtceth).
+
+### 8. Write your own protocol with `wrtcconn`
+
+It is almost trivial to build your own dstributed applications with weron, similarly to how [PeerJS](https://peerjs.com/) works. Here is the core logic behind a simple echo example:
+
+```go
+// ...
+for {
+	select {
+	case id := <-ids:
+		log.Println("Connected to signaler", id)
+	case peer := <-adapter.Accept():
+		log.Println("Connected to peer", peer.PeerID, "and channel", peer.ChannelID)
+
+		go func() {
+			defer func() {
+				log.Println("Disconnected from peer", peer.PeerID, "and channel", peer.ChannelID)
+			}()
+
+			reader := bufio.NewScanner(peer.Conn)
+			for reader.Scan() {
+				log.Printf("%s", reader.Bytes())
+			}
+		}()
+
+		go func() {
+			for {
+				if _, err := peer.Conn.Write([]byte("Hello!\n")); err != nil {
+					return
+				}
+
+				time.Sleep(time.Second)
+			}
+		}()
+	}
+}
+```
+
+You can either use the [minimal adapter](https://pkg.go.dev/github.com/pojntfx/weron@main/pkg/wrtcconn#Adapter) or the [named adapter](https://pkg.go.dev/github.com/pojntfx/weron@main/pkg/wrtcconn#NamedAdapter); the latter negotiates a username between the peers, while the former does not check for duplicates. For more information, check out the [Go API](https://pkg.go.dev/github.com/pojntfx/weron@main) and take a look at the other utilities and services in the package for examples.
+
+🚀 **That's it!** We hope you enjoy using weron.
 
 ## Reference
 
