namesys

package
v0.24.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 7, 2024 License: Apache-2.0, MIT Imports: 29 Imported by: 35

Documentation

Overview

Package namesys defines Resolver and Publisher interfaces for IPNS paths, that is, IPFS paths in the form of /ipns/<name_to_be_resolved>. A "resolved" IPNS path becomes an /ipfs/<cid> path.

Traditionally, these paths would be in the form of /ipns/peer_id, which references an IPNS record in a distributed ValueStore (usually the IPFS DHT).

Additionally, the /ipns/ namespace can also be used with domain names that use DNSLink (/ipns/<dnslink_name>, https://docs.ipfs.io/concepts/dnslink/)

The package provides implementations for all three resolvers.

Index

Constants

View Source 
const (
	// DefaultDepthLimit is the default depth limit used by [Resolver].
	DefaultDepthLimit = 32

	// UnlimitedDepth allows infinite recursion in [Resolver]. You probably don't want
	// to use this, but it's here if you absolutely trust resolution to eventually
	// complete and can't put an upper limit on how many steps it will take.
	UnlimitedDepth = 0

	// DefaultResolverRecordCount is the number of IPNS Record copies to
	// retrieve from the routing system like Amino DHT (the best record is
	// selected from this set).
	DefaultResolverDhtRecordCount = 16

	// DefaultResolverDhtTimeout is the amount of time to wait for records to be fetched
	// and verified.
	DefaultResolverDhtTimeout = time.Minute

	// DefaultResolverCacheTTL defines default TTL of a record placed in [NameSystem] cache.
	DefaultResolverCacheTTL = time.Minute
)

Variables

View Source 
var (
	// ErrResolveFailed signals an error when attempting to resolve.
	ErrResolveFailed = errors.New("could not resolve name")

	// ErrResolveRecursion signals a recursion-depth limit.
	ErrResolveRecursion = errors.New("could not resolve name (recursion limit exceeded)")

	// ErrNoNamesys is an explicit error for when no [NameSystem] is provided.
	ErrNoNamesys = errors.New("no namesys has been provided")

	// ErrMultipleDNSLinkRecords signals that the domain had multiple valid DNSLink TXT entries.
	ErrMultipleDNSLinkRecords = fmt.Errorf("%w: DNSLink lookup returned more than one IPFS content path; ask domain owner to remove duplicate TXT records", ErrResolveFailed)

	// ErrMissingDNSLinkRecord signals that the domain has no DNSLink TXT entries.
	ErrMissingDNSLinkRecord = fmt.Errorf("%w: DNSLink lookup could not find a TXT record (https://docs.ipfs.tech/concepts/dnslink/)", ErrResolveFailed)
)

Functions

func IpnsDsKey 

func IpnsDsKey(name ipns.Name) ds.Key

IpnsDsKey returns a datastore key given an IPNS identifier (peer ID). Defines the storage key for IPNS records in the local datastore.

func PkRoutingKey added in v0.14.0 

func PkRoutingKey(id peer.ID) string

PkRoutingKey returns the public key routing key for the given peer.ID.

func PublishIPNSRecord added in v0.14.0 

func PublishIPNSRecord(ctx context.Context, r routing.ValueStore, pubKey crypto.PubKey, rec *ipns.Record) error

PublishIPNSRecord publishes the given ipns.Record for the provided crypto.PubKey in the provided routing.ValueStore. The public key is also made available to the routing system if it cannot be derived from the corresponding peer.ID.

func PutIPNSRecord added in v0.14.0 

func PutIPNSRecord(ctx context.Context, r routing.ValueStore, name ipns.Name, rec *ipns.Record) error

PutIPNSRecord puts the given ipns.Record for the given ipns.Name in the routing.ValueStore.

func PutPublicKey added in v0.14.0 

func PutPublicKey(ctx context.Context, r routing.ValueStore, pid peer.ID, pubKey crypto.PubKey) error

PutPublicKey puts the given crypto.PubKey for the given peer.ID in the routing.ValueStore.

Types

type AsyncResult added in v0.14.0 

type AsyncResult struct {
	Path    path.Path
	TTL     time.Duration
	LastMod time.Time
	Err     error
}

AsyncResult is the return type for [Resolver.ResolveAsync].

type DNSResolver 

type DNSResolver struct {
	// contains filtered or unexported fields
}

DNSResolver implements Resolver on DNS domains.

func NewDNSResolver 

func NewDNSResolver(lookup LookupTXTFunc) *DNSResolver

NewDNSResolver constructs a name resolver using DNS TXT records.

func (*DNSResolver) Resolve 

func (r *DNSResolver) Resolve(ctx context.Context, p path.Path, options ...ResolveOption) (Result, error)

func (*DNSResolver) ResolveAsync 

func (r *DNSResolver) ResolveAsync(ctx context.Context, p path.Path, options ...ResolveOption) <-chan AsyncResult

type IPNSPublisher added in v0.14.0 

type IPNSPublisher struct {
	// contains filtered or unexported fields
}

IPNSPublisher implements Publisher for IPNS Records.

func NewIPNSPublisher added in v0.14.0 

func NewIPNSPublisher(route routing.ValueStore, ds ds.Datastore) *IPNSPublisher

NewIPNSResolver constructs a new IPNSResolver from a routing.ValueStore and a ds.Datastore.

func (*IPNSPublisher) GetPublished added in v0.14.0 

func (p *IPNSPublisher) GetPublished(ctx context.Context, name ipns.Name, checkRouting bool) (*ipns.Record, error)

GetPublished returns the record this node has published corresponding to the given peer ID.

If `checkRouting` is true and we have no existing record, this method will check the routing system for any existing records.

func (*IPNSPublisher) ListPublished added in v0.14.0 

func (p *IPNSPublisher) ListPublished(ctx context.Context) (map[ipns.Name]*ipns.Record, error)

ListPublished returns the latest IPNS records published by this node and their expiration times.

This method will not search the routing system for records published by other nodes.

func (*IPNSPublisher) Publish added in v0.14.0 

func (p *IPNSPublisher) Publish(ctx context.Context, priv crypto.PrivKey, value path.Path, options ...PublishOption) error

type IPNSResolver added in v0.14.0 

type IPNSResolver struct {
	// contains filtered or unexported fields
}

IPNSResolver implements Resolver for IPNS Records. This resolver always returns a TTL if the record is still valid. It happens as follows:

  1. Provisory TTL is chosen: record TTL if it exists, otherwise `ipns.DefaultRecordTTL`.
  2. If provisory TTL expires before EOL, then returned TTL is duration between EOL and now.
  3. If record is expired, 0 is returned as TTL.

func NewIPNSResolver added in v0.14.0 

func NewIPNSResolver(route routing.ValueStore) *IPNSResolver

NewIPNSResolver constructs a new IPNSResolver from a routing.ValueStore.

func (*IPNSResolver) Resolve added in v0.14.0 

func (r *IPNSResolver) Resolve(ctx context.Context, p path.Path, options ...ResolveOption) (Result, error)

func (*IPNSResolver) ResolveAsync added in v0.14.0 

func (r *IPNSResolver) ResolveAsync(ctx context.Context, p path.Path, options ...ResolveOption) <-chan AsyncResult

type LookupTXTFunc 

type LookupTXTFunc func(ctx context.Context, name string) (txt []string, err error)

LookupTXTFunc is a function that lookups TXT record values.

type NameSystem 

type NameSystem interface {
	Resolver
	Publisher
}

NameSystem represents a cohesive name publishing and resolving system.

Publishing a name is the process of establishing a mapping, a key-value pair, according to naming rules and databases.

Resolving a name is the process of looking up the value associated with the key (name).

func NewNameSystem 

func NewNameSystem(r routing.ValueStore, opts ...Option) (NameSystem, error)

NewNameSystem constructs an IPFS NameSystem based on the given routing.ValueStore.

type Option 

type Option func(*namesys) error

func WithCache 

func WithCache(size int) Option

WithCache is an option that instructs the name system to use a (LRU) cache of the given size.

func WithDNSResolver 

func WithDNSResolver(rslv madns.BasicResolver) Option

WithDNSResolver is an option that supplies a custom DNS resolver to use instead of the system default.

func WithDatastore 

func WithDatastore(ds ds.Datastore) Option

WithDatastore is an option that supplies a datastore to use instead of an in-memory map datastore. The datastore is used to store published IPNS Records and make them available for querying.

func WithMaxCacheTTL added in v0.18.0 

func WithMaxCacheTTL(dur time.Duration) Option

WithMaxCacheTTL configures the maximum cache TTL. By default, if the cache is enabled, the entry TTL will be used for caching. By setting this option, you can limit how long that TTL is.

For example, if you configure a maximum cache TTL of 1 minute:

  • Entry TTL is 5 minutes -> Cache TTL is 1 minute
  • Entry TTL is 30 seconds -> Cache TTL is 30 seconds

type PublishOption added in v0.14.0 

type PublishOption func(*PublishOptions)

PublishOption is used to set an option for PublishOptions.

func PublishWithEOL added in v0.14.0 

func PublishWithEOL(eol time.Time) PublishOption

PublishWithEOL sets [PublishOptions.EOL].

func PublishWithIPNSOption added in v0.14.0 

func PublishWithIPNSOption(option ipns.Option) PublishOption

PublishWithIPNSOption adds an ipns.Option to [PublishOptions.IPNSOptions]. These options are used by IPNSPublisher, which passes them onto the IPNS record creation at ipns.NewRecord

func PublishWithTTL added in v0.14.0 

func PublishWithTTL(ttl time.Duration) PublishOption

PublishWithEOL sets [PublishOptions.TTL].

type PublishOptions added in v0.14.0 

type PublishOptions struct {
	// EOL defines for how long the published value is valid.
	EOL time.Time

	// TTL defines for how long the published value is cached locally before checking for updates.
	TTL time.Duration

	// IPNSOptions are options passed by [IPNSPublisher] to [ipns.NewRecord] when
	// creating a new record to publish. With this options, you can further customize
	// the way IPNS Records are created.
	IPNSOptions []ipns.Option
}

PublishOptions specifies options for publishing an IPNS Record.

func DefaultPublishOptions added in v0.14.0 

func DefaultPublishOptions() PublishOptions

DefaultPublishOptions returns the default options for publishing an IPNS Record.

func ProcessPublishOptions added in v0.14.0 

func ProcessPublishOptions(opts []PublishOption) PublishOptions

ProcessPublishOptions converts an array of PublishOption into a PublishOptions object.

type Publisher 

type Publisher interface {
	// Publish publishes the given value under the name represented by the given private key.
	Publish(ctx context.Context, sk ci.PrivKey, value path.Path, options ...PublishOption) error
}

Publisher is an object capable of publishing particular names.

type ResolveOption added in v0.14.0 

type ResolveOption func(*ResolveOptions)

ResolveOption is used to set a resolve option.

func ResolveWithDepth added in v0.14.0 

func ResolveWithDepth(depth uint) ResolveOption

ResolveWithDepth sets [ResolveOptions.Depth].

func ResolveWithDhtRecordCount added in v0.14.0 

func ResolveWithDhtRecordCount(count uint) ResolveOption

ResolveWithDhtRecordCount sets [ResolveOptions.DhtRecordCount].

func ResolveWithDhtTimeout added in v0.14.0 

func ResolveWithDhtTimeout(timeout time.Duration) ResolveOption

ResolveWithDhtTimeout sets [ResolveOptions.ResolveWithDhtTimeout].

type ResolveOptions added in v0.14.0 

type ResolveOptions struct {
	// Depth is the recursion depth limit.
	Depth uint

	// DhtRecordCount is the number of IPNS Records to retrieve from the routing system
	// (the best record is selected from this set).
	DhtRecordCount uint

	// DhtTimeout is the amount of time to wait for records to be fetched and
	// verified. A zero value indicates that there is no explicit timeout
	// (although there may be an implicit timeout due to dial timeouts within
	// the specific routing system like DHT).
	DhtTimeout time.Duration
}

ResolveOptions specifies options for resolving an IPNS Path.

func DefaultResolveOptions added in v0.14.0 

func DefaultResolveOptions() ResolveOptions

DefaultResolveOptions returns the default options for resolving an IPNS Path.

func ProcessResolveOptions added in v0.14.0 

func ProcessResolveOptions(opts []ResolveOption) ResolveOptions

ProcessResolveOptions converts an array of ResolveOption into a ResolveOptions object.

type Resolver 

type Resolver interface {
	// Resolve performs a recursive lookup, returning the dereferenced path and the TTL.
	// If the TTL is unknown, then a TTL of 0 is returned. For example, if example.com
	// has a DNS TXT record pointing to:
	//
	//   /ipns/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
	//
	// and there is a DHT IPNS entry for
	//
	//   QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
	//   -> /ipfs/Qmcqtw8FfrVSBaRmbWwHxt3AuySBhJLcvmFYi3Lbc4xnwj
	//
	// then
	//
	//   Resolve(ctx, "/ipns/ipfs.io")
	//
	// will resolve both names, returning
	//
	//   /ipfs/Qmcqtw8FfrVSBaRmbWwHxt3AuySBhJLcvmFYi3Lbc4xnwj
	//
	// There is a default depth-limit to avoid infinite recursion. Most users will be fine with
	// this default limit, but if you need to adjust the limit you can specify it as an option.
	Resolve(context.Context, path.Path, ...ResolveOption) (Result, error)

	// ResolveAsync performs recursive name lookup, like Resolve, but it returns entries as
	// they are discovered in the DHT. Each returned result is guaranteed to be "better"
	// (which usually means newer) than the previous one.
	ResolveAsync(context.Context, path.Path, ...ResolveOption) <-chan AsyncResult
}

Resolver is an object capable of resolving names.

type Result 

type Result struct {
	Path    path.Path
	TTL     time.Duration
	LastMod time.Time
}

Result is the return type for [Resolver.Resolve].

func Resolve added in v0.14.0 

func Resolve(ctx context.Context, ns NameSystem, p path.Path) (Result, error)

Resolve is an utility function that takes a NameSystem and a path.Path, and returns the result of [NameSystem.Resolve] for the given path. If the given namesys is nil, ErrNoNamesys is returned.

Source Files

View all Source files

Directories

Path Synopsis
Package republisher provides a utility to automatically re-publish IPNS records related to the keys in a Keystore.
 Package republisher provides a utility to automatically re-publish IPNS records related to the keys in a Keystore.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.