Documentation
¶
Overview ¶
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.
Index ¶
- Variables
- type CustomAddr
- func (a CustomAddr) Compare(other TransportAddr) int
- func (a CustomAddr) Data() []byte
- func (a CustomAddr) ID() uint64
- func (a CustomAddr) MarshalBinary() ([]byte, error)
- func (a CustomAddr) MarshalText() ([]byte, error)
- func (CustomAddr) Network() string
- func (a CustomAddr) String() string
- func (a *CustomAddr) UnmarshalBinary(data []byte) error
- func (a *CustomAddr) UnmarshalText(text []byte) error
- type EndpointAddr
- func (a EndpointAddr) Addrs() []TransportAddr
- func (a EndpointAddr) IPAddrs() []netip.AddrPort
- func (a EndpointAddr) IsEmpty() bool
- func (a EndpointAddr) RelayURLs() []RelayURL
- func (a EndpointAddr) String() string
- func (a EndpointAddr) WithAddrs(addrs ...TransportAddr) EndpointAddr
- func (a EndpointAddr) WithIP(ap netip.AddrPort) EndpointAddr
- func (a EndpointAddr) WithRelayURL(u RelayURL) EndpointAddr
- type IPAddr
- type RelayAddr
- type RelayURL
- func (r RelayURL) Compare(other RelayURL) int
- func (r RelayURL) Equal(other RelayURL) bool
- func (r RelayURL) Host() string
- func (r RelayURL) IsZero() bool
- func (r RelayURL) MarshalText() ([]byte, error)
- func (r RelayURL) String() string
- func (r RelayURL) URL() *url.URL
- func (r *RelayURL) UnmarshalText(text []byte) error
- type TransportAddr
Constants ¶
This section is empty.
Variables ¶
var ( ErrCustomAddrMissingSeparator = errors.New("missing '_' separator") ErrCustomAddrInvalidID = errors.New("invalid ID") ErrCustomAddrInvalidData = errors.New("invalid data") ErrCustomAddrTooShort = errors.New("data too short") )
CustomAddr parse/encode errors.
var ErrParseRelayURL = errors.New("failed to parse relay URL")
ErrParseRelayURL is returned (wrapped) when a relay URL cannot be parsed.
Functions ¶
This section is empty.
Types ¶
type CustomAddr ¶
type CustomAddr struct {
// contains filtered or unexported fields
}
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.
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).
func NewCustomAddr ¶
func NewCustomAddr(id uint64, data []byte) CustomAddr
NewCustomAddr creates a CustomAddr from a transport ID and raw address data. The data is copied.
func ParseCustomAddr ¶
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 (CustomAddr) Compare ¶
func (a CustomAddr) Compare(other TransportAddr) int
Compare orders custom addresses by numeric transport id, then by data bytes.
func (CustomAddr) MarshalBinary ¶
func (a CustomAddr) MarshalBinary() ([]byte, error)
MarshalBinary implements encoding.BinaryMarshaler using the binary encoding described on CustomAddr.
func (CustomAddr) MarshalText ¶
func (a CustomAddr) MarshalText() ([]byte, error)
MarshalText implements encoding.TextMarshaler using the string encoding described on CustomAddr.
func (CustomAddr) Network ¶
func (CustomAddr) Network() string
func (CustomAddr) String ¶
func (a CustomAddr) String() string
func (*CustomAddr) UnmarshalBinary ¶
func (a *CustomAddr) UnmarshalBinary(data []byte) error
UnmarshalBinary implements encoding.BinaryUnmarshaler using the binary encoding described on CustomAddr.
func (*CustomAddr) UnmarshalText ¶
func (a *CustomAddr) UnmarshalText(text []byte) error
UnmarshalText implements encoding.TextUnmarshaler using the string encoding described on CustomAddr.
type EndpointAddr ¶
type EndpointAddr struct {
// ID is the endpoint's identifier.
ID key.EndpointID
// contains filtered or unexported fields
}
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.
func NewEndpointAddr ¶
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 (EndpointAddr) Addrs ¶
func (a EndpointAddr) Addrs() []TransportAddr
Addrs returns the sorted, deduplicated transport addresses.
func (EndpointAddr) IPAddrs ¶
func (a EndpointAddr) IPAddrs() []netip.AddrPort
IPAddrs returns the IP socket addresses of this endpoint.
func (EndpointAddr) IsEmpty ¶
func (a EndpointAddr) IsEmpty() bool
IsEmpty reports whether only the key.EndpointID is present.
func (EndpointAddr) RelayURLs ¶
func (a EndpointAddr) RelayURLs() []RelayURL
RelayURLs returns the relay URLs of this endpoint. In practice this is expected to be zero or one home relay.
func (EndpointAddr) String ¶
func (a EndpointAddr) String() string
String returns a diagnostic string for a.
func (EndpointAddr) WithAddrs ¶
func (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.
func (EndpointAddr) WithIP ¶
func (a EndpointAddr) WithIP(ap netip.AddrPort) EndpointAddr
WithIP returns a copy of a with the given IP address added.
func (EndpointAddr) WithRelayURL ¶
func (a EndpointAddr) WithRelayURL(u RelayURL) EndpointAddr
WithRelayURL returns a copy of a with the given relay URL added.
type IPAddr ¶
IPAddr is a TransportAddr reachable at an IP socket address.
func (IPAddr) Compare ¶
func (a IPAddr) Compare(other TransportAddr) int
Compare orders IP addresses numerically (by netip.AddrPort.Compare).
func (IPAddr) MarshalText ¶
MarshalText implements encoding.TextMarshaler using the string encoding described on TransportAddr.
func (*IPAddr) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler using the string encoding described on TransportAddr.
type RelayAddr ¶
type RelayAddr struct{ URL RelayURL }
RelayAddr is a TransportAddr reachable via a relay server.
func (RelayAddr) Compare ¶
func (a RelayAddr) Compare(other TransportAddr) int
Compare orders relay addresses by their normalized URL string.
func (RelayAddr) MarshalText ¶
MarshalText implements encoding.TextMarshaler using the string encoding described on TransportAddr.
func (*RelayAddr) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler using the string encoding described on TransportAddr.
type RelayURL ¶
type RelayURL struct {
// contains filtered or unexported fields
}
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.
func ParseRelayURL ¶
ParseRelayURL parses s into a RelayURL. It returns an error wrapping ErrParseRelayURL if s is not a valid URL.
func RelayURLFromURL ¶
RelayURLFromURL wraps an already-parsed URL as a RelayURL, normalizing it so that equivalent URLs compare equal (see RelayURL.String).
func (RelayURL) Compare ¶
Compare returns -1, 0, or +1 comparing r and other by their normalized string form, giving RelayURL a total order.
func (RelayURL) MarshalText ¶
MarshalText implements encoding.TextMarshaler.
func (RelayURL) 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/").
func (*RelayURL) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler.
type TransportAddr ¶
type TransportAddr interface {
// Network returns the transport kind: "relay", "ip", or "custom".
Network() string
// String renders the address in its "kind:value" form, e.g. "ip:127.0.0.1:9".
String() string
// 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).
Compare(other TransportAddr) int
// contains filtered or unexported methods
}
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.
func ParseTransportAddr ¶
func ParseTransportAddr(s string) (TransportAddr, error)
ParseTransportAddr parses a TransportAddr from its "kind:value" string form.
Source Files