reputation

type Cleaner interface {
	// Cleanup removes expired entries from storage.
	// This is called periodically by the service to prevent memory bloat.
	Cleanup()
}

type Config struct {
	// Enabled determines if reputation tracking is active.
	// IMPORTANT: Reputation is MANDATORY - setting this to false is ignored.
	// This field is kept for backward compatibility.
	Enabled bool `yaml:"enabled"`

	// InitialScore is the starting score for new endpoints.
	// Default: 80
	InitialScore float64 `yaml:"initial_score"`

	// MinThreshold is the minimum score for endpoint selection.
	// Default: 30
	MinThreshold float64 `yaml:"min_threshold"`

	// RecoveryTimeout is the duration after which a low-scoring endpoint
	// with no signals is reset to InitialScore. This allows endpoints
	// to recover from temporary failures (crashes, network issues, etc.).
	// IMPORTANT: This is IGNORED when TieredSelection.Probation or HealthChecks are enabled.
	// Signal-based recovery takes precedence over time-based recovery.
	// Default: 5m
	RecoveryTimeout time.Duration `yaml:"recovery_timeout"`

	// StorageType specifies the storage backend ("memory" or "redis").
	// Default: "memory"
	StorageType string `yaml:"storage_type"`

	// KeyGranularity determines how endpoints are grouped for scoring (global default).
	// Options: "per-endpoint" (default), "per-domain", "per-supplier"
	// Default: "per-endpoint"
	KeyGranularity string `yaml:"key_granularity"`

	// ServiceOverrides allows per-service configuration overrides.
	// Use this to apply different granularity rules to specific services.
	ServiceOverrides map[string]ServiceConfig `yaml:"service_overrides,omitempty"`

	// SyncConfig configures background synchronization behavior.
	SyncConfig SyncConfig `yaml:"sync_config"`

	// TieredSelection configures endpoint selection based on reputation tiers.
	// Endpoints are grouped into tiers based on their scores.
	TieredSelection TieredSelectionConfig `yaml:"tiered_selection,omitempty"`

	// Latency configures how response latency affects reputation scoring.
	// Fast endpoints get bonuses, slow endpoints get penalties.
	Latency LatencyConfig `yaml:"latency,omitempty"`

	// SignalImpacts configures how much each signal type affects the reputation score.
	// This allows tuning how aggressively endpoints are penalized or rewarded.
	SignalImpacts SignalImpactsConfig `yaml:"signal_impacts,omitempty"`
}

type DomainKeyBuilder struct{}

type EndpointKey struct {
	ServiceID    protocol.ServiceID
	EndpointAddr protocol.EndpointAddr
	RPCType      sharedtypes.RPCType // REQUIRED: RPC type dimension for reputation tracking
}

type EndpointKeyBuilder struct{}

type KeyBuilder interface {
	// BuildKey creates an EndpointKey for the given service, endpoint, and RPC type.
	// The RPC type is required to track reputation separately for different protocols.
	BuildKey(serviceID protocol.ServiceID, endpointAddr protocol.EndpointAddr, rpcType sharedtypes.RPCType) EndpointKey
}

type LatencyConfig struct {
	// Enabled enables latency-aware scoring. Default: true
	Enabled bool `yaml:"enabled,omitempty"`

	// FastThreshold is the maximum latency for "fast" responses.
	// Fast responses get a bonus multiplier on success signals.
	// Default: 100ms (appropriate for blockchain services)
	FastThreshold time.Duration `yaml:"fast_threshold,omitempty"`

	// NormalThreshold is the maximum latency for "normal" responses.
	// Normal responses get standard success impact.
	// Default: 500ms
	NormalThreshold time.Duration `yaml:"normal_threshold,omitempty"`

	// SlowThreshold is the maximum latency for "slow" responses.
	// Slow responses get reduced success impact.
	// Default: 1000ms (1 second)
	SlowThreshold time.Duration `yaml:"slow_threshold,omitempty"`

	// PenaltyThreshold triggers a slow_response penalty signal.
	// Responses slower than this get a reputation penalty even if successful.
	// Default: 2000ms (2 seconds)
	PenaltyThreshold time.Duration `yaml:"penalty_threshold,omitempty"`

	// SevereThreshold triggers a very_slow_response penalty signal.
	// Responses slower than this get a larger reputation penalty.
	// Default: 5000ms (5 seconds)
	SevereThreshold time.Duration `yaml:"severe_threshold,omitempty"`

	// FastBonus is the multiplier for success impact when response is fast.
	// Default: 2.0 (fast success = +2 instead of +1)
	FastBonus float64 `yaml:"fast_bonus,omitempty"`

	// SlowPenalty is the multiplier for success impact when response is slow.
	// Default: 0.5 (slow success = +0.5 instead of +1)
	SlowPenalty float64 `yaml:"slow_penalty,omitempty"`

	// VerySlowPenalty is the multiplier for success when response is very slow.
	// Default: 0.0 (very slow success = +0, no reputation gain)
	VerySlowPenalty float64 `yaml:"very_slow_penalty,omitempty"`

	// ServiceProfiles defines latency thresholds for different service types.
	// Services can reference a profile by name, or define inline thresholds.
	// If a service doesn't match any profile, global defaults are used.
	ServiceProfiles map[string]LatencyProfile `yaml:"service_profiles,omitempty"`
}

type LatencyImpactResult struct {
	FinalImpact     float64
	BaseImpact      float64
	Modifier        float64
	LatencyCategory string // "fast", "normal", "slow", "very_slow", or "skipped"
	Latency         time.Duration
	Config          LatencyConfig
}

type LatencyMetrics struct {
	// LastLatency is the most recent response latency.
	LastLatency time.Duration

	// AvgLatency is the exponential moving average of response latency.
	// Updated using: avg = (1-alpha)*avg + alpha*new_sample, where alpha=0.1
	AvgLatency time.Duration

	// MinLatency is the minimum latency observed (best case).
	MinLatency time.Duration

	// MaxLatency is the maximum latency observed (worst case).
	MaxLatency time.Duration

	// SampleCount is the number of latency samples collected.
	SampleCount int64

	// LastUpdated is when the latency metrics were last updated.
	LastUpdated time.Time
}

type LatencyProfile struct {
	// Name is the profile identifier (e.g., "evm", "llm", "cosmos")
	Name string `yaml:"name,omitempty"`

	// Description explains what services this profile is for
	Description string `yaml:"description,omitempty"`

	// FastThreshold - responses faster than this get a bonus
	FastThreshold time.Duration `yaml:"fast_threshold"`

	// NormalThreshold - responses faster than this are considered normal
	NormalThreshold time.Duration `yaml:"normal_threshold"`

	// SlowThreshold - responses faster than this are slow but acceptable
	SlowThreshold time.Duration `yaml:"slow_threshold"`

	// PenaltyThreshold - responses slower than this get a penalty signal
	PenaltyThreshold time.Duration `yaml:"penalty_threshold"`

	// SevereThreshold - responses slower than this get a severe penalty
	SevereThreshold time.Duration `yaml:"severe_threshold"`
}

type ProbationConfig struct {
	// Enabled enables/disables the probation system.
	Enabled bool `yaml:"enabled,omitempty"`
	// Threshold is the score below which endpoints enter probation.
	Threshold float64 `yaml:"threshold,omitempty"`
	// TrafficPercent is the percentage of traffic sent to probation endpoints.
	TrafficPercent float64 `yaml:"traffic_percent,omitempty"`
	// RecoveryMultiplier multiplies the score increase for successful requests from probation.
	RecoveryMultiplier float64 `yaml:"recovery_multiplier,omitempty"`
}

type RecoveryConflictResult struct {
	// HasConflict indicates if there's a conflict between recovery mechanisms.
	HasConflict bool
	// HasNoRecovery indicates if no recovery mechanism is configured at all.
	HasNoRecovery bool
	// OriginalRecoveryTimeout is the recovery_timeout value before resolution.
	OriginalRecoveryTimeout time.Duration
	// Message contains a description of the issue found.
	Message string
}

type RedisConfig struct {
	// Address is the Redis server address (host:port).
	Address string `yaml:"address"`

	// Password for Redis authentication (optional).
	Password string `yaml:"password"`

	// DB is the Redis database number.
	DB int `yaml:"db"`

	// KeyPrefix is prepended to all keys stored in Redis.
	// Default: "path:reputation:"
	KeyPrefix string `yaml:"key_prefix"`

	// PoolSize is the maximum number of socket connections.
	// Default: 10
	PoolSize int `yaml:"pool_size"`

	// DialTimeout is the timeout for establishing new connections.
	// Default: 5s
	DialTimeout time.Duration `yaml:"dial_timeout"`

	// ReadTimeout is the timeout for socket reads.
	// Default: 3s
	ReadTimeout time.Duration `yaml:"read_timeout"`

	// WriteTimeout is the timeout for socket writes.
	// Default: 3s
	WriteTimeout time.Duration `yaml:"write_timeout"`
}

type ReputationService interface {
	// RecordSignal records a signal event for an endpoint.
	// Updates local cache immediately and queues async write to backend storage.
	// This method is non-blocking - it returns immediately after updating local cache.
	RecordSignal(ctx context.Context, key EndpointKey, signal Signal) error

	// GetScore retrieves the current reputation score for an endpoint.
	// Always reads from local cache for minimal latency (<1μs).
	// Returns the score or an error if the endpoint is not found.
	GetScore(ctx context.Context, key EndpointKey) (Score, error)

	// GetScores retrieves reputation scores for multiple endpoints.
	// Always reads from local cache for minimal latency.
	// Returns a map of endpoint keys to scores. Missing endpoints are omitted.
	GetScores(ctx context.Context, keys []EndpointKey) (map[EndpointKey]Score, error)

	// FilterByScore filters endpoints that meet the minimum score threshold.
	// Always reads from local cache for minimal latency.
	// Returns only endpoints with scores >= minThreshold.
	FilterByScore(ctx context.Context, keys []EndpointKey, minThreshold float64) ([]EndpointKey, error)

	// ResetScore resets an endpoint's score to the initial value.
	// Used for administrative purposes or testing.
	ResetScore(ctx context.Context, key EndpointKey) error

	// KeyBuilderForService returns the KeyBuilder for the given service.
	// Uses service-specific config if available, otherwise falls back to global default.
	KeyBuilderForService(serviceID protocol.ServiceID) KeyBuilder

	// SetServiceConfig sets per-service reputation configuration overrides.
	// This allows different services to have different initial scores and min thresholds.
	SetServiceConfig(serviceID protocol.ServiceID, config ServiceConfig)

	// GetInitialScoreForService returns the initial score for a service.
	// Uses per-service config if set, otherwise falls back to global default.
	GetInitialScoreForService(serviceID protocol.ServiceID) float64

	// GetMinThresholdForService returns the min threshold for a service.
	// Uses per-service config if set, otherwise falls back to global default.
	GetMinThresholdForService(serviceID protocol.ServiceID) float64

	// SetLatencyProfile sets per-service latency profile configuration.
	// This allows different services to have different latency thresholds and bonuses/penalties.
	SetLatencyProfile(serviceID protocol.ServiceID, latencyConfig LatencyConfig)

	// GetLatencyConfigForService returns the latency config for a service.
	// Uses per-service config if set, otherwise falls back to global default.
	GetLatencyConfigForService(serviceID protocol.ServiceID) LatencyConfig

	// Start begins background sync processes (e.g., Redis pub/sub, periodic refresh).
	// Should be called once during initialization.
	Start(ctx context.Context) error

	// Stop gracefully shuts down background processes and flushes pending writes.
	Stop() error

	// SetLogger sets the logger for the reputation service.
	// This enables debug logging for latency scoring and other operations.
	SetLogger(logger polylog.Logger)
}

type Score struct {
	// Value is the current score (0-100).
	// Higher scores indicate more reliable endpoints.
	Value float64

	// LastUpdated is when the score was last modified.
	LastUpdated time.Time

	// SuccessCount is the total number of successful requests.
	SuccessCount int64

	// ErrorCount is the total number of failed requests.
	ErrorCount int64

	// LatencyMetrics tracks response latency statistics for this endpoint.
	// Updated from both health checks and client requests.
	LatencyMetrics LatencyMetrics

	// CriticalStrikes counts consecutive critical/fatal errors without recovery.
	// Used by the strike system to apply extended cooldowns for persistently failing endpoints.
	// Reset to 0 when endpoint has a successful request.
	CriticalStrikes int

	// CooldownUntil is when the endpoint's cooldown period ends.
	// Endpoints in cooldown are excluded from selection even if their score is above threshold.
	// Set when CriticalStrikes exceeds StrikeThreshold.
	CooldownUntil time.Time
}

type ServiceConfig struct {
	// KeyGranularity overrides the global key granularity for this service.
	// Options: "per-endpoint", "per-domain", "per-supplier"
	KeyGranularity string `yaml:"key_granularity"`

	// InitialScore overrides the initial score for new endpoints in this service.
	// If 0, uses the global default.
	InitialScore float64 `yaml:"initial_score,omitempty"`

	// MinThreshold overrides the minimum score for endpoint selection in this service.
	// If 0, uses the global default.
	MinThreshold float64 `yaml:"min_threshold,omitempty"`

	// RecoveryTimeout overrides the recovery timeout for this service.
	// If 0, uses the global default.
	RecoveryTimeout time.Duration `yaml:"recovery_timeout,omitempty"`

	// HealthChecksEnabled indicates whether health checks are enabled for this service.
	// If true, time-based recovery is skipped (health checks handle recovery).
	HealthChecksEnabled bool

	// ProbationEnabled indicates whether probation is enabled for this service.
	// If true, time-based recovery is skipped (probation handles recovery).
	ProbationEnabled bool
}

type Signal struct {
	// Type categorizes the signal's severity.
	Type SignalType

	// Timestamp when the signal was generated.
	Timestamp time.Time

	// Latency of the request that generated this signal (if applicable).
	Latency time.Duration

	// Reason provides additional context for the signal.
	Reason string

	// Metadata holds additional signal-specific data.
	Metadata map[string]string
}

type SignalImpactsConfig struct {
	// Success is the score change for successful responses. Default: +1
	Success float64 `yaml:"success,omitempty"`

	// MinorError is the score change for minor errors (validation issues). Default: -3
	MinorError float64 `yaml:"minor_error,omitempty"`

	// MajorError is the score change for major errors (timeout, connection). Default: -10
	MajorError float64 `yaml:"major_error,omitempty"`

	// CriticalError is the score change for critical errors (HTTP 5xx). Default: -25
	CriticalError float64 `yaml:"critical_error,omitempty"`

	// FatalError is the score change for fatal errors (config issues). Default: -50
	FatalError float64 `yaml:"fatal_error,omitempty"`

	// RecoverySuccess is the score change for successful probation recovery. Default: +5
	// Reduced from +15 to require sustained good behavior for recovery.
	RecoverySuccess float64 `yaml:"recovery_success,omitempty"`

	// SlowResponse is the score change for slow responses. Default: -1
	SlowResponse float64 `yaml:"slow_response,omitempty"`

	// VerySlowResponse is the score change for very slow responses. Default: -3
	VerySlowResponse float64 `yaml:"very_slow_response,omitempty"`
}

type SignalType string

type Storage interface {
	// Get retrieves the score for an endpoint.
	// Returns ErrNotFound if the endpoint has no stored score.
	Get(ctx context.Context, key EndpointKey) (Score, error)

	// GetMultiple retrieves scores for multiple endpoints.
	// Returns a map containing only the endpoints that were found.
	// Missing endpoints are omitted from the result (no error).
	GetMultiple(ctx context.Context, keys []EndpointKey) (map[EndpointKey]Score, error)

	// Set stores or updates the score for an endpoint.
	Set(ctx context.Context, key EndpointKey, score Score) error

	// SetMultiple stores or updates scores for multiple endpoints.
	SetMultiple(ctx context.Context, scores map[EndpointKey]Score) error

	// Delete removes the score for an endpoint.
	// Returns nil if the endpoint doesn't exist.
	Delete(ctx context.Context, key EndpointKey) error

	// List returns all stored endpoint keys for a service.
	// If serviceID is empty, returns all endpoint keys.
	List(ctx context.Context, serviceID string) ([]EndpointKey, error)

	// Close releases any resources held by the storage.
	Close() error
}

type SupplierKeyBuilder struct{}

type SyncConfig struct {
	// RefreshInterval is how often to refresh scores from the backend storage.
	// Only applies when using shared storage (Redis).
	// Default: 5s
	RefreshInterval time.Duration `yaml:"refresh_interval"`

	// WriteBufferSize is the max number of pending writes to buffer before blocking.
	// Default: 1000
	WriteBufferSize int `yaml:"write_buffer_size"`

	// FlushInterval is how often to flush buffered writes to backend storage.
	// Default: 100ms
	FlushInterval time.Duration `yaml:"flush_interval"`
}

type TieredSelectionConfig struct {
	// Enabled enables/disables tiered selection.
	Enabled bool `yaml:"enabled,omitempty"`
	// Tier1Threshold is the minimum score for tier 1 (highest quality).
	Tier1Threshold float64 `yaml:"tier1_threshold,omitempty"`
	// Tier2Threshold is the minimum score for tier 2 (medium quality).
	Tier2Threshold float64 `yaml:"tier2_threshold,omitempty"`
	// Probation configures the probation system for recovering low-scoring endpoints.
	Probation ProbationConfig `yaml:"probation,omitempty"`
}

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