service

type ActivityStatus string

type App struct {
	// Service is the scaling advisor service instance.
	Service ScalingAdvisorService
	// Ctx is the application context.
	Ctx context.Context
	// Cancel is the context cancellation function.
	Cancel context.CancelFunc
}

type ClusterSnapshot struct {
	// Pods are the pods that are present in the cluster.
	Pods []PodInfo
	// Nodes are the nodes that are present in the cluster.
	Nodes []NodeInfo
	// PriorityClasses are the priority classes that are present in the cluster.
	PriorityClasses []schedulingv1.PriorityClass
	// RuntimeClasses are the runtime classes that are present in the cluster.
	RuntimeClasses []nodev1.RuntimeClass
}

type GetNodeScoreSelector func(scoringStrategy commontypes.NodeScoringStrategy) (NodeScoreSelector, error)

type GetNodeScorer func(scoringStrategy commontypes.NodeScoringStrategy, instanceTypeInfoAccess InstancePricingAccess, weightsFn GetWeightsFunc) (NodeScorer, error)

type GetProviderInstancePricingAccessFunc func(provider commontypes.CloudProvider, instanceTypeInfoPath string) (InstancePricingAccess, error)

type GetWeightsFunc func(instanceType string) (map[corev1.ResourceName]float64, error)

type InstancePriceInfo struct {
	// InstanceType is the name of the instance type.
	InstanceType string `json:"instanceType"`
	// Region is the cloud region where the instance is available.
	Region string `json:"region"`
	// OS is the operating system for the instance type.
	OS string `json:"os"`
	// Memory is the amount of memory in GB for the instance type.
	Memory int64 `json:"memory"`
	// GPUMemory is the amount of GPU memory in GB for the instance type.
	GPUMemory int64 `json:"GPUMemory"`
	// HourlyPrice is the hourly cost for the instance type.
	HourlyPrice float64 `json:"hourlyPrice"`
	// GPU is the number of GPUs for the instance type.
	GPU int32 `json:"GPU"`
	// VCPU is the number of virtual CPUs for the instance type.
	VCPU int32 `json:"VCPU"`
}

type InstancePricingAccess interface {
	// GetInfo gets the InstancePriceInfo (whicn includes price) for the given region and instance type.
	// TODO: should we also pass OS name here ? if so, we need to need to change ClusterScalingConstraint.
	GetInfo(region, instanceTypeName string) (InstancePriceInfo, error)
}

type NodeInfo struct {
	// Capacity is the total resource capacity of the node.
	Capacity map[corev1.ResourceName]int64 `json:"capacity,omitempty"`
	// Allocatable is the allocatable resource capacity of the node.
	Allocatable map[corev1.ResourceName]int64 `json:"allocatable,omitempty"`
	// CSIDriverVolumeMaximums is a map of CSI driver names to the maximum number of unique volumes managed by the
	// CSI driver that can be used on a node.
	CSIDriverVolumeMaximums map[string]int32 `json:"csiDriverVolumeMaximums,omitempty"`
	// InstanceType is the instance type for the Node.
	InstanceType string `json:"instanceType"`
	ResourceMeta
	// Taints are the node's taints.
	Taints []corev1.Taint `json:"taints,omitempty"`
	// Conditions are the node's conditions.
	Conditions []corev1.NodeCondition `json:"conditions,omitempty"`
	// Unschedulable indicates whether the node is unschedulable.
	Unschedulable bool `json:"unschedulable"`
}

type NodePodAssignment struct {
	// Node contains the resource information for the node.
	Node NodeResourceInfo
	// ScheduledPods contains the list of pods scheduled to this node.
	ScheduledPods []PodResourceInfo
}

type NodeResourceInfo struct {
	// Capacity is the total resource capacity of the node.
	Capacity map[corev1.ResourceName]int64
	// Allocatable is the allocatable resource capacity of the node.
	Allocatable map[corev1.ResourceName]int64
	// Name is the node name.
	Name string
	// InstanceType is the cloud instance type of the node.
	InstanceType string
}

