package dns

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

Dependency Relation
	imports 18 packages, and imported by one package

Involved Source Files

	    attrs.go
	  d doc.go
		Package dns provides DNS-based endpoint discovery for go-iroh: publishing and
		resolving endpoint addressing information via DNS using the pkarr signed
		packet format.
		
		It is a port of the Rust crate iroh-dns. The central types are [EndpointData]
		(a relay URL, direct addresses, and optional user data about an endpoint) and
		[EndpointInfo] (an [key.EndpointID] coupled with its [EndpointData]).
		
		Records are published under the name "_iroh.<z32-endpoint-id>.<origin>" as TXT
		records of the form "key=value" (RFC 1464), with keys "relay", "addr", and
		"user-data". [EndpointInfo] converts to and from both TXT record sets and
		pkarr signed packets.
		
		The Go API is not stable before v1 and may change in any v0 release.

	    doh.go
	    dot.go
	    endpointinfo.go
	    resolver.go
	    signedpacket.go
Package-Level Type Names (total 9)

	/* sort by: alphabet | popularity */
	 type DoHLookuper (struct)
		DoHLookuper resolves TXT records using DNS-over-HTTPS.
		
		It sends RFC 8484 POST requests with Content-Type application/dns-message.
		The zero value is not usable; set URL before calling LookupTXT.

		Fields (total 2)
			HTTPClient *http.Client
				HTTPClient sends requests. If nil, [http.DefaultClient] is used.

			URL string
				URL is the DNS-over-HTTPS endpoint.

		Methods (only one)
			(*DoHLookuper) LookupTXT(ctx context.Context, name string) ([]string, error)
				LookupTXT resolves name as TXT using DNS-over-HTTPS.

		Implements (at least one exported)
			*DoHLookuper : TXTLookuper

	 type DoTLookuper (struct)
		DoTLookuper resolves TXT records using DNS-over-TLS.
		
		Address is a host:port pair. TLSConfig may be nil to use the default TLS
		configuration.

		Fields (total 3)
			Address string
			Dialer *net.Dialer
			TLSConfig *tls.Config
		Methods (only one)
			(*DoTLookuper) LookupTXT(ctx context.Context, name string) ([]string, error)
				LookupTXT resolves name as TXT using DNS-over-TLS.

		Implements (at least one exported)
			*DoTLookuper : TXTLookuper

	 type EndpointData (struct)
		EndpointData is the addressing and metadata published about an endpoint: a set
		of transport addresses (in priority order) and optional [UserData]. It does
		not include the endpoint's id; see [EndpointInfo].
		
		The zero value is an empty EndpointData and is ready to use.

		Methods (total 18)
			(*EndpointData) AddAddrs(addrs ...netaddr.TransportAddr)
				AddAddrs adds addresses in order, skipping duplicates and ones already
				present. Duplicate filtering preserves the existing order.

			(*EndpointData) AddIPAddrs(addrs ...netip.AddrPort)
				AddIPAddrs adds IP addresses in order, skipping duplicates and existing ones.

			(*EndpointData) AddRelayURL(u netaddr.RelayURL)
				AddRelayURL adds a relay URL to the end of the address list, unless already
				present.

			( EndpointData) Addrs() []netaddr.TransportAddr
				Addrs returns the ordered transport addresses.

			(*EndpointData) ClearIPAddrs()
				ClearIPAddrs removes all direct IP addresses.

			(*EndpointData) ClearRelayURLs()
				ClearRelayURLs removes all relay addresses.

			( EndpointData) HasAddrs() bool
				HasAddrs reports whether any addresses are present.

			( EndpointData) IPAddrs() []netip.AddrPort
				IPAddrs returns the direct IP addresses in order.

			( EndpointData) RelayURLs() []netaddr.RelayURL
				RelayURLs returns the relay URLs in order.

			(*EndpointData) SetUserData(u *UserData)
				SetUserData sets or clears the user data.

			( EndpointData) String() string
				String returns a diagnostic string for d.

			( EndpointData) UserData() *UserData
				UserData returns the user data, or nil if unset.

			( EndpointData) WithAddrs(addrs ...netaddr.TransportAddr) EndpointData
				WithAddrs returns a copy of d with addrs added in order, skipping duplicates
				and existing ones.

			( EndpointData) WithIPAddrs(addrs ...netip.AddrPort) EndpointData
				WithIPAddrs returns a copy of d with addrs added in order, skipping
				duplicates and existing ones.

			( EndpointData) WithRelayURL(u netaddr.RelayURL) EndpointData
				WithRelayURL returns a copy of d with u added to the end of the address list,
				unless already present.

			( EndpointData) WithUserData(u *UserData) EndpointData
				WithUserData returns a copy of d with the user data set or cleared.

			( EndpointData) WithoutIPAddrs() EndpointData
				WithoutIPAddrs returns a copy of d with all direct IP addresses removed.

			( EndpointData) WithoutRelayURLs() EndpointData
				WithoutRelayURLs returns a copy of d with all relay addresses removed.

		Implements (at least 2)
			 EndpointData : expvar.Var
			 EndpointData : fmt.Stringer
		As Outputs Of (at least 9)
			func EndpointDataFromAddr(addr netaddr.EndpointAddr) EndpointData
			func NewEndpointData(addrs ...netaddr.TransportAddr) EndpointData
			func EndpointData.WithAddrs(addrs ...netaddr.TransportAddr) EndpointData
			func EndpointData.WithIPAddrs(addrs ...netip.AddrPort) EndpointData
			func EndpointData.WithoutIPAddrs() EndpointData
			func EndpointData.WithoutRelayURLs() EndpointData
			func EndpointData.WithRelayURL(u netaddr.RelayURL) EndpointData
			func EndpointData.WithUserData(u *UserData) EndpointData
			func github.com/tmc/go-iroh/iroh.(*MemoryLookup).SetEndpointInfo(info EndpointInfo) (EndpointData, bool)
		As Inputs Of (at least 5)
			func github.com/tmc/go-iroh/iroh.(*AddressLookupServices).Publish(data EndpointData)
			func github.com/tmc/go-iroh/iroh.AddressPublisher.Publish(data EndpointData)
			func github.com/tmc/go-iroh/iroh.AddressPublisherFunc.Publish(data EndpointData)
			func github.com/tmc/go-iroh/iroh.FilteredAddressPublisher.Publish(data EndpointData)
			func github.com/tmc/go-iroh/iroh.(*PkarrPublisher).Publish(data EndpointData)

	 type EndpointInfo (struct)
		EndpointInfo couples an [key.EndpointID] with the [EndpointData] published
		about it.

		Fields (total 2)
			Data EndpointData
				Data is the addressing and metadata.

			ID key.EndpointID
				ID is the endpoint this information is about.

		Methods (total 4)
			( EndpointInfo) Addr() netaddr.EndpointAddr
				Addr converts the info into an [netaddr.EndpointAddr].

			( EndpointInfo) String() string
				String returns a diagnostic string for e.

			( EndpointInfo) ToSignedPacket(secretKey key.SecretKey, ttl uint32) (*SignedPacket, error)
				ToSignedPacket builds a signed packet for this endpoint info, signed with
				secretKey and using the given record TTL in seconds.

			( EndpointInfo) ToTXTStrings() []string
				ToTXTStrings renders the endpoint info as "key=value" TXT record strings.

		Implements (at least 2)
			 EndpointInfo : expvar.Var
			 EndpointInfo : fmt.Stringer
		As Outputs Of (at least 8)
			func EndpointInfoFromAddr(addr netaddr.EndpointAddr) EndpointInfo
			func EndpointInfoFromSignedPacket(packet *SignedPacket) (EndpointInfo, error)
			func EndpointInfoFromTXTLookup(domainName string, values []string) (EndpointInfo, error)
			func (*Resolver).LookupEndpointByDomainName(ctx context.Context, name string) (EndpointInfo, error)
			func (*Resolver).LookupEndpointByID(ctx context.Context, id key.EndpointID, origin string) (EndpointInfo, error)
			func github.com/tmc/go-iroh/iroh.Item.EndpointInfo() EndpointInfo
			func github.com/tmc/go-iroh/iroh.(*MemoryLookup).GetEndpointInfo(id key.EndpointID) (EndpointInfo, bool)
			func github.com/tmc/go-iroh/iroh.(*MemoryLookup).RemoveEndpointInfo(id key.EndpointID) (EndpointInfo, bool)
		As Inputs Of (at least 6)
			func github.com/tmc/go-iroh/iroh.MemoryLookupFromInfo(infos ...EndpointInfo) *iroh.MemoryLookup
			func github.com/tmc/go-iroh/iroh.NewItem(info EndpointInfo, provenance string, lastUpdated *uint64) iroh.Item
			func github.com/tmc/go-iroh/iroh.NewStaticLookup(infos ...EndpointInfo) *iroh.StaticLookup
			func github.com/tmc/go-iroh/iroh.NewStaticLookupWithProvenance(provenance string, infos ...EndpointInfo) *iroh.StaticLookup
			func github.com/tmc/go-iroh/iroh.(*MemoryLookup).AddEndpointInfo(info EndpointInfo)
			func github.com/tmc/go-iroh/iroh.(*MemoryLookup).SetEndpointInfo(info EndpointInfo) (EndpointData, bool)

	 type Resolver (struct)
		Resolver resolves iroh endpoint information from DNS. The zero value uses the
		host's default DNS configuration; set [Resolver.Lookuper] to override.

		Fields (only one)
			Lookuper TXTLookuper
				Lookuper performs the underlying TXT lookups. If nil, a [net.Resolver]
				with the default configuration is used.

		Methods (total 2)
			(*Resolver) LookupEndpointByDomainName(ctx context.Context, name string) (EndpointInfo, error)
				LookupEndpointByDomainName resolves the endpoint info from the TXT records at
				name, which must be of the form "_iroh.<z32-id>.<origin>".

			(*Resolver) LookupEndpointByID(ctx context.Context, id key.EndpointID, origin string) (EndpointInfo, error)
				LookupEndpointByID resolves the endpoint info for id published under
				"_iroh.<z32-id>.<origin>". Pass [N0DNSEndpointOriginProd] for the number0
				production service.

		As Inputs Of (at least 3)
			func github.com/tmc/go-iroh/iroh.N0DNSAddressLookup(resolver *Resolver) *iroh.DNSAddressLookup
			func github.com/tmc/go-iroh/iroh.NewDNSAddressLookup(origin string, resolver *Resolver) *iroh.DNSAddressLookup
			func github.com/tmc/go-iroh/iroh.WithDNSResolver(r *Resolver) iroh.Option

	 type SignedPacket (struct)
		SignedPacket is a signed DNS packet in the pkarr format used for iroh
		endpoint discovery.
		
		A SignedPacket is immutable. Accessors return copies where mutation would
		otherwise affect the packet.

		Methods (total 6)
			(*SignedPacket) Bytes() []byte
				Bytes returns the full serialized wire bytes.

			(*SignedPacket) MoreRecentThan(other *SignedPacket) bool
				MoreRecentThan reports whether p should replace other. Equal timestamps are
				ordered by their encoded DNS packets, matching pkarr's conflict rule.

			(*SignedPacket) PublicKey() key.PublicKey
				PublicKey returns the signer's public key.

			(*SignedPacket) RelayPayload() []byte
				RelayPayload returns the relay payload: everything after the public key.

			(*SignedPacket) TXTRecords(name string) []string
				TXTRecords returns the TXT string values under name, normalized relative to
				the signer's z-base-32 public key.

			(*SignedPacket) TimestampMicros() uint64
				TimestampMicros returns the packet timestamp in microseconds since the UNIX
				epoch.

		Implements (at least one exported)
			*SignedPacket : github.com/apache/arrow-go/v18/internal/hashing.ByteSlice
		As Outputs Of (at least 3)
			func SignedPacketFromBytes(b []byte) (*SignedPacket, error)
			func SignedPacketFromBytesUnchecked(b []byte) (*SignedPacket, error)
			func EndpointInfo.ToSignedPacket(secretKey key.SecretKey, ttl uint32) (*SignedPacket, error)
		As Inputs Of (at least 2)
			func EndpointInfoFromSignedPacket(packet *SignedPacket) (EndpointInfo, error)
			func (*SignedPacket).MoreRecentThan(other *SignedPacket) bool

	 type TXTLookuper (interface)
		TXTLookuper looks up the TXT records for a DNS name. It is the minimal
		resolver seam: any implementation (the stdlib-backed [Resolver], a DoH/DoT
		client, or a test fake) satisfies it.
		
		It is the Go analog of iroh's Resolver trait, narrowed to the TXT lookup that
		endpoint discovery needs.

		Methods (only one)
			( TXTLookuper) LookupTXT(ctx context.Context, name string) ([]string, error)
				LookupTXT returns the TXT record string values for name.

		Implemented By (at least 9)
			*DoHLookuper
			*DoTLookuper
			 TXTLookuperFunc
			 github.com/libp2p/go-libp2p/p2p/net/swarm.ResolverFromMaDNS
			 github.com/multiformats/go-multiaddr-dns.BasicResolver (interface)
			*github.com/multiformats/go-multiaddr-dns.MockResolver
			*github.com/multiformats/go-multiaddr-dns.Resolver
			 google.golang.org/grpc/internal/resolver/dns/internal.NetResolver (interface)
			*net.Resolver

	 type TXTLookuperFunc (func)
		TXTLookuperFunc adapts a function to [TXTLookuper].

		Methods (only one)
			( TXTLookuperFunc) LookupTXT(ctx context.Context, name string) ([]string, error)
				LookupTXT calls f(ctx, name).

		Implements (at least one exported)
			 TXTLookuperFunc : TXTLookuper

	 type UserData (struct)
		UserData is application-defined data published and resolved through endpoint
		discovery. It is a UTF-8 string of at most [UserDataMaxLength] bytes. iroh
		neither inspects nor uses it.

		Methods (total 3)
			( UserData) MarshalText() ([]byte, error)
				MarshalText implements encoding.TextMarshaler.

			( UserData) String() string
				String returns the user data string.

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

		Implements (at least 4)
			 UserData : encoding.TextMarshaler
			*UserData : encoding.TextUnmarshaler
			 UserData : expvar.Var
			 UserData : fmt.Stringer
		As Outputs Of (at least 3)
			func NewUserData(s string) (UserData, error)
			func EndpointData.UserData() *UserData
			func github.com/tmc/go-iroh/iroh.Item.UserData() (UserData, bool)
		As Inputs Of (at least 2)
			func (*EndpointData).SetUserData(u *UserData)
			func EndpointData.WithUserData(u *UserData) EndpointData


