types

package
v0.24.0 Latest Latest
Warning

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

 Go to latest Published: Dec 19, 2024 License: Apache-2.0, MIT Imports: 28 Imported by: 11

Documentation

Index

Constants

View Source 
const (
	RaceCoordination       = "race"
	SequentialCoordination = "sequential"
)
View Source 
const BitswapIndentifier = "Bitswap"
View Source 
const FilecoinPrecision = uint64(1_000_000_000_000_000_000)

Variables

View Source 
var ErrIncorrectContextValue = errors.New("context key does not point to a valid retrieval id")

ErrIncorrectContextValue indicates a value for the retrieval id context key that wasn't a retrieval id

View Source 
var ErrMissingContextKey = errors.New("context key for retrieval is missing")

ErrMissingContextKey indicates no retrieval context key was present for a given context

Functions

func IsUnknownPeerID added in v0.20.0 

func IsUnknownPeerID(p peer.ID) bool

func MakeAsyncCandidates added in v0.6.0 

func MakeAsyncCandidates(buffer int) (InboundAsyncCandidates, OutboundAsyncCandidates)

func ParseProtocolsString added in v0.6.9 

func ParseProtocolsString(v string) ([]multicodec.Code, error)

func QueryResponseFromReader added in v0.4.0 

func QueryResponseFromReader(r io.Reader) (*retrievaltypes.QueryResponse, error)

QueryResponseFromReader reads a QueryResponse object in dag-cbor form from a stream

func QueryToWriter added in v0.4.0 

func QueryToWriter(q *retrievaltypes.Query, w io.Writer) error

QueryToWriter writes a Query object in dag-cbor form to a stream

func RegisterRetrievalIDToContext added in v0.4.0 

func RegisterRetrievalIDToContext(parentCtx context.Context, id RetrievalID) context.Context

func ToProviderString added in v0.16.0 

func ToProviderString(ai []Provider) (string, error)

Types

type AsyncCandidateSplitter added in v0.6.0 

type AsyncCandidateSplitter[T comparable] interface {
	SplitRetrievalRequest(ctx context.Context, request RetrievalRequest, events func(RetrievalEvent)) AsyncRetrievalSplitter[T]
}

type AsyncRetrievalSplitter added in v0.6.0 

type AsyncRetrievalSplitter[T comparable] interface {
	SplitAsyncCandidates(asyncCandidates InboundAsyncCandidates) (map[T]InboundAsyncCandidates, <-chan error)
}

type AsyncRetrievalTask added in v0.6.0 

type AsyncRetrievalTask struct {
	Candidates              InboundAsyncCandidates
	AsyncCandidateRetrieval CandidateRetrieval
}

AsyncRetrievalTask runs an asynchronous retrieval and returns a result

func (AsyncRetrievalTask) Run added in v0.6.0 

func (art AsyncRetrievalTask) Run() (*RetrievalStats, error)

Run executes the asynchronous retrieval task

type CandidateFinder added in v0.4.0 

type CandidateFinder interface {
	FindCandidates(ctx context.Context, request RetrievalRequest, events func(RetrievalEvent), onCandidates func([]RetrievalCandidate)) error
}

type CandidateRetrieval added in v0.4.0 

type CandidateRetrieval interface {
	RetrieveFromAsyncCandidates(asyncCandidates InboundAsyncCandidates) (*RetrievalStats, error)
}

type CandidateRetriever added in v0.3.0 

type CandidateRetriever interface {
	Retrieve(ctx context.Context, request RetrievalRequest, events func(RetrievalEvent)) CandidateRetrieval
}

type CandidateSource added in v0.22.0 

type CandidateSource interface {
	FindCandidates(context.Context, cid.Cid, func(RetrievalCandidate)) error
}

type CandidateSplitter added in v0.4.0 

type CandidateSplitter[T comparable] interface {
	SplitRetrievalRequest(ctx context.Context, request RetrievalRequest, events func(RetrievalEvent)) RetrievalSplitter[T]
}

type CoordinationKind added in v0.4.0 

type CoordinationKind string

type DeferredErrorTask added in v0.6.0 

type DeferredErrorTask struct {
	Ctx     context.Context
	ErrChan <-chan error
}

DeferredErrorTask simply reads from an error channel and returns the result as an error

func (DeferredErrorTask) Run added in v0.6.0 

func (det DeferredErrorTask) Run() (*RetrievalStats, error)

Run reads the error channel and returns a result

type EventCode added in v0.3.0 

type EventCode string
const (
	CandidatesFoundCode          EventCode = "candidates-found"
	CandidatesFilteredCode       EventCode = "candidates-filtered"
	StartedCode                  EventCode = "started"
	StartedFetchCode             EventCode = "started-fetch"
	StartedFindingCandidatesCode EventCode = "started-finding-candidates"
	StartedRetrievalCode         EventCode = "started-retrieval"
	ConnectedToProviderCode      EventCode = "connected-to-provider"
	QueryAskedCode               EventCode = "query-asked"
	QueryAskedFilteredCode       EventCode = "query-asked-filtered"
	ProposedCode                 EventCode = "proposed"
	AcceptedCode                 EventCode = "accepted"
	FirstByteCode                EventCode = "first-byte-received"
	FailedCode                   EventCode = "failed"
	FailedRetrievalCode          EventCode = "failed-retrieval"
	SuccessCode                  EventCode = "success"
	FinishedCode                 EventCode = "finished"
	BlockReceivedCode            EventCode = "block-received"
)

