providerstates

Documentation

Overview

Package providerstates contains state machine logic relating to the `RetrievalProvider`.

provider_fsm.go is where the state transitions are defined, and the default handlers for each new state are defined.

provider_states.go contains state handler functions.

The following diagram illustrates the operation of the provider 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/retrievalprovider.mmd.svg

Index

• Variables
• func CancelDeal(ctx fsm.Context, environment ProviderDealEnvironment, ...) error
• func CleanupDeal(ctx fsm.Context, environment ProviderDealEnvironment, ...) error
• func UnpauseDeal(ctx fsm.Context, environment ProviderDealEnvironment, ...) error
• func UnsealData(ctx fsm.Context, environment ProviderDealEnvironment, ...) error
• func UpdateFunding(ctx fsm.Context, environment ProviderDealEnvironment, ...) error
• type ProviderDealEnvironment

Variables

var ProviderEvents = fsm.Events{

	fsm.Event(rm.ProviderEventOpen).
		From(rm.DealStatusNew).ToNoChange().
		Action(
			func(deal *rm.ProviderDealState) error {
				deal.FundsReceived = abi.NewTokenAmount(0)
				return nil
			},
		),

	fsm.Event(rm.ProviderEventDealAccepted).
		From(rm.DealStatusFundsNeededUnseal).ToNoChange().
		From(rm.DealStatusNew).To(rm.DealStatusUnsealing).
		Action(func(deal *rm.ProviderDealState, channelID datatransfer.ChannelID) error {
			deal.ChannelID = &channelID
			return nil
		}),

	fsm.Event(rm.ProviderEventUnsealError).
		From(rm.DealStatusUnsealing).To(rm.DealStatusFailing).
		Action(recordError),
	fsm.Event(rm.ProviderEventUnsealComplete).
		From(rm.DealStatusUnsealing).To(rm.DealStatusUnsealed),

	fsm.Event(rm.ProviderEventBlockSent).
		FromMany(rm.DealStatusOngoing).ToNoChange().
		From(rm.DealStatusUnsealed).To(rm.DealStatusOngoing),

	fsm.Event(rm.ProviderEventPaymentRequested).
		FromMany(rm.DealStatusOngoing, rm.DealStatusUnsealed).To(rm.DealStatusFundsNeeded).
		From(rm.DealStatusFundsNeeded).ToJustRecord().
		From(rm.DealStatusNew).To(rm.DealStatusFundsNeededUnseal),

	fsm.Event(rm.ProviderEventLastPaymentRequested).
		FromMany(rm.DealStatusOngoing, rm.DealStatusUnsealed).To(rm.DealStatusFundsNeededLastPayment),

	fsm.Event(rm.ProviderEventSaveVoucherFailed).
		FromMany(rm.DealStatusFundsNeededUnseal, rm.DealStatusFundsNeeded, rm.DealStatusFundsNeededLastPayment).To(rm.DealStatusFailing).
		Action(recordError),

	fsm.Event(rm.ProviderEventPartialPaymentReceived).
		FromMany(rm.DealStatusFundsNeededUnseal,
			rm.DealStatusFundsNeeded,
			rm.DealStatusFundsNeededLastPayment).ToNoChange().
		Action(func(deal *rm.ProviderDealState, fundsReceived abi.TokenAmount) error {
			deal.FundsReceived = big.Add(deal.FundsReceived, fundsReceived)
			return nil
		}),

	fsm.Event(rm.ProviderEventPaymentReceived).
		From(rm.DealStatusFundsNeeded).To(rm.DealStatusOngoing).
		From(rm.DealStatusFundsNeededLastPayment).To(rm.DealStatusFinalizing).
		From(rm.DealStatusFundsNeededUnseal).To(rm.DealStatusUnsealing).
		FromMany(rm.DealStatusBlocksComplete, rm.DealStatusOngoing, rm.DealStatusFinalizing).ToJustRecord().
		Action(func(deal *rm.ProviderDealState, fundsReceived abi.TokenAmount) error {
			deal.FundsReceived = big.Add(deal.FundsReceived, fundsReceived)
			return nil
		}),

	fsm.Event(rm.ProviderEventProcessPayment).FromAny().ToNoChange(),

	fsm.Event(rm.ProviderEventComplete).FromAny().To(rm.DealStatusCompleting),
	fsm.Event(rm.ProviderEventCleanupComplete).From(rm.DealStatusCompleting).To(rm.DealStatusCompleted),

	fsm.Event(rm.ProviderEventCancelComplete).
		From(rm.DealStatusCancelling).To(rm.DealStatusCancelled).
		From(rm.DealStatusFailing).To(rm.DealStatusErrored),

	fsm.Event(rm.ProviderEventDataTransferError).
		FromAny().To(rm.DealStatusErrored).
		Action(recordError),

	fsm.Event(rm.ProviderEventMultiStoreError).
		FromAny().To(rm.DealStatusErrored).
		Action(recordError),

	fsm.Event(rm.ProviderEventClientCancelled).
		From(rm.DealStatusFailing).ToJustRecord().
		From(rm.DealStatusCancelling).ToJustRecord().
		FromAny().To(rm.DealStatusCancelling).Action(
		func(deal *rm.ProviderDealState) error {
			if deal.Status != rm.DealStatusFailing {
				deal.Message = "Client cancelled retrieval"
			}
			return nil
		},
	),
}

ProviderEvents are the events that can happen in a retrieval provider

var ProviderFinalityStates = []fsm.StateKey{
	rm.DealStatusErrored,
	rm.DealStatusCompleted,
	rm.DealStatusCancelled,
}

ProviderFinalityStates are the terminal states for a retrieval provider

var ProviderStateEntryFuncs = fsm.StateEntryFuncs{
	rm.DealStatusUnsealing:              UnsealData,
	rm.DealStatusUnsealed:               UnpauseDeal,
	rm.DealStatusFundsNeeded:            UpdateFunding,
	rm.DealStatusFundsNeededUnseal:      UpdateFunding,
	rm.DealStatusFundsNeededLastPayment: UpdateFunding,
	rm.DealStatusFailing:                CancelDeal,
	rm.DealStatusCancelling:             CancelDeal,
	rm.DealStatusCompleting:             CleanupDeal,
}

ProviderStateEntryFuncs are the handlers for different states in a retrieval provider

Functions

func CancelDeal

func CancelDeal(ctx fsm.Context, environment ProviderDealEnvironment, deal rm.ProviderDealState) error

CancelDeal clears a deal that went wrong for an unknown reason

func CleanupDeal

func CleanupDeal(ctx fsm.Context, environment ProviderDealEnvironment, deal rm.ProviderDealState) error

CleanupDeal runs to do memory cleanup for an in progress deal

func UnpauseDeal

func UnpauseDeal(ctx fsm.Context, environment ProviderDealEnvironment, deal rm.ProviderDealState) error

UnpauseDeal resumes a deal so we can start sending data after its unsealed

func UnsealData

func UnsealData(ctx fsm.Context, environment ProviderDealEnvironment, deal rm.ProviderDealState) error

UnsealData fetches the piece containing data needed for the retrieval, unsealing it if necessary

func UpdateFunding

func UpdateFunding(ctx fsm.Context, environment ProviderDealEnvironment, deal rm.ProviderDealState) error

UpdateFunding saves payments as needed until a transfer can resume

Types

type ProviderDealEnvironment

type ProviderDealEnvironment interface {
	// Node returns the node interface for this deal
	Node() rm.RetrievalProviderNode
	PrepareBlockstore(ctx context.Context, dealID rm.DealID, pieceCid cid.Cid) error
	DeleteStore(dealID rm.DealID) error
	ResumeDataTransfer(context.Context, datatransfer.ChannelID) error
	CloseDataTransfer(context.Context, datatransfer.ChannelID) error
	ChannelState(ctx context.Context, chid datatransfer.ChannelID) (datatransfer.ChannelState, error)
	UpdateValidationStatus(ctx context.Context, chid datatransfer.ChannelID, result datatransfer.ValidationResult) error
}

ProviderDealEnvironment is a bridge to the environment a provider deal is executing in It provides access to relevant functionality on the retrieval provider