type NodeScore struct {
	ScaledNodeResource NodeResourceInfo
	// Placement represents the placement information for the Node.
	Placement sacorev1alpha1.NodePlacement
	// ID uniquely identifies this NodeScore
	ID              string
	UnscheduledPods []types.NamespacedName
	// Value is the score value for this Node.
	Value int
}

type NodeScoreSelector func(groupNodeScores []NodeScore, weightsFn GetWeightsFunc, pricing InstancePricingAccess) (winningNodeScore *NodeScore, err error)

type NodeScorer interface {
	// Compute computes the node score given the NodeScorerArgs. On failure, it must return an error with the sentinel error api.ErrComputeNodeScore
	Compute(args NodeScorerArgs) (NodeScore, error)
}

type NodeScorerArgs struct {
	// ID that must be given to the NodeScore produced by the NodeScorer
	ID string
	// Placement represents the placement information for the Node.
	Placement sacorev1alpha1.NodePlacement
	// ScaledAssignment represents the assignment of the scaled Node for the current run.
	ScaledAssignment *NodePodAssignment
	// OtherAssignments represent the assignment of unscheduled Pods to either an existing Node which is part of the ClusterSnapshot
	// or it is a winning simulated Node from a previous run.
	OtherAssignments []NodePodAssignment
	// UnscheduledPods is the slice of unscheduled pods that remain unscheduled after simulation is completed.
	UnscheduledPods []types.NamespacedName
}

type PodInfo struct {
	ResourceMeta
	// AggregatedRequests is an aggregated resource requests for all containers of the Pod.
	AggregatedRequests map[corev1.ResourceName]int64 `json:"aggregatedRequests,omitempty"`
	// Volumes are the volumes that are attached to the Pod.
	Volumes []corev1.Volume `json:"volumes,omitempty"`
	// NodeSelector is the node selector for the Pod.
	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
	// NodeName is the name of the node where the Pod is scheduled.
	NodeName string `json:"nodeName,omitempty"`
	// Affinity is the affinity rules for the Pod.
	Affinity *corev1.Affinity `json:"affinity,omitempty"`
	// SchedulerName is the name of the scheduler that should be used to schedule the Pod.
	SchedulerName string `json:"schedulerName,omitempty"`
	// Tolerations are the tolerations for the Pod.
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
	// PriorityClassName is the name of the priority class that should be used to schedule the Pod.
	PriorityClassName         string                            `json:"priorityClassName,omitempty"`
	Priority                  *int32                            `json:"priority,omitempty"`
	PreemptionPolicy          *corev1.PreemptionPolicy          `json:"preemptionPolicy,omitempty"`
	RuntimeClassName          *string                           `json:"runtimeClassName,omitempty"`
	Overhead                  map[corev1.ResourceName]int64     `json:"overhead,omitempty"`
	TopologySpreadConstraints []corev1.TopologySpreadConstraint `json:"topologySpreadConstraints,omitempty"`
	ResourceClaims            []corev1.PodResourceClaim         `json:"resourceClaims,omitempty"`
}

type PodResourceInfo struct {
	// AggregatedRequests is an aggregated resource requests for all containers of the Pod.
	AggregatedRequests map[corev1.ResourceName]int64
	// NamespacedName contains the namespace and name of the pod.
	types.NamespacedName
	// UID is the unique identifier for the pod.
	UID types.UID
}

type PriceKey struct {
	// Name is the instance type name.
	Name string
	// Region is the cloud region.
	Region string
}

type ResourceMeta struct {
	// UID is the unique identifier for the resource.
	UID types.UID `json:"uid"`
	types.NamespacedName
	// Labels are the labels associated with the resource.
	Labels map[string]string `json:"labels,omitempty"`
	// Annotations are the annotations associated with the resource.
	Annotations map[string]string `json:"annotations,omitempty"`
	// DeletionTimestamp is the timestamp when the resource deletion was triggered.
	DeletionTimestamp *metav1.Time `json:"deletionTimestamp,omitempty"`
	// OwnerReferences are the owner references associated with the resource.
	OwnerReferences []metav1.OwnerReference `json:"ownerReferences,omitempty"`
}

type ScalingAdviceRequest struct {
	// Snapshot is the snapshot of the resources in the cluster at the time of the request.
	Snapshot *ClusterSnapshot
	// Feedback captures feedback from the consumer of the scaling advice, which can be used to improve future scaling advice generation.
	Feedback *sacorev1alpha1.ClusterScalingFeedback
	// Constraint represents the constraints using which the scaling advice is generated.
	Constraint *sacorev1alpha1.ClusterScalingConstraint
	ScalingAdviceRequestRef
	// EnableDiagnostics indicates whether diagnostics should be enabled for the scaling advice generation.
	// If it is enabled then it will populate ScalingAdviceResponse.ScalingAdvice.Status.Diagnostic field.
	EnableDiagnostics bool
}

type ScalingAdviceRequestRef struct {
	// ID is the Request unique identifier for which this response is generated.
	ID string
	// CorrelationID is the correlation identifier for the request. It can be used to correlate a response with a request.
	CorrelationID string
}

type ScalingAdviceResponse struct {
	// ScalingAdvice contains the scaling advice generated by the scaling advisor service.
	ScalingAdvice *sacorev1alpha1.ClusterScalingAdvice
	// Diagnostic provides diagnostics information for the scaling advice.
	// This is only set by the scaling advisor service if ScalingAdviceRequest.EnableDiagnostics is set to true.
	Diagnostics *sacorev1alpha1.ScalingAdviceDiagnostic
	// RequestRef encapsulates the unique reference to a request for which this response is produced.
	RequestRef ScalingAdviceRequestRef
	// Message is a human-readable message providing additional context about the response.
	Message string
}

type ScalingAdviceResponseFn func(response ScalingAdviceResponse) error

type ScalingAdviceResult struct {
	// Response contains a piece of scaling advice generated by the service.
	// It is non-nil only when Err is nil.
	Response *ScalingAdviceResponse

	// Err contains a fatal error that occurred during generation.
	// It is non-nil only when Response is nil.
	Err error
}

type ScalingAdvisorService interface {
	commontypes.Service
	// GenerateAdvice begins generating scaling advice for the given request.
	//
	// It returns a channel of ScalingAdviceResult values. The channel will be closed
	// when advice generation is completed or a fatal error has occurred.
	//
	// The caller must consume all events from the channel until it is closed to
	// avoid leaking goroutines inside the service implementation.
	//
	// The provided context can be used to cancel generation prematurely. In this
	// case, the channel will be closed without further events.
	GenerateAdvice(ctx context.Context, req ScalingAdviceRequest) <-chan ScalingAdviceResult
}

type ScalingAdvisorServiceConfig struct {
	// CloudProvider is the cloud provider for which the scaling advisor service is initialized.
	CloudProvider commontypes.CloudProvider
	// LogBaseDir is the base directory for storing log files used by the scaling advisor service.
	LogBaseDir string
	commontypes.ServerConfig
	// MinKAPIConfig holds the configuration for the MinKAPI server used by the scaling advisor service.
	MinKAPIConfig mkapi.Config
	commontypes.QPSBurst
	// MaxParallelSimulations is the maximum number of parallel simulations that can be run by the scaling advisor service.
	MaxParallelSimulations int
}

type SchedulerHandle interface {
	io.Closer
	// GetParams returns the parameters used to launch the scheduler instance.
	GetParams() SchedulerLaunchParams
}

type SchedulerLaunchParams struct {
	// EventSink is the event sink used to send events from the kube-scheduler.
	EventSink events.EventSink
	commontypes.ClientFacades
}

type SchedulerLauncher interface {
	// Launch launches and runs an embedded scheduler instance asynchronously.
	// If the limit of running schedulers is reached, it will block.
	// An error is returned if the scheduler fails to start.
	Launch(ctx context.Context, params *SchedulerLaunchParams) (SchedulerHandle, error)
}

type SimGroupKey struct {
	// NodePoolPriority is the priority of the node pool.
	NodePoolPriority int32
	// NodeTemplatePriority is the priority of the node template.
	NodeTemplatePriority int32
}

type SimGroupRunResult struct {
	// Name of the group that produced this result.
	Name string
	// SimulationResults contains the results from all simulations in the group.
	SimulationResults []SimRunResult
	// Key is the simulation group key (partition key)
	Key SimGroupKey
}

type SimGroupScores struct {
	// WinnerNodeScore is the highest scoring node in the group.
	WinnerNodeScore *NodeScore
	// WinnerNode is the actual node corresponding to the winner score.
	WinnerNode *corev1.Node
	// AllNodeScores contains all computed node scores for the group.
	AllNodeScores []NodeScore
}

type SimRunResult struct {
	// Name of the Simulation that produced this result.
	Name string
	// ScaledNode is the simulated scaled node.
	ScaledNode *corev1.Node
	NodeScorerArgs
}

type Simulation interface {
	// Name returns the logical simulation name
	Name() string
	// ActivityStatus returns the current ActivityStatus of the simulation
	ActivityStatus() ActivityStatus
	// NodePool returns the target node pool against which the simulation should be run
	NodePool() *sacorev1alpha1.NodePool
	// NodeTemplate returns the target node template against which the simulation should be run
	NodeTemplate() *sacorev1alpha1.NodeTemplate
	// Run executes the simulation to completion and returns any encountered error. This is a blocking call and callers are
	// expected to manage concurrency and SimRunResult consumption.
	Run(ctx context.Context) error
	// Result returns the latest SimRunResult if the simulation is in ActivityStatusSuccess,
	// or nil if the simulation is in ActivityStatusPending or ActivityStatusRunning
	// or an error if the ActivityStatus is ActivityStatusFailure
	Result() (SimRunResult, error)
}

type SimulationArgs struct {
	// SchedulerLauncher is used to launch scheduler instances for the simulation.
	SchedulerLauncher SchedulerLauncher
	// View is the MinKAPI view used for the simulation.
	View mkapi.View
	// NodePool is the target node pool for the simulation.
	NodePool *sacorev1alpha1.NodePool
	// GroupRunPassCounter is an atomic counter for tracking simulation group passes.
	GroupRunPassCounter *atomic.Uint32
	// AvailabilityZone is the target availability zone for the simulation.
	AvailabilityZone string
	// NodeTemplateName is the name of the node template to use in the simulation.
	NodeTemplateName string
	// TrackPollInterval is the polling interval for tracking pod scheduling in the view and reconciling simulation state
	TrackPollInterval time.Duration
}

type SimulationCreator interface {
	// Create creates a simulation instance with the given name and arguments.
	Create(name string, args *SimulationArgs) (Simulation, error)
}

type SimulationCreatorFunc func(name string, args *SimulationArgs) (Simulation, error)

type SimulationGroup interface {
	// Name returns the name of the simulation group.
	Name() string
	// GetKey returns the simulation group key.
	GetKey() SimGroupKey
	// GetSimulations returns all simulations in this group.
	GetSimulations() []Simulation
	// Run executes all simulations in the group and returns the results.
	Run(ctx context.Context) (SimGroupRunResult, error)
}

type SimulationGrouper interface {
	Group(simulations []Simulation) ([]SimulationGroup, error)
}

type SimulationGrouperFunc func(simulations []Simulation) ([]SimulationGroup, error)