namesys

package
v0.0.5 Latest Latest
Warning

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

Go to latest
Published: Apr 27, 2024 License: Apache-2.0, MIT Imports: 29 Imported by: 0

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

func PkRoutingKey(id peer.ID) string

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

func PublishIPNSRecord

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

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

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

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

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

IPNSPublisher implements Publisher for IPNS Records.

func NewIPNSPublisher

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

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

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

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

type IPNSResolver

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

func NewIPNSResolver(route routing.ValueStore) *IPNSResolver

NewIPNSResolver constructs a new IPNSResolver from a routing.ValueStore.

func (*IPNSResolver) Resolve

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

func (*IPNSResolver) ResolveAsync

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

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

type PublishOption func(*PublishOptions)

PublishOption is used to set an option for PublishOptions.

func PublishWithEOL

func PublishWithEOL(eol time.Time) PublishOption

PublishWithEOL sets [PublishOptions.EOL].

func PublishWithIPNSOption

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

func PublishWithTTL(ttl time.Duration) PublishOption

PublishWithEOL sets [PublishOptions.TTL].

type PublishOptions

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

func DefaultPublishOptions() PublishOptions

DefaultPublishOptions returns the default options for publishing an IPNS Record.

func ProcessPublishOptions

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

type ResolveOption func(*ResolveOptions)

ResolveOption is used to set a resolve option.

func ResolveWithDepth

func ResolveWithDepth(depth uint) ResolveOption

ResolveWithDepth sets [ResolveOptions.Depth].

func ResolveWithDhtRecordCount

func ResolveWithDhtRecordCount(count uint) ResolveOption

ResolveWithDhtRecordCount sets [ResolveOptions.DhtRecordCount].

func ResolveWithDhtTimeout

func ResolveWithDhtTimeout(timeout time.Duration) ResolveOption

ResolveWithDhtTimeout sets [ResolveOptions.ResolveWithDhtTimeout].

type ResolveOptions

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

func DefaultResolveOptions() ResolveOptions

DefaultResolveOptions returns the default options for resolving an IPNS Path.

func ProcessResolveOptions

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

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.

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