Merge pull request #2 from VictorUvarov/vu/pion-interop

Interop testing with pion stun

Author: VictorUvarov

.github/workflows/ci.yml

@@ -12,26 +12,28 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
           cache: true
-      # `just lint` shells out to golangci-lint; install both up front.
       - uses: taiki-e/install-action@v2
         with:
-          tool: just,golangci-lint
+          tool: just
+      # `just lint` shells out to golangci-lint and adds GOPATH/bin to PATH,
+      # so install it there (go install is the method `just lint` recommends).
+      - run: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
       - run: just lint
 
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
           cache: true
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.x"
       - uses: taiki-e/install-action@v2
@@ -44,3 +46,17 @@ jobs:
       # stunc against stund over UDP/TCP/TLS/DTLS + the auth handshake
       # (openssl for cert generation ships on the runner).
       - run: just test-e2e
+
+  interop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: just
+      # Foreign implementation on the wire: pion/stun against our stund.
+      - run: just interop

.gitignore

@@ -1,6 +1,7 @@
 # build artifacts
 /bin/
 /stund
+/test/interop/pion/stun-interop-pion
 
 # generated dev TLS certs (just cert)
 /dev/

internal/stunclient/client_test.go

@@ -138,8 +138,10 @@ func TestAuth(t *testing.T) {
 		t.Fatal(err)
 	}
 	server.Credentials = auth
-	addr := startUDP(t)
+	// Reset only after startUDP's cleanup has stopped the server goroutine —
+	// cleanups run LIFO, so register this one first (it runs last).
 	t.Cleanup(func() { server.Credentials = nil })
+	addr := startUDP(t)
 
 	t.Run("good credentials", func(t *testing.T) {
 		c, err := DialUDP(addr, Config{Username: "alice", Password: "s3cret"})
@@ -184,8 +186,9 @@ func TestAuth(t *testing.T) {
 func TestRedirect(t *testing.T) {
 	target := netip.MustParseAddrPort("192.0.2.7:3478")
 	server.Alternate = &server.AlternateServer{V4: target, Domain: "stun.example.org"}
-	addr := startUDP(t)
+	// Register before startUDP so this reset runs after the server stops (LIFO).
 	t.Cleanup(func() { server.Alternate = nil })
+	addr := startUDP(t)
 
 	c, err := DialUDP(addr, Config{})
 	if err != nil {

justfile

@@ -166,7 +166,24 @@ test-e2e: build cert
     bin/stunc -user alice:s3cret {{auth-addr}}
     echo "e2e ok"
 
+# ── Third-party interop ────────────────────────────────────────────────────
+# Validate the wire against an implementation we didn't write — the class of
+# bug a stunc-against-stund e2e can't catch, since both sides share our code.
+
+# Foreign Go client (pion/stun) sends a Binding request to our stund.
+interop: build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    {{bin}} -addr {{addr}} & pid=$!
+    trap 'kill $pid 2>/dev/null || true' EXIT
+    sleep 0.3
+    go -C test/interop/pion run . {{addr}}
+
 # ── everything ────────────────────────────────────────────────────────────
 
-# Full check: lint, Go tests, and the integration tests (Python + Go e2e).
-check: lint test test-py test-e2e
+# Full check: lint, Go tests (race), and the integration tests (Python + Go e2e).
+# Uses test-race to match CI — a plain `go test` won't surface data races.
+check: lint test-race test-py test-e2e
+
+# Everything in `check` plus third-party (pion) interop.
+check-all: check interop

test/interop/pion/go.mod

@@ -0,0 +1,14 @@
+module stun-interop-pion
+
+go 1.26.4
+
+require github.com/pion/stun/v3 v3.1.6
+
+require (
+	github.com/pion/dtls/v3 v3.1.4 // indirect
+	github.com/pion/logging v0.2.4 // indirect
+	github.com/pion/transport/v4 v4.0.2 // indirect
+	github.com/wlynxg/anet v0.0.5 // indirect
+	golang.org/x/crypto v0.48.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+)

test/interop/pion/go.sum

@@ -0,0 +1,24 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pion/dtls/v3 v3.1.4 h1:QhvtMflMfu9Kf0RcDC5BJBle4caPskByrKQR6uuYqpY=
+github.com/pion/dtls/v3 v3.1.4/go.mod h1:cr/qotLISUw/9C1m83ZPNZtj9WnXkYLpfCptPqbkInc=
+github.com/pion/logging v0.2.4 h1:tTew+7cmQ+Mc1pTBLKH2puKsOvhm32dROumOZ655zB8=
+github.com/pion/logging v0.2.4/go.mod h1:DffhXTKYdNZU+KtJ5pyQDjvOAh/GsNSyv1lbkFbe3so=
+github.com/pion/stun/v3 v3.1.6 h1:WnhsD0eHCiwCfKNkVx0VJJwr2Y3eV4Ueih3KJ+dfZy8=
+github.com/pion/stun/v3 v3.1.6/go.mod h1:zRUghXSQU32Lx5orJsz3uYMkIihweXb3mu5gIns02fs=
+github.com/pion/transport/v4 v4.0.2 h1:ifYlPqNwsy6aKQ9y8yzxXlHae5431ZrH2avkD/Rn6Tk=
+github.com/pion/transport/v4 v4.0.2/go.mod h1:06hFI+jCFcok2X2MekVufNZ/uzNZXivGBPfviSVcjgM=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/wlynxg/anet v0.0.5 h1:J3VJGi1gvo0JwZ/P1/Yc/8p63SoW98B5dHkYDmpgvvU=
+github.com/wlynxg/anet v0.0.5/go.mod h1:eay5PRQr7fIVAMbTbchTnO9gG65Hg/uYGdc7mguHxoA=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
+golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
+golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

test/interop/pion/main.go

@@ -0,0 +1,54 @@
+// Command pion-interop sends a STUN Binding request to a running stund using
+// pion/stun — a wholly independent Go implementation — and validates the
+// XOR-MAPPED-ADDRESS it gets back. Sharing no code with our server, it catches
+// the class of wire-format bug that a stunc-against-stund e2e never can.
+//
+// It lives in its own module so pion/stun stays out of the main go.mod.
+//
+//	go -C test/interop/pion run . 127.0.0.1:3478
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/pion/stun/v3"
+)
+
+func main() {
+	addr := "127.0.0.1:3478"
+	if len(os.Args) > 1 {
+		addr = os.Args[1]
+	}
+
+	c, err := stun.Dial("udp", addr)
+	if err != nil {
+		fail("dial", err)
+	}
+	defer c.Close() //nolint:errcheck // best-effort on a throwaway client
+
+	var (
+		xorAddr stun.XORMappedAddress
+		inner   error
+	)
+	req := stun.MustBuild(stun.TransactionID, stun.BindingRequest)
+	if err := c.Do(req, func(res stun.Event) {
+		if res.Error != nil {
+			inner = res.Error
+			return
+		}
+		inner = xorAddr.GetFrom(res.Message)
+	}); err != nil {
+		fail("binding", err)
+	}
+	if inner != nil {
+		fail("response", inner)
+	}
+
+	fmt.Printf("pion interop OK: XOR-MAPPED-ADDRESS %s\n", xorAddr)
+}
+
+func fail(stage string, err error) {
+	fmt.Fprintf(os.Stderr, "pion-interop: %s: %v\n", stage, err)
+	os.Exit(1)
+}