Documentation
¶
Index ¶
- Constants
- func NetworkOnlyACLService(acl *NetworkOnlyACL, refresh time.Duration) node.NetworkService
- func RelayServiceResources(c RelayService) relayv2.Resources
- type Config
- type Connection
- type Discovery
- type Ledger
- type NAT
- type NetworkOnlyACL
- type Ownership
- type PeerGuard
- type RelayService
- type ResourceLimit
Constants ¶
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 // DefaultRelayServiceACLRefresh is how often the NetworkOnly ACL // re-snapshots the alive bucket. Should be ≤ the alive-service // announce interval (default 120s) so peers leaving/joining are // reflected within a couple of ticks. DefaultRelayServiceACLRefresh time.Duration = 30 * time.Second )
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.
Variables ¶
This section is empty.
Functions ¶
func NetworkOnlyACLService ¶
func NetworkOnlyACLService(acl *NetworkOnlyACL, refresh time.Duration) node.NetworkService
NetworkOnlyACLService is a node.NetworkService that periodically snapshots the ledger's alive bucket into the supplied ACL.
The first non-empty snapshot ends the bootstrap window. If the bucket is empty (e.g. the alive service is disabled), the ACL stays in open-mode and a debug log line is emitted on each tick so operators can spot the misconfiguration.
The refresh cadence should be ≤ the alive-service announce interval; once per 30 s is a reasonable default.
func RelayServiceResources ¶
func RelayServiceResources(c RelayService) relayv2.Resources
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.
Types ¶
type Config ¶
type Config struct {
NetworkConfig, NetworkToken string
Address string
ListenMaddrs []string
DHTAnnounceMaddrs []multiaddr.Multiaddr
Router string
Interface string
Libp2pLogLevel, LogLevel string
LowProfile, BootstrapIface bool
Blacklist []string
Concurrency int
FrameTimeout string
ChannelBufferSize, InterfaceMTU, PacketMTU int
NAT NAT
Connection Connection
Discovery Discovery
Ledger Ledger
Limit ResourceLimit
Privkey []byte
// PeerGuard (experimental)
// enable peerguardian and add specific auth options
PeerGuard PeerGuard
// Ownership (experimental) authenticates ledger writes so a leaked token
// alone no longer lets a peer overwrite another peer's entries.
Ownership Ownership
Whitelist []multiaddr.Multiaddr
}
Config is the config struct for the node and the default EdgeVPN services It is used to generate opts for the node and the services before start.
type Connection ¶
type Connection struct {
HolePunch bool
AutoRelay bool
AutoRelayDiscoveryInterval time.Duration
StaticRelays []string
OnlyStaticRelays bool
PeerTable map[string]peer.ID
MaxConnections int
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
}
Connection is the configuration section relative to the connection services
type NAT ¶
type NAT struct {
Service bool
Map bool
RateLimit bool
RateLimitGlobal, RateLimitPeer int
RateLimitInterval time.Duration
}
NAT is the structure relative to NAT configuration settings It allows to enable/disable the service and NAT mapping, and rate limiting too.
type NetworkOnlyACL ¶
type NetworkOnlyACL struct {
// contains filtered or unexported fields
}
NetworkOnlyACL is a relayv2.ACLFilter that gates incoming circuit-v2 relay reservations on cluster membership. A peer is a "cluster member" when its libp2p peer ID is present in the local ledger's alive bucket (i.e. it has successfully gossiped a healthcheck timestamp against our network token).
During a short bootstrap window — before the ACL has been told "you can start strict-mode now" — every reservation is allowed. Without this window a new peer joining a network where we are reachable would be unable to reserve a slot on us before having proved itself, even though it can't prove itself until it has joined gossipsub, which on many NAT'd setups requires going through a relay first.
The zero value is usable: AllowReserve returns true (open) until the first call to Members(...) flips the gate via Start.
func (*NetworkOnlyACL) AllowConnect ¶
AllowConnect implements relayv2.ACLFilter. We only gate the reservation step — once a peer has a reservation it is by definition a cluster member, so any connect through it stays permitted. This keeps in-flight relayed sessions stable even if the alive bucket flickers.
func (*NetworkOnlyACL) AllowReserve ¶
AllowReserve implements relayv2.ACLFilter. Returns true if the peer is a recognised cluster member, or if strict-mode hasn't been entered yet (bootstrap window).
func (*NetworkOnlyACL) Members ¶
func (a *NetworkOnlyACL) Members(set map[peer.ID]struct{})
Members replaces the authorised peer set. Callers can drop or add peers atomically; readers see a consistent snapshot. Calling Members for the first time also flips the gate out of bootstrap mode: subsequent AllowReserve calls enforce the set strictly.
type Ownership ¶
Ownership configures ledger ownership enforcement. Mode is one of "off" (legacy opt-out), "observe" (sign + log violations) or "enforce" (sign + reject unauthorized writes; CLI default).
type RelayService ¶
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
// NetworkOnly, when true, gates incoming relay reservations on
// cluster membership: only peers whose libp2p peer ID appears in
// our local ledger's alive bucket (peers that completed a
// gossipsub handshake against our network token) may reserve a
// slot on this node. Strangers that found us via the public DHT
// or another relay discovery path are rejected. During a short
// bootstrap window — before the alive bucket has been observed —
// every reservation is allowed so the node itself can finish
// joining its cluster. Requires the alive service to be running.
//
// Note on the default: the CLI flag --relay-service-network-only
// defaults to TRUE (secure by default). The Go zero value of this
// field is false purely because Go doesn't let us pick a different
// zero. Programmatic callers constructing &config.Config{} who
// want to match the CLI default should set NetworkOnly: true
// explicitly.
NetworkOnly bool
// NetworkOnlyRefresh is the cadence at which the NetworkOnly ACL
// re-snapshots the alive bucket. Zero means the package default
// (30s).
NetworkOnlyRefresh time.Duration
// 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
}
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.