Documentation
¶
Overview ¶
Package host provides libp2p host creation and identity management.
Index ¶
- Constants
- func Create(cfg *Config, priv crypto.PrivKey, logger *slog.Logger, ...) (host.Host, error)
- func LoadIdentityFromFile(path string) (crypto.PrivKey, error)
- func LoadIdentityFromSeed(seed []byte) (crypto.PrivKey, error)
- func LoadOrCreateIdentity(path string) (crypto.PrivKey, error)
- func PeerIDFromIdentity(priv crypto.PrivKey) (peer.ID, error)
- type Config
- type RelayLimits
Constants ¶
const DefaultConnManagerGracePeriod = 30 * time.Second
DefaultConnManagerGracePeriod is how long a new connection is protected from trimming. Long enough for a client to finish its handshake and first request; short enough that a reconnect storm does not become untrimmable.
const DefaultYamuxMaxIncomingStreams = 512
DefaultYamuxMaxIncomingStreams caps the streams one connection may have open towards this host at once. go-libp2p's own yamux default is effectively unlimited because it expects the resource manager to bound streams per peer; this is the per-connection backstop under that.
Variables ¶
This section is empty.
Functions ¶
func Create ¶
func Create(cfg *Config, priv crypto.PrivKey, logger *slog.Logger, transports ...libp2p.Option) (host.Host, error)
Create creates a libp2p host with the given configuration and identity. The transports parameter allows callers to provide custom transport constructors (e.g., UDX, TCP, QUIC). If empty, the default libp2p transports are used.
func LoadIdentityFromFile ¶
LoadIdentityFromFile loads an Ed25519 identity from a file in one of these formats: a 32-byte seed as raw bytes, 64 hex characters or 44 base64 characters; or the 64-byte private key that LoadOrCreateIdentity writes.
func LoadIdentityFromSeed ¶
LoadIdentityFromSeed creates an Ed25519 private key from a 32-byte seed.
func LoadOrCreateIdentity ¶
LoadOrCreateIdentity loads an existing Ed25519 private key from disk, or generates and persists a new one if none exists.
Types ¶
type Config ¶
type Config struct {
// Network
Port int `yaml:"port"`
ListenAddresses []string `yaml:"listen_addresses"`
ExternalAddresses []string `yaml:"external_addresses"`
BootstrapPeers []string `yaml:"bootstrap_peers"`
// Yamux tuning
YamuxKeepAlive time.Duration `yaml:"yamux_keepalive"`
YamuxWriteTimeout time.Duration `yaml:"yamux_write_timeout"`
// YamuxMaxIncomingStreams caps concurrent inbound streams per connection.
// Zero means DefaultYamuxMaxIncomingStreams.
YamuxMaxIncomingStreams uint32 `yaml:"yamux_max_incoming_streams"`
// Resource limits.
// MaxConnections is the hard cap on connections this host holds open,
// enforced by the libp2p resource manager, with a connection manager
// trimming idle peers before the cap is reached. Zero leaves go-libp2p's
// memory-scaled defaults in place.
MaxConnections int `yaml:"max_connections"`
// MaxConnectionsPerIP caps the connections held open with any one
// source address: an IPv4 address, or an IPv6 /56, with eight times as
// many per /48. Zero means no per-address cap, and that is the
// deliberate default: many clients legitimately share one address
// behind a carrier NAT or an office gateway, and go-libp2p's own default
// of eight per address turned the ninth of them away. Loopback is never
// capped. The per-address rate limit go-libp2p also applies by default
// is always off: this host bounds concurrency, not rate.
MaxConnectionsPerIP int `yaml:"max_connections_per_ip"`
// ConnManagerGracePeriod is how long a new connection is safe from
// trimming. Zero means DefaultConnManagerGracePeriod.
ConnManagerGracePeriod time.Duration `yaml:"connmgr_grace_period"`
// ConnectionGater, when set, is consulted for every connection and can
// refuse peers before any stream is opened. It is code, not
// configuration, so it has no YAML form; the application builds it from
// its own allow-list settings.
ConnectionGater connmgr.ConnectionGater `yaml:"-"`
// Relay
EnableRelay bool `yaml:"enable_relay"`
EnableRelayService bool `yaml:"enable_relay_service"`
EnableAutoRelay bool `yaml:"enable_auto_relay"`
EnableHolePunching bool `yaml:"enable_hole_punching"`
EnableAutoNAT bool `yaml:"enable_autonat"`
RelayLimits RelayLimits `yaml:"relay_limits"`
}
Config holds host creation configuration. This is the P2P-specific subset — application config lives in the application.
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns sensible defaults for a libp2p server host.
type RelayLimits ¶
type RelayLimits struct {
MaxReservations int `yaml:"max_reservations"`
MaxCircuits int `yaml:"max_circuits"`
BufferSize int `yaml:"buffer_size"`
MaxReservationsPerPeer int `yaml:"max_reservations_per_peer"`
MaxReservationsPerIP int `yaml:"max_reservations_per_ip"`
MaxReservationsPerASN int `yaml:"max_reservations_per_asn"`
ReservationTTL time.Duration `yaml:"reservation_ttl"`
ConnectionDuration time.Duration `yaml:"connection_duration"`
ConnectionData int64 `yaml:"connection_data"`
// UnlimitedConnections relays connections for as long, and as much
// data, as the two peers want; ConnectionDuration and ConnectionData
// are then ignored. Without it each relayed connection is cut at those
// limits (zero takes go-libp2p's 2 minutes and 128 KiB), which is only
// enough to coordinate a hole punch. Peers see an unlimited relayed
// connection as an ordinary one, not a limited one.
UnlimitedConnections bool `yaml:"unlimited_connections"`
}
RelayLimits configures circuit relay v2 service resource limits.