refact: simplify bootstrap logic

Author: gosunuts

cmd/demo-app/main.go

@@ -34,8 +34,8 @@ func main() {
 	log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stdout, TimeFormat: time.RFC3339})
 	logger := log.With().Str("component", "demo-app").Logger()
 
-	flag.StringVar(&flagRelayURLs, "relays", "https://localhost:4017", "additional relay API URLs (comma-separated; scheme omitted defaults to https; appended to registry.json defaults unless --default-relays=false is set) [env: RELAYS]")
-	flag.BoolVar(&flagDefaultRelays, "default-relays", utils.ParseBoolEnv("DEFAULT_RELAYS", true), "include repository registry.json default relays [env: DEFAULT_RELAYS]")
+	flag.StringVar(&flagRelayURLs, "relays", "https://localhost:4017", "additional relay API URLs (comma-separated; scheme omitted defaults to https; merged with public registry relays unless --default-relays=false is set) [env: RELAYS]")
+	flag.BoolVar(&flagDefaultRelays, "default-relays", utils.ParseBoolEnv("DEFAULT_RELAYS", true), "include public registry relays [env: DEFAULT_RELAYS]")
 	flag.StringVar(&flagAddr, "addr", "127.0.0.1:8092", "local demo HTTP listen address (host:port or URL; disable if empty)")
 	flag.StringVar(&flagName, "name", "demo-app", "public hostname prefix (single DNS label)")
 	flag.StringVar(&flagDesc, "description", "Portal demo connectivity app", "lease description")
