Merge pull request #277 from gosuda/fix/all-path-multi-hop

refactor(discovery): unify route planning and optimize discovery lifecycle

Author: gosunuts

cmd/portal-loadtest/main.go

@@ -33,7 +33,6 @@ import (
 func main() {
 	clients := flag.Int("clients", 100, "number of synthetic clients")
 	relays := flag.Int("relays", 5, "number of synthetic relays")
-	multiHop := flag.Int("multi-hop", 0, "multi-hop depth (0 = priority; ≥2 = multi-hop)")
 	flag.Parse()
 
 	if *clients <= 0 {
@@ -44,31 +43,6 @@ func main() {
 		fmt.Fprintln(os.Stderr, "portal-loadtest: -relays must be > 0")
 		os.Exit(1)
 	}
-	// MultiHopDepth ≤ 1 causes SelectMultiHop to return nil (see mols.go).
-	// Reject 1 explicitly; 0 means priority mode.
-	if *multiHop == 1 {
-		fmt.Fprintln(os.Stderr, "portal-loadtest: -multi-hop=1 is not valid; use 0 for priority or ≥2 for multi-hop")
-		os.Exit(1)
-	}
-
-	mode := "priority"
-	if *multiHop >= 2 {
-		mode = "multihop"
-	}
-
-	// Build K synthetic relay states. We construct discovery.RelayState values
-	// directly (not via RelaySet.InsertAnnounced) because the public announce
-	// path requires real EVM-signed descriptors. Selection functions are called
-	// directly so that no signature gate runs.
-	//
-	// For priority mode: states without an observed descriptor (LastSeenAt zero)
-	// are accepted into the auto pool by SelectPriority; the expiry/protocol
-	// gates only fire when hasObservedDescriptor() is true.
-	//
-	// For multi-hop mode: SelectMultiHop requires hasObservedDescriptor, a
-	// non-expired ExpiresAt, and HasOverlayPeer()==true. We populate those
-	// fields with dummy-but-valid values using a far-future ExpiresAt and a
-	// syntactically valid WireGuard public key placeholder.
 	now := time.Now().UTC()
 	relayStates := make([]discovery.RelayState, *relays)
 	for i := range relayStates {
@@ -77,19 +51,10 @@ func main() {
 			Descriptor: types.RelayDescriptor{
 				APIHTTPSAddr: relayURL,
 			},
+			LastSeenAt: now,
 		}
-		if mode == "multihop" {
-			// Populate the fields required by SelectMultiHop's eligibility
-			// gates: hasObservedDescriptor (LastSeenAt non-zero), valid ExpiresAt,
-			// and HasOverlayPeer() = SupportsOverlay && WireGuardPublicKey != "" &&
-			// WireGuardPort in [1, 65535].
-			rs.LastSeenAt = now
-			rs.Descriptor.IssuedAt = now
-			rs.Descriptor.ExpiresAt = now.Add(24 * time.Hour)
-			rs.Descriptor.SupportsOverlay = true
-			rs.Descriptor.WireGuardPublicKey = fmt.Sprintf("synthetic-wg-key-%d", i+1)
-			rs.Descriptor.WireGuardPort = 51820
-		}
+		rs.Descriptor.IssuedAt = now
+		rs.Descriptor.ExpiresAt = now.Add(24 * time.Hour)
 		relayStates[i] = rs
 	}
 
@@ -98,16 +63,8 @@ func main() {
 	// would make all clients pick identically, falsely appearing as 100% imbalance.
 	picks := make(map[string]int, *relays) // relay URL → count of clients that picked it first
 	for i := 0; i < *clients; i++ {
-		cs := discovery.RouteState{
-			LocalAddress:  fmt.Sprintf("synthetic-client-%d", i),
-			MultiHopDepth: *multiHop,
-		}
-		var outputURLs []string
-		if mode == "multihop" {
-			outputURLs = discovery.SelectMultiHop(relayStates, cs)
-		} else {
-			outputURLs = discovery.SelectPriority(relayStates, cs)
-		}
+		localAddr := fmt.Sprintf("synthetic-client-%d", i)
+		outputURLs := discovery.RankRelayPool(relayStates, localAddr)
 		if len(outputURLs) == 0 {
 			// All relays were filtered; skip this client.
 			continue
@@ -139,7 +96,7 @@ func main() {
 	pval := igamc(float64(df)/2.0, chi2/2.0)
 
 	// Print results.
-	header := fmt.Sprintf("portal-loadtest: N=%d clients, K=%d relays, mode=%s", *clients, *relays, mode)
+	header := fmt.Sprintf("portal-loadtest: N=%d clients, K=%d relays, mode=mols", *clients, *relays)
 	fmt.Println(header)
 	fmt.Printf("%-45s %6s  %8s\n", "relay", "picks", "expected")
 	fmt.Println("---------------------------------------------------------------")

cmd/portal-tunnel/README.md

@@ -99,9 +99,9 @@ Common `portal expose` flags:
 --name               Public hostname prefix; auto-generated when omitted
 --relays             Additional relay API URLs, comma-separated
 --discovery          Include registry relays and relay discovery expansion
---max-active-relays  Maximum auto-selected relays
+--max-active-relays  Maximum auto-selected single-hop relays; multi-hop uses every eligible relay as an entry
 --multi-hop          Ordered multi-hop relay API URLs, comma-separated
---multi-hop-depth    Automatically select one multi-hop route with this hop count
+--multi-hop-depth    Automatically create this-depth multi-hop routes for every eligible entry relay
 --ban-mitm           Ban relay when the MITM self-probe detects termination
 --identity-path      Identity JSON file path; created automatically when missing
 --identity-json      Identity JSON payload; overrides --identity-path when set

cmd/portal-tunnel/main.go

@@ -97,8 +97,8 @@ func runExposeCommand(args []string) error {
 	utils.BoolFlagEnv(fs, &flags.udp, "udp", false, "Enable public UDP relay in addition to the default TCP relay", "UDP_ENABLED")
 	utils.StringFlagEnv(fs, &flags.udpAddr, "udp-addr", "", "Local UDP target address for relayed datagrams (host:port or port only); defaults to the target when --udp is enabled", "UDP_ADDR")
 	utils.BoolFlagEnv(fs, &flags.tcp, "tcp", false, "Request a dedicated TCP port on the relay for raw TCP services (no TLS; e.g., Minecraft, game servers)", "TCP_ENABLED")
-	utils.IntFlagEnv(fs, &flags.maxActiveRelays, "max-active-relays", 3, nil, "Maximum number of auto-selected relays to keep connected; explicit --relays are always included", "MAX_ACTIVE_RELAYS")
-	utils.IntFlagEnv(fs, &flags.multiHopDepth, "multi-hop-depth", 0, nil, "Automatically select one multi-hop route with this hop count; 0 or 1 disables multi-hop", "MULTI_HOP_DEPTH")
+	utils.IntFlagEnv(fs, &flags.maxActiveRelays, "max-active-relays", 3, nil, "Maximum auto-selected single-hop relays to keep connected; multi-hop uses every eligible relay as an entry", "MAX_ACTIVE_RELAYS")
+	utils.IntFlagEnv(fs, &flags.multiHopDepth, "multi-hop-depth", 0, nil, "Automatically create multi-hop routes at this hop count for every eligible entry relay; 0 or 1 disables multi-hop", "MULTI_HOP_DEPTH")
 	utils.StringFlag(fs, &flags.metricsAddr, "metrics-addr", "", "Optional address (host:port) to serve Prometheus /metrics. Empty = disabled.")
 
 	if err := utils.ParseFlagSet(fs, args, printExposeUsage); err != nil {

docs/src/routes/cli-reference/+page.md

@@ -87,9 +87,9 @@ not supported.
 |------|------|---------|-------------|
 | `--relays` | string | registry | Additional relay API URLs, comma-separated |
 | `--discovery` | bool | `true` | Include registry relays and relay discovery expansion |
-| `--max-active-relays` | int | `3` | Maximum auto-selected relays to keep connected; explicit relays are always included |
+| `--max-active-relays` | int | `3` | Maximum auto-selected single-hop relays to keep connected; multi-hop uses every eligible relay as an entry; explicit relays are always included |
 | `--multi-hop` | string | | Ordered multi-hop relay API URLs, comma-separated |
-| `--multi-hop-depth` | int | `0` | Automatically select one multi-hop route with this hop count; `0` or `1` disables multi-hop |
+| `--multi-hop-depth` | int | `0` | Automatically create this-depth multi-hop routes for every eligible entry relay; `0` or `1` disables multi-hop |
 | `--ban-mitm` | bool | `false` | Ban relay when the MITM self-probe detects TLS termination |
 | `--identity-path` | string | `identity.json` | Identity JSON file path; created automatically when missing |
 | `--identity-json` | string | | Identity JSON payload; overrides `--identity-path` contents and is persisted there when both are set |
@@ -167,7 +167,7 @@ Use an explicit multi-hop route:
 portal expose 3000 --multi-hop https://entry.example.com,https://exit.example.com
 ```
 
-Ask Portal to select one three-hop route:
+Ask Portal to create three-hop routes for every eligible entry relay:
 
 ```bash
 portal expose 3000 --multi-hop-depth 3

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

@@ -141,8 +141,8 @@ The `portal expose` subcommand accepts the following flags. Flags that read from
 | `--relays` | | string | _(registry)_ | Additional Portal relay server API URLs (comma-separated; scheme omitted defaults to https) |
 | `--discovery` | | bool | `true` | Include public registry relays and discover additional relay bootstraps |
 | `--multi-hop` | `MULTI_HOP` | string | | Ordered multi-hop relay API URLs, comma-separated |
-| `--multi-hop-depth` | `MULTI_HOP_DEPTH` | int | `0` | Automatically select one multi-hop route with this hop count; 0 or 1 disables multi-hop |
-| `--max-active-relays` | `MAX_ACTIVE_RELAYS` | int | `3` | Maximum auto-selected relays to keep connected; explicit relays are always included |
+| `--multi-hop-depth` | `MULTI_HOP_DEPTH` | int | `0` | Automatically create this-depth multi-hop routes for every eligible entry relay; 0 or 1 disables multi-hop |
+| `--max-active-relays` | `MAX_ACTIVE_RELAYS` | int | `3` | Maximum auto-selected single-hop relays to keep connected; multi-hop uses every eligible relay as an entry; explicit relays are always included |
 | `--ban-mitm` | `BAN_MITM` | bool | `false` | Ban relay when the MITM self-probe detects TLS termination |
 
 ### Identity
@@ -258,7 +258,7 @@ Tunnel fields mirror `portal expose` flags:
 | `relays` | string array | Explicit relay API URLs |
 | `discovery` | bool | Include registry and relay discovery expansion |
 | `multi_hop` | string array | Ordered multi-hop relay path |
-| `multi_hop_depth` | int | Automatically select one multi-hop route with this depth |
+| `multi_hop_depth` | int | Automatically create this-depth multi-hop routes for every eligible entry relay |
 | `identity_path` | string | Tunnel identity JSON file path. When omitted, one tunnel uses the platform default `identity.json`; multiple tunnels use `<state-dir>/<tunnel-id>/identity.json` |
 | `identity_json` | string | Identity JSON payload; overrides `identity_path` contents and is persisted there when both are set |
 | `udp`, `udp_addr`, `tcp` | bool/string | UDP and raw TCP relay options |

docs/src/routes/portal-agent/+page.md

@@ -168,7 +168,7 @@ tunnel or `Routes` for routed HTTP. Routes use this syntax:
 Each entry is `PATH=UPSTREAM [METHOD[,METHOD...]:USDC_AMOUNT]`. Fill `X402 Pay
 To` when any route has an amount, and set `X402 Testnet` to `true` for Sui
 testnet. The form also accepts explicit `Relays`,
-`Discovery`, and `Max Relays`; max relays caps auto-selected discovery relays
+`Discovery`, and `Max Relays`; max relays caps auto-selected single-hop discovery relays
 while explicit relays are still included.
 
 After creation, routed HTTP paths, x402 payment amounts, payment network, and
@@ -191,7 +191,7 @@ Common fields:
 | `http_routes` | Routed HTTP mappings; cannot be combined with `target` or `udp` |
 | `relays` | Explicit relay API URLs |
 | `discovery` | Include registry and relay discovery expansion |
-| `max_active_relays` | Maximum auto-selected relays kept connected |
+| `max_active_relays` | Maximum auto-selected single-hop relays kept connected; multi-hop uses every eligible relay as an entry |
 | `identity_path` | Tunnel identity JSON path |
 | `identity_json` | Identity JSON payload; persisted to `identity_path` when both are set |
 | `udp`, `udp_addr` | UDP transport settings |

portal/discovery/announce_test.go

@@ -67,8 +67,20 @@ func TestInsertAnnouncedRejectsUnsigned(t *testing.T) {
 	signing := mustSigningIdentity(t)
 	now := time.Now().UTC().Truncate(time.Microsecond)
 	desc := mustUnsignedDescriptor(t, signing, "https://relay-unsigned.example")
-	if err := set.InsertAnnounced(desc, now); err == nil {
-		t.Fatal("expected unsigned reject")
+	err := set.InsertAnnounced(desc, now)
+	if err == nil || err.Error() != "relay descriptor is not signed" {
+		t.Fatalf("InsertAnnounced() error = %v, want unsigned descriptor error", err)
+	}
+}
+
+func TestInsertAnnouncedRejectsExpired(t *testing.T) {
+	set := NewRelaySet(nil)
+	signing := mustSigningIdentity(t)
+	now := time.Now().UTC().Truncate(time.Microsecond)
+	desc := mustSignedDescriptor(t, signing, "https://relay-expired.example", now.Add(-DiscoveryDescriptorTTL-time.Second))
+	err := set.InsertAnnounced(desc, now)
+	if err == nil || err.Error() != "relay descriptor already expired" {
+		t.Fatalf("InsertAnnounced() error = %v, want expired descriptor error", err)
 	}
 }