session

Documentation

Index

• type Config
  • func DefaultConfig() *Config
• type ProviderConfig
• type Session
  • func NewSession(config *Config, withState bool) *Session
  • func (session *Session) FilterIndexerCandidate(candidate types.RetrievalCandidate) (bool, types.RetrievalCandidate)
  • func (session *Session) GetStorageProviderTimeout(storageProviderId peer.ID) time.Duration
• type SessionState
  • func NewSessionState(config *Config) *SessionState
  • func (spt *SessionState) AddToRetrieval(retrievalId types.RetrievalID, storageProviderIds []peer.ID) error
  • func (spt *SessionState) CompareStorageProviders(protocol multicodec.Code, a, b peer.ID, mda, mdb metadata.Protocol) bool
  • func (spt *SessionState) EndRetrieval(retrievalId types.RetrievalID) error
  • func (spt *SessionState) GetConcurrency(storageProviderId peer.ID) uint
  • func (spt *SessionState) IsSuspended(storageProviderId peer.ID) bool
  • func (spt *SessionState) RecordFailure(storageProviderId peer.ID, retrievalId types.RetrievalID) error
  • func (spt *SessionState) RegisterConnectTime(storageProviderId peer.ID, current time.Duration)
  • func (spt *SessionState) RegisterRetrieval(retrievalId types.RetrievalID, cid cid.Cid, selector datamodel.Node) bool
  • func (spt *SessionState) RemoveFromRetrieval(storageProviderId peer.ID, retrievalId types.RetrievalID) error
• type State

Types

type Config

type Config struct {
	ProviderBlockList     map[peer.ID]bool
	ProviderAllowList     map[peer.ID]bool
	DefaultProviderConfig ProviderConfig
	ProviderConfigs       map[peer.ID]ProviderConfig
	PaidRetrievals        bool

	MaxFailuresBeforeSuspend uint
	FailureHistoryDuration   time.Duration
	SuspensionDuration       time.Duration

	// ConnectTimeAlpha is the alpha value for the exponential moving average
	// of the connect time for a storage provider. The connect time is the time
	// it takes to connect to a storage provider, it is used to determine the
	// prioritisation of storage providers. The value determines the weight of
	// previous connect times, a lower value will give more weight to recent
	// connect times. A value of 0 will only use the most recent connect time.
	ConnectTimeAlpha float64
}

All config values should be safe to leave uninitialized

func DefaultConfig

func DefaultConfig() *Config

type ProviderConfig

type ProviderConfig struct {
	RetrievalTimeout        time.Duration
	MaxConcurrentRetrievals uint
}

type Session

type Session struct {
	State
	// contains filtered or unexported fields
}

Session and State both deal with per-storage provider data and usage questions. While State is responsible for gathering data of ongoing interactions with storage providers and making dynamic decisions based on that information, Session extends it and provides harder rules that arise from configuration and other static heuristics.

func NewSession

func NewSession(config *Config, withState bool) *Session

NewSession constructs a new Session with the given config and with or without ongoing dynamic data collection. When withState is false, no dynamic data will be collected and decisions will be made solely based on the config.

func (*Session) FilterIndexerCandidate

func (session *Session) FilterIndexerCandidate(candidate types.RetrievalCandidate) (bool, types.RetrievalCandidate)

FilterIndexerCandidate filters out protocols that are not acceptable for the given candidate. It returns a bool indicating whether the candidate should be considered at all, and a new candidate with the filtered protocols.

func (*Session) GetStorageProviderTimeout

func (session *Session) GetStorageProviderTimeout(storageProviderId peer.ID) time.Duration

GetStorageProviderTimeout returns the per-retrieval timeout from the RetrievalTimeout configuration option.

type SessionState

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

func NewSessionState

func NewSessionState(config *Config) *SessionState

NewSessionState creates a new SessionState with the given config. If the config is nil, a default config will be used.

func (*SessionState) AddToRetrieval

func (spt *SessionState) AddToRetrieval(retrievalId types.RetrievalID, storageProviderIds []peer.ID) error

func (*SessionState) CompareStorageProviders

func (spt *SessionState) CompareStorageProviders(protocol multicodec.Code, a, b peer.ID, mda, mdb metadata.Protocol) bool

func (*SessionState) EndRetrieval

func (spt *SessionState) EndRetrieval(retrievalId types.RetrievalID) error

func (*SessionState) GetConcurrency

func (spt *SessionState) GetConcurrency(storageProviderId peer.ID) uint

func (*SessionState) IsSuspended

func (spt *SessionState) IsSuspended(storageProviderId peer.ID) bool

func (*SessionState) RecordFailure

func (spt *SessionState) RecordFailure(storageProviderId peer.ID, retrievalId types.RetrievalID) error

func (*SessionState) RegisterConnectTime

func (spt *SessionState) RegisterConnectTime(storageProviderId peer.ID, current time.Duration)

func (*SessionState) RegisterRetrieval

func (spt *SessionState) RegisterRetrieval(retrievalId types.RetrievalID, cid cid.Cid, selector datamodel.Node) bool

func (*SessionState) RemoveFromRetrieval

func (spt *SessionState) RemoveFromRetrieval(storageProviderId peer.ID, retrievalId types.RetrievalID) error

type State

type State interface {
	// IsSuspended determines whether a storage provider has been temporarily
	// suspended due to an excessive number of recent errors.
	IsSuspended(storageProviderId peer.ID) bool

	// GetConcurrency returns the number of retrievals the given storage
	// provider is currently recorded as being involved in.
	GetConcurrency(storageProviderId peer.ID) uint

	// RecordFailure records a failure for a storage provider, potentially
	// leading to a suspension; this is used on both query and retrieval
	// phases.
	RecordFailure(storageProviderId peer.ID, retrievalId types.RetrievalID) error

	// RegisterRetrieval registers a retrieval, returning false if the
	// retrieval for this RetrievalID or this CID already exists, or true if it
	// is new.
	RegisterRetrieval(retrievalId types.RetrievalID, cid cid.Cid, selector datamodel.Node) bool

	// AddToRetrieval adds a set of storage providers to an existing retrieval,
	// this will increase the concurrency for each of the storage providers
	// until the retrieval has finished.
	AddToRetrieval(retrievalId types.RetrievalID, storageProviderIds []peer.ID) error

	// RemoveFromRetrieval removes a storage provider from a an active
	// retrieval, decreasing the concurrency for that storage provider. Used in
	// both the case of a retrieval failure (RecordFailure) and when a
	// QueryResponse is unacceptable.
	RemoveFromRetrieval(storageProviderId peer.ID, retrievalId types.RetrievalID) error

	// EndRetrieval cleans up an existing retrieval.
	EndRetrieval(retrievalId types.RetrievalID) error

	// RegisterConnectTime records the time it took to connect to a storage
	// provider. This is used for prioritisation of storage providers and is
	// recorded with a decay according to SessionStateConfig#ConnectTimeAlpha.
	RegisterConnectTime(storageProviderId peer.ID, connectTime time.Duration)

	// CompareStorageProviders compares two storage providers and returns true
	// if the first storage provider is preferred over the second storage
	// provider. This uses both historically collected state and information
	// contained within the metadata, depending on protocol.
	CompareStorageProviders(protocol multicodec.Code, a, b peer.ID, mda, mdb metadata.Protocol) bool
}

State defines an interface for the collection, monitoring and management of dynamic retrieval information on a per-storage provider basis. It augments a session with dynamic data collection to make decisions based on ongong interactions with storage providers.