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 TrackTransfer(ctx fsm.Context, environment ProviderDealEnvironment, ...) error
• func UnpauseDeal(ctx fsm.Context, environment ProviderDealEnvironment, ...) error
• func UnsealData(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.TotalSent = 0
				deal.FundsReceived = abi.NewTokenAmount(0)
				deal.CurrentInterval = deal.PaymentInterval
				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).
		Action(func(deal *rm.ProviderDealState, totalSent uint64) error {
			deal.TotalSent = totalSent
			return nil
		}),
	fsm.Event(rm.ProviderEventBlocksCompleted).
		FromMany(rm.DealStatusOngoing).To(rm.DealStatusBlocksComplete),

	fsm.Event(rm.ProviderEventPaymentRequested).
		FromMany(rm.DealStatusOngoing, rm.DealStatusUnsealed).To(rm.DealStatusFundsNeeded).
		From(rm.DealStatusFundsNeeded).ToJustRecord().
		From(rm.DealStatusBlocksComplete).To(rm.DealStatusFundsNeededLastPayment).
		From(rm.DealStatusNew).To(rm.DealStatusFundsNeededUnseal).
		Action(func(deal *rm.ProviderDealState, totalSent uint64) error {
			deal.TotalSent = totalSent
			return nil
		}),

	fsm.Event(rm.ProviderEventSaveVoucherFailed).
		FromMany(rm.DealStatusFundsNeeded, rm.DealStatusFundsNeededLastPayment).To(rm.DealStatusFailing).
		Action(recordError),
	fsm.Event(rm.ProviderEventPartialPaymentReceived).
		FromMany(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)

			if deal.Status != rm.DealStatusFundsNeededUnseal {
				deal.CurrentInterval = deal.NextInterval()
			}
			return nil
		}),

	fsm.Event(rm.ProviderEventComplete).FromMany(rm.DealStatusBlocksComplete, rm.DealStatusFinalizing).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.DealStatusFundsNeededUnseal: TrackTransfer,
	rm.DealStatusUnsealing:         UnsealData,
	rm.DealStatusUnsealed:          UnpauseDeal,
	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 TrackTransfer

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

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

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

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
	TrackTransfer(deal rm.ProviderDealState) error
	UntrackTransfer(deal rm.ProviderDealState) error
	DeleteStore(dealID rm.DealID) error
	ResumeDataTransfer(context.Context, datatransfer.ChannelID) error
	CloseDataTransfer(context.Context, datatransfer.ChannelID) error
}

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