Merge pull request #258 from gosuda/local-multihop-harness

Add local multi-hop relay test harness

Author: gosunuts

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install fmt vet lint lint-auto test vuln tidy all run build build-frontend build-docs build-tunnel build-server clean load-test
+.PHONY: help install fmt vet lint lint-auto test test-local-multihop vuln tidy all run build build-frontend build-docs build-tunnel build-server clean load-test
 
 .DEFAULT_GOAL := help
 
@@ -15,6 +15,8 @@ help:
 	@echo "  make install           - Install Go developer tools used by this repo"
 	@echo "  make fmt               - Apply gofmt/goimports"
 	@echo "  make lint-auto         - Run autofix lint/format pipeline"
+	@echo "  make test              - Run Go tests, including the local multi-hop harness"
+	@echo "  make test-local-multihop - Run the focused local multi-hop relay harness"
 	@echo "  make build             - Build everything (frontend, tunnel, server)"
 	@echo "  make build-frontend    - Build React frontend (Tailwind CSS 4)"
 	@echo "  make build-docs        - Build documentation site (SvelteKit)"
@@ -46,6 +48,9 @@ lint-auto:
 test:
 	go test -v -coverprofile=coverage.out $(GO_PACKAGES)
 
+test-local-multihop:
+	go test -v ./portal -run 'TestLocalCluster'
+
 vuln:
 	govulncheck $(GO_PACKAGES)
 

docs/src/routes/architecture/+page.md

@@ -300,6 +300,14 @@ Result: raw public UDP exposure with an internal QUIC datagram backhaul. UDP and
 - The overlay peer API is plain HTTP on the WireGuard network, not public Internet HTTP. It serves the same discovery payload shape used by public `/discovery`.
 - Overlay failure affects inter-relay discovery, mesh synchronization, and multi-hop relay forwarding. Direct tenant TLS routing, keyless TLS, register/renew/connect, and public UDP ingress do not depend on the WireGuard transport path.
 
+### Local multi-hop test harness
+
+`portal/multihop_local_test.go` verifies the multi-hop relay path inside one `go test` process. It starts local relay servers on `127.0.0.1:0`, seeds signed local discovery descriptors, and uses test fakes only for the WireGuard transport layer.
+
+Use `make test-local-multihop` for the focused local harness. The same tests are also included in `make test` through the `./portal/...` package set. Use `go test ./portal ./sdk` when checking the narrower portal and SDK interaction without the full repository test suite.
+
+The harness exercises SDK expose/register logic, `/sdk/hop`, `RelaySet`, signed descriptors, route registration, SNI ingress, hop token matching, and `bridgeLeaseConn`. It intentionally excludes public DNS, ACME provider side effects, public registry bootstrap, and real WireGuard devices. `localRelaySpec` provides relay-level server and descriptor mutation hooks for future policy tests, and the fake overlay records synced peers so fake hop streams only open after the `/sdk/hop` overlay sync path has run.
+
 ## Control Plane Flow
 
 ### 1. Register

portal/api_server.go

@@ -332,7 +332,7 @@ func (s *Server) handleRegisterChallenge(w http.ResponseWriter, r *http.Request)
 		Path:   types.PathSDKRegister,
 	}).String()
 
-	if strings.TrimSpace(req.HopToken) != "" && s.overlay == nil {
+	if strings.TrimSpace(req.HopToken) != "" && !s.hasHopTransport() {
 		utils.WriteAPIError(w, http.StatusServiceUnavailable, types.APIErrorCodeFeatureUnavailable, errFeatureUnavailable.Error())
 		return
 	}
@@ -406,7 +406,7 @@ func (s *Server) handleHop(w http.ResponseWriter, r *http.Request) {
 		utils.MethodNotAllowedError().Write(w)
 		return
 	}
-	if s.overlay == nil || s.relaySet == nil {
+	if !s.hasHopTransport() || !s.hasOverlayRuntime() || s.relaySet == nil {
 		utils.WriteAPIError(w, http.StatusServiceUnavailable, types.APIErrorCodeFeatureUnavailable, errFeatureUnavailable.Error())
 		return
 	}
@@ -459,7 +459,7 @@ func (s *Server) handleHop(w http.ResponseWriter, r *http.Request) {
 		utils.InvalidRequestError(fmt.Errorf("forward relay: %w", err)).Write(w)
 		return
 	}
-	if err := s.overlay.Sync(s.relaySet.OverlayPeerStates()); err != nil {
+	if err := s.syncOverlayPeers(s.relaySet.OverlayPeerStates()); err != nil {
 		utils.WriteAPIError(w, http.StatusInternalServerError, types.APIErrorCodeInternal, err.Error())
 		return
 	}

portal/discovery/refresher.go

@@ -161,10 +161,26 @@ func (r *Refresher) refreshHTTPS(ctx context.Context) error {
 			}
 			continue
 		}
+		client := r.httpClient
+		var closeClient func()
+		if utils.IsLocalRelayHost(baseURL.Hostname()) {
+			_, localClient, transport, err := utils.NewHTTPTLSClient(ctx, baseURL, defaultRequestTimeout)
+			if err != nil {
+				if recoveryFailures > 0 {
+					r.logDiscoveryFailure(relayURL, relayURL, recoveryFailures, err)
+				}
+				continue
+			}
+			client = localClient
+			closeClient = transport.CloseIdleConnections
+		}
 
 		startedAt := time.Now()
 		var resp types.DiscoveryResponse
-		if err := utils.HTTPDoAPIPath(ctx, r.httpClient, baseURL, http.MethodGet, types.PathDiscovery, nil, nil, &resp); err != nil {
+		if err := utils.HTTPDoAPIPath(ctx, client, baseURL, http.MethodGet, types.PathDiscovery, nil, nil, &resp); err != nil {
+			if closeClient != nil {
+				closeClient()
+			}
 			if ctx.Err() != nil {
 				return ctx.Err()
 			}
@@ -173,6 +189,9 @@ func (r *Refresher) refreshHTTPS(ctx context.Context) error {
 			}
 			continue
 		}
+		if closeClient != nil {
+			closeClient()
+		}
 		measuredAt := time.Now().UTC()
 
 		if _, err := r.relaySet.ApplyRelayDiscoveryResponse(relayURL, resp, measuredAt); err != nil {

portal/lease.go

@@ -438,6 +438,7 @@ func (r *leaseRegistry) Renew(req types.RenewRequest, clientIP string) (types.Re
 	if strings.TrimSpace(reportedIP) != "" {
 		record.ReportedIP = reportedIP
 	}
+	record.Metadata = req.Metadata.Copy()
 	r.policy.IPFilter().RegisterIdentityIP(leaseKey, clientIP)
 	identity := record.Identity
 	r.mu.Unlock()