@@ -58,20 +58,17 @@ func runDemo() error {
 	defer stop()
 
 	relayURLs := utils.SplitCSV(flagRelayURLs)
-	if flagDefaultRelays {
-		relayURLs = sdk.WithDefaultRelayURLs(ctx, "", relayURLs...)
-	}
-	relayURLs, err := utils.NormalizeRelayURLs(relayURLs)
-	if err != nil {
-		return fmt.Errorf("resolve relay urls: %w", err)
-	}
-
-	exposure, err := sdk.Expose(ctx, relayURLs, flagName, false, types.LeaseMetadata{
-		Description: flagDesc,
-		Tags:        utils.SplitCSV(flagTags),
-		Owner:       flagOwner,
-		Thumbnail:   flagThumbnail,
-		Hide:        flagHide,
+	exposure, err := sdk.Expose(ctx, sdk.ExposeConfig{
+		RelayURLs:           relayURLs,
+		DefaultRelayEnabled: flagDefaultRelays,
+		Name:                flagName,
+		Metadata: types.LeaseMetadata{
+			Description: flagDesc,
+			Tags:        utils.SplitCSV(flagTags),
+			Owner:       flagOwner,
+			Thumbnail:   flagThumbnail,
+			Hide:        flagHide,
+		},
 	})
 	if err != nil {
 		return fmt.Errorf("exposure listen error: %w", err)

cmd/demo-udp/main.go

@@ -36,8 +36,8 @@ func main() {
 	log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stdout, TimeFormat: time.RFC3339})
 	logger := log.With().Str("component", "demo-udp").Logger()
 
-	flag.StringVar(&flagRelayURLs, "relays", "https://localhost:4017", "additional relay API URLs (comma-separated; scheme omitted defaults to https; appended to registry.json defaults unless --default-relays=false is set) [env: RELAYS]")
-	flag.BoolVar(&flagDefaultRelays, "default-relays", utils.ParseBoolEnv("DEFAULT_RELAYS", false), "include repository registry.json default relays [env: DEFAULT_RELAYS]")
+	flag.StringVar(&flagRelayURLs, "relays", "https://localhost:4017", "additional relay API URLs (comma-separated; scheme omitted defaults to https; merged with public registry relays unless --default-relays=false is set) [env: RELAYS]")
+	flag.BoolVar(&flagDefaultRelays, "default-relays", utils.ParseBoolEnv("DEFAULT_RELAYS", false), "include public registry relays [env: DEFAULT_RELAYS]")
 	flag.StringVar(&flagName, "name", "demo-udp", "public hostname prefix (single DNS label)")
 	flag.StringVar(&flagDesc, "description", "Portal demo UDP echo service", "lease description")
 	flag.StringVar(&flagTags, "tags", "demo,udp,echo", "comma-separated lease tags")
@@ -59,20 +59,18 @@ func runDemoUDP() error {
 	defer stop()
 
 	relayURLs := utils.SplitCSV(flagRelayURLs)
-	if flagDefaultRelays {
-		relayURLs = sdk.WithDefaultRelayURLs(ctx, "", relayURLs...)
-	}
-	relayURLs, err := utils.NormalizeRelayURLs(relayURLs)
-	if err != nil {
-		return fmt.Errorf("resolve relay urls: %w", err)
-	}
-
-	exposure, err := sdk.Expose(ctx, relayURLs, flagName, true, types.LeaseMetadata{
-		Description: flagDesc,
-		Tags:        utils.SplitCSV(flagTags),
-		Owner:       flagOwner,
-		Thumbnail:   flagThumbnail,
-		Hide:        flagHide,
+	exposure, err := sdk.Expose(ctx, sdk.ExposeConfig{
+		RelayURLs:           relayURLs,
+		DefaultRelayEnabled: flagDefaultRelays,
+		Name:                flagName,
+		UDPEnabled:          true,
+		Metadata: types.LeaseMetadata{
+			Description: flagDesc,
+			Tags:        utils.SplitCSV(flagTags),
+			Owner:       flagOwner,
+			Thumbnail:   flagThumbnail,
+			Hide:        flagHide,
+		},
 	})
 	if err != nil {
 		return fmt.Errorf("exposure listen error: %w", err)

cmd/portal-tunnel/README.md

@@ -42,7 +42,7 @@ Flags:
 
 ```text
 --relays          Portal relay API URLs (comma-separated, https only)
---default-relays  Include repository registry.json public relays
+--default-relays  Include public registry relays
 --name            Public hostname prefix (single DNS label); auto-generated when omitted
 --description     Service description metadata
 --tags            Service tags metadata (comma-separated)
@@ -78,7 +78,7 @@ Legacy execution compatibility has been removed:
 - The tunnel consumes one aggregate SDK listener, so the CLI no longer manages per-relay listener loops itself.
 - Relay startup and reconnect failures are retried independently in the background. A relay that is down does not stop healthy relays from continuing to serve traffic.
 - The tunnel starts once relay URLs pass local validation. Remote compatibility checks, lease registration, and reconnects continue in the background until each relay becomes ready.
-- The configured relay list is either `registry.json + installed/configured relay URLs` or, with `--default-relays=false`, just the explicit relay URLs. Published public URLs appear only for relays that have registered successfully.
+- The configured relay list is either `public registry + installed/configured relay URLs` or, with `--default-relays=false`, just the explicit relay URLs. Published public URLs appear only for relays that have registered successfully.
 - SDK callers that do not set `ListenerConfig.RetryCount` use infinite retry semantics for each relay.
 - Tenant TLS is provisioned automatically through the relay keyless signer. The SDK fetches the relay certificate chain and uses `/v1/sign` for remote signing.
 - When the local service is unreachable, the tunnel returns an HTTP 503 page.

cmd/portal-tunnel/main.go

@@ -168,14 +168,6 @@ func runExposeCommand(args []string) error {
 		relayInputs = []string{explicitRelays}
 	}
 
-	relayURLs, err := resolveRelayURLs(ctx, "", relayInputs, defaultRelays)
-	if err != nil {
-		return fmt.Errorf("resolve relay urls: %w", err)
-	}
-	if len(relayURLs) == 0 {
-		return errors.New("no relay URLs configured; run the installer first or pass --relays")
-	}
-
 	previousOwnerPrivateKey := cfg.OwnerPrivateKey
 	if strings.TrimSpace(privateKey) != "" {
 		cfg.OwnerPrivateKey = privateKey
@@ -185,11 +177,12 @@ func runExposeCommand(args []string) error {
 		ownerPrivateKey = &cfg.OwnerPrivateKey
 	}
 
-	exposure, err := sdk.ExposeWithConfig(ctx, sdk.ExposeConfig{
-		RelayURLs:  relayURLs,
-		Name:       name,
-		UDPEnabled: udp,
-		Discovery:  discoveryEnabled,
+	exposure, err := sdk.Expose(ctx, sdk.ExposeConfig{
+		RelayURLs:           relayInputs,
+		DefaultRelayEnabled: defaultRelays,
+		Name:                name,
+		UDPEnabled:          udp,
+		Discovery:           discoveryEnabled,
 		Metadata: types.LeaseMetadata{
 			Description: desc,
 			Tags:        utils.SplitCSV(tags),
@@ -261,7 +254,7 @@ func runListCommand(args []string) error {
 		relayInputs = []string{explicitRelays}
 	}
 
-	relayURLs, err := resolveRelayURLs(ctx, "", relayInputs, defaultRelays)
+	relayURLs, err := sdk.ResolveRelayURLs(ctx, relayInputs, defaultRelays)
 	if err != nil {
 		return fmt.Errorf("resolve relay urls: %w", err)
 	}
@@ -366,17 +359,6 @@ func runTunnel(
 	return errors.Join(waitErr, udpErr, closeErr)
 }
 
-func resolveRelayURLs(ctx context.Context, registryURL string, inputs []string, includeDefaultRelays bool) ([]string, error) {
-	if includeDefaultRelays {
-		relayURLs := sdk.WithDefaultRelayURLs(ctx, registryURL, inputs...)
-		if len(relayURLs) == 0 {
-			return nil, nil
-		}
-		return relayURLs, nil
-	}
-	return utils.NormalizeRelayURLs(inputs)
-}
-
 var exposeNameOpeners = []string{
 	"arcade", "bouncy", "bravo", "bubble", "candy", "cosmic", "dapper", "electric",
 	"fancy", "fizzy", "flashy", "fuzzy", "gentle", "glitter", "golden", "happy",

docs/architecture.md

@@ -115,12 +115,13 @@ That distinction matters because `/sdk/connect` stops being ordinary HTTP once h
 
 ### SDK (`sdk/`)
 
-- `WithDefaultRelayURLs`: fetches the default Portal relay list from the repository-root `registry.json`, appends explicit relay inputs, and normalizes the combined list
+- `ExposeConfig.DefaultRelayEnabled`: when true, `Expose` fetches the default Portal relay registry, merges it with explicit relay inputs, and normalizes the result
 - Entry points can opt out of registry defaults and call `utils.NormalizeRelayURLs` directly when they need explicit relay inputs only
 - `Listener`: validates one relay URL locally, then starts relay compatibility checks, lease registration, reverse session maintenance, and lease renewal in the background until ready
 - `api_client.go`: internal relay client for control-plane requests, reverse session dialing, and internal QUIC tunnel setup
 - `ListenerConfig.RetryCount <= 0` means retry forever; positive values close the listener after the retry budget is exhausted
-- Default app flow is `WithDefaultRelayURLs -> NewListener -> PublicURL -> http.Server.Serve(listener)` or `WithDefaultRelayURLs -> Expose -> PublicURLs -> http.Server.Serve(exposure)`, with an opt-out path for explicit relay inputs only
+- `NewListener` callers provide explicit normalized relay URLs
+- Default exposure flow is `Expose{DefaultRelayEnabled: true} -> PublicURLs -> http.Server.Serve(exposure)`, with an opt-out path for explicit relay inputs only
 - `expose.go`: optional `RunHTTP` helper for serving one handler on both a local HTTP port and the relay listener
 - `Expose` keeps one listener per configured relay URL. Relay startup and reconnect failures are retried independently per relay, and successful relays remain available while failed relays keep retrying in the background
 - `Exposure.RelayURLs()` returns the configured normalized relay URLs, while `Exposure.PublicURLs()` returns only relays that are currently registered and ready

portal/api_server.go

@@ -80,7 +80,7 @@ func (s *Server) apiHandler(base *http.ServeMux, keylessSignerHandler http.Handl
 				base.ServeHTTP(w, r)
 				return
 			}
-			s.discovery.ServeHTTP(w, r)
+			discovery.ServeHTTP(w, r, []string{s.cfg.PortalURL}, s.discoveryBootstrapsSnapshot(), s.discover)
 		case types.PathV1Sign:
 			if keylessSignerHandler == nil {
 				http.NotFound(w, r)
@@ -517,17 +517,17 @@ func (s *Server) registerLease(req types.RegisterRequest, clientIP string) (type
 		record.Close()
 		return types.RegisterResponse{}, err
 	}
-	if s.discovery != nil {
-		if err := s.discovery.MergeBootstraps(bootstraps); err != nil {
+	if s.DiscoveryEnabled() {
+		if err := s.mergeDiscoveryBootstraps(bootstraps); err != nil {
 			record.Close()
 			_, _ = s.registry.Unregister(record.ID, record.ReverseToken)
 			return types.RegisterResponse{}, err
 		}
 	}
 
 	responseBootstraps := append([]string(nil), s.cfg.Bootstraps...)
-	if s.discovery != nil {
-		responseBootstraps = s.discovery.Bootstraps()
+	if s.DiscoveryEnabled() {
+		responseBootstraps = s.discoveryBootstrapsSnapshot()
 	} else {
 		responseBootstraps, err = utils.NormalizeRelayURLs(append(responseBootstraps, record.Bootstraps...))
 		if err != nil {