v1alpha1

type EmbeddedSandboxTemplate struct {
	// Template defines the Pod template. ALL Pods in this Pool share the same
	// resources (requests/limits). The image specified here is used as the IDLE image
	// unless IdleImage is explicitly set.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	// +optional
	Template *corev1.PodTemplateSpec `json:"template,omitempty"`

	// IdleImage is the image to use when Pods are in the idle state.
	// If not specified, the image from Template.Spec.Containers[0].Image will be used.
	// +optional
	IdleImage string `json:"idleImage,omitempty"`

	// Runtimes specifies the runtimes to use for the sandbox pods. Each runtime has a type and optional configuration.
	// If not specified, a default runtime will be used.
	// +listType=map
	// +listMapKey=name
	// +optional
	Runtimes []SandboxRuntimeSpec `json:"runtimes,omitempty"`
}

type PodCreationImagePolicy string

type PoolAutoscalingSpec struct {
	// Enabled controls whether the PoolAutoscaler is active.
	// When false (default), spec.replicas is the only source of truth and
	// MinReplicas/MaxReplicas are ignored.
	// +optional
	// +kubebuilder:default=false
	Enabled bool `json:"enabled,omitempty"`

	// ScaleUpPolicy defines when and how the pool scales up.
	// +optional
	ScaleUpPolicy *PoolScaleUpPolicy `json:"scaleUpPolicy,omitempty"`

	// ScaleDownPolicy defines when and how the pool scales down.
	// +optional
	ScaleDownPolicy *PoolScaleDownPolicy `json:"scaleDownPolicy,omitempty"`
}

type PoolScaleDownPolicy struct {
	// IdleTimeoutSeconds is the minimum duration (in seconds) a Pod must remain
	// in Idle state before it becomes a candidate for scale-down.
	// Defaults to 300 (5 minutes).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=300
	IdleTimeoutSeconds int32 `json:"idleTimeoutSeconds,omitempty"`

	// StabilizationSeconds is the minimum number of seconds between two consecutive
	// scale-down events. Prevents thrashing when load fluctuates around the threshold.
	// Defaults to 60.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=60
	StabilizationSeconds int32 `json:"stabilizationSeconds,omitempty"`

	// ProtectionWindowSeconds is the time window after a Pod is marked for
	// scale-down (via the scale-down-protected annotation) during which a new
	// Create Sandbox request can still claim it, cancelling the scale-down intent.
	// Defaults to 10.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=10
	ProtectionWindowSeconds int32 `json:"protectionWindowSeconds,omitempty"`
}

type PoolScaleUpMode string

type PoolScaleUpPolicy struct {
	// Mode controls how aggressively the pool grows on each scale-up decision.
	//   - Conservative: +1 per decision
	//   - Default:      +max(1, ceil(currentReplicas/2))
	//   - Aggressive:   scale to min(currentReplicas*2, maxReplicas)
	// Defaults to Default.
	// +optional
	// +kubebuilder:validation:Enum=Conservative;Default;Aggressive
	// +kubebuilder:default=Default
	Mode PoolScaleUpMode `json:"mode,omitempty"`

	// CooldownSeconds is the minimum number of seconds between two consecutive
	// scale-up events. Prevents scale-up storms when many requests arrive simultaneously.
	// Defaults to 30.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=30
	CooldownSeconds int32 `json:"cooldownSeconds,omitempty"`

	// IdleThresholdSeconds triggers a proactive scale-up when idleReplicas == 0
	// has persisted for this many seconds. Set to 0 to disable proactive scale-up.
	// Defaults to 30.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=30
	IdleThresholdSeconds int32 `json:"idleThresholdSeconds,omitempty"`
}

type SandboxPool struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of SandboxPool
	// +required
	Spec SandboxPoolSpec `json:"spec"`

	// status defines the observed state of SandboxPool
	// +optional
	Status SandboxPoolStatus `json:"status,omitzero"`
}

type SandboxPoolList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []SandboxPool `json:"items"`
}

type SandboxPoolPhase string