type FIL 

type FIL gostatetypesbig.Int

func (FIL) String 

func (f FIL) String() string

func (FIL) Unitless 

func (f FIL) Unitless() string

type FetchConfig added in v0.19.0 

type FetchConfig struct {
	EventsCallback func(RetrievalEvent)
}

func NewFetchConfig added in v0.19.0 

func NewFetchConfig(opts ...FetchOption) FetchConfig

NewFetchConfig creates a new FetchConfig with the given options.

type FetchOption added in v0.19.0 

type FetchOption func(cfg *FetchConfig)

func WithEventsCallback added in v0.19.0 

func WithEventsCallback(callback func(RetrievalEvent)) FetchOption

WithEventsCallback sets the callback function for events that occur during the retrieval process. Only one callback can be set per retrieval.

type Fetcher added in v0.14.3 

type Fetcher interface {
	Fetch(context.Context, RetrievalRequest, ...FetchOption) (*RetrievalStats, error)
}

type FindCandidatesResult added in v0.4.0 

type FindCandidatesResult struct {
	Candidate RetrievalCandidate
	Err       error
}

type InboundAsyncCandidates added in v0.6.0 

type InboundAsyncCandidates <-chan []RetrievalCandidate

func (InboundAsyncCandidates) Next added in v0.6.0 

func (ias InboundAsyncCandidates) Next(ctx context.Context) (bool, []RetrievalCandidate, error)

type OutboundAsyncCandidates added in v0.6.0 

type OutboundAsyncCandidates chan<- []RetrievalCandidate

func (OutboundAsyncCandidates) SendNext added in v0.6.0 

func (oas OutboundAsyncCandidates) SendNext(ctx context.Context, next []RetrievalCandidate) error

type Provider added in v0.22.0 

type Provider struct {
	Peer      peer.AddrInfo
	Protocols []metadata.Protocol
}

func ParseProviderStrings added in v0.9.0 

func ParseProviderStrings(v string) ([]Provider, error)

type QueueRetrievalsFn added in v0.6.0 

type QueueRetrievalsFn func(ctx context.Context, nextRetrievalCall func(RetrievalTask))

type ReadableWritableStorage added in v0.5.0 

type ReadableWritableStorage interface {
	ipldstorage.ReadableStorage
	ipldstorage.WritableStorage
	ipldstorage.StreamingReadableStorage
}

type RetrievalCandidate added in v0.3.0 

type RetrievalCandidate struct {
	MinerPeer peer.AddrInfo
	RootCid   cid.Cid
	Metadata  metadata.Metadata
}

RetrievalCandidate describes a peer and CID combination that can be used to retrieve data from the peer. The RootCid describes the head of an IPLD graph that is being retrieved. The MinerPeer is the peer that is (apparently) storing the data.

The Metadata field contains information about the protocols supported by the peer that may be used to further refine how the retrieval is performed.

func NewRetrievalCandidate added in v0.3.0 

func NewRetrievalCandidate(pid peer.ID, addrs []multiaddr.Multiaddr, rootCid cid.Cid, protocols ...metadata.Protocol) RetrievalCandidate

NewRetrievalCandidate creates a new RetrievalCandidate with the given parameters.

func (RetrievalCandidate) ToURL added in v0.10.0 

func (rc RetrievalCandidate) ToURL() (*url.URL, error)

ToURL generates a valid HTTP URL from the candidate if possible

type RetrievalCoordinator added in v0.4.0 

type RetrievalCoordinator func(context.Context, QueueRetrievalsFn) (*RetrievalStats, error)

type RetrievalEvent added in v0.3.0 

type RetrievalEvent interface {
	fmt.Stringer

	// Time returns the time that the event occurred
	Time() time.Time
	// RetrievalId returns the unique ID for this retrieval
	RetrievalId() RetrievalID
	// Code returns the type of event this is
	Code() EventCode
	// RootCid returns the CID being requested
	RootCid() cid.Cid
}

type RetrievalEventSubscriber added in v0.3.0 

type RetrievalEventSubscriber func(event RetrievalEvent)

RetrievalEventSubscriber is a function that receives a stream of retrieval events from all retrievals that are in progress. Various different types implement the RetrievalEvent interface and may contain additional information about the event beyond what is available on the RetrievalEvent interface.

type RetrievalID added in v0.3.0 

type RetrievalID uuid.UUID

func NewRetrievalID added in v0.3.0 

func NewRetrievalID() (RetrievalID, error)

func RetrievalIDFromContext added in v0.4.0 

