schema

Documentation

Overview

Package schema defines the makeup of an advertisement. An advertisement is used to inform an indexer that there are updates to a provider's content. The IsRm and Entries fields determine how the indexer handles the advertisement, as described by the following table:

IsRm    Entries    Action

------+-----------+------------------------------------ false | NoEntries | Update metadata false | data | Update metadata and index entries true | NoEntries | Delete content with context ID true | data | Delete content with context ID (ignore entries)

When removing content (IsRm true) the metadata and entries are ignored. An advertisement that removes content cannot have extended provider information.

All advertisements update the provider's addresses. To create an advertisement that only updates a provider's address, create an advertisement that contains no metadata and no entries.

Index

• Constants
• Variables
• type Advertisement
  • func BytesToAdvertisement(adCid cid.Cid, data []byte) (Advertisement, error)
  • func UnwrapAdvertisement(node ipld.Node) (*Advertisement, error)
  • func (a Advertisement) PreviousCid() cid.Cid
  • func (ad *Advertisement) Sign(key crypto.PrivKey) error
  • func (ad *Advertisement) SignWithExtendedProviders(key crypto.PrivKey, ...) error
  • func (a Advertisement) ToNode() (n ipld.Node, err error)
  • func (a Advertisement) Validate() error
  • func (ad *Advertisement) VerifySignature() (peer.ID, error)
• type EntryChunk
  • func BytesToEntryChunk(entCid cid.Cid, data []byte) (EntryChunk, error)
  • func UnwrapEntryChunk(node ipld.Node) (*EntryChunk, error)
  • func (e EntryChunk) ToNode() (n ipld.Node, err error)
• type ExtendedProvider
• type Provider

Constants

const (
	// MaxContextIDLen specifies the maximum number of bytes accepted as Advertisement.ContextID.
	MaxContextIDLen = 64
	// MaxMetadataLen specifies the maximum number of bytes an advertisement metadata can contain.
	MaxMetadataLen = 1024 // 1KiB
)

Variables

var (
	// NoEntries is a special value used to explicitly indicate that an
	// advertisement does not have any entries. When isRm is true it and serves to
	// remove content by context ID, and when isRm is false it serves to update
	// metadata only.
	NoEntries cidlink.Link

	// Linkproto is the ipld.LinkProtocol used for the ingestion protocol.
	// Refer to it if you have encoding questions.
	Linkproto = cidlink.LinkPrototype{
		Prefix: cid.Prefix{
			Version:  1,
			Codec:    uint64(multicodec.DagJson),
			MhType:   uint64(multicodec.Sha2_256),
			MhLength: -1,
		},
	}

	// AdvertisementPrototype represents the IPLD node prototype of Advertisement.
	//
	// See: bindnode.Prototype.
	AdvertisementPrototype schema.TypedPrototype

	// EntryChunkPrototype represents the IPLD node prototype of EntryChunk.
	//
	// See: bindnode.Prototype.
	EntryChunkPrototype schema.TypedPrototype
)

Types

type Advertisement

type Advertisement struct {
	PreviousID       ipld.Link
	Provider         string
	Addresses        []string
	Signature        []byte
	Entries          ipld.Link
	ContextID        []byte
	Metadata         []byte
	IsRm             bool
	ExtendedProvider *ExtendedProvider
}

func BytesToAdvertisement

func BytesToAdvertisement(adCid cid.Cid, data []byte) (Advertisement, error)

BytesToAdvertisement deserializes an Advertisement from a buffer. It does not check that the given CID matches the data, as this should have been done when the data was acquired.

func UnwrapAdvertisement

func UnwrapAdvertisement(node ipld.Node) (*Advertisement, error)

UnwrapAdvertisement unwraps the given node as an advertisement.

Note that the node is reassigned to AdvertisementPrototype if its prototype is different. Therefore, it is recommended to load the node using the correct prototype initially function to avoid unnecessary node assignment.

func (Advertisement) PreviousCid

func (a Advertisement) PreviousCid() cid.Cid

Return the Advertisement's previous CID, or cid.Undef if there is no previous CID.

func (*Advertisement) Sign

func (ad *Advertisement) Sign(key crypto.PrivKey) error

Sign signs an advertisement using the given private key. This function will return an error if used to sign an ad with extended providers.

func (*Advertisement) SignWithExtendedProviders

func (ad *Advertisement) SignWithExtendedProviders(key crypto.PrivKey, extendedProviderKeyFetcher func(string) (crypto.PrivKey, error)) error

SignWithExtendedProviders signs an advertisement by the main provider as well as by all extended providers if they are present.

func (Advertisement) ToNode

func (a Advertisement) ToNode() (n ipld.Node, err error)

ToNode converts this advertisement to its representation as an IPLD typed node.

See: bindnode.Wrap.

func (Advertisement) Validate

func (a Advertisement) Validate() error

func (*Advertisement) VerifySignature

func (ad *Advertisement) VerifySignature() (peer.ID, error)

VerifySignature verifies that the advertisement has been signed and generated correctly. Returns the peer ID of the signer.

The signer may be different than the provider ID in the advertisement, so the caller will need to check if the signer is allowed to sign this advertisement.

Extended providers signatures are also verified.

type EntryChunk

type EntryChunk struct {
	Entries []multihash.Multihash
	Next    ipld.Link
}

func BytesToEntryChunk

func BytesToEntryChunk(entCid cid.Cid, data []byte) (EntryChunk, error)

BytesToEntryChunk deserializes an EntryChunk from a buffer. It does not check that the given CID matches the data, as this should have been done when the data was acquired.

func UnwrapEntryChunk

func UnwrapEntryChunk(node ipld.Node) (*EntryChunk, error)

UnwrapEntryChunk unwraps the given node as an entry chunk.

Note that the node is reassigned to EntryChunkPrototype if its prototype is different. Therefore, it is recommended to load the node using the correct prototype initially function to avoid unnecessary node assignment.

func (EntryChunk) ToNode

func (e EntryChunk) ToNode() (n ipld.Node, err error)

ToNode converts this entry chunk to its representation as an IPLD typed node.

See: bindnode.Wrap.

type ExtendedProvider

type ExtendedProvider struct {
	Providers []Provider
	Override  bool
}

type Provider

type Provider struct {
	ID        string
	Addresses []string
	Metadata  []byte
	Signature []byte
}