type SandboxPoolSpec struct {

	// Replicas is the total desired number of Pods (Idle + Running + Starting + Stopping).
	// Can be adjusted by PoolAutoscaler when MinReplicas != MaxReplicas.
	// +kubebuilder:validation:Minimum=0
	Replicas int32 `json:"replicas"`

	// MinReplicas is the lower bound for PoolAutoscaler.
	// When MinReplicas == MaxReplicas, autoscaler is disabled (manual-only scaling).
	// +optional
	// +kubebuilder:validation:Minimum=0
	MinReplicas *int32 `json:"minReplicas,omitempty"`

	// MaxReplicas is the upper bound for PoolAutoscaler.
	// When MinReplicas == MaxReplicas, autoscaler is disabled (manual-only scaling).
	// +optional
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`

	// TemplateName references a cluster-scoped SandboxTemplate to use as the base
	// configuration. When set, the template's EmbeddedSandboxTemplate is copied at
	// creation time. Inline fields in SandboxPoolSpec override template fields.
	// +optional
	TemplateName string `json:"templateName,omitempty"`

	// DefaultStartupTimeout is the default startup timeout applied to sandbox create
	// requests in this pool when the CreateSandbox request does not specify a startupTimeout.
	// It also serves as the upper bound for the Starting phase: the controller deletes any pod
	// that has been in Starting phase longer than this value.
	//
	// When nil, the controller does not enforce an upper bound on the Starting phase
	// (pods with a per-pod agentbox.navix.sh/startup-timeout annotation are still cleaned up),
	// and create requests without an explicit startupTimeout use the internal default (2 minutes).
	// +optional
	DefaultStartupTimeout *metav1.Duration `json:"defaultStartupTimeout,omitempty"`

	// DefaultIdleTimeout is the default idle timeout applied to sandboxes created
	// in this pool when the CreateSandbox request does not specify an idleTimeout.
	// If nil, sandboxes have no idle timeout by default (they run until explicitly released).
	// +optional
	DefaultIdleTimeout *metav1.Duration `json:"defaultIdleTimeout,omitempty"`

	// PodCreationImagePolicy controls which image newly created Pods start with,
	// regardless of whether replicas are increased manually or by autoscaling.
	//   - PoolDefaultImage: preserve template container image (current behavior)
	//   - IdleImage:        override the first container image with spec.idleImage
	// +optional
	// +kubebuilder:validation:Enum=PoolDefaultImage;IdleImage
	// +kubebuilder:default=IdleImage
	PodCreationImagePolicy PodCreationImagePolicy `json:"podCreationImagePolicy,omitempty"`

	// Autoscaling defines the autoscaling configuration for this pool.
	// When nil or autoscaling.enabled=false, the pool is managed manually via spec.replicas.
	// +optional
	Autoscaling *PoolAutoscalingSpec `json:"autoscaling,omitempty"`

	EmbeddedSandboxTemplate `json:",inline"`
}

type SandboxPoolStatus struct {

	// Phase is a high-level summary of the pool's current state.
	// Possible values: Pending, Ready, ScalingUp, ScalingDown, Degraded.
	//
	// Phase is determined by the following priority rules:
	//   - Pending:     spec.replicas == 0 and no pods exist
	//   - ScalingUp:   current pod count < spec.replicas
	//   - ScalingDown: current pod count > spec.replicas (may persist while running pods cannot be deleted)
	//   - Degraded:    replica count is stable but unavailableIdleReplicas > 0 or failedReplicas > 0
	//   - Ready:       all replicas present and all pods are healthy
	// +optional
	Phase SandboxPoolPhase `json:"phase,omitempty"`

	// IdleReplicas is the number of Pods in idle state
	// +optional
	IdleReplicas int32 `json:"idleReplicas,omitempty"`

	// UnavailableIdleReplicas is the number of Pods in idle phase whose Kubernetes PodReady
	// condition is not True (e.g. Pending, CrashLoopBackOff, ErrImagePull).
	// These Pods are counted in IdleReplicas but cannot accept sandbox requests.
	// A non-zero value causes the pool to enter the Degraded phase.
	// +optional
	UnavailableIdleReplicas int32 `json:"unavailableIdleReplicas,omitempty"`

	// RunningReplicas is the number of Pods in running state
	// +optional
	RunningReplicas int32 `json:"runningReplicas,omitempty"`

	// StartingReplicas is the number of Pods being activated (Idle → Running)
	// +optional
	StartingReplicas int32 `json:"startingReplicas,omitempty"`

	// StoppingReplicas is the number of Pods being recycled (Running → Idle)
	// +optional
	StoppingReplicas int32 `json:"stoppingReplicas,omitempty"`

	// FailedReplicas is the number of Pods in failed state
	// +optional
	FailedReplicas int32 `json:"failedReplicas,omitempty"`

	// LastScaleUpTime is the timestamp of the most recent scale-up event triggered
	// by the PoolAutoscaler. Used to enforce scaleUpPolicy.cooldownSeconds.
	// +optional
	LastScaleUpTime *metav1.Time `json:"lastScaleUpTime,omitempty"`

	// LastScaleDownTime is the timestamp of the most recent scale-down event triggered
	// by the PoolAutoscaler. Used to enforce scaleDownPolicy.stabilizationSeconds.
	// +optional
	LastScaleDownTime *metav1.Time `json:"lastScaleDownTime,omitempty"`

	// IdleZeroSince is the timestamp when idleReplicas first dropped to zero in the
	// current continuous zero-idle window. Used to evaluate scaleUpPolicy.idleThresholdSeconds.
	// Cleared when idleReplicas > 0.
	// +optional
	IdleZeroSince *metav1.Time `json:"idleZeroSince,omitempty"`

	// Selector is the label selector string used to identify Pods managed by this Pool.
	// Deprecated: Use LabelSelector for structured access or PhaseSelectors for per-phase filtering.
	// This field is retained for kubectl scale / HPA compatibility (subresource:scale selectorpath).
	// +optional
	Selector string `json:"selector,omitempty"`

	// LabelSelector is the structured label selector matching all Pods managed by this Pool.
	// Equivalent to the Selector field but in structured metav1.LabelSelector form.
	// +optional
	LabelSelector *metav1.LabelSelector `json:"labelSelector,omitempty"`

	// PhaseSelectors contains pre-computed label selector strings for filtering Pods by phase,
	// suitable for direct use with `kubectl get pods -l <selector>`.
	// Keys: "all", "idle", "running", "starting", "stopping", "failed".
	// Example: kubectl get pods -l <phaseSelectors.running>
	// +optional
	PhaseSelectors map[string]string `json:"phaseSelectors,omitempty"`

	// conditions represent the current state of the SandboxPool resource.
	// Each condition has a unique type and reflects the status of a specific aspect of the resource.
	//
	// Standard condition types:
	// - "Available":  True when healthy idle pods are available to accept new sandbox requests.
	// - "Scaling":    True when the pool is actively scaling up or down.
	// - "Degraded":   True when unavailable idle pods or failed pods are present.
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type SandboxReservationSpec struct {
	PriorityClassName string              `json:"priorityClassName,omitempty"`
	ReplicaQuota      corev1.ResourceList `json:"replicaQuota"`
}

type SandboxRuntimeSpec struct {
	// Name specifies the name of the runtime to use for the sandbox pods.
	// Supported values are "e2b", "swerex", "aiosanbdox", etc.
	Name string `json:"name"`

	// Port specifies the port number that the runtime should listen on for incoming connections.
	// +optional
	Port *int32 `json:"port,omitempty"`

	// Protocol for port. Must be UDP, TCP, or SCTP.
	// Defaults to "TCP".
	// +optional
	// +default="TCP"
	Protocol *corev1.Protocol `json:"protocol,omitempty"`

	// Description is a human-readable description of this runtime.
	// +optional
	Description string `json:"description,omitempty"`

	// LogDir is the path to the runtime's log file inside the container.
	// When set, the GetLogs API can retrieve runtime logs via file read.
	// Example: "/tmp/envd.log"
	// +optional
	LogDir string `json:"logDir,omitempty"`

	// ReadinessProbe defines the readiness check configuration for the runtime.
	// +optional
	ReadinessProbe *corev1.Probe `json:"readinessProbe,omitempty"`

	// Config contains runtime-specific configuration parameters.
	// The content and structure of this field depend on the runtime type.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	// +optional
	Config *runtime.RawExtension `json:"config,omitempty"`
}

type SandboxStatusDetail struct {
	// Reason is a machine-readable cause, e.g. "Pulling", "ImagePullBackOff",
	// "ErrImagePull", "CrashLoopBackOff", "OOMKilled", "PodFailed".
	Reason string `json:"reason"`
	// Message is a human-readable description of the current state.
	Message string `json:"message"`
	// LastUpdatedTime is the RFC3339 timestamp when this record was last written.
	LastUpdatedTime string `json:"lastUpdatedTime"`
}

type SandboxStopReason string

type SandboxTemplate struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of SandboxTemplate
	// +required
	Spec SandboxTemplateSpec `json:"spec"`

	// status defines the observed state of SandboxTemplate
	// +optional
	Status SandboxTemplateStatus `json:"status,omitzero"`
}

type SandboxTemplateList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []SandboxTemplate `json:"items"`
}

type SandboxTemplateSpec struct {
	EmbeddedSandboxTemplate `json:",inline"`

	// Version is an optional semantic version string for this template (e.g. "v1.2.0").
	// +optional
	Version string `json:"version,omitempty"`

	// Description is a human-readable description of this template.
	// +optional
	Description string `json:"description,omitempty"`

	// Visibility controls which tenants can see this template.
	// When nil or Rules is empty, the template is public (visible to all).
	// +optional
	Visibility *TemplateVisibility `json:"visibility,omitempty"`
}

type SandboxTemplateStatus struct {

	// conditions represent the current state of the SandboxTemplate resource.
	// Each condition has a unique type and reflects the status of a specific aspect of the resource.
	//
	// Standard condition types include:
	// - "Available": the resource is fully functional
	// - "Progressing": the resource is being created or updated
	// - "Degraded": the resource failed to reach or maintain its desired state
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type TemplateVisibility struct {
	// Rules is the list of visibility rules.
	// +optional
	Rules []TemplateVisibilityRule `json:"rules,omitempty"`
}

type TemplateVisibilityRule struct {
	// Team specifies the team that can see the template.
	// Empty means any team.
	// +optional
	Team string `json:"team,omitempty"`

	// Users specifies the users that can see the template.
	// Empty means any user.
	// +optional
	Users []string `json:"users,omitempty"`
}