github.com/keltia/go-ipfs@v0.3.8-0.20150909044612-210793031c63/namesys/interface.go (about)

     1  /*
     2  Package namesys implements resolvers and publishers for the IPFS
     3  naming system (IPNS).
     4  
     5  The core of IPFS is an immutable, content-addressable Merkle graph.
     6  That works well for many use cases, but doesn't allow you to answer
     7  questions like "what is Alice's current homepage?".  The mutable name
     8  system allows Alice to publish information like:
     9  
    10    The current homepage for alice.example.com is
    11    /ipfs/Qmcqtw8FfrVSBaRmbWwHxt3AuySBhJLcvmFYi3Lbc4xnwj
    12  
    13  or:
    14  
    15    The current homepage for node
    16    QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
    17    is
    18    /ipfs/Qmcqtw8FfrVSBaRmbWwHxt3AuySBhJLcvmFYi3Lbc4xnwj
    19  
    20  The mutable name system also allows users to resolve those references
    21  to find the immutable IPFS object currently referenced by a given
    22  mutable name.
    23  
    24  For command-line bindings to this functionality, see:
    25  
    26    ipfs name
    27    ipfs dns
    28    ipfs resolve
    29  */
    30  package namesys
    31  
    32  import (
    33  	"errors"
    34  
    35  	context "github.com/ipfs/go-ipfs/Godeps/_workspace/src/golang.org/x/net/context"
    36  	ci "github.com/ipfs/go-ipfs/p2p/crypto"
    37  	path "github.com/ipfs/go-ipfs/path"
    38  )
    39  
    40  const (
    41  	// DefaultDepthLimit is the default depth limit used by Resolve.
    42  	DefaultDepthLimit = 32
    43  
    44  	// UnlimitedDepth allows infinite recursion in ResolveN.  You
    45  	// probably don't want to use this, but it's here if you absolutely
    46  	// trust resolution to eventually complete and can't put an upper
    47  	// limit on how many steps it will take.
    48  	UnlimitedDepth = 0
    49  )
    50  
    51  // ErrResolveFailed signals an error when attempting to resolve.
    52  var ErrResolveFailed = errors.New("could not resolve name.")
    53  
    54  // ErrResolveRecursion signals a recursion-depth limit.
    55  var ErrResolveRecursion = errors.New(
    56  	"could not resolve name (recursion limit exceeded).")
    57  
    58  // ErrPublishFailed signals an error when attempting to publish.
    59  var ErrPublishFailed = errors.New("could not publish name.")
    60  
    61  // Namesys represents a cohesive name publishing and resolving system.
    62  //
    63  // Publishing a name is the process of establishing a mapping, a key-value
    64  // pair, according to naming rules and databases.
    65  //
    66  // Resolving a name is the process of looking up the value associated with the
    67  // key (name).
    68  type NameSystem interface {
    69  	Resolver
    70  	Publisher
    71  }
    72  
    73  // Resolver is an object capable of resolving names.
    74  type Resolver interface {
    75  
    76  	// Resolve performs a recursive lookup, returning the dereferenced
    77  	// path.  For example, if ipfs.io has a DNS TXT record pointing to
    78  	//   /ipns/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
    79  	// and there is a DHT IPNS entry for
    80  	//   QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
    81  	//   -> /ipfs/Qmcqtw8FfrVSBaRmbWwHxt3AuySBhJLcvmFYi3Lbc4xnwj
    82  	// then
    83  	//   Resolve(ctx, "/ipns/ipfs.io")
    84  	// will resolve both names, returning
    85  	//   /ipfs/Qmcqtw8FfrVSBaRmbWwHxt3AuySBhJLcvmFYi3Lbc4xnwj
    86  	//
    87  	// There is a default depth-limit to avoid infinite recursion.  Most
    88  	// users will be fine with this default limit, but if you need to
    89  	// adjust the limit you can use ResolveN.
    90  	Resolve(ctx context.Context, name string) (value path.Path, err error)
    91  
    92  	// ResolveN performs a recursive lookup, returning the dereferenced
    93  	// path.  The only difference from Resolve is that the depth limit
    94  	// is configurable.  You can use DefaultDepthLimit, UnlimitedDepth,
    95  	// or a depth limit of your own choosing.
    96  	//
    97  	// Most users should use Resolve, since the default limit works well
    98  	// in most real-world situations.
    99  	ResolveN(ctx context.Context, name string, depth int) (value path.Path, err error)
   100  }
   101  
   102  // Publisher is an object capable of publishing particular names.
   103  type Publisher interface {
   104  
   105  	// Publish establishes a name-value mapping.
   106  	// TODO make this not PrivKey specific.
   107  	Publish(ctx context.Context, name ci.PrivKey, value path.Path) error
   108  }