session

package
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2023 License: Apache-2.0, MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

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

	// Random is an optional rng, if nil, math/rand will be used.
	Random Random

	// 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
	// FirstByteTimeAlpha is the alpha value for the exponential moving average
	// of the time to first byte for a storage provider. The time to first byte
	// is the time it takes to receive the first byte of data from a storage
	// provider, it is used to determine the prioritisation of storage
	// providers. The value determines the weight of previous time to first
	// bytes, a lower value will give more weight to recent time to first bytes.
	// A value of 0 will only use the most recent time to first byte.
	FirstByteTimeAlpha float64
	// OverallConnectTimeAlpha is the alpha value for the exponential moving
	// average of the overall connect time. The overall connect time is the
	// average connect time of *all* storage providers, used to normalise the
	// connect time metric.
	OverallConnectTimeAlpha float64
	// OverallFirstByteTimeAlpha is the alpha value for the exponential moving
	// average of the overall time to first byte. The overall time to first byte
	// is the average time to first byte of *all* storage providers, used to
	// normalise the time to first byte metric.
	OverallFirstByteTimeAlpha float64
	// BandwidthAlpha is the alpha value for the exponential moving average of
	// the bandwidth metric for a storage provider. The bandwidth metric is
	// measured in bytes per second. The value of BandwidthAlpha determines the
	// weight of previous bandwidth metrics, a lower value will give more weight
	// to recent bandwidth metrics. A value of 0 will only use the most recent
	// bandwidth metric.
	BandwidthAlpha float64
	// OverallBandwidthAlpha is the alpha value for the exponential moving
	// average of the overall bandwidth metric. The overall bandwidth metric is
	// the average bandwidth of *all* storage providers, used to normalise the
	// bandwidth metric.
	OverallBandwidthAlpha float64
	// SuccessAlpha is the alpha value for the exponential moving average of
	// the success metric for a storage provider. The success metric is the
	// ratio of successful retrievals to total retrievals. The value determines
	// the weight of previous success metrics, a lower value will give more
	// weight to recent success metrics. A value of 0 will only use the most
	// recent success metric.
	SuccessAlpha float64

	// GraphsyncVerifiedDealWeight is the scoring weight applied when a
	// graphsync candidate has a VerifiedDeal metadata. The weight is a
	// multiplier of the base value of `1.0` when VerifiedDeal is found.
	GraphsyncVerifiedDealWeight float64
	// GraphsyncFastRetrievalWeight is the scoring weight applied when a
	// graphsync candidate has a FastRetrieval metadata. The weight is a
	// multiplier of the base value of `1.0` when FastRetrieval is found.
	GraphsyncFastRetrievalWeight float64
	// ConnectTimeWeight is the scoring weight applied to the connect time
	// exponential moving average for the candidate at time of scoring. The
	// weight is a multiplier the base value, which should be a normalised
	// score in the range of [0, 1].
	ConnectTimeWeight float64
	// FirstByteTimeWeight is the scoring weight applied to the time to first
	// byte exponential moving average for the candidate at time of scoring. The
	// weight is a multiplier the base value, which should be a normalised
	// score in the range of [0, 1].
	FirstByteTimeWeight float64
	// BandwidthWeight is the scoring weight applied to the bandwidth
	// exponential moving average for the candidate at time of scoring. The
	// weight is a multiplier the base value, which should be a normalised
	// score in the range of [0, 1].
	BandwidthWeight float64
	// SuccessWeight is the scoring weight applied to the success exponential
	// moving average for the candidate at time of scoring. The weight is a
	// multiplier the base value, which should be a normalised score in the
	// range of [0, 1] (where each failure contributes a 0 and each success
	// contributes a 1).
	SuccessWeight float64
}

All config values should be safe to leave uninitialized

func DefaultConfig added in v0.11.0 

func DefaultConfig() *Config

DefaultConfig returns a default config with usable alpha and weight values.

func (Config) WithConnectTimeAlpha added in v0.12.0 

func (cfg Config) WithConnectTimeAlpha(alpha float64) *Config

WithConnectTimeAlpha sets the connect time alpha.

func (Config) WithConnectTimeWeight added in v0.12.0 

func (cfg Config) WithConnectTimeWeight(weight float64) *Config

WithConnectTimeWeight sets the connect time weight.

func (Config) WithDefaultProviderConfig added in v0.12.0 

func (cfg Config) WithDefaultProviderConfig(providerConfig ProviderConfig) *Config

WithDefaultProviderConfig sets the default provider config.

func (Config) WithFirstByteTimeAlpha added in v0.12.0 

func (cfg Config) WithFirstByteTimeAlpha(alpha float64) *Config

WithFirstByteTimeAlpha sets the time to first byte alpha.

func (Config) WithFirstByteTimeWeight added in v0.12.0 

func (cfg Config) WithFirstByteTimeWeight(weight float64) *Config

WithFirstByteTimeWeight sets the time to first byte weight.

func (Config) WithGraphsyncFastRetrievalWeight added in v0.12.0 

func (cfg Config) WithGraphsyncFastRetrievalWeight(weight float64) *Config

WithGraphsyncFastRetrievalWeight sets the fast retrieval weight.

func (Config) WithGraphsyncVerifiedDealWeight added in v0.12.0 

func (cfg Config) WithGraphsyncVerifiedDealWeight(weight float64) *Config

WithGraphsyncVerifiedDealWeight sets the verified deal weight.

func (Config) WithOverallConnectTimeAlpha added in v0.12.0 

func (cfg Config) WithOverallConnectTimeAlpha(alpha float64) *Config

WithOverallConnectTimeAlpha sets the overall connect time alpha.

func (Config) WithOverallFirstByteTimeAlpha added in v0.12.0 

func (cfg Config) WithOverallFirstByteTimeAlpha(alpha float64) *Config

WithOverallFirstByteTimeAlpha sets the overall time to first byte alpha.

func (Config) WithProviderAllowList added in v0.12.0 

func (cfg Config) WithProviderAllowList(allowlist map[peer.ID]bool) *Config

WithProviderAllowList sets the provider allowlist.

func (Config) WithProviderBlockList added in v0.12.0 

func (cfg Config) WithProviderBlockList(blocklist map[peer.ID]bool) *Config

WithProviderBlockList sets the provider blocklist.

func (Config) WithProviderConfigs added in v0.12.0 

func (cfg Config) WithProviderConfigs(providerConfigs map[peer.ID]ProviderConfig) *Config

WithProviderConfigs sets the provider configs.

func (Config) WithSuccessAlpha added in v0.12.0 

func (cfg Config) WithSuccessAlpha(alpha float64) *Config

WithSuccessAlpha sets the success alpha.

func (Config) WithSuccessWeight added in v0.12.0 

func (cfg Config) WithSuccessWeight(weight float64) *Config

WithSuccessWeight sets the success weight.

func (Config) WithoutRandomness added in v0.12.0 

func (cfg Config) WithoutRandomness() *Config

WithoutRandomness removes the dice roll for choosing the best peer, with this set, it will always choose the peer with the highest score.

type ProviderConfig added in v0.11.0 

type ProviderConfig struct {
	RetrievalTimeout        time.Duration
	MaxConcurrentRetrievals uint
}

type Random added in v0.12.0 

type Random interface{ Float64() float64 }

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 added in v0.11.0 

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

func NewSessionState added in v0.11.0 

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 added in v0.11.0 

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

func (*SessionState) ChooseNextProvider added in v0.12.0 

func (spt *SessionState) ChooseNextProvider(peers []peer.ID, mda []metadata.Protocol) int

func (*SessionState) EndRetrieval added in v0.11.0 

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

func (*SessionState) GetConcurrency added in v0.11.0 

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

func (*SessionState) RecordConnectTime added in v0.12.0 

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

func (*SessionState) RecordFailure added in v0.11.0 

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

func (*SessionState) RecordFirstByteTime added in v0.12.0 

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

func (*SessionState) RecordSuccess added in v0.12.0 

func (spt *SessionState) RecordSuccess(storageProviderId peer.ID, bandwidthBytesPerSecond uint64)

func (*SessionState) RegisterRetrieval added in v0.11.0 

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

type State 

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

	// 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

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

	// RecordConnectTime 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.
	RecordConnectTime(storageProviderId peer.ID, connectTime time.Duration)

	// RecordFirstByteTime records the time it took to receive the first byte
	// from a storage provider. This is used for prioritisation of storage
	// providers and is recorded with a decay according to
	// SessionStateConfig#FirstByteTimeAlpha.
	RecordFirstByteTime(storageProviderId peer.ID, firstByteTime time.Duration)

	// RecordFailure records a failure for a storage provider. This is used for
	// prioritisation of storage providers and is recorded as a success=0 with a
	// decay according to SessionStateConfig#SuccessAlpha.
	RecordFailure(retrievalId types.RetrievalID, storageProviderId peer.ID) error

	// RecordSuccess records a success for a storage provider. This is used for
	// prioritisation of storage providers and is recorded as a success=1 with a
	// decay according to SessionStateConfig#SuccessAlpha. Bandwidth is also
	// used for prioritisation and is recorded with a decay according to
	// SessionStateConfig#BandwidthAlpha.
	RecordSuccess(storageProviderId peer.ID, bandwidthBytesPerSecond uint64)

	// ChooseNextProvider compares a list of storage providers and returns the
	// index of the next storage provider to use. This uses both historically
	// collected state and information contained within the metadata, depending
	// on protocol.
	ChooseNextProvider(peers []peer.ID, metadata []metadata.Protocol) int
}

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.