func RetrievalIDFromContext(ctx context.Context) (RetrievalID, error)

func (RetrievalID) MarshalText added in v0.3.0 

func (id RetrievalID) MarshalText() ([]byte, error)

func (RetrievalID) String added in v0.3.0 

func (id RetrievalID) String() string

func (*RetrievalID) UnmarshalText added in v0.3.0 

func (id *RetrievalID) UnmarshalText(data []byte) error

type RetrievalRequest added in v0.3.0 

type RetrievalRequest struct {
	trustlessutils.Request

	// RetrievalID is a unique identifier for this request.
	RetrievalID RetrievalID

	// LinkSystem is the destination for the blocks to fetch, it may be
	// pre-populated with existing blocks in the DAG, in which case they may
	// be used to satisfy the request (except in the case of an HTTP retrieval,
	// which will fetch the entire DAG, regardless).
	LinkSystem ipld.LinkSystem

	// Selector is the IPLD selector to use when fetching the DAG. If nil, the
	// Path and Scope will be used to generate a selector.
	Selector ipld.Node

	// Protocols is an optional list of protocols to use when fetching the DAG.
	// If nil, the default protocols will be used.
	Protocols []multicodec.Code

	// PreloadLinkSystem must be setup to enable Bitswap preload behavior. This
	// LinkSystem must be thread-safe as multiple goroutines may be using it to
	// store and retrieve blocks concurrently.
	PreloadLinkSystem ipld.LinkSystem

	// MaxBlocks optionally specifies the maximum number of blocks to fetch.
	// If zero, no limit is applied.
	MaxBlocks uint64

	// Providers optionally specifies a list of peers to use when fetching
	// blocks. If nil, the default peer discovery mechanism will be used.
	Providers []Provider
}

RetrievalRequest describes the parameters of a request. It is intended to be immutable.

func NewRequestForPath added in v0.5.0 

func NewRequestForPath(
	store ipldstorage.WritableStorage,
	rootCid cid.Cid,
	path string,
	dagScope trustlessutils.DagScope,
	byteRange *trustlessutils.ByteRange,
) (RetrievalRequest, error)

NewRequestForPath creates a new RetrievalRequest for the given root CID as the head of the graph to fetch, the path within that graph to fetch, the scope that dictates the depth of fetching withint he graph and the byte range to fetch if intending to fetch part of a large UnixFS file.

The byteRange parameter should be left nil if this is not a request for a partial UnixFS file; and if it is set, the dagScope should be DagScopeEntity.

The LinkSystem is configured to use the provided store for both reading and writing and it is explicitly set to be trusted (i.e. it will not check CIDs match bytes). If the storage is not truested, request.LinkSystem.TrustedStore should be set to false after this call.

func (RetrievalRequest) GetDescriptorString added in v0.16.0 

func (r RetrievalRequest) GetDescriptorString() (string, error)

GetDescriptorString returns a URL and query string-style descriptor string for the request. This is different from GetUrlPath as it is not intended (nor safe) to use as an HTTP request. Instead, this should be used for logging and other descriptive purposes.

If this request uses an explicit Selector rather than a Path, an error will be returned.

func (RetrievalRequest) GetSelector added in v0.5.0 

func (r RetrievalRequest) GetSelector() ipld.Node

GetSelector will safely return a selector for this request. If none has been set, it will generate one for the path & scope.

func (RetrievalRequest) GetSupportedProtocols added in v0.6.9 

func (r RetrievalRequest) GetSupportedProtocols(allSupportedProtocols []multicodec.Code) []multicodec.Code

GetSupportedProtocols will safely return the supported protocols for a specific request. It takes a list of all supported protocols, and -- if the request has protocols, it will return all the request protocols that are in the supported list -- if the request has no protocols, it will return the entire supported protocol list

func (RetrievalRequest) HasPreloadLinkSystem added in v0.13.0 

func (r RetrievalRequest) HasPreloadLinkSystem() bool

type RetrievalResult added in v0.4.0 

type RetrievalResult struct {
	Stats *RetrievalStats
	Err   error
}

type RetrievalSplitter added in v0.4.0 

type RetrievalSplitter[T comparable] interface {
	SplitCandidates([]RetrievalCandidate) (map[T][]RetrievalCandidate, error)
}

type RetrievalStats added in v0.3.0 

type RetrievalStats struct {
	StorageProviderId peer.ID
	RootCid           cid.Cid
	Size              uint64
	Blocks            uint64
	Duration          time.Duration
	AverageSpeed      uint64
	TotalPayment      abi.TokenAmount
	NumPayments       int
	AskPrice          abi.TokenAmount
	TimeToFirstByte   time.Duration
	Selector          string
}

type RetrievalTask added in v0.6.0 

type RetrievalTask interface {
	Run() (*RetrievalStats, error)
}

retrieval task is any task that can be run to produce a result

type Retriever added in v0.3.0 

type Retriever interface {
	Retrieve(ctx context.Context, request RetrievalRequest, events func(RetrievalEvent)) (*RetrievalStats, error)
}

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.