autoscale

type Condition struct {
	Healthy bool   `json:"healthy"`
	Reason  string `json:"reason"`
	Message string `json:"message"`
}

type Controller struct {
	Store         Store
	Signals       Signals
	Recorder      Recorder
	Nudge         func()
	Ceiling       int
	FlapThreshold int
	Logger        *slog.Logger
	Now           func() time.Time
}

type Decision struct {
	Current   int
	Desired   int
	Value     float64
	Reason    string
	BlockedBy string
	Message   string
	DownSince time.Time
	DownFloor int
}

type Event struct {
	ID        int64     `json:"id"`
	App       string    `json:"app"`
	Kind      string    `json:"kind"`
	Current   int       `json:"current"`
	Desired   int       `json:"desired"`
	Value     float64   `json:"value"`
	Reason    string    `json:"reason"`
	BlockedBy string    `json:"blocked_by"`
	Detail    string    `json:"detail"`
	At        time.Time `json:"at"`
}

type Gauge struct {
	App        string
	Current    int
	Desired    int
	NoCapacity bool
	Flaps      int
}

type Input struct {
	Now     time.Time
	Current int
	// Value is the metric in the units of the policy target; it is only
	// meaningful while ValueKnown is true.
	Value      float64
	ValueKnown bool
	// MetricNote says why the value is unknown.
	MetricNote string
	// Ceiling is the operator's global maximum; 0 means none.
	Ceiling       int
	LastScaleUp   time.Time
	LastScaleDown time.Time
	// DownSince and DownFloor carry the scale down stabilization window
	// between calls: when a lower count was first recommended and the highest
	// count recommended since.
	DownSince time.Time
	DownFloor int
	// SpendBlocked is true while a spend cap is being enforced.
	SpendBlocked bool
	// Headroom reports how many of extra more replicas the placement can
	// hold. A negative answer, or a nil func, means unknown and never blocks.
	Headroom func(extra int) int
}

type Policy struct {
	App         string  `json:"app"`
	MinReplicas int     `json:"min_replicas"`
	MaxReplicas int     `json:"max_replicas"`
	Metric      string  `json:"metric"`
	Target      float64 `json:"target"`
	// Scale up only when the metric is this far above Target, scale down only
	// when it is this far below: the gap between them is the dead band.
	ScaleUpTolerancePct   int `json:"scale_up_tolerance_pct"`
	ScaleDownTolerancePct int `json:"scale_down_tolerance_pct"`
	ScaleUpCooldownSecs   int `json:"scale_up_cooldown_secs"`
	ScaleDownCooldownSecs int `json:"scale_down_cooldown_secs"`
	StabilizationSecs     int `json:"stabilization_secs"`
	MaxStepUp             int `json:"max_step_up"`
	MaxStepDown           int `json:"max_step_down"`
}

type Reading struct {
	Value float64
	Known bool
	// Note says why the value is unknown.
	Note string
}

type Recorder interface {
	RecordGauges(ctx context.Context, gauges []Gauge, at time.Time) error
}

type Signals interface {
	Metric(ctx context.Context, p Policy, current int, now time.Time) (Reading, error)
	// Headroom reports how many of extra more replicas fit on the app's node,
	// or a negative number when that cannot be told.
	Headroom(ctx context.Context, app string, extra int) (int, error)
	// SpendEnforced returns the spend cap action in force for the app, "" when none.
	SpendEnforced(ctx context.Context, app string) (string, error)
}

type State struct {
	App           string
	Current       int
	Desired       int
	Value         float64
	ValueKnown    bool
	Reason        string
	BlockedBy     string
	Message       string
	LastScaleUp   time.Time
	LastScaleDown time.Time
	DownSince     time.Time
	DownFloor     int
	UpdatedAt     time.Time
}

type Status struct {
	Policy
	EffectiveMax int        `json:"effective_max"`
	Current      int        `json:"current"`
	Desired      int        `json:"desired"`
	Value        float64    `json:"value"`
	ValueKnown   bool       `json:"value_known"`
	BlockedBy    string     `json:"blocked_by"`
	Flaps1h      int        `json:"flaps_1h"`
	Flapping     bool       `json:"flapping"`
	LastScaleUp  *time.Time `json:"last_scale_up,omitempty"`
	LastScaleDn  *time.Time `json:"last_scale_down,omitempty"`
	EvaluatedAt  *time.Time `json:"evaluated_at,omitempty"`
	Condition    Condition  `json:"condition"`
}

type Store interface {
	ListAutoscalePolicies(ctx context.Context) ([]Policy, error)
	GetAutoscalePolicy(ctx context.Context, app string) (Policy, error)
	SaveAutoscalePolicy(ctx context.Context, p Policy, ev Event, now time.Time) error
	DeleteAutoscalePolicy(ctx context.Context, app string, ev Event) error
	GetAutoscaleState(ctx context.Context, app string) (State, bool, error)
	SaveAutoscaleState(ctx context.Context, st State, events []Event) error
	ListAutoscaleEvents(ctx context.Context, app string, limit int) ([]Event, error)
	// AutoscaleReplicas returns the app's desired replica count and whether it
	// is suspended, or ErrNotFound.
	AutoscaleReplicas(ctx context.Context, app string) (replicas int, suspended bool, err error)
	// SetAutoscaleReplicas writes the app's desired replica count. It is the
	// only writer of that column besides a manual update.
	SetAutoscaleReplicas(ctx context.Context, app string, replicas int) error
}