retrievalimpl

Documentation

Overview

Package retrievalimpl provides the primary implementation of retrieval market top level interfaces interfaces

This package provides a production implementation of `RetrievalClient` and `RetrievalProvider`.

Index

• Variables
• func NewClient(network rmnet.RetrievalMarketNetwork, multiStore *multistore.MultiStore, ...) (retrievalmarket.RetrievalClient, error)
• func NewProvider(minerAddress address.Address, node retrievalmarket.RetrievalProviderNode, ...) (retrievalmarket.RetrievalProvider, error)
• type Client
  • func (c *Client) CancelDeal(dealID retrievalmarket.DealID) error
  • func (c *Client) FindProviders(payloadCID cid.Cid) []retrievalmarket.RetrievalPeer
  • func (c *Client) GetDeal(dealID retrievalmarket.DealID) (retrievalmarket.ClientDealState, error)
  • func (c *Client) ListDeals() (map[retrievalmarket.DealID]retrievalmarket.ClientDealState, error)
  • func (c *Client) Query(ctx context.Context, p retrievalmarket.RetrievalPeer, payloadCID cid.Cid, ...) (retrievalmarket.QueryResponse, error)
  • func (c *Client) Retrieve(ctx context.Context, payloadCID cid.Cid, params retrievalmarket.Params, ...) (retrievalmarket.DealID, error)
  • func (c *Client) SubscribeToEvents(subscriber retrievalmarket.ClientSubscriber) retrievalmarket.Unsubscribe
  • func (c *Client) TryRestartInsufficientFunds(paymentChannel address.Address) error
• type DealDecider
• type Provider
  • func (p *Provider) Configure(opts ...RetrievalProviderOption)
  • func (p *Provider) GetAsk() *retrievalmarket.Ask
  • func (p *Provider) HandleQueryStream(stream rmnet.RetrievalQueryStream)
  • func (p *Provider) ListDeals() map[retrievalmarket.ProviderDealIdentifier]retrievalmarket.ProviderDealState
  • func (p *Provider) SetAsk(ask *retrievalmarket.Ask)
  • func (p *Provider) Start() error
  • func (p *Provider) Stop() error
  • func (p *Provider) SubscribeToEvents(subscriber retrievalmarket.ProviderSubscriber) retrievalmarket.Unsubscribe
• type RetrievalProviderOption
  • func DealDeciderOpt(dd DealDecider) RetrievalProviderOption

Variables

var ClientFSMParameterSpec = fsm.Parameters{
	Environment:     &clientDealEnvironment{},
	StateType:       retrievalmarket.ClientDealState{},
	StateKeyField:   "Status",
	Events:          clientstates.ClientEvents,
	StateEntryFuncs: clientstates.ClientStateEntryFuncs,
}

ClientFSMParameterSpec is a valid set of parameters for a client deal FSM - used in doc generation

var ProviderFSMParameterSpec = fsm.Parameters{
	Environment:     &providerDealEnvironment{},
	StateType:       retrievalmarket.ProviderDealState{},
	StateKeyField:   "Status",
	Events:          providerstates.ProviderEvents,
	StateEntryFuncs: providerstates.ProviderStateEntryFuncs,
}

ProviderFSMParameterSpec is a valid set of parameters for a provider FSM - used in doc generation

Functions

func NewClient

func NewClient(
	network rmnet.RetrievalMarketNetwork,
	multiStore *multistore.MultiStore,
	dataTransfer datatransfer.Manager,
	node retrievalmarket.RetrievalClientNode,
	resolver retrievalmarket.PeerResolver,
	ds datastore.Batching,
	storedCounter *storedcounter.StoredCounter,
) (retrievalmarket.RetrievalClient, error)

NewClient creates a new retrieval client

func NewProvider

func NewProvider(minerAddress address.Address,
	node retrievalmarket.RetrievalProviderNode,
	network rmnet.RetrievalMarketNetwork,
	pieceStore piecestore.PieceStore,
	multiStore *multistore.MultiStore,
	dataTransfer datatransfer.Manager,
	ds datastore.Batching,
	opts ...RetrievalProviderOption,
) (retrievalmarket.RetrievalProvider, error)

NewProvider returns a new retrieval Provider

Types

type Client

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

Client is the production implementation of the RetrievalClient interface

func (*Client) CancelDeal

func (c *Client) CancelDeal(dealID retrievalmarket.DealID) error

CancelDeal attempts to cancel an in progress deal

func (*Client) FindProviders

func (c *Client) FindProviders(payloadCID cid.Cid) []retrievalmarket.RetrievalPeer

FindProviders uses PeerResolver interface to locate a list of providers who may have a given payload CID.

func (*Client) GetDeal

func (c *Client) GetDeal(dealID retrievalmarket.DealID) (retrievalmarket.ClientDealState, error)

GetDeal returns a given deal by deal ID, if it exists

func (*Client) ListDeals

func (c *Client) ListDeals() (map[retrievalmarket.DealID]retrievalmarket.ClientDealState, error)

ListDeals lists all known retrieval deals

func (*Client) Query

func (c *Client) Query(ctx context.Context, p retrievalmarket.RetrievalPeer, payloadCID cid.Cid, params retrievalmarket.QueryParams) (retrievalmarket.QueryResponse, error)

Query sends a retrieval query to a specific retrieval provider, to determine if the provider can serve a retrieval request and what its specific parameters for the request are.

The client creates a new `RetrievalQueryStream` for the chosen peer ID, and calls `WriteQuery` on it, which constructs a data-transfer message and writes it to the Query stream.

func (*Client) Retrieve

func (c *Client) Retrieve(ctx context.Context, payloadCID cid.Cid, params retrievalmarket.Params, totalFunds abi.TokenAmount, p retrievalmarket.RetrievalPeer, clientWallet address.Address, minerWallet address.Address, storeID *multistore.StoreID) (retrievalmarket.DealID, error)

Retrieve initiates the retrieval deal flow, which involves multiple requests and responses

To start this processes, the client creates a new `RetrievalDealStream`. Currently, this connection is kept open through the entire deal until completion or failure. Make deals pauseable as well as surviving a restart is a planned future feature.

Retrieve should be called after using FindProviders and Query are used to identify an appropriate provider to retrieve the deal from. The parameters identified in Query should be passed to Retrieve to ensure the greatest likelihood the provider will accept the deal

When called, the client takes the following actions:

1. Creates a deal ID using the next value from its `storedCounter`.

2. Constructs a `DealProposal` with deal terms

3. Tells its statemachine to begin tracking this deal state by dealID.

4. Constructs a `blockio.SelectorVerifier` and adds it to its dealID-keyed map of block verifiers.

5. Triggers a `ClientEventOpen` event on its statemachine.

From then on, the statemachine controls the deal flow in the client. Other components may listen for events in this flow by calling `SubscribeToEvents` on the Client. The Client handles consuming blocks it receives from the provider, via `ConsumeBlocks` function

Documentation of the client state machine can be found at https://godoc.org/github.com/filecoin-project/go-fil-markets/retrievalmarket/impl/clientstates

func (*Client) SubscribeToEvents

func (c *Client) SubscribeToEvents(subscriber retrievalmarket.ClientSubscriber) retrievalmarket.Unsubscribe

SubscribeToEvents allows another component to listen for events on the RetrievalClient in order to track deals as they progress through the deal flow

func (*Client) TryRestartInsufficientFunds

func (c *Client) TryRestartInsufficientFunds(paymentChannel address.Address) error

TryRestartInsufficientFunds attempts to restart any deals stuck in the insufficient funds state after funds are added to a given payment channel

type DealDecider

type DealDecider func(ctx context.Context, state retrievalmarket.ProviderDealState) (bool, string, error)

DealDecider is a function that makes a decision about whether to accept a deal

type Provider

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

Provider is the production implementation of the RetrievalProvider interface

func (*Provider) Configure

func (p *Provider) Configure(opts ...RetrievalProviderOption)

Configure reconfigures a provider after initialization

func (*Provider) GetAsk

func (p *Provider) GetAsk() *retrievalmarket.Ask

GetAsk returns the current deal parameters this provider accepts

func (*Provider) HandleQueryStream

func (p *Provider) HandleQueryStream(stream rmnet.RetrievalQueryStream)

HandleQueryStream is called by the network implementation whenever a new message is received on the query protocol

A Provider handling a retrieval `Query` does the following:

1. Get the node's chain head in order to get its miner worker address.

2. Look in its piece store to determine if it can serve the given payload CID.

3. Combine these results with its existing parameters for retrieval deals to construct a `retrievalmarket.QueryResponse` struct.

4. Writes this response to the `Query` stream.

The connection is kept open only as long as the query-response exchange.

func (*Provider) ListDeals

func (p *Provider) ListDeals() map[retrievalmarket.ProviderDealIdentifier]retrievalmarket.ProviderDealState

ListDeals lists all known retrieval deals

func (*Provider) SetAsk

func (p *Provider) SetAsk(ask *retrievalmarket.Ask)

SetAsk sets the deal parameters this provider accepts

func (*Provider) Start

func (p *Provider) Start() error

Start begins listening for deals on the given host. Start must be called in order to accept incoming deals.

func (*Provider) Stop

func (p *Provider) Stop() error

Stop stops handling incoming requests.

func (*Provider) SubscribeToEvents

func (p *Provider) SubscribeToEvents(subscriber retrievalmarket.ProviderSubscriber) retrievalmarket.Unsubscribe

SubscribeToEvents listens for events that happen related to client retrievals

type RetrievalProviderOption

type RetrievalProviderOption func(p *Provider)

RetrievalProviderOption is a function that configures a retrieval provider

func DealDeciderOpt

func DealDeciderOpt(dd DealDecider) RetrievalProviderOption

DealDeciderOpt sets a custom protocol