Documentation
¶
Overview ¶
Package clientstates contains state machine logic relating to the `StorageMarket`.
client_fsm.go is where the state transitions are defined, and the default handlers for each new state are defined.
client_states.go contains state handler functions.
The following diagram illustrates the operation of the client state machine. This diagram is auto-generated from current code and should remain up to date over time:
https://raw.githubusercontent.com/filecoin-project/go-fil-markets/master/docs/storageclient.mmd.svg
Index ¶
- Variables
- func CheckForDealAcceptance(ctx fsm.Context, environment ClientDealEnvironment, ...) error
- func EnsureClientFunds(ctx fsm.Context, environment ClientDealEnvironment, ...) error
- func FailDeal(ctx fsm.Context, environment ClientDealEnvironment, ...) error
- func InitiateDataTransfer(ctx fsm.Context, environment ClientDealEnvironment, ...) error
- func ProposeDeal(ctx fsm.Context, environment ClientDealEnvironment, ...) error
- func ValidateDealPublished(ctx fsm.Context, environment ClientDealEnvironment, ...) error
- func VerifyDealActivated(ctx fsm.Context, environment ClientDealEnvironment, ...) error
- func WaitForDealCompletion(ctx fsm.Context, environment ClientDealEnvironment, ...) error
- func WaitForFunding(ctx fsm.Context, environment ClientDealEnvironment, ...) error
- type ClientDealEnvironment
- type ClientStateEntryFunc
Constants ¶
This section is empty.
Variables ¶
var ClientEvents = fsm.Events{ fsm.Event(storagemarket.ClientEventOpen). From(storagemarket.StorageDealUnknown).To(storagemarket.StorageDealEnsureClientFunds), fsm.Event(storagemarket.ClientEventFundingInitiated). From(storagemarket.StorageDealEnsureClientFunds).To(storagemarket.StorageDealClientFunding). Action(func(deal *storagemarket.ClientDeal, mcid cid.Cid) error { deal.AddFundsCid = &mcid return nil }), fsm.Event(storagemarket.ClientEventEnsureFundsFailed). FromMany(storagemarket.StorageDealClientFunding, storagemarket.StorageDealEnsureClientFunds).To(storagemarket.StorageDealFailing). Action(func(deal *storagemarket.ClientDeal, err error) error { deal.Message = xerrors.Errorf("adding market funds failed: %w", err).Error() return nil }), fsm.Event(storagemarket.ClientEventFundsReserved). From(storagemarket.StorageDealEnsureClientFunds).ToJustRecord(). Action(func(deal *storagemarket.ClientDeal, fundsReserved abi.TokenAmount) error { if deal.FundsReserved.Nil() { deal.FundsReserved = fundsReserved } else { deal.FundsReserved = big.Add(deal.FundsReserved, fundsReserved) } return nil }), fsm.Event(storagemarket.ClientEventFundsReleased). FromMany(storagemarket.StorageDealProposalAccepted, storagemarket.StorageDealFailing).ToJustRecord(). Action(func(deal *storagemarket.ClientDeal, fundsReleased abi.TokenAmount) error { deal.FundsReserved = big.Subtract(deal.FundsReserved, fundsReleased) return nil }), fsm.Event(storagemarket.ClientEventFundsEnsured). FromMany(storagemarket.StorageDealEnsureClientFunds, storagemarket.StorageDealClientFunding).To(storagemarket.StorageDealFundsEnsured), fsm.Event(storagemarket.ClientEventWriteProposalFailed). From(storagemarket.StorageDealFundsEnsured).To(storagemarket.StorageDealError). Action(func(deal *storagemarket.ClientDeal, err error) error { deal.Message = xerrors.Errorf("sending proposal to storage provider failed: %w", err).Error() return nil }), fsm.Event(storagemarket.ClientEventReadResponseFailed). From(storagemarket.StorageDealFundsEnsured).To(storagemarket.StorageDealFailing). Action(func(deal *storagemarket.ClientDeal, err error) error { deal.Message = xerrors.Errorf("error reading Response message: %w", err).Error() return nil }), fsm.Event(storagemarket.ClientEventResponseVerificationFailed). From(storagemarket.StorageDealFundsEnsured).To(storagemarket.StorageDealFailing). Action(func(deal *storagemarket.ClientDeal) error { deal.Message = "unable to verify signature on deal response" return nil }), fsm.Event(storagemarket.ClientEventInitiateDataTransfer). From(storagemarket.StorageDealFundsEnsured).To(storagemarket.StorageDealStartDataTransfer), fsm.Event(storagemarket.ClientEventUnexpectedDealState). From(storagemarket.StorageDealFundsEnsured).To(storagemarket.StorageDealFailing). Action(func(deal *storagemarket.ClientDeal, status storagemarket.StorageDealStatus, providerMessage string) error { deal.Message = xerrors.Errorf("unexpected deal status while waiting for data request: %d (%s). Provider message: %s", status, storagemarket.DealStates[status], providerMessage).Error() return nil }), fsm.Event(storagemarket.ClientEventDataTransferFailed). FromMany(storagemarket.StorageDealStartDataTransfer, storagemarket.StorageDealTransferring).To(storagemarket.StorageDealFailing). Action(func(deal *storagemarket.ClientDeal, err error) error { deal.Message = xerrors.Errorf("failed to initiate data transfer: %w", err).Error() return nil }), fsm.Event(storagemarket.ClientEventDataTransferInitiated). From(storagemarket.StorageDealStartDataTransfer).To(storagemarket.StorageDealTransferring), fsm.Event(storagemarket.ClientEventDataTransferComplete). FromMany(storagemarket.StorageDealTransferring, storagemarket.StorageDealStartDataTransfer).To(storagemarket.StorageDealCheckForAcceptance), fsm.Event(storagemarket.ClientEventWaitForDealState). From(storagemarket.StorageDealCheckForAcceptance).ToNoChange(). Action(func(deal *storagemarket.ClientDeal, pollError bool) error { deal.PollRetryCount++ if pollError { deal.PollErrorCount++ } return nil }), fsm.Event(storagemarket.ClientEventResponseDealDidNotMatch). From(storagemarket.StorageDealCheckForAcceptance).To(storagemarket.StorageDealFailing). Action(func(deal *storagemarket.ClientDeal, responseCid cid.Cid, proposalCid cid.Cid) error { deal.Message = xerrors.Errorf("miner responded to a wrong proposal: %s != %s", responseCid, proposalCid).Error() return nil }), fsm.Event(storagemarket.ClientEventDealRejected). From(storagemarket.StorageDealCheckForAcceptance).To(storagemarket.StorageDealFailing). Action(func(deal *storagemarket.ClientDeal, state storagemarket.StorageDealStatus, reason string) error { deal.Message = xerrors.Errorf("deal failed: (State=%d) %s", state, reason).Error() return nil }), fsm.Event(storagemarket.ClientEventDealAccepted). From(storagemarket.StorageDealCheckForAcceptance).To(storagemarket.StorageDealProposalAccepted). Action(func(deal *storagemarket.ClientDeal, publishMessage *cid.Cid) error { deal.PublishMessage = publishMessage return nil }), fsm.Event(storagemarket.ClientEventStreamCloseError). FromAny().To(storagemarket.StorageDealError). Action(func(deal *storagemarket.ClientDeal, err error) error { deal.Message = xerrors.Errorf("error attempting to close stream: %w", err).Error() return nil }), fsm.Event(storagemarket.ClientEventDealPublishFailed). From(storagemarket.StorageDealProposalAccepted).To(storagemarket.StorageDealError). Action(func(deal *storagemarket.ClientDeal, err error) error { deal.Message = xerrors.Errorf("error validating deal published: %w", err).Error() return nil }), fsm.Event(storagemarket.ClientEventDealPublished). From(storagemarket.StorageDealProposalAccepted).To(storagemarket.StorageDealSealing). Action(func(deal *storagemarket.ClientDeal, dealID abi.DealID) error { deal.DealID = dealID return nil }), fsm.Event(storagemarket.ClientEventDealActivationFailed). From(storagemarket.StorageDealSealing).To(storagemarket.StorageDealError). Action(func(deal *storagemarket.ClientDeal, err error) error { deal.Message = xerrors.Errorf("error in deal activation: %w", err).Error() return nil }), fsm.Event(storagemarket.ClientEventDealActivated). From(storagemarket.StorageDealSealing).To(storagemarket.StorageDealActive), fsm.Event(storagemarket.ClientEventDealSlashed). From(storagemarket.StorageDealActive).To(storagemarket.StorageDealSlashed). Action(func(deal *storagemarket.ClientDeal, slashEpoch abi.ChainEpoch) error { deal.SlashEpoch = slashEpoch return nil }), fsm.Event(storagemarket.ClientEventDealExpired). From(storagemarket.StorageDealActive).To(storagemarket.StorageDealExpired), fsm.Event(storagemarket.ClientEventDealCompletionFailed). From(storagemarket.StorageDealActive).To(storagemarket.StorageDealError). Action(func(deal *storagemarket.ClientDeal, err error) error { deal.Message = xerrors.Errorf("error waiting for deal completion: %w", err).Error() return nil }), fsm.Event(storagemarket.ClientEventFailed). From(storagemarket.StorageDealFailing).To(storagemarket.StorageDealError), fsm.Event(storagemarket.ClientEventRestart).From(storagemarket.StorageDealTransferring).To(storagemarket.StorageDealStartDataTransfer). FromAny().ToNoChange(), }
ClientEvents are the events that can happen in a storage client
var ClientFinalityStates = []fsm.StateKey{ storagemarket.StorageDealSlashed, storagemarket.StorageDealExpired, storagemarket.StorageDealError, }
ClientFinalityStates are the states that terminate deal processing for a deal. When a client restarts, it restarts only deals that are not in a finality state.
var ClientStateEntryFuncs = fsm.StateEntryFuncs{ storagemarket.StorageDealEnsureClientFunds: EnsureClientFunds, storagemarket.StorageDealClientFunding: WaitForFunding, storagemarket.StorageDealFundsEnsured: ProposeDeal, storagemarket.StorageDealStartDataTransfer: InitiateDataTransfer, storagemarket.StorageDealCheckForAcceptance: CheckForDealAcceptance, storagemarket.StorageDealProposalAccepted: ValidateDealPublished, storagemarket.StorageDealSealing: VerifyDealActivated, storagemarket.StorageDealActive: WaitForDealCompletion, storagemarket.StorageDealFailing: FailDeal, }
ClientStateEntryFuncs are the handlers for different states in a storage client
Functions ¶
func CheckForDealAcceptance ¶ added in v0.4.0
func CheckForDealAcceptance(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
CheckForDealAcceptance is run until the deal is sealed and published by the provider, or errors
func EnsureClientFunds ¶ added in v0.2.0
func EnsureClientFunds(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
EnsureClientFunds attempts to ensure the client has enough funds for the deal being proposed
func FailDeal ¶
func FailDeal(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
FailDeal cleans up a failing deal
func InitiateDataTransfer ¶ added in v0.4.0
func InitiateDataTransfer(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
InitiateDataTransfer initiates data transfer to the provider
func ProposeDeal ¶
func ProposeDeal(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
ProposeDeal sends the deal proposal to the provider
func ValidateDealPublished ¶
func ValidateDealPublished(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
ValidateDealPublished confirms with the chain that a deal was published
func VerifyDealActivated ¶
func VerifyDealActivated(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
VerifyDealActivated confirms that a deal was successfully committed to a sector and is active
func WaitForDealCompletion ¶ added in v0.3.2
func WaitForDealCompletion(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
WaitForDealCompletion waits for the deal to be slashed or to expire
func WaitForFunding ¶ added in v0.2.0
func WaitForFunding(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
WaitForFunding waits for an AddFunds message to appear on the chain
Types ¶
type ClientDealEnvironment ¶
type ClientDealEnvironment interface { Node() storagemarket.StorageClientNode NewDealStream(ctx context.Context, p peer.ID) (network.StorageDealStream, error) StartDataTransfer(ctx context.Context, to peer.ID, voucher datatransfer.Voucher, baseCid cid.Cid, selector ipld.Node) error GetProviderDealState(ctx context.Context, proposalCid cid.Cid) (*storagemarket.ProviderDealState, error) PollingInterval() time.Duration DealFunds() funds.DealFunds network.PeerTagger }
ClientDealEnvironment is an abstraction for interacting with dependencies from the storage client environment
type ClientStateEntryFunc ¶
type ClientStateEntryFunc func(ctx fsm.Context, environment ClientDealEnvironment, deal storagemarket.ClientDeal) error
ClientStateEntryFunc is the type for all state entry functions on a storage client