scalingalgorithm

type ActionType string

type MetricsPollResponse struct {
	// Actions contains the list of scaling actions to take as a result of the analysis
	Actions []ScalingAction
	// The updated scaling state to be persisted until the next run
	Status iface.ScalingAlgorithmStatus
	// When to poll metrics again
	NextPoll *time.Duration
}

type ScalingAction struct {
	ScalingGroupKey string     `json:"scaling_group_key"`
	Action          ActionType `json:"action"`
	Count           *int32     `json:"count,omitempty"`
}

type ScalingAlgorithm interface {
	// CompatibleLaunchStrategies returns the list of launch strategies the scaling algorithm can work with
	CompatibleLaunchStrategies() []computeprovider.LaunchStrategy

	// ValidateConfig checks the provided config for correctness. If any issues are found returns an
	// error with a description. Returns nil if no issues are found.
	ValidateConfig(ctx context.Context, config iface.ScalingAlgorithmConfig) error

	// ProcessTaskAdd handles events triggered from Matching Service signaling. Might request certain actions
	// to be taken (e.g. scale-up or down) and return an adjusted status.
	ProcessTaskAdd(ctx context.Context, config iface.ScalingAlgorithmConfig, priorStatus iface.ScalingAlgorithmStatus, event iface.SignalTaskAddRequest) (*TaskAddResponse, error)

	// ProcessDeferredScalingDecision handles deferred scaling decisions requested by a prior
	// ActionTypeDeferredScalingDecision action. event is forwarded verbatim from the original
	// task-add signal. The snapshot returned by getMetricsSnapshot is pre-filtered to the
	// scaling group's effective task types (fields outside that set are nil); see the
	// ScalingMetricsSnapshotGetter type for caching and read-only semantics.
	//
	// Why this exists: ProcessTaskAdd runs as a local activity to keep the signal-handler
	// path fast, but local activities cannot use the metrics API (it issues a query against
	// the same workflow, which would deadlock). Algorithms that need a metrics snapshot — or
	// any other higher-latency processing — emit ActionTypeDeferredScalingDecision to push
	// that work into this normal activity, where the snapshot is available.
	//
	// The returned Actions MUST NOT contain ActionTypeDeferredScalingDecision: deferred
	// actions cannot themselves chain into more deferred work.
	ProcessDeferredScalingDecision(ctx context.Context, config iface.ScalingAlgorithmConfig, priorStatus iface.ScalingAlgorithmStatus, event iface.SignalTaskAddRequest, getMetricsSnapshot ScalingMetricsSnapshotGetter) (*TaskAddResponse, error)

	// ProcessMetricsPoll handles the results of regular queue metrics polls. It only recieves data
	// for task queue types the scaling algorithm is responsible for. Can return a set of actions to
	// take as a result, as well as updated scaling status and when to poll again at the latest.
	//
	// Note: the next invocation might be earlier than the provided time, if other algorithms requested
	// a higher frequency.
	//
	// The returned Actions MUST NOT contain ActionTypeDeferredScalingDecision as it is not supported.
	ProcessMetricsPoll(ctx context.Context, config iface.ScalingAlgorithmConfig, priorStatus iface.ScalingAlgorithmStatus, metricsSnapshot ScalingMetricsSnapshot) (*MetricsPollResponse, error)

	// TaskQueueRegistrationActions returns the actions that bring a group's worker set up enough to
	// register its task queues, plus the reconciled status. The algorithm owns both the size
	// and the launch strategy: worker-set algorithms emit an UpdateWorkerSetSize sized to
	// their floor/initial count (at least 1) and fold that count into the returned Status;
	// invoke-only algorithms emit an InvokeWorker and leave Status untouched. The caller
	// applies the actions and persists the Status.
	TaskQueueRegistrationActions(ctx context.Context, config iface.ScalingAlgorithmConfig, status iface.ScalingAlgorithmStatus) (*TaskQueueRegistrationResponse, error)
}

type ScalingAlgorithmConstructor func(context.Context) (ScalingAlgorithm, error)

type ScalingMetricsSnapshot struct {
	Workflow *iface.QueueTypeScalingMetrics `json:"workflow,omitempty"`
	Activity *iface.QueueTypeScalingMetrics `json:"activity,omitempty"`
	Nexus    *iface.QueueTypeScalingMetrics `json:"nexus,omitempty"`
}

type ScalingMetricsSnapshotGetter func() (*ScalingMetricsSnapshot, error)

type TaskAddResponse struct {
	// Actions contains the list of scaling actions to take as a result of the analysis
	Actions []ScalingAction
	// The updated scaling status to be persisted until the next run
	Status iface.ScalingAlgorithmStatus
	// The number of task-add events that were throttled
	ThrottledCount int
}

type TaskQueueRegistrationResponse struct {
	// Actions contains the scaling actions that bring a group's worker set up enough to
	// register its task queues (an UpdateWorkerSetSize for worker-set algorithms, an
	// InvokeWorker for invoke-only ones).
	Actions []ScalingAction
	// Status is the reconciled status to persist, so a later decision does not see a
	// phantom count for a resize made on the registration path.
	Status iface.ScalingAlgorithmStatus
}