Package-Level Functions (total 8)

	 func EndpointDataFromAddr(addr netaddr.EndpointAddr) EndpointData
		EndpointDataFromAddr builds EndpointData from an [netaddr.EndpointAddr], taking
		its (already de-duplicated, sorted) addresses.

	 func EndpointInfoFromAddr(addr netaddr.EndpointAddr) EndpointInfo
		EndpointInfoFromAddr converts an [netaddr.EndpointAddr] into an EndpointInfo.

	 func EndpointInfoFromSignedPacket(packet *SignedPacket) (EndpointInfo, error)
		EndpointInfoFromSignedPacket parses an EndpointInfo from a signed packet.

	 func EndpointInfoFromTXTLookup(domainName string, values []string) (EndpointInfo, error)
		EndpointInfoFromTXTLookup parses an EndpointInfo from DNS TXT lookup results.
		domainName is the queried name ("_iroh.<z32>.<origin>") and values are the
		TXT record string values.

	 func NewEndpointData(addrs ...netaddr.TransportAddr) EndpointData
		NewEndpointData returns an EndpointData with the given addresses. Order is
		preserved; duplicates are removed.

	 func NewUserData(s string) (UserData, error)
		NewUserData returns a UserData wrapping s, or [ErrUserDataTooLong] if s
		exceeds [UserDataMaxLength] bytes.

	 func SignedPacketFromBytes(b []byte) (*SignedPacket, error)
		SignedPacketFromBytes parses and verifies a signed packet from its wire
		representation.

	 func SignedPacketFromBytesUnchecked(b []byte) (*SignedPacket, error)
		SignedPacketFromBytesUnchecked parses a signed packet without verifying its
		signature. It still validates the minimum length and DNS packet encoding.


Package-Level Variables (total 5)

	  var ErrInvalidTXTAttr error
		ErrInvalidTXTAttr is returned for a TXT value not of the form key=value.

	  var ErrNotIrohRecord error
		ErrNotIrohRecord is returned when the first label is not "_iroh".

	  var ErrNumLabels error
		ErrNumLabels is returned when a DNS name has too few labels.

	  var ErrUnknownAttr error
		ErrUnknownAttr is returned for an unrecognized attribute key.

	  var ErrUserDataTooLong error
		ErrUserDataTooLong is returned when a [UserData] value exceeds
		[UserDataMaxLength].


Package-Level Constants (total 6)

	const DNSTimeout time.Duration = 3000000000
		DNSTimeout is the default per-lookup timeout.

	const IrohTXTName = "_iroh"
		IrohTXTName is the DNS record name under which iroh TXT records are published.

	const MaxSignedPacketSize = 1104
		MaxSignedPacketSize is the maximum wire size of a signed packet, including
		its public key.

	const N0DNSEndpointOriginProd = "dns.iroh.link."
		N0DNSEndpointOriginProd is the number0 production discovery origin.

	const N0DNSEndpointOriginStaging = "staging-dns.iroh.link."
		N0DNSEndpointOriginStaging is the number0 staging discovery origin.

	const UserDataMaxLength = 245
		UserDataMaxLength is the maximum byte length of [UserData]. A DNS TXT
		character-string holds at most 255 bytes; subtracting the "user-data=" prefix
		leaves 245 bytes.

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.