package relay

Import Path
	github.com/tmc/go-iroh/relay (on go.dev)

Dependency Relation
	imports 11 packages, and imported by 3 packages

Involved Source Files

	    nearest.go
	  d relay.go
		Package relay provides the public configuration types for iroh relay servers:
		relay URLs grouped into a [Map], per-relay [Config], and the [Mode] selecting
		which relays an endpoint uses.
		
		It is the public surface of the Rust crate iroh-relay (the client connection
		and wire protocol live in internal packages).
		
		The Go API is not stable before v1 and may change in any v0 release.
Package-Level Type Names (total 6)

	/* sort by: alphabet | popularity */
	 type Config (struct)
		Config is the configuration for a single relay server.

		Fields (total 3)
			AuthToken string
				AuthToken, if non-empty, is sent to authenticate with the relay.

			QUIC *QUICConfig
				QUIC, if non-nil, enables QUIC address discovery via this relay.

			URL netaddr.RelayURL
				URL is the relay server URL.

		Methods (total 3)
			( Config) MarshalText() ([]byte, error)
				MarshalText implements encoding.TextMarshaler using the relay URL string.

			( Config) String() string
			( Config) WithAuthToken(token string) Config
				WithAuthToken returns a copy of c with the auth token set.

		Implements (at least 3)
			 Config : encoding.TextMarshaler
			 Config : expvar.Var
			 Config : fmt.Stringer
		As Outputs Of (at least 10)
			func NewConfig(url netaddr.RelayURL, quic *QUICConfig) Config
			func Config.WithAuthToken(token string) Config
			func (*Map).Configs() []Config
			func (*Map).Get(url netaddr.RelayURL) (Config, bool)
			func (*Map).Insert(c Config) (Config, bool)
			func (*Map).Remove(url netaddr.RelayURL) (Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayActor).InsertRelay(url netaddr.RelayURL, cfg Config) (Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayActor).RemoveRelay(url netaddr.RelayURL) (Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayTransport).InsertRelay(url netaddr.RelayURL, cfg Config) (Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayTransport).RemoveRelay(url netaddr.RelayURL) (Config, bool)
		As Inputs Of (at least 4)
			func NewMap(configs ...Config) *Map
			func (*Map).Insert(c Config) (Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayActor).InsertRelay(url netaddr.RelayURL, cfg Config) (Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayTransport).InsertRelay(url netaddr.RelayURL, cfg Config) (Config, bool)

	 type Map (struct)
		Map is a set of relay servers keyed by URL.
		
		The zero Map is empty and ready to use, but is not safe for concurrent
		mutation; build it up before sharing.

		Methods (total 12)
			(*Map) Clone() *Map
				Clone returns a deep copy of the map.

			(*Map) Configs() []Config
				Configs returns the relay configs in URL-sorted order.

			(*Map) Contains(url netaddr.RelayURL) bool
				Contains reports whether url is in the map.

			(*Map) Get(url netaddr.RelayURL) (Config, bool)
				Get returns the config for url and whether it is present.

			(*Map) Insert(c Config) (Config, bool)
				Insert adds or replaces the config for its URL, returning the previous config
				and whether one was present.

			(*Map) IsEmpty() bool
				IsEmpty reports whether the map has no relays.

			(*Map) Len() int
				Len returns the number of relays.

			(*Map) Nearest(ctx context.Context, prober Prober) (netaddr.RelayURL, error)
				Nearest probes the relays in m and returns the URL of the lowest-latency
				reachable relay. It returns [ErrNoRelays] if the map is empty or no relay
				could be reached. If prober is nil, [HTTPConnectProber] is used.
				
				Nearest is the seam a ticket minter (e.g. ccl's transfer layer) calls to pick
				a home relay close to the local machine instead of an arbitrary one.

			(*Map) PreferNearest(ctx context.Context, prober Prober) (*Map, error)
				PreferNearest returns a Map containing only the lowest-latency reachable relay
				in m, using prober (or [HTTPConnectProber] if nil). It is a convenience for
				wiring nearest-relay selection into a [Mode]:
				
					m, err := relay.DefaultMap().PreferNearest(ctx, nil)
					if err == nil {
						mode = relay.ModeCustom(m)
					}
				
				On error (empty map or all relays unreachable) it returns the error and a nil
				map so the caller can fall back to the full set.

			(*Map) Remove(url netaddr.RelayURL) (Config, bool)
				Remove deletes the config for url, returning it and whether it was present.

			(*Map) String() string
			(*Map) URLs() []netaddr.RelayURL
				URLs returns the relay URLs in sorted order.

		Implements (at least 2)
			*Map : expvar.Var
			*Map : fmt.Stringer
		As Outputs Of (at least 7)
			func DefaultMap() *Map
			func MapFromURLs(urls ...netaddr.RelayURL) *Map
			func NewMap(configs ...Config) *Map
			func StagingMap() *Map
			func (*Map).Clone() *Map
			func (*Map).PreferNearest(ctx context.Context, prober Prober) (*Map, error)
			func Mode.Map() *Map
		As Inputs Of (at least 3)
			func ModeCustom(m *Map) Mode
			func RankByLatency(ctx context.Context, m *Map, prober Prober) []RelayLatency
			func github.com/tmc/go-iroh/internal/netreport.NewClient(relayMap *Map) *netreport.Client

	 type Mode (struct)
		Mode selects which relay servers an endpoint uses.

		Methods (only one)
			( Mode) Map() *Map
				Map returns the relay map for this mode.

		As Outputs Of (at least 5)
			func ModeCustom(m *Map) Mode
			func ModeCustomURLs(urls ...netaddr.RelayURL) Mode
			func ModeDefault() Mode
			func ModeDisabled() Mode
			func ModeStaging() Mode
		As Inputs Of (at least one exported)
			func github.com/tmc/go-iroh/iroh.WithRelayMode(mode Mode) iroh.Option

	 type Prober (func)
		A Prober measures the connect latency to a single relay. It returns the
		round-trip establishment time and nil on success, or a non-nil error if the
		relay could not be reached within ctx.
		
		Prober is the seam for latency-aware relay selection: [RankByLatency] and
		[Map.Nearest] call it once per candidate relay, concurrently. The default
		implementation is [HTTPConnectProber]; tests inject a deterministic Prober.

		As Outputs Of (at least one exported)
			func HTTPConnectProber(tlsConfig *tls.Config) Prober
		As Inputs Of (at least 3)
			func RankByLatency(ctx context.Context, m *Map, prober Prober) []RelayLatency
			func (*Map).Nearest(ctx context.Context, prober Prober) (netaddr.RelayURL, error)
			func (*Map).PreferNearest(ctx context.Context, prober Prober) (*Map, error)

	 type QUICConfig (struct)
		QUICConfig configures relay-based QUIC address discovery.

		Fields (only one)
			Port uint16
				Port is the QUIC port on the relay server.

		As Inputs Of (at least one exported)
			func NewConfig(url netaddr.RelayURL, quic *QUICConfig) Config

	 type RelayLatency (struct)
		RelayLatency pairs a relay URL with its measured connect latency.
		
		Err is non-nil when the relay could not be probed; in that case Latency is
		not meaningful. [RankByLatency] sorts reachable relays (Err == nil) ahead of
		unreachable ones.

		Fields (total 3)
			Err error
			Latency time.Duration
			URL netaddr.RelayURL
		As Outputs Of (at least one exported)
			func RankByLatency(ctx context.Context, m *Map, prober Prober) []RelayLatency


Package-Level Functions (total 12)

	 func DefaultMap() *Map
		DefaultMap returns the number0 production relay map.

	 func HTTPConnectProber(tlsConfig *tls.Config) Prober
		HTTPConnectProber returns a Prober that measures the time to establish a TLS
		connection to a relay's HTTPS endpoint. It reflects the real connect cost a
		relay client pays, which is dominated by round-trip latency to the relay, and
		is cheaper than a full net-report probe.
		
		tlsConfig, if non-nil, overrides the TLS configuration (used in tests to skip
		verification against a local relay). A relay URL without an explicit port uses
		443.

	 func MapFromURLs(urls ...netaddr.RelayURL) *Map
		MapFromURLs builds a Map from relay URLs, each with a default config that
		enables QUIC address discovery on [DefaultQUICPort]. net_report only probes
		relays whose config has a QUIC section, so a nil default would disable
		address discovery for every URL-built map, including [DefaultMap]. A relay
		without QAD just fails the probe, which stays latency-only.

	 func ModeCustom(m *Map) Mode
		ModeCustom uses a custom relay map.

	 func ModeCustomURLs(urls ...netaddr.RelayURL) Mode
		ModeCustomURLs uses a custom relay map built from the given URLs.

	 func ModeDefault() Mode
		ModeDefault uses the number0 production relay servers.

	 func ModeDisabled() Mode
		ModeDisabled disables relay servers entirely.

	 func ModeStaging() Mode
		ModeStaging uses the number0 staging relay servers.

	 func NewConfig(url netaddr.RelayURL, quic *QUICConfig) Config
		NewConfig returns a Config for url with the given optional QUIC config.

	 func NewMap(configs ...Config) *Map
		NewMap builds a Map from the given relay configs.

	 func RankByLatency(ctx context.Context, m *Map, prober Prober) []RelayLatency
		RankByLatency probes every relay in m using prober, concurrently, and returns
		the results sorted by ascending latency. Reachable relays (Err == nil) sort
		before unreachable ones; ties and unreachable relays are ordered
		deterministically by relay URL so selection is reproducible.
		
		If prober is nil, [HTTPConnectProber] is used. RankByLatency never returns a
		nil slice for a non-empty map: an unreachable relay appears with its Err set.

	 func StagingMap() *Map
		StagingMap returns the number0 staging relay map.


Package-Level Variables (only one)

	  var ErrNoRelays error
		ErrNoRelays is returned by [Map.Nearest] when the map has no relays or none
		could be reached.


Package-Level Constants (only one)

	const DefaultQUICPort = 7842
		DefaultQUICPort is the default port for relay QUIC address discovery.

The pages are generated with Golds v0.8.4. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.