From 1d8efc31aa0e9f65110272d772aef6eec782d477 Mon Sep 17 00:00:00 2001 From: Steven Allen Date: Sat, 6 Apr 2019 07:34:52 -0700 Subject: [PATCH] doc: document relay options --- options.go | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/options.go b/options.go index 125ec8d6..9ef466c3 100644 --- a/options.go +++ b/options.go @@ -201,7 +201,12 @@ func AddrsFactory(factory config.AddrsFactory) Option { } } -// EnableRelay configures libp2p to enable the relay transport with configuration options. +// EnableRelay configures libp2p to enable the relay transport with +// configuration options. By default, this option only configures libp2p to +// accept inbound connections from relays and make outbound connections +// _through_ relays when requested by the remote peer. (default: enabled) +// +// To _act_ as a relay, pass the circuit.OptHop option. func EnableRelay(options ...circuit.RelayOpt) Option { return func(cfg *Config) error { cfg.RelayCustom = true @@ -211,7 +216,7 @@ func EnableRelay(options ...circuit.RelayOpt) Option { } } -// DisableRelay configures libp2p to disable the relay transport +// DisableRelay configures libp2p to disable the relay transport. func DisableRelay() Option { return func(cfg *Config) error { cfg.RelayCustom = true @@ -220,8 +225,18 @@ func DisableRelay() Option { } } -// EnableAutoRelay configures libp2p to enable autorelay advertising; requires relay to -// be enabled and the Routing option to provide an instance of ContentRouting. +// EnableAutoRelay configures libp2p to enable the AutoRelay subsystem. It is an +// error to enable AutoRelay without enabling relay (enabled by default) and +// routing (not enabled by default). +// +// This subsystem performs two functions: +// +// 1. When this libp2p node is configured to act as a relay "hop" +// (circuit.OptHop is passed to EnableRelay), this node will advertise itself +// as a public relay using the provided routing system. +// 2. When this libp2p node is _not_ configured as a relay "hop", it will +// automatically if it is unreachable (e.g., behind a NAT). If so, it will +// find, configure, and announce a set of public relays. func EnableAutoRelay() Option { return func(cfg *Config) error { cfg.EnableAutoRelay = true