cid

package
v0.0.0-...-8b9b725 Latest Latest
Warning

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

 Go to latest Published: Apr 7, 2019 License: MIT, MIT Imports: 9 Imported by: 300

README

go-cid

GoDoc Coverage Status Travis CI

A package to handle content IDs in Go.

This is an implementation in Go of the CID spec. It is used in go-ipfs and related packages to refer to a typed hunk of data.

Table of Contents

Install

go-cid is a standard Go module which can be installed with:

go get github.com/ipfs/go-cid

Note that go-cid is packaged with Gx, so it is recommended to use Gx to install and use it (see Usage section).

Usage

Using Gx and Gx-go

This module is packaged with Gx. In order to use it in your own project it is recommended that you:

go get -u github.com/whyrusleeping/gx
go get -u github.com/whyrusleeping/gx-go
cd <your-project-repository>
gx init
gx import github.com/ipfs/go-cid
gx install --global
gx-go --rewrite

Please check Gx and Gx-go documentation for more information.

Running tests

Before running tests, please run:

make deps

This will make sure that dependencies are rewritten to known working versions.

Examples
Parsing string input from users
// Create a cid from a marshaled string
c, err := cid.Decode("zdvgqEMYmNeH5fKciougvQcfzMcNjF3Z1tPouJ8C7pc3pe63k")
if err != nil {...}

fmt.Println("Got CID: ", c)
Creating a CID from scratch
// Create a cid manually by specifying the 'prefix' parameters
pref := cid.Prefix{
	Version: 1,
	Codec: cid.Raw,
	MhType: mh.SHA2_256,
	MhLength: -1, // default length
}

// And then feed it some data
c, err := pref.Sum([]byte("Hello World!"))
if err != nil {...}

fmt.Println("Created CID: ", c)
Check if two CIDs match
// To test if two cid's are equivalent, be sure to use the 'Equals' method:
if c1.Equals(c2) {
	fmt.Println("These two refer to the same exact data!")
}
Check if some data matches a given CID
// To check if some data matches a given cid, 
// Get your CIDs prefix, and use that to sum the data in question:
other, err := c.Prefix().Sum(mydata)
if err != nil {...}

if !c.Equals(other) {
	fmt.Println("This data is different.")
}

Contribute

PRs are welcome!

Small note: If editing the Readme, please conform to the standard-readme specification.

License

MIT © Jeromy Johnson

Documentation

Overview

Package cid implements the Content-IDentifiers specification (https://github.com/ipld/cid) in Go. CIDs are self-describing content-addressed identifiers useful for distributed information systems. CIDs are used in the IPFS (https://ipfs.io) project ecosystem.

CIDs have two major versions. A CIDv0 corresponds to a multihash of type DagProtobuf, is deprecated and exists for compatibility reasons. Usually, CIDv1 should be used.

A CIDv1 has four parts: 

<cidv1> ::= <multibase-prefix><cid-version><multicodec-packed-content-type><multihash-content-address>

As shown above, the CID implementation relies heavily on Multiformats, particularly Multibase (https://github.com/multiformats/go-multibase), Multicodec (https://github.com/multiformats/multicodec) and Multihash implementations (https://github.com/multiformats/go-multihash).

Index

Examples

Constants

View Source 
const (
	Raw = 0x55

	DagProtobuf = 0x70
	DagCBOR     = 0x71

	GitRaw = 0x78

	EthBlock           = 0x90
	EthBlockList       = 0x91
	EthTxTrie          = 0x92
	EthTx              = 0x93
	EthTxReceiptTrie   = 0x94
	EthTxReceipt       = 0x95
	EthStateTrie       = 0x96
	EthAccountSnapshot = 0x97
	EthStorageTrie     = 0x98
	BitcoinBlock       = 0xb0
	BitcoinTx          = 0xb1
	ZcashBlock         = 0xc0
	ZcashTx            = 0xc1
	DecredBlock        = 0xe0
	DecredTx           = 0xe1
	DashBlock          = 0xf0
	DashTx             = 0xf1
)

These are multicodec-packed content types. The should match the codes described in the authoritative document: https://github.com/multiformats/multicodec/blob/master/table.csv

View Source 
const UnsupportedVersionString = "<unsupported cid version>"

UnsupportedVersionString just holds an error message

Variables

View Source 
var (
	// ErrVarintBuffSmall means that a buffer passed to the cid parser was not
	// long enough, or did not contain an invalid cid
	ErrVarintBuffSmall = errors.New("reading varint: buffer too small")

	// ErrVarintTooBig means that the varint in the given cid was above the
	// limit of 2^64
	ErrVarintTooBig = errors.New("reading varint: varint bigger than 64bits" +
		" and not supported")

	// ErrCidTooShort means that the cid passed to decode was not long
	// enough to be a valid Cid
	ErrCidTooShort = errors.New("cid too short")

	// ErrInvalidEncoding means that selected encoding is not supported
	// by this Cid version
	ErrInvalidEncoding = errors.New("invalid base encoding")
)
View Source 
var CodecToStr = map[uint64]string{
	Raw:                "raw",
	DagProtobuf:        "protobuf",
	DagCBOR:            "cbor",
	GitRaw:             "git-raw",
	EthBlock:           "eth-block",
	EthBlockList:       "eth-block-list",
	EthTxTrie:          "eth-tx-trie",
	EthTx:              "eth-tx",
	EthTxReceiptTrie:   "eth-tx-receipt-trie",
	EthTxReceipt:       "eth-tx-receipt",
	EthStateTrie:       "eth-state-trie",
	EthAccountSnapshot: "eth-account-snapshot",
	EthStorageTrie:     "eth-storage-trie",
	BitcoinBlock:       "bitcoin-block",
	BitcoinTx:          "bitcoin-tx",
	ZcashBlock:         "zcash-block",
	ZcashTx:            "zcash-tx",
	DecredBlock:        "decred-block",
	DecredTx:           "decred-tx",
	DashBlock:          "dash-block",
	DashTx:             "dash-tx",
}

CodecToStr maps the numeric codec to its name

View Source 
var Codecs = map[string]uint64{
	"v0":                   DagProtobuf,
	"raw":                  Raw,
	"protobuf":             DagProtobuf,
	"cbor":                 DagCBOR,
	"git-raw":              GitRaw,
	"eth-block":            EthBlock,
	"eth-block-list":       EthBlockList,
	"eth-tx-trie":          EthTxTrie,
	"eth-tx":               EthTx,
	"eth-tx-receipt-trie":  EthTxReceiptTrie,
	"eth-tx-receipt":       EthTxReceipt,
	"eth-state-trie":       EthStateTrie,
	"eth-account-snapshot": EthAccountSnapshot,
	"eth-storage-trie":     EthStorageTrie,
	"bitcoin-block":        BitcoinBlock,
	"bitcoin-tx":           BitcoinTx,
	"zcash-block":          ZcashBlock,
	"zcash-tx":             ZcashTx,
	"decred-block":         DecredBlock,
	"decred-tx":            DecredTx,
	"dash-block":           DashBlock,
	"dash-tx":              DashTx,
}

Codecs maps the name of a codec to its type

View Source 
var Undef = Cid{}

Undef can be used to represent a nil or undefined Cid, using Cid{} directly is also acceptable.

Functions

func ExtractEncoding 

func ExtractEncoding(v string) (mbase.Encoding, error)

Extract the encoding from a Cid. If Decode on the same string did not return an error neither will this function.

Types

type Builder 

type Builder interface {
	Sum(data []byte) (Cid, error)
	GetCodec() uint64
	WithCodec(uint64) Builder
}

type Cid 

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

Cid represents a self-describing content addressed identifier. It is formed by a Version, a Codec (which indicates a multicodec-packed content type) and a Multihash.

func Cast 

func Cast(data []byte) (Cid, error)

Cast takes a Cid data slice, parses it and returns a Cid. For CidV1, the data buffer is in the form: 

<version><codec-type><multihash>

CidV0 are also supported. In particular, data buffers starting with length 34 bytes, which starts with bytes [18,32...] are considered binary multihashes.

Please use decode when parsing a regular Cid string, as Cast does not expect multibase-encoded data. Cast accepts the output of Cid.Bytes().

func Decode 

func Decode(v string) (Cid, error)

Decode parses a Cid-encoded string and returns a Cid object. For CidV1, a Cid-encoded string is primarily a multibase string: 

<multibase-type-code><base-encoded-string>

The base-encoded string represents a:

<version><codec-type><multihash>

Decode will also detect and parse CidV0 strings. Strings starting with "Qm" are considered CidV0 and treated directly as B58-encoded multihashes.

Example 
encoded := "zb2rhhFAEMepUBbGyP1k8tGfz7BSciKXP6GHuUeUsJBaK6cqG"
c, err := Decode(encoded)
if err != nil {
	fmt.Printf("Error: %s", err)
	return
}

fmt.Println(c)

Output:

zb2rhhFAEMepUBbGyP1k8tGfz7BSciKXP6GHuUeUsJBaK6cqG

func NewCidV0 

func NewCidV0(mhash mh.Multihash) Cid

NewCidV0 returns a Cid-wrapped multihash. They exist to allow IPFS to work with Cids while keeping compatibility with the plain-multihash format used used in IPFS. NewCidV1 should be used preferentially.

func NewCidV1 

func NewCidV1(codecType uint64, mhash mh.Multihash) Cid

NewCidV1 returns a new Cid using the given multicodec-packed content type.

func Parse 

func Parse(v interface{}) (Cid, error)

Parse is a short-hand function to perform Decode, Cast etc... on a generic interface{} type.

func (Cid) Bytes 

func (c Cid) Bytes() []byte

Bytes returns the byte representation of a Cid. The output of bytes can be parsed back into a Cid with Cast().

func (Cid) Defined 

func (c Cid) Defined() bool

Defined returns true if a Cid is defined Calling any other methods on an undefined Cid will result in undefined behavior.

func (Cid) Encode 

func (c Cid) Encode(base mbase.Encoder) string

Encode return the string representation of a Cid in a given base when applicable. Version 0 Cid's are always in Base58 as they do not take a multibase prefix.

func (Cid) Equals 

func (c Cid) Equals(o Cid) bool

Equals checks that two Cids are the same. In order for two Cids to be considered equal, the Version, the Codec and the Multihash must match.

func (Cid) Hash 

func (c Cid) Hash() mh.Multihash

Hash returns the multihash contained by a Cid.

func (Cid) KeyString 

func (c Cid) KeyString() string

KeyString returns the binary representation of the Cid as a string

func (Cid) Loggable 

func (c Cid) Loggable() map[string]interface{}

Loggable returns a Loggable (as defined by https://godoc.org/github.com/ipfs/go-log).

func (Cid) MarshalBinary 

func (c Cid) MarshalBinary() ([]byte, error)

MarshalBinary is equivalent to Bytes(). It implements the encoding.BinaryMarshaler interface.

func (Cid) MarshalJSON 

func (c Cid) MarshalJSON() ([]byte, error)

MarshalJSON procudes a JSON representation of a Cid, which looks as follows: 

{ "/": "<cid-string>" }

Note that this formatting comes from the IPLD specification (https://github.com/ipld/specs/tree/master/ipld)

func (Cid) MarshalText 

func (c Cid) MarshalText() ([]byte, error)

MarshalText is equivalent to String(). It implements the encoding.TextMarshaler interface.

func (Cid) Prefix 

func (c Cid) Prefix() Prefix

Prefix builds and returns a Prefix out of a Cid.

func (Cid) String 

func (c Cid) String() string

String returns the default string representation of a Cid. Currently, Base58 is used as the encoding for the multibase string.

func (Cid) StringOfBase 

func (c Cid) StringOfBase(base mbase.Encoding) (string, error)

String returns the string representation of a Cid encoded is selected base

func (Cid) Type 

func (c Cid) Type() uint64

Type returns the multicodec-packed content type of a Cid.

func (*Cid) UnmarshalBinary 

func (c *Cid) UnmarshalBinary(data []byte) error

UnmarshalBinary is equivalent to Cast(). It implements the encoding.BinaryUnmarshaler interface.

func (*Cid) UnmarshalJSON 

func (c *Cid) UnmarshalJSON(b []byte) error

UnmarshalJSON parses the JSON representation of a Cid.

func (*Cid) UnmarshalText 

func (c *Cid) UnmarshalText(text []byte) error

UnmarshalText is equivalent to Decode(). It implements the encoding.TextUnmarshaler interface.

func (Cid) Version 

func (c Cid) Version() uint64

Version returns the Cid version.

type Prefix 

type Prefix struct {
	Version  uint64
	Codec    uint64
	MhType   uint64
	MhLength int
}

Prefix represents all the metadata of a Cid, that is, the Version, the Codec, the Multihash type and the Multihash length. It does not contains any actual content information. NOTE: The use -1 in MhLength to mean default length is deprecated, 

use the V0Builder or V1Builder structures instead

func NewPrefixV0 

func NewPrefixV0(mhType uint64) Prefix

NewPrefixV0 returns a CIDv0 prefix with the specified multihash type. DEPRECATED: Use V0Builder

func NewPrefixV1 

func NewPrefixV1(codecType uint64, mhType uint64) Prefix

NewPrefixV1 returns a CIDv1 prefix with the specified codec and multihash type. DEPRECATED: Use V1Builder

func PrefixFromBytes 

func PrefixFromBytes(buf []byte) (Prefix, error)

PrefixFromBytes parses a Prefix-byte representation onto a Prefix.

func (Prefix) Bytes 

func (p Prefix) Bytes() []byte

Bytes returns a byte representation of a Prefix. It looks like: 

<version><codec><mh-type><mh-length>

func (Prefix) GetCodec 

func (p Prefix) GetCodec() uint64

func (Prefix) Sum 

func (p Prefix) Sum(data []byte) (Cid, error)

Sum uses the information in a prefix to perform a multihash.Sum() and return a newly constructed Cid with the resulting multihash.

func (Prefix) WithCodec 

func (p Prefix) WithCodec(c uint64) Builder

type Set 

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

Set is a implementation of a set of Cids, that is, a structure to which holds a single copy of every Cids that is added to it.

func NewSet 

func NewSet() *Set

NewSet initializes and returns a new Set.

func (*Set) Add 

func (s *Set) Add(c Cid)

Add puts a Cid in the Set.

func (*Set) ForEach 

func (s *Set) ForEach(f func(c Cid) error) error

ForEach allows to run a custom function on each Cid in the set.

func (*Set) Has 

func (s *Set) Has(c Cid) bool

Has returns if the Set contains a given Cid.

func (*Set) Keys 

func (s *Set) Keys() []Cid

Keys returns the Cids in the set.

func (*Set) Len 

func (s *Set) Len() int

Len returns how many elements the Set has.

func (*Set) Remove 

func (s *Set) Remove(c Cid)

Remove deletes a Cid from the Set.

func (*Set) Visit 

func (s *Set) Visit(c Cid) bool

Visit adds a Cid to the set only if it is not in it already.

type V0Builder 

type V0Builder struct{}

func (V0Builder) GetCodec 

func (p V0Builder) GetCodec() uint64

func (V0Builder) Sum 

func (p V0Builder) Sum(data []byte) (Cid, error)

func (V0Builder) WithCodec 

func (p V0Builder) WithCodec(c uint64) Builder

type V1Builder 

type V1Builder struct {
	Codec    uint64
	MhType   uint64
	MhLength int // MhLength <= 0 means the default length
}

func (V1Builder) GetCodec 

func (p V1Builder) GetCodec() uint64

func (V1Builder) Sum 

func (p V1Builder) Sum(data []byte) (Cid, error)

func (V1Builder) WithCodec 

func (p V1Builder) WithCodec(c uint64) Builder

Source Files

View all Source files

Directories

Path Synopsis
_rsrch
cidiface

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.