package netaddr

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

Dependency Relation
	imports 12 packages, and imported by 7 packages

Involved Source Files

	  d doc.go
		Package netaddr provides endpoint and transport addresses for go-iroh.
		
		An [EndpointAddr] combines a key.EndpointID with the network-level
		[TransportAddr] values at which the endpoint may be reached. A transport
		address is a [RelayAddr], [IPAddr], or [CustomAddr]. A [RelayURL] identifies
		an iroh relay server.
		
		The Go API is not stable before v1 and may change in any v0 release.

	    endpointaddr.go
	    relayurl.go
Package-Level Type Names (total 6)

	/* sort by: alphabet | popularity */
	 type CustomAddr (struct)
		CustomAddr is a custom transport address: a freely-chosen u64 transport id
		plus opaque, unvalidated address data.
		
		A registry of well-known transport ids is at
		https://github.com/n0-computer/iroh/blob/main/TRANSPORTS.md.
		
		CustomAddr mirrors upstream iroh's experimental custom-transport address
		surface, which upstream excludes from its stability guarantees. The Go API
		below follows this module's normal compatibility policy, but the
		endpoint-ticket wire encoding of a CustomAddr may change to track upstream
		without a major go-iroh version bump.
		
		String encoding ([CustomAddr.String], [ParseCustomAddr]): "<id>_<data>" where
		<id> is the transport ID as lowercase hex (no "0x", no leading zeros) and
		<data> is the address bytes as lowercase hex.
		
		Binary encoding ([CustomAddr.MarshalBinary], [CustomAddr.UnmarshalBinary]):
		8-byte little-endian u64 ID followed by the raw data bytes (minimum 8 bytes).
		
		CustomAddr mirrors upstream iroh's experimental custom-transport address
		surface, which upstream excludes from its stability guarantees. The Go API
		below follows this module's normal compatibility policy, but the
		endpoint-ticket wire encoding of a CustomAddr may change to track upstream
		without a major go-iroh version bump.

		Methods (total 9)
			( CustomAddr) Compare(other TransportAddr) int
				Compare orders custom addresses by numeric transport id, then by data bytes.

			( CustomAddr) Data() []byte
				Data returns the opaque address data.

			( CustomAddr) ID() uint64
				ID returns the transport ID.

			( CustomAddr) MarshalBinary() ([]byte, error)
				MarshalBinary implements encoding.BinaryMarshaler using the binary encoding
				described on [CustomAddr].

			( CustomAddr) MarshalText() ([]byte, error)
				MarshalText implements encoding.TextMarshaler using the string encoding
				described on [CustomAddr].

			( CustomAddr) Network() string
			( CustomAddr) String() string
			(*CustomAddr) UnmarshalBinary(data []byte) error
				UnmarshalBinary implements encoding.BinaryUnmarshaler using the binary
				encoding described on [CustomAddr].

			(*CustomAddr) UnmarshalText(text []byte) error
				UnmarshalText implements encoding.TextUnmarshaler using the string encoding
				described on [CustomAddr].

		Implements (at least 8)
			 CustomAddr : TransportAddr
			 CustomAddr : encoding.BinaryMarshaler
			*CustomAddr : encoding.BinaryUnmarshaler
			 CustomAddr : encoding.TextMarshaler
			*CustomAddr : encoding.TextUnmarshaler
			 CustomAddr : expvar.Var
			 CustomAddr : fmt.Stringer
			 CustomAddr : net.Addr
		As Outputs Of (at least 5)
			func NewCustomAddr(id uint64, data []byte) CustomAddr
			func ParseCustomAddr(s string) (CustomAddr, error)
			func github.com/tmc/go-iroh/internal/socket.Addr.Custom() (CustomAddr, bool)
			func github.com/tmc/go-iroh/internal/socket.(*Socket).LookupCustom(m socket.CustomMappedAddr) (CustomAddr, bool)
			func github.com/tmc/go-iroh/iroh.AdvertisingCustomTransport.LocalCustomAddrs(context.Context) ([]CustomAddr, error)
		As Inputs Of (at least 12)
			func github.com/tmc/go-iroh/internal/socket.CustomAddr(c CustomAddr) socket.Addr
			func github.com/tmc/go-iroh/internal/socket.CustomTransport.Send(remote CustomAddr, local *CustomAddr, p []byte) bool
			func github.com/tmc/go-iroh/internal/socket.CustomTransport.Send(remote CustomAddr, local *CustomAddr, p []byte) bool
			func github.com/tmc/go-iroh/internal/socket.PacketTransport.Send(remote CustomAddr, local *CustomAddr, p []byte) bool
			func github.com/tmc/go-iroh/internal/socket.PacketTransport.Send(remote CustomAddr, local *CustomAddr, p []byte) bool
			func github.com/tmc/go-iroh/internal/socket.PacketTransport.SendPacket(remote CustomAddr, local *CustomAddr, p []byte) bool
			func github.com/tmc/go-iroh/internal/socket.PacketTransport.SendPacket(remote CustomAddr, local *CustomAddr, p []byte) bool
			func github.com/tmc/go-iroh/internal/socket.(*Socket).CustomMappedAddrFor(c CustomAddr) socket.CustomMappedAddr
			func github.com/tmc/go-iroh/iroh.AdvertisingCustomTransport.Send(remote CustomAddr, local *CustomAddr, p []byte) bool
			func github.com/tmc/go-iroh/iroh.AdvertisingCustomTransport.Send(remote CustomAddr, local *CustomAddr, p []byte) bool
			func github.com/tmc/go-iroh/iroh.CustomTransport.Send(remote CustomAddr, local *CustomAddr, p []byte) bool
			func github.com/tmc/go-iroh/iroh.CustomTransport.Send(remote CustomAddr, local *CustomAddr, p []byte) bool

	 type EndpointAddr (struct)
		EndpointAddr combines an endpoint's [key.EndpointID] with the network-level
		addresses at which it may be reached.
		
		To establish a connection both the key.EndpointID and at least one path (a relay
		URL or a direct IP address) are needed; an EndpointAddr with no addresses is
		still usable together with an address-lookup service.

		Fields (only one)
			ID key.EndpointID
				ID is the endpoint's identifier.

		Methods (total 8)
			( EndpointAddr) Addrs() []TransportAddr
				Addrs returns the sorted, deduplicated transport addresses.

			( EndpointAddr) IPAddrs() []netip.AddrPort
				IPAddrs returns the IP socket addresses of this endpoint.

			( EndpointAddr) IsEmpty() bool
				IsEmpty reports whether only the key.EndpointID is present.

			( EndpointAddr) RelayURLs() []RelayURL
				RelayURLs returns the relay URLs of this endpoint. In practice this is
				expected to be zero or one home relay.

			( EndpointAddr) String() string
				String returns a diagnostic string for a.

			( EndpointAddr) WithAddrs(addrs ...TransportAddr) EndpointAddr
				WithAddrs returns a copy of a with the given addresses added. The result's
				address set is sorted and deduplicated.

			( EndpointAddr) WithIP(ap netip.AddrPort) EndpointAddr
				WithIP returns a copy of a with the given IP address added.

			( EndpointAddr) WithRelayURL(u RelayURL) EndpointAddr
				WithRelayURL returns a copy of a with the given relay URL added.

		Implements (at least 2)
			 EndpointAddr : expvar.Var
			 EndpointAddr : fmt.Stringer
		As Outputs Of (at least 10)
			func NewEndpointAddr(id key.EndpointID, addrs ...TransportAddr) EndpointAddr
			func EndpointAddr.WithAddrs(addrs ...TransportAddr) EndpointAddr
			func EndpointAddr.WithIP(ap netip.AddrPort) EndpointAddr
			func EndpointAddr.WithRelayURL(u RelayURL) EndpointAddr
			func github.com/tmc/go-iroh/dns.EndpointInfo.Addr() EndpointAddr
			func github.com/tmc/go-iroh/endpointticket.Decode(s string) (EndpointAddr, error)
			func github.com/tmc/go-iroh/endpointticket.ShortAddr(addr EndpointAddr) EndpointAddr
			func github.com/tmc/go-iroh/endpointticket.Ticket.Addr() EndpointAddr
			func github.com/tmc/go-iroh/iroh.(*Endpoint).Addr() EndpointAddr
			func github.com/tmc/go-iroh/iroh.Item.Addr() EndpointAddr
		As Inputs Of (at least 14)
			func github.com/tmc/go-iroh/dns.EndpointDataFromAddr(addr EndpointAddr) dns.EndpointData
			func github.com/tmc/go-iroh/dns.EndpointInfoFromAddr(addr EndpointAddr) dns.EndpointInfo
			func github.com/tmc/go-iroh/endpointticket.Encode(addr EndpointAddr) string
			func github.com/tmc/go-iroh/endpointticket.New(addr EndpointAddr) endpointticket.Ticket
			func github.com/tmc/go-iroh/endpointticket.Short(addr EndpointAddr) endpointticket.Ticket
			func github.com/tmc/go-iroh/endpointticket.ShortAddr(addr EndpointAddr) EndpointAddr
			func github.com/tmc/go-iroh/internal/socket.(*RemoteMap).ResolveRemote(addr EndpointAddr) error
			func github.com/tmc/go-iroh/internal/socket.(*RemoteStateActor).ResolveRemote(addr EndpointAddr) error
			func github.com/tmc/go-iroh/iroh.StaticLookupFromAddrs(addrs ...EndpointAddr) *iroh.StaticLookup
			func github.com/tmc/go-iroh/iroh.(*Endpoint).Connect(ctx context.Context, addr EndpointAddr, alpn string) (*iroh.Conn, error)
			func github.com/tmc/go-iroh/iroh.(*Endpoint).ConnectEarly(ctx context.Context, addr EndpointAddr, alpn string) (*iroh.Connecting, error)
			func github.com/tmc/go-iroh/iroh.(*Endpoint).Dial(ctx context.Context, addr EndpointAddr, alpn string) (net.Conn, error)
			func github.com/tmc/go-iroh/iroh.EndpointHooks.BeforeConnect(ctx context.Context, addr EndpointAddr, alpn string) error
			func github.com/tmc/go-iroh/iroh.(*MemoryLookup).AddEndpointAddr(addr EndpointAddr)

	 type IPAddr (struct)
		IPAddr is a [TransportAddr] reachable at an IP socket address.

		Fields (only one)
			Addr netip.AddrPort
		Methods (total 5)
			( IPAddr) Compare(other TransportAddr) int
				Compare orders IP addresses numerically (by [netip.AddrPort.Compare]).

			( IPAddr) MarshalText() ([]byte, error)
				MarshalText implements encoding.TextMarshaler using the string encoding
				described on [TransportAddr].

			( IPAddr) Network() string
			( IPAddr) String() string
			(*IPAddr) UnmarshalText(text []byte) error
				UnmarshalText implements encoding.TextUnmarshaler using the string encoding
				described on [TransportAddr].

		Implements (at least 6)
			 IPAddr : TransportAddr
			 IPAddr : encoding.TextMarshaler
			*IPAddr : encoding.TextUnmarshaler
			 IPAddr : expvar.Var
			 IPAddr : fmt.Stringer
			 IPAddr : net.Addr

	 type RelayAddr (struct)
		RelayAddr is a [TransportAddr] reachable via a relay server.

		Fields (only one)
			URL RelayURL
		Methods (total 5)
			( RelayAddr) Compare(other TransportAddr) int
				Compare orders relay addresses by their normalized URL string.

			( RelayAddr) MarshalText() ([]byte, error)
				MarshalText implements encoding.TextMarshaler using the string encoding
				described on [TransportAddr].

			( RelayAddr) Network() string
			( RelayAddr) String() string
			(*RelayAddr) UnmarshalText(text []byte) error
				UnmarshalText implements encoding.TextUnmarshaler using the string encoding
				described on [TransportAddr].

		Implements (at least 6)
			 RelayAddr : TransportAddr
			 RelayAddr : encoding.TextMarshaler
			*RelayAddr : encoding.TextUnmarshaler
			 RelayAddr : expvar.Var
			 RelayAddr : fmt.Stringer
			 RelayAddr : net.Addr

	 type RelayURL (struct)
		RelayURL is a URL identifying a relay server.
		
		It wraps a parsed URL and is cheap to copy. It is encouraged to use a
		fully-qualified DNS domain name (one ending in a ".", e.g. "relay.example.com.")
		so that local DNS search domains do not interfere with resolution.
		
		The zero value is not usable; construct a RelayURL with [ParseRelayURL] or
		[RelayURLFromURL].

		Methods (total 8)
			( RelayURL) Compare(other RelayURL) int
				Compare returns -1, 0, or +1 comparing r and other by their normalized
				string form, giving RelayURL a total order.

			( RelayURL) Equal(other RelayURL) bool
				Equal reports whether r and other are the same relay URL.

			( RelayURL) Host() string
				Host returns the host (without port) of the relay URL.

			( RelayURL) IsZero() bool
				IsZero reports whether r is the unusable zero value.

			( RelayURL) MarshalText() ([]byte, error)
				MarshalText implements encoding.TextMarshaler.

			( RelayURL) String() string
				String returns the normalized string form of the URL. An empty path is
				rendered as "/", matching the WHATWG URL serialization used by the Rust
				reference implementation (e.g. "https://example.com" -> "https://example.com/").

			( RelayURL) URL() *url.URL
				URL returns a copy of the underlying parsed URL.

			(*RelayURL) UnmarshalText(text []byte) error
				UnmarshalText implements encoding.TextUnmarshaler.

		Implements (at least 5)
			 RelayURL : encoding.TextMarshaler
			*RelayURL : encoding.TextUnmarshaler
			 RelayURL : expvar.Var
			 RelayURL : fmt.Stringer
			 RelayURL : gopkg.in/yaml.v3.IsZeroer
		As Outputs Of (at least 8)
			func ParseRelayURL(s string) (RelayURL, error)
			func RelayURLFromURL(u *url.URL) RelayURL
			func EndpointAddr.RelayURLs() []RelayURL
			func github.com/tmc/go-iroh/dns.EndpointData.RelayURLs() []RelayURL
			func github.com/tmc/go-iroh/internal/netreport.(*RelayLatencies).Snapshot() map[RelayURL]time.Duration
			func github.com/tmc/go-iroh/internal/socket.Addr.Relay() (RelayURL, key.EndpointID, bool)
			func github.com/tmc/go-iroh/relay.(*Map).Nearest(ctx context.Context, prober relay.Prober) (RelayURL, error)
			func github.com/tmc/go-iroh/relay.(*Map).URLs() []RelayURL
		As Inputs Of (at least 22)
			func EndpointAddr.WithRelayURL(u RelayURL) EndpointAddr
			func RelayURL.Compare(other RelayURL) int
			func RelayURL.Equal(other RelayURL) bool
			func github.com/tmc/go-iroh/dns.(*EndpointData).AddRelayURL(u RelayURL)
			func github.com/tmc/go-iroh/dns.EndpointData.WithRelayURL(u RelayURL) dns.EndpointData
			func github.com/tmc/go-iroh/internal/relayclient.Connect(ctx context.Context, u RelayURL, opts relayclient.Options) (*relayclient.Client, error)
			func github.com/tmc/go-iroh/internal/socket.RelayAddr(url RelayURL, eid key.EndpointID) socket.Addr
			func github.com/tmc/go-iroh/internal/socket.(*RelayActor).InsertRelay(url RelayURL, cfg relay.Config) (relay.Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayActor).RemoveRelay(url RelayURL) (relay.Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayActor).SetHomeRelay(url RelayURL)
			func github.com/tmc/go-iroh/internal/socket.(*RelayTransport).InsertRelay(url RelayURL, cfg relay.Config) (relay.Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayTransport).RemoveRelay(url RelayURL) (relay.Config, bool)
			func github.com/tmc/go-iroh/internal/socket.(*RelayTransport).SetHomeRelay(url RelayURL)
			func github.com/tmc/go-iroh/internal/socket.(*Socket).RelayMappedAddrFor(url RelayURL, eid key.EndpointID) socket.RelayMappedAddr
			func github.com/tmc/go-iroh/iroh.(*Endpoint).InsertRelay(url RelayURL, cfg *iroh.RelayConfig) (*iroh.RelayConfig, error)
			func github.com/tmc/go-iroh/iroh.(*Endpoint).RemoveRelay(url RelayURL) *iroh.RelayConfig
			func github.com/tmc/go-iroh/relay.MapFromURLs(urls ...RelayURL) *relay.Map
			func github.com/tmc/go-iroh/relay.ModeCustomURLs(urls ...RelayURL) relay.Mode
			func github.com/tmc/go-iroh/relay.NewConfig(url RelayURL, quic *relay.QUICConfig) relay.Config
			func github.com/tmc/go-iroh/relay.(*Map).Contains(url RelayURL) bool
			func github.com/tmc/go-iroh/relay.(*Map).Get(url RelayURL) (relay.Config, bool)
			func github.com/tmc/go-iroh/relay.(*Map).Remove(url RelayURL) (relay.Config, bool)

	 type TransportAddr (interface)
		TransportAddr is a network-level address at which an endpoint may be reached.
		It is one of [RelayAddr], [IPAddr], or [CustomAddr].
		
		The interface is closed: only the implementations in this package satisfy it.

		Methods (total 3)
			( TransportAddr) Compare(other TransportAddr) int
				Compare returns -1, 0, or +1 ordering this address against other. The
				order matches the Rust reference's derived Ord on the TransportAddr enum:
				by kind first (relay < ip < custom), then by value (relay URLs by their
				normalized string, IP addresses numerically, custom by id then data).

			( TransportAddr) Network() string
				Network returns the transport kind: "relay", "ip", or "custom".

			( TransportAddr) String() string
				String renders the address in its "kind:value" form, e.g. "ip:127.0.0.1:9".

		Implemented By (at least 3)
			 CustomAddr
			 IPAddr
			 RelayAddr
		Implements (at least 3)
			 TransportAddr : expvar.Var
			 TransportAddr : fmt.Stringer
			 TransportAddr : net.Addr
		As Outputs Of (at least 7)
			func ParseTransportAddr(s string) (TransportAddr, error)
			func EndpointAddr.Addrs() []TransportAddr
			func github.com/tmc/go-iroh/dns.EndpointData.Addrs() []TransportAddr
			func github.com/tmc/go-iroh/iroh.IPOnlyFilter(addrs []TransportAddr) []TransportAddr
			func github.com/tmc/go-iroh/iroh.RelayOnlyFilter(addrs []TransportAddr) []TransportAddr
			func github.com/tmc/go-iroh/iroh.BiasedRttPathSelector.Select(current TransportAddr, candidates []iroh.PathCandidate) (TransportAddr, bool)
			func github.com/tmc/go-iroh/iroh.PathSelector.Select(current TransportAddr, candidates []iroh.PathCandidate) (selected TransportAddr, ok bool)
		As Inputs Of (at least 13)
			func NewEndpointAddr(id key.EndpointID, addrs ...TransportAddr) EndpointAddr
			func CustomAddr.Compare(other TransportAddr) int
			func EndpointAddr.WithAddrs(addrs ...TransportAddr) EndpointAddr
			func IPAddr.Compare(other TransportAddr) int
			func RelayAddr.Compare(other TransportAddr) int
			func TransportAddr.Compare(other TransportAddr) int
			func github.com/tmc/go-iroh/dns.NewEndpointData(addrs ...TransportAddr) dns.EndpointData
			func github.com/tmc/go-iroh/dns.(*EndpointData).AddAddrs(addrs ...TransportAddr)
			func github.com/tmc/go-iroh/dns.EndpointData.WithAddrs(addrs ...TransportAddr) dns.EndpointData
			func github.com/tmc/go-iroh/iroh.IPOnlyFilter(addrs []TransportAddr) []TransportAddr
			func github.com/tmc/go-iroh/iroh.RelayOnlyFilter(addrs []TransportAddr) []TransportAddr
			func github.com/tmc/go-iroh/iroh.BiasedRttPathSelector.Select(current TransportAddr, candidates []iroh.PathCandidate) (TransportAddr, bool)
			func github.com/tmc/go-iroh/iroh.PathSelector.Select(current TransportAddr, candidates []iroh.PathCandidate) (selected TransportAddr, ok bool)


Package-Level Functions (total 6)

	 func NewCustomAddr(id uint64, data []byte) CustomAddr
		NewCustomAddr creates a CustomAddr from a transport ID and raw address data.
		The data is copied.

	 func NewEndpointAddr(id key.EndpointID, addrs ...TransportAddr) EndpointAddr
		NewEndpointAddr creates an EndpointAddr with the given id and transport
		addresses. Addresses are deduplicated and sorted.

	 func ParseCustomAddr(s string) (CustomAddr, error)
		ParseCustomAddr parses a CustomAddr from its "<id>_<data>" string form.
		It also accepts the "custom:" prefix used by [ParseTransportAddr].

	 func ParseRelayURL(s string) (RelayURL, error)
		ParseRelayURL parses s into a RelayURL. It returns an error wrapping
		[ErrParseRelayURL] if s is not a valid URL.

	 func ParseTransportAddr(s string) (TransportAddr, error)
		ParseTransportAddr parses a TransportAddr from its "kind:value" string form.

	 func RelayURLFromURL(u *url.URL) RelayURL
		RelayURLFromURL wraps an already-parsed URL as a RelayURL, normalizing it so
		that equivalent URLs compare equal (see [RelayURL.String]).


Package-Level Variables (total 5)

	  var ErrCustomAddrInvalidData error
		CustomAddr parse/encode errors.

	  var ErrCustomAddrInvalidID error
		CustomAddr parse/encode errors.

	  var ErrCustomAddrMissingSeparator error
		CustomAddr parse/encode errors.

	  var ErrCustomAddrTooShort error
		CustomAddr parse/encode errors.

	  var ErrParseRelayURL error
		ErrParseRelayURL is returned (wrapped) when a relay URL cannot be parsed.

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.