reputation

Documentation

Index

• Variables
• func AddAuditToHistory(a *pb.AuditHistory, online bool, auditTime time.Time, ...) error
• func DuplicateAuditHistory(auditHistory *pb.AuditHistory) *pb.AuditHistory
• type AuditHistoryConfig
• type AuditType
  • func (auditType AuditType) String() string
• type Config
• type DB
• type Info
• type Service
  • func NewService(log *zap.Logger, overlay overlay.DB, db DB, config Config) *Service
  • func (service *Service) ApplyAudit(ctx context.Context, nodeID storj.NodeID, reputation overlay.ReputationStatus, ...) (err error)
  • func (service *Service) Close() error
  • func (service *Service) Get(ctx context.Context, nodeID storj.NodeID) (info *Info, err error)
  • func (service *Service) TestDisqualifyNode(ctx context.Context, nodeID storj.NodeID, ...) (err error)
  • func (service *Service) TestSuspendNodeUnknownAudit(ctx context.Context, nodeID storj.NodeID, suspendedAt time.Time) (err error)
  • func (service *Service) TestUnsuspendNodeUnknownAudit(ctx context.Context, nodeID storj.NodeID) (err error)
• type UpdateAuditHistoryResponse
• type UpdateRequest

Variables

var (

	// Error is the default reputation errs class.
	Error = errs.Class("reputation")
	// ErrNodeNotFound is returned if a node does not exist in database.
	ErrNodeNotFound = errs.Class("node not found")
)

Functions

func AddAuditToHistory

func AddAuditToHistory(a *pb.AuditHistory, online bool, auditTime time.Time, config AuditHistoryConfig) error

AddAuditToHistory adds a single online/not-online event to an AuditHistory. If the AuditHistory contains windows that are now outside the tracking period, those windows will be trimmed.

func DuplicateAuditHistory

func DuplicateAuditHistory(auditHistory *pb.AuditHistory) *pb.AuditHistory

DuplicateAuditHistory creates a duplicate (deep copy) of an AuditHistory object.

Types

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
)

func (AuditType) String

func (auditType AuditType) String() string

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) (_ *Info, err error)
	Get(ctx context.Context, nodeID storj.NodeID) (*Info, error)

	// UnsuspendNodeUnknownAudit unsuspends a storage node for unknown audits.
	UnsuspendNodeUnknownAudit(ctx context.Context, nodeID storj.NodeID) (err error)
	// DisqualifyNode disqualifies a storage node.
	DisqualifyNode(ctx context.Context, nodeID storj.NodeID, disqualifiedAt time.Time, reason overlay.DisqualificationReason) (err error)
	// SuspendNodeUnknownAudit suspends a storage node for unknown audits.
	SuspendNodeUnknownAudit(ctx context.Context, nodeID storj.NodeID, suspendedAt time.Time) (err error)
}

DB is an interface for storing reputation data.

type Info

type Info struct {
	AuditSuccessCount           int64
	TotalAuditCount             int64
	VettedAt                    *time.Time
	UnknownAuditSuspended       *time.Time
	OfflineSuspended            *time.Time
	UnderReview                 *time.Time
	Disqualified                *time.Time
	DisqualificationReason      overlay.DisqualificationReason
	OnlineScore                 float64
	AuditHistory                *pb.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.DB, db DB, config Config) *Service

NewService creates a new reputation service.

func (*Service) ApplyAudit

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

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

func (*Service) Close

func (service *Service) Close() error

Close closes resources.

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. If a node is not found in the DB, default reputation information is returned.

func (*Service) TestDisqualifyNode

func (service *Service) TestDisqualifyNode(ctx context.Context, nodeID storj.NodeID, reason overlay.DisqualificationReason) (err error)

TestDisqualifyNode disqualifies a storage node.

func (*Service) TestSuspendNodeUnknownAudit

func (service *Service) TestSuspendNodeUnknownAudit(ctx context.Context, nodeID storj.NodeID, suspendedAt time.Time) (err error)

TestSuspendNodeUnknownAudit suspends a storage node for unknown audits.

func (*Service) TestUnsuspendNodeUnknownAudit

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

TestUnsuspendNodeUnknownAudit unsuspends a storage node for unknown audits.

type UpdateAuditHistoryResponse

type UpdateAuditHistoryResponse struct {
	NewScore           float64
	TrackingPeriodFull bool
	History            []byte
}

UpdateAuditHistoryResponse contains information returned by UpdateAuditHistory.

type UpdateRequest

type UpdateRequest struct {
	NodeID       storj.NodeID
	AuditOutcome AuditType
	// Config is a copy of the Config struct from the satellite.
	// It is part of the UpdateRequest struct in order to be more easily
	// accessible from satellitedb code.
	Config
}

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