cid

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2025 License: Apache-2.0, MIT, Apache-2.0, + 1 more Imports: 11 Imported by: 0

Documentation

Overview

Package cid is an implementation of Content Identifiers, specifically the restricted DASL subset of CIDs.

https://dasl.ing/cid.html

Example 
package main

import (
	"fmt"

	"github.com/hyphacoop/go-dasl/cid"
)

func main() {
	// Create a CID from a string representation
	cidString := "bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4"
	c1, err := cid.NewCidFromString(cidString)
	if err != nil {
		panic(err)
	}
	fmt.Printf("CID from string: %s\n", c1.String())

	// Create a CID from binary bytes
	cidBytes := []byte{0x01, 0x55, 0x12, 0x20, 0xad, 0xee, 0x2e, 0x8f, 0xb5, 0x45, 0x9c, 0x9b, 0xcf, 0x07, 0xd7, 0xd7, 0x8d, 0x11, 0x83, 0xbf, 0x40, 0xa7, 0xf6, 0x0f, 0x57, 0xa5, 0x4a, 0x19, 0x19, 0x48, 0x01, 0xc9, 0xa2, 0x7e, 0xad, 0x87}
	c2, err := cid.NewCidFromBytes(cidBytes)
	if err != nil {
		panic(err)
	}
	fmt.Printf("CID from bytes: %s\n", c2.String())

	// Both should be equal
	fmt.Printf("CIDs are equal: %t\n", c1.Equal(c2))

	// Show CID properties
	fmt.Printf("Codec: %d\n", c1.Codec())
	fmt.Printf("Hash type: %d\n", c1.HashType())
}

Output:
CID from string: bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4
CID from bytes: bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4
CIDs are equal: true
Codec: 85
Hash type: 18

Index

Examples

Constants

View Source 
const (
	// All DASL CIDs are 36 bytes long
	// 4 header bytes + 32 hash digest bytes
	CidBinaryLength = 36

	// Encoded as a base32 string it is 58 bytes, plus the 'b' prefix.
	CidStrLength = 59

	CidVersion              = 0x01
	CodecRaw       Codec    = 0x55
	CodecDrisl     Codec    = 0x71
	HashTypeSha256 HashType = 0x12
	HashTypeBlake3 HashType = 0x1e

	// The hash digest length
	HashSize = 32
)

Variables

View Source 
var (

	// EmptyCid is a raw SHA-256 CID that represents no data.
	// Its digest is the SHA-256 hash of the empty byte string "".
	// Try not to use it as a sentinel value.
	EmptyCid = Cid{/* contains filtered or unexported fields */}

	ErrUndefinedCid = errors.New("go-dasl/cid: cannot marshal nil Cid (use omitzero over omitempty)")
)

Functions

This section is empty.

Types

type Cid 

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

Cid is a DASL CID.

It is always valid, unless created directly such as cid.Cid{} or new(cid.Cid). That will cause invalid output if methods are called upon it, unless otherwise documented. Marshal methods like MarshalBinary can return errors, and so will check for this and return UndefinedCidError instead of panicing or encoding an invalid CID.

Programs using CIDs should typically store and pass them as values, not pointers. That is, CID variables and struct fields should be of type cid.Cid, not *cid.Cid.

If you want to omit empty CID values from being encoded, use the omitzero struct tag instead of omitempty.

https://dasl.ing/cid.html

func HashBytes 

func HashBytes(b []byte) Cid

HashBytes creates a raw SHA-256 CID by hashing the provided bytes.

func HashBytesBlake3 added in v0.8.0 

func HashBytesBlake3(b []byte) Cid

HashBytesBlake3 creates a raw BLAKE3 CID by hashing the provided bytes.

func HashReader 

func HashReader(r io.Reader) (Cid, error)

HashReader creates a raw SHA-256 CID by hashing all the data in the reader. Any error returned comes from the reader.

func HashReaderBlake3 added in v0.8.0 

func HashReaderBlake3(r io.Reader) (Cid, error)

HashReaderBlake3 creates a raw Blake3 CID by hashing all the data in the reader. Any error returned comes from the reader.

func MustNewCidFromBytes added in v0.3.0 

func MustNewCidFromBytes(b []byte) Cid

MustNewCidFromBytes calls NewCidFromBytes and panics if it returns an error.

func MustNewCidFromString added in v0.3.0 

func MustNewCidFromString(s string) Cid

MustNewCidFromString calls NewCidFromString and panics if it returns an error.

func NewCidFromBytes 

func NewCidFromBytes(in []byte) (Cid, error)

NewCidFromBytes parses a binary DASL CID. A ForbiddenCidError is returned if it is invalid in any way.

Note this is not the same as the bytes for a CID encoded in DRISL (CBOR).

The input data is copied and so can be modified afterward.

func NewCidFromInfo 

func NewCidFromInfo(codec Codec, hashType HashType, digest [HashSize]byte) (Cid, error)

NewCidFromInfo creates a DASL CID manually from the codec, hash type, and hash digest. An error is only returned if the codec or hashType provided don't conform to DASL.

func NewCidFromReader 

func NewCidFromReader(r ReadByteReader) (Cid, error)

NewCidFromReader parses a binary DASL CID from the given reader. A ForbiddenCidError is returned if it is invalid in any way. Extra data after the CID is allowed.

Note this is not the same as the bytes for a CID encoded in DRISL (CBOR).

If your reader does not support io.ByteReader, you can easily fulfill this interface by wrapping it with bufio.NewReader.

func NewCidFromString 

func NewCidFromString(s string) (Cid, error)

NewCidFromString parses a string DASL CID. A ForbiddenCidError is returned if it is invalid DASL.

func (Cid) AppendBinary added in v0.5.0 

func (c Cid) AppendBinary(b []byte) ([]byte, error)

AppendBinary fulfills the encoding.BinaryAppender interface. It simply appends the Bytes() output.

func (Cid) Bytes 

func (c Cid) Bytes() []byte

Bytes returns the CID in binary format. It is safe to modify. It is always CidBinaryLength bytes long. Note this is not the representation used in DRISL (CBOR).

func (Cid) Codec 

func (c Cid) Codec() Codec

Codec returns the codec of the CID.

func (Cid) Defined 

func (c Cid) Defined() bool

Defined returns false if this Cid has no data due to being created with cid.Cid{} or new(cid.Cid). This method shouldn't be needed as long as you don't do this.

func (Cid) Digest 

func (c Cid) Digest() [HashSize]byte

Digest returns the hash digest stored in the CID. It is safe to modify.

func (Cid) Equal added in v0.7.0 

func (c Cid) Equal(o Cid) bool

Equal returns true if the two CIDs are exactly the same.

CIDs with the same hash type and digest but different codecs are not considered equal.

This is equivalent to comparing the .Bytes() or .String() output of two CIDs, but more efficient.

func (Cid) HashType 

func (c Cid) HashType() HashType

HashType returns the hash type of the CID.

func (Cid) Hasher added in v0.8.0 

func (c Cid) Hasher() hash.Hash

Hasher returns a new appropriate hash interface based on the hash type of the CID.

This could be used to hash some data and compare against the CID digest, although note VerifyBytes and VerifyReader already do that.

func (Cid) MarshalBinary added in v0.5.0 

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

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

func (Cid) MarshalCBOR 

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

MarshalCBOR fulfills the drisl.Marshaler interface.

func (Cid) MarshalJSON added in v0.5.0 

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

MarshalJSON fulfills the json.Marshaler interface. It follows the ATproto standard: {"$link": "bafkr..."}

This is just for simple display purposes.

func (Cid) MarshalText added in v0.5.0 

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

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

func (Cid) String 

func (c Cid) String() string

String returns the CID in string format. It will always be CidStrLength bytes (or ASCII characters) long.

func (*Cid) UnmarshalBinary added in v0.5.0 

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

UnmarshalBinary fulfills the encoding.BinaryUnmarshaler interface. It is equivalent to NewCidFromBytes.

func (*Cid) UnmarshalCBOR 

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

UnmarshalCBOR fulfills the drisl.Unmarshaler interface.

func (*Cid) UnmarshalJSON added in v0.8.0 

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

UnmarshalJSON fulfills the json.Unmarshaler interface. It follows the ATproto standard: {"$link": "bafkr..."}

func (*Cid) UnmarshalText added in v0.5.0 

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

UnmarshalText fulfills the encoding.TextUnmarshaler interface. It is equivalent to NewCidFromString.

func (Cid) VerifyBytes added in v0.8.0 

func (c Cid) VerifyBytes(b []byte) bool

VerifyBytes checks whether the provided bytes match the hash digest in the CID. The codec information is not checked.

func (Cid) VerifyReader added in v0.8.0 

func (c Cid) VerifyReader(r io.Reader) (bool, error)

VerifyReader checks whether the provided reader data matches the hash digest in the CID. The codec information is not checked.

type Codec 

type Codec byte

Codec is the encoding of the data represented by the CID.

type ForbiddenCidError 

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

ForbiddenCidError is returned if the CID is invalid in some way according to the DRISL spec.

func (*ForbiddenCidError) Error 

func (e *ForbiddenCidError) Error() string

type HashType 

type HashType byte

HashType is the algorithm of the hash digest embedded in the CID.

type RawCid added in v0.4.0 

type RawCid []byte

RawCid is an unvalidated CID.

It is used to store CID information when decoding non-DASL CIDs from DRISL is enabled. You can also use it to encode non-DASL CIDs. Only do this if you are not working in a DASL-compliant ecosystem!

It holds the bytes of a binary CID. It is not the same bytes as CID-in-CBOR.

There are no guarantees this is a valid CID by any spec.

You can pass it to NewCidFromBytes to validate it as a DASL CID, or to the Cast function of the go-cid library to parse it as an original IPFS CID.

func (RawCid) MarshalCBOR added in v0.4.0 

func (c RawCid) MarshalCBOR() ([]byte, error)

func (RawCid) String added in v0.4.0 

func (c RawCid) String() string

func (*RawCid) UnmarshalCBOR added in v0.4.0 

func (c *RawCid) UnmarshalCBOR(b []byte) error

type ReadByteReader added in v0.4.0 

type ReadByteReader interface {
	io.Reader
	io.ByteReader
}

Source Files

View all Source files

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.