overload

Documentation

Overview

Package overload implements a 5-stage degradation ladder for backpressure and load shedding.

The overload manager monitors CPU utilization and progressively escalates through stages: Normal → Expand → Reap → Reorder → Backpressure → Reject. Each stage applies engine hooks to shed load. De-escalation requires sustained improvement and respects per-stage cooldown timers.

Index

• type Config
  • func DefaultConfig() Config
• type EngineHooks
• type Manager
  • func NewManager(cfg Config, mon cpumon.Monitor, hooks EngineHooks, logger *slog.Logger) *Manager
  • func (m *Manager) Run(ctx context.Context) error
  • func (m *Manager) SetFreezeHook(fn func(frozen bool))
  • func (m *Manager) Stage() Stage
• type Stage
  • func (s Stage) String() string
• type StageConfig

Types

type Config

type Config struct {
	Enabled  bool
	Stages   [6]StageConfig
	Interval time.Duration
}

Config configures the overload manager.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the default overload configuration per SDD 10.1.

type EngineHooks

type EngineHooks interface {
	ExpandWorkers(maxWorkers int) int
	ReapIdleConnections(idleThreshold time.Duration) int
	SetSchedulingMode(lifo bool)
	SetAcceptPaused(paused bool)
	SetAcceptDelay(d time.Duration)
	SetMaxConcurrent(n int)
	ShrinkWorkers(baseWorkers int, idleThreshold time.Duration) int
	ActiveConnections() int64
	WorkerCount() int
}

EngineHooks is the interface engines implement to respond to overload actions. The overload package does not import any engine package.

type Manager

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

Manager monitors CPU utilization and drives a 5-stage degradation ladder.

func NewManager

func NewManager(cfg Config, mon cpumon.Monitor, hooks EngineHooks, logger *slog.Logger) *Manager

NewManager creates an overload manager.

func (*Manager) Run

func (m *Manager) Run(ctx context.Context) error

Run starts the overload evaluation loop. Blocks until ctx is canceled.

func (*Manager) SetFreezeHook

func (m *Manager) SetFreezeHook(fn func(frozen bool))

SetFreezeHook registers a callback for freeze/unfreeze (adaptive engine integration).

func (*Manager) Stage

func (m *Manager) Stage() Stage

Stage returns the current overload stage.

type Stage

type Stage uint8

Stage represents the current overload degradation level.

const (
	Normal       Stage = iota // normal operation
	Expand                    // expand worker pool
	Reap                      // reap idle connections
	Reorder                   // switch to LIFO scheduling
	Backpressure              // delay accepts, limit concurrency
	Reject                    // reject new connections
)

Overload degradation stages, ordered by severity.

func (Stage) String

func (s Stage) String() string

type StageConfig

type StageConfig struct {
	EscalateThreshold   float64
	EscalateSustained   time.Duration
	DeescalateThreshold float64
	DeescalateSustained time.Duration
	Cooldown            time.Duration
}

StageConfig defines the thresholds and timing for a single stage transition.