feat(relay): expose circuit-v2 relay-service resource knobs (#1031)

* feat(relay): expose circuit-v2 relay-service resource knobs

EdgeVPN previously never enabled libp2p's circuit-v2 relay *service*
(only the relay *client* via DefaultEnableRelay). That meant publicly
reachable cluster peers refused to carry relayed traffic for NAT-traversed
peers that failed to DCUtR hole-punch (QEMU slirp, CGNAT, double-NAT).

This change unconditionally enables libp2p.EnableRelayService and exposes
the relayv2.Resources tunables as CLI flags / env vars so operators can
widen the small libp2p defaults (128KB/2min/16 circuits/2048 buffer) when
they need cluster peers to relay bulk transfers (e.g. model files for
distributed inference):

  --relay-service-max-data         EDGEVPN_RELAY_MAX_DATA          1 GiB
  --relay-service-max-duration     EDGEVPN_RELAY_MAX_DURATION      30m
  --relay-service-max-circuits     EDGEVPN_RELAY_MAX_CIRCUITS      64
  --relay-service-reservation-ttl  EDGEVPN_RELAY_RESERVATION_TTL   1h
  --relay-service-buffer-size      EDGEVPN_RELAY_BUFFER_SIZE       64 KiB

* feat(relay): add --relay-service flag to disable the relay-service offering

When operators don't want a node to act as a circuit-v2 relay for
others (resource-constrained edge nodes, untrusted environments,
deployments where only a few designated nodes should relay), set
--relay-service=false / EDGEVPN_RELAY_SERVICE=false / programmatic
Connection.RelayService.Disabled=true. The node still runs as a relay
client (can reserve slots on OTHER relays via AutoRelay) — only the
incoming-reservation service is skipped.

The struct field is named Disabled (not Enabled) so the Go zero value
preserves the prior "always offer relay service" behaviour for
programmatic callers constructing &config.Config{} directly.

Adds TestRelayServiceDisabledSkipsLibp2pOption which asserts that
ToOpts produces strictly fewer node options with Disabled=true (the
libp2p.EnableRelayService wrapper disappears) and that both variants
still produce a constructible Node.

A follow-up will add a NetworkOnly mode (relay-service ACL gated on
ledger membership) so cluster relays don't service random internet
peers that found us via DHT.

Assisted-by: Claude:claude-opus-4-7

Author: mudler

cmd/util.go

@@ -248,6 +248,42 @@ var CommonFlags []cli.Flag = []cli.Flag{
 		Usage:   "List of autorelay static peers to use",
 		EnvVars: []string{"EDGEVPNAUTORELAYPEERS"},
 	},
+	&cli.BoolFlag{
+		Name:    "relay-service",
+		Usage:   "Offer the circuit-v2 relay service to cluster peers (i.e. let other peers reserve a slot on this node and route relayed traffic through us). Disabling does NOT prevent this node from USING other relays as a client via AutoRelay — set this to false on resource-constrained nodes or nodes that should not act as relays.",
+		EnvVars: []string{"EDGEVPN_RELAY_SERVICE"},
+		Value:   true,
+	},
+	&cli.Int64Flag{
+		Name:    "relay-service-max-data",
+		Usage:   "Bytes (per direction) a relayed connection may carry before reset. Higher values let cluster peers carry larger relayed transfers (e.g. model files for distributed inference) at the cost of a larger memory footprint per relay client. Set lower for resource-constrained deployments.",
+		EnvVars: []string{"EDGEVPN_RELAY_MAX_DATA"},
+		Value:   int64(config.DefaultRelayServiceMaxData),
+	},
+	&cli.StringFlag{
+		Name:    "relay-service-max-duration",
+		Usage:   "Maximum lifetime of a single relayed connection (Go duration). Higher values let cluster peers carry longer-running relayed transfers at the cost of holding circuits open. Set lower for resource-constrained deployments.",
+		EnvVars: []string{"EDGEVPN_RELAY_MAX_DURATION"},
+		Value:   config.DefaultRelayServiceMaxDuration.String(),
+	},
+	&cli.IntFlag{
+		Name:    "relay-service-max-circuits",
+		Usage:   "Maximum number of concurrent relay circuits per peer. Higher values let more peers tunnel through this node simultaneously at the cost of a larger memory footprint. Set lower for resource-constrained deployments.",
+		EnvVars: []string{"EDGEVPN_RELAY_MAX_CIRCUITS"},
+		Value:   config.DefaultRelayServiceMaxCircuits,
+	},
+	&cli.StringFlag{
+		Name:    "relay-service-reservation-ttl",
+		Usage:   "Time-to-live of a relay reservation (Go duration). Higher values reduce reservation churn for stable cluster peers; lower values free relay slots faster.",
+		EnvVars: []string{"EDGEVPN_RELAY_RESERVATION_TTL"},
+		Value:   config.DefaultRelayServiceReservationTTL.String(),
+	},
+	&cli.IntFlag{
+		Name:    "relay-service-buffer-size",
+		Usage:   "Per-circuit relayed connection buffer size in bytes. Higher values improve throughput of large relayed transfers at the cost of memory per relay client. Set lower for resource-constrained deployments.",
+		EnvVars: []string{"EDGEVPN_RELAY_BUFFER_SIZE"},
+		Value:   config.DefaultRelayServiceBufferSize,
+	},
 	&cli.StringSliceFlag{
 		Name:    "blacklist",
 		Usage:   "List of peers/cidr to gate",
@@ -409,6 +445,15 @@ func ConfigFromContext(c *cli.Context) *config.Config {
 		autorelayInterval = 0
 	}
 
+	relayMaxDuration, err := time.ParseDuration(c.String("relay-service-max-duration"))
+	if err != nil {
+		relayMaxDuration = 0
+	}
+	relayReservationTTL, err := time.ParseDuration(c.String("relay-service-reservation-ttl"))
+	if err != nil {
+		relayReservationTTL = 0
+	}
+
 	// Authproviders are supposed to be passed as a json object
 	pa := c.String("peergate-auth")
 	d := map[string]map[string]interface{}{}
@@ -461,6 +506,14 @@ func ConfigFromContext(c *cli.Context) *config.Config {
 			OnlyStaticRelays:           c.Bool("autorelay-static-only"),
 			HighWater:                  c.Int("connection-high-water"),
 			LowWater:                   c.Int("connection-low-water"),
+			RelayService: config.RelayService{
+				Disabled:       !c.Bool("relay-service"),
+				MaxData:        c.Int64("relay-service-max-data"),
+				MaxDuration:    relayMaxDuration,
+				MaxCircuits:    c.Int("relay-service-max-circuits"),
+				ReservationTTL: relayReservationTTL,
+				BufferSize:     c.Int("relay-service-buffer-size"),
+			},
 		},
 		Limit: config.ResourceLimit{
 			Enable:      c.Bool("limit-enable"),

pkg/config/config.go

@@ -29,6 +29,7 @@ import (
 	"github.com/libp2p/go-libp2p/p2p/host/autorelay"
 	rcmgr "github.com/libp2p/go-libp2p/p2p/host/resource-manager"
 	connmanager "github.com/libp2p/go-libp2p/p2p/net/connmgr"
+	relayv2 "github.com/libp2p/go-libp2p/p2p/protocol/circuitv2/relay"
 	"github.com/mudler/edgevpn/pkg/blockchain"
 	"github.com/mudler/edgevpn/pkg/crypto"
 	"github.com/mudler/edgevpn/pkg/discovery"
@@ -122,6 +123,43 @@ type Connection struct {
 
 	LowWater  int
 	HighWater int
+
+	// RelayService configures circuit-v2 relay-service resource limits
+	// applied when this node acts as a relay for other peers.
+	RelayService RelayService
+}
+
+// RelayService holds the circuit-v2 relay-service resource limits
+// applied to this node when it serves as a relay for other peers.
+//
+// Higher values let cluster peers carry larger relayed transfers
+// (e.g. model files for distributed inference) at the cost of a
+// larger memory footprint per relay client. Lower values are safer
+// for resource-constrained deployments.
+type RelayService struct {
+	// Disabled, when true, turns off the circuit-v2 relay *service* on
+	// this node so it no longer accepts reservations from other peers.
+	// The relay *client* (the ability to reserve slots on OTHER relays
+	// via AutoRelay) stays on regardless — turning the service off does
+	// not prevent this node from using third-party relays to traverse
+	// its own NAT. Default (zero value) is false → service is offered,
+	// preserving back-compat for programmatic callers.
+	Disabled bool
+	// MaxData is the byte limit (per direction) for a single relayed
+	// connection before it is reset. libp2p default is 128 KiB.
+	MaxData int64
+	// MaxDuration is the time limit before a relayed connection is reset.
+	// libp2p default is 2 minutes.
+	MaxDuration time.Duration
+	// MaxCircuits is the maximum number of open relay circuits per peer.
+	// libp2p default is 16.
+	MaxCircuits int
+	// ReservationTTL is the duration of a relay reservation.
+	// libp2p default is 1 hour.
+	ReservationTTL time.Duration
+	// BufferSize is the per-circuit relayed connection buffer size in bytes.
+	// libp2p default is 2048.
+	BufferSize int
 }
 
 // NAT is the structure relative to NAT configuration settings
@@ -279,6 +317,20 @@ func (c Config) ToOpts(l log.StandardLogger) ([]node.Option, []vpn.Option, error
 			libp2p.EnableAutoRelay(relayOpts...))
 	}
 
+	// Offer the circuit-v2 relay SERVICE unless explicitly disabled. Any
+	// publicly-reachable cluster peer can carry relayed traffic for
+	// NAT-traversed peers that fail to DCUtR hole-punch. Resources are
+	// tuned via Connection.RelayService. Set RelayService.Disabled=true
+	// to opt out of serving as a relay (resource-constrained nodes,
+	// edge devices, untrusted environments). The relay CLIENT (the
+	// ability to reserve slots on OTHER relays via AutoRelay) stays on
+	// regardless — disabling the service does not prevent this node
+	// from using third-party relays to traverse its own NAT.
+	if !c.Connection.RelayService.Disabled {
+		libp2pOpts = append(libp2pOpts,
+			libp2p.EnableRelayService(relayv2.WithResources(RelayServiceResources(c.Connection.RelayService))))
+	}
+
 	if c.NAT.RateLimit {
 		libp2pOpts = append(libp2pOpts, libp2p.AutoNATServiceRateLimit(
 			c.NAT.RateLimitGlobal,
@@ -517,3 +569,58 @@ func logScale(val int) int {
 	bitlen := bits.Len(uint(val))
 	return 1 << bitlen
 }
+
+// Default circuit-v2 relay-service resource limits for edgevpn.
+// These are deliberately much wider than libp2p's defaults so cluster
+// peers can carry larger / longer relayed transfers (e.g. model files
+// for distributed inference) when DCUtR hole-punching fails. Operators
+// can override any of these via the Connection.RelayService config.
+const (
+	DefaultRelayServiceMaxData        int64         = 1 << 30 // 1 GiB
+	DefaultRelayServiceMaxDuration    time.Duration = 30 * time.Minute
+	DefaultRelayServiceMaxCircuits    int           = 64
+	DefaultRelayServiceReservationTTL time.Duration = time.Hour
+	DefaultRelayServiceBufferSize     int           = 64 << 10 // 64 KiB
+)
+
+// RelayServiceResources builds a relayv2.Resources struct from the
+// configured knobs, falling back to edgevpn defaults (wider than
+// libp2p's defaults) for any zero-valued field. libp2p's Resources
+// struct is passed by value to relayv2.WithResources; it has no public
+// constructor that merges with defaults, so we apply defaults here.
+func RelayServiceResources(c RelayService) relayv2.Resources {
+	res := relayv2.DefaultResources()
+
+	if c.MaxCircuits > 0 {
+		res.MaxCircuits = c.MaxCircuits
+	} else {
+		res.MaxCircuits = DefaultRelayServiceMaxCircuits
+	}
+
+	if c.BufferSize > 0 {
+		res.BufferSize = c.BufferSize
+	} else {
+		res.BufferSize = DefaultRelayServiceBufferSize
+	}
+
+	if c.ReservationTTL > 0 {
+		res.ReservationTTL = c.ReservationTTL
+	} else {
+		res.ReservationTTL = DefaultRelayServiceReservationTTL
+	}
+
+	limit := *res.Limit // copy so we don't mutate the DefaultLimit singleton
+	if c.MaxDuration > 0 {
+		limit.Duration = c.MaxDuration
+	} else {
+		limit.Duration = DefaultRelayServiceMaxDuration
+	}
+	if c.MaxData > 0 {
+		limit.Data = c.MaxData
+	} else {
+		limit.Data = DefaultRelayServiceMaxData
+	}
+	res.Limit = &limit
+
+	return res
+}

pkg/config/config_test.go

@@ -0,0 +1,95 @@
+/*
+Copyright © 2021-2022 Ettore Di Giacinto <mudler@mocaccino.org>
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package config
+
+import (
+	"testing"
+	"time"
+)
+
+// TestRelayServiceResourcesDefaults verifies that a zero-valued RelayService
+// produces relayv2.Resources populated with edgevpn's wider defaults, not
+// libp2p's conservative ones.
+func TestRelayServiceResourcesDefaults(t *testing.T) {
+	res := RelayServiceResources(RelayService{})
+
+	if res.MaxCircuits != DefaultRelayServiceMaxCircuits {
+		t.Errorf("MaxCircuits: got %d, want %d", res.MaxCircuits, DefaultRelayServiceMaxCircuits)
+	}
+	if res.BufferSize != DefaultRelayServiceBufferSize {
+		t.Errorf("BufferSize: got %d, want %d", res.BufferSize, DefaultRelayServiceBufferSize)
+	}
+	if res.ReservationTTL != DefaultRelayServiceReservationTTL {
+		t.Errorf("ReservationTTL: got %s, want %s", res.ReservationTTL, DefaultRelayServiceReservationTTL)
+	}
+	if res.Limit == nil {
+		t.Fatal("Limit is nil")
+	}
+	if res.Limit.Duration != DefaultRelayServiceMaxDuration {
+		t.Errorf("Limit.Duration: got %s, want %s", res.Limit.Duration, DefaultRelayServiceMaxDuration)
+	}
+	if res.Limit.Data != DefaultRelayServiceMaxData {
+		t.Errorf("Limit.Data: got %d, want %d", res.Limit.Data, DefaultRelayServiceMaxData)
+	}
+}
+
+// TestRelayServiceResourcesCustom verifies that explicit knob values override
+// the defaults end-to-end into the relayv2.Resources struct.
+func TestRelayServiceResourcesCustom(t *testing.T) {
+	custom := RelayService{
+		MaxData:        2 << 30, // 2 GiB
+		MaxDuration:    45 * time.Minute,
+		MaxCircuits:    128,
+		ReservationTTL: 2 * time.Hour,
+		BufferSize:     128 << 10, // 128 KiB
+	}
+	res := RelayServiceResources(custom)
+
+	if res.MaxCircuits != 128 {
+		t.Errorf("MaxCircuits: got %d, want 128", res.MaxCircuits)
+	}
+	if res.BufferSize != 128<<10 {
+		t.Errorf("BufferSize: got %d, want %d", res.BufferSize, 128<<10)
+	}
+	if res.ReservationTTL != 2*time.Hour {
+		t.Errorf("ReservationTTL: got %s, want %s", res.ReservationTTL, 2*time.Hour)
+	}
+	if res.Limit == nil {
+		t.Fatal("Limit is nil")
+	}
+	if res.Limit.Duration != 45*time.Minute {
+		t.Errorf("Limit.Duration: got %s, want %s", res.Limit.Duration, 45*time.Minute)
+	}
+	if res.Limit.Data != 2<<30 {
+		t.Errorf("Limit.Data: got %d, want %d", res.Limit.Data, int64(2<<30))
+	}
+}
+
+// TestRelayServiceResourcesDoesNotMutateDefaults guards against the
+// DefaultLimit() singleton being mutated through res.Limit aliasing.
+// Two independent calls with different overrides must not interfere.
+func TestRelayServiceResourcesDoesNotMutateDefaults(t *testing.T) {
+	a := RelayServiceResources(RelayService{MaxData: 1})
+	b := RelayServiceResources(RelayService{MaxData: 2})
+
+	if a.Limit.Data != 1 {
+		t.Errorf("a.Limit.Data: got %d, want 1 (mutated by b?)", a.Limit.Data)
+	}
+	if b.Limit.Data != 2 {
+		t.Errorf("b.Limit.Data: got %d, want 2", b.Limit.Data)
+	}
+	if a.Limit == b.Limit {
+		t.Error("a.Limit and b.Limit share the same pointer; defaults are being aliased")
+	}
+}