reputation

Documentation

Index

• Variables
• func AuditHistoryToPB(auditHistory AuditHistory) (historyPB *pb.AuditHistory)
• type AuditHistory
• type AuditHistoryConfig
• type AuditType
• type AuditWindow
• 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 AuditHistoryToPB

func AuditHistoryToPB(auditHistory AuditHistory) (historyPB *pb.AuditHistory)

AuditHistoryToPB converts an overlay.AuditHistory to a pb.AuditHistory.

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, 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) (err error)
	// SuspendNodeUnknownAudit suspends a storage node for unknown audits.
	SuspendNodeUnknownAudit(ctx context.Context, nodeID storj.NodeID, suspendedAt time.Time) (err error)
	// UpdateAuditHistory updates a node's audit history
	UpdateAuditHistory(ctx context.Context, oldHistory []byte, updateReq UpdateRequest, auditTime time.Time) (res *UpdateAuditHistoryResponse, err error)
}

DB is an interface for storing reputation data.

type Info

type Info struct {
	AuditSuccessCount           int64
	TotalAuditCount             int64
	VettedAt                    *time.Time
	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.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) (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
	// 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.