reputation

Documentation

Index

• type AuditHistory
• type AuditHistoryConfig
• type AuditType
• type AuditWindow
• type Config
• type DB
• type Info
• type Service
  • func NewService(log *zap.Logger, overlay *overlay.Service, db DB, config Config) *Service
  • func (service *Service) ApplyAudit(ctx context.Context, nodeID storj.NodeID, result AuditType) (err error)
  • func (service *Service) Get(ctx context.Context, nodeID storj.NodeID) (info *Info, err error)
  • func (service *Service) TestingSetState(state Info) error
• type UpdateRequest

Types

type AuditHistory

type AuditHistory struct {
	Score   float64
	Windows []*AuditWindow
}

AuditHistory represents a node's audit history for the most recent tracking period.

type AuditHistoryConfig

type AuditHistoryConfig struct {
	WindowSize               time.Duration `help:"The length of time spanning a single audit window" releaseDefault:"12h" devDefault:"5m" testDefault:"10m"`
	TrackingPeriod           time.Duration `` /* 127-byte string literal not displayed */
	GracePeriod              time.Duration `` /* 236-byte string literal not displayed */
	OfflineThreshold         float64       `` /* 226-byte string literal not displayed */
	OfflineDQEnabled         bool          `` /* 134-byte string literal not displayed */
	OfflineSuspensionEnabled bool          `help:"whether nodes will be suspended if they have low online score" releaseDefault:"true" devDefault:"true"`
}

AuditHistoryConfig is a configuration struct defining time periods and thresholds for penalizing nodes for being offline. It is used for downtime suspension and disqualification.

type AuditType

type AuditType int

AuditType is an enum representing the outcome of a particular audit.

const (
	// AuditSuccess represents a successful audit.
	AuditSuccess AuditType = iota
	// AuditFailure represents a failed audit.
	AuditFailure
	// AuditUnknown represents an audit that resulted in an unknown error from the node.
	AuditUnknown
	// AuditOffline represents an audit where a node was offline.
	AuditOffline
)

type AuditWindow

type AuditWindow struct {
	WindowStart time.Time
	TotalCount  int32
	OnlineCount int32
}

AuditWindow represents the number of online and total audits a node received for a specific time period.

type Config

type Config struct {
	AuditRepairWeight     float64       `help:"weight to apply to audit reputation for total repair reputation calculation" default:"1.0"`
	AuditUplinkWeight     float64       `help:"weight to apply to audit reputation for total uplink reputation calculation" default:"1.0"`
	AuditLambda           float64       `help:"the forgetting factor used to calculate the audit SNs reputation" default:"0.95"`
	AuditWeight           float64       `help:"the normalization weight used to calculate the audit SNs reputation" default:"1.0"`
	AuditDQ               float64       `help:"the reputation cut-off for disqualifying SNs based on audit history" default:"0.6"`
	SuspensionGracePeriod time.Duration `help:"the time period that must pass before suspended nodes will be disqualified" releaseDefault:"168h" devDefault:"1h"`
	SuspensionDQEnabled   bool          `` /* 153-byte string literal not displayed */
	AuditCount            int64         `help:"the number of times a node has been audited to not be considered a New Node" releaseDefault:"100" devDefault:"0"`
	AuditHistory          AuditHistoryConfig
}

Config contains all config values for the reputation service.

type DB

type DB interface {
	Update(ctx context.Context, request UpdateRequest, now time.Time) (_ *overlay.ReputationStatus, changed bool, err error)
	Get(ctx context.Context, nodeID storj.NodeID) (*Info, error)
}

DB is an interface for storing reputation data.

type Info

type Info struct {
	AuditSuccessCount           int64
	TotalAuditCount             int64
	VettedAt                    *time.Time
	Contained                   bool
	Disqualified                *time.Time
	Suspended                   *time.Time
	UnknownAuditSuspended       *time.Time
	OfflineSuspended            *time.Time
	UnderReview                 *time.Time
	OnlineScore                 float64
	AuditHistory                AuditHistory
	AuditReputationAlpha        float64
	AuditReputationBeta         float64
	UnknownAuditReputationAlpha float64
	UnknownAuditReputationBeta  float64
}

Info contains all reputation data to be stored in DB.

type Service

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

Service handles storing node reputation data and updating the overlay cache when a node's status changes.

func NewService

func NewService(log *zap.Logger, overlay *overlay.Service, db DB, config Config) *Service

NewService creates a new reputation service.

func (*Service) ApplyAudit

func (service *Service) ApplyAudit(ctx context.Context, nodeID storj.NodeID, result AuditType) (err error)

ApplyAudit receives an audit result and applies it to the relevant node in DB.

func (*Service) Get

func (service *Service) Get(ctx context.Context, nodeID storj.NodeID) (info *Info, err error)

Get returns a node's reputation info from DB.

func (*Service) TestingSetState

func (service *Service) TestingSetState(state Info) error

TestingSetState manually sets a node's info in DB.

type UpdateRequest

type UpdateRequest struct {
	NodeID       storj.NodeID
	AuditOutcome AuditType
	// n.b. these are set values from the satellite.
	// They are part of the UpdateRequest struct in order to be
	// more easily accessible in satellite/satellitedb/reputation.go.
	AuditCount               int64
	AuditLambda              float64
	AuditWeight              float64
	AuditDQ                  float64
	SuspensionGracePeriod    time.Duration
	SuspensionDQEnabled      bool
	AuditsRequiredForVetting int64
	AuditHistory             AuditHistoryConfig
}

UpdateRequest is used to update a node's reputation status.