concepts

type Alive interface {
	// ConvergingStatus returns the resource's current progress towards "Ready".
	// The provided ConvergingOperation helps the resource decide if it's currently Creating or Updating.
	ConvergingStatus(op ConvergingOperation) (AliveStatusWithReason, error)
}

type AliveConvergingStatus string

type AliveStatusWithReason struct {
	// Status is the status of the resource while converging towards healthy (can also be healthy).
	Status AliveConvergingStatus
	// Reason explains why the resource is currently healthy, Creating, Updating or Scaling.
	// Examples:
	//  - With Status=healthy: Deployment is healthy.
	//  - With Status=Created (ConvergingOperationCreated): Deployment has 2/3 healthy replicas.
	//  - With Status=Updated (ConvergingOperationUpdated): Deployment has 2/3 healthy replicas.
	//  - With Status=Scaling (ConvergingOperationNone): Deployment has 0/3 healthy replicas.
	//  - With Status=failing: failing to pull image
	Reason string
}

type Completable interface {
	// ConvergingStatus returns the resource's current completion state.
	// The provided ConvergingOperation helps the resource decide its current status.
	ConvergingStatus(op ConvergingOperation) (CompletionStatusWithReason, error)
}

type CompletionStatus string

type CompletionStatusWithReason struct {
	// Status is the current execution state of the resource.
	Status CompletionStatus
	// Reason explains why the resource is in the current status.
	// Examples:
	//  - With Status=Completed: Job has finished successfully.
	//  - With Status=TaskRunning: Job has 1/1 active pods.
	//  - With Status=TaskPending: Job is waiting for pods to be scheduled.
	//  - With Status=TaskFailing: Job failed with exit code 1.
	Reason string
}

type ConvergingOperation string

type DataExtractable interface {
	// ExtractData performs the data extraction from the resource's underlying Kubernetes object.
	// The implementation should store the extracted data in its own fields or shared state
	// where it can be accessed by the caller.
	ExtractData() error
}

type GraceStatus string

type GraceStatusWithReason struct {
	// Status is the status of the resource when the grace period expired.
	Status GraceStatus
	// Reason explains the reason why the resource is healthy, Down or Degraded at grace expiry.
	// Examples:
	//  - With Status=healthy: Deployment is healthy.
	//  - With Status=Degraded: Deployment has 2/3 healthy replicas.
	//  - With Status=Down: Deployment has 0/3 healthy replicas.
	Reason string
}

type Graceful interface {
	// GraceStatus returns the final health assessment after the component's grace period has expired.
	// The implementation should assume the grace period HAS expired and return its current state
	// (healthy, Degraded, or Down) without internal timing logic.
	GraceStatus() (GraceStatusWithReason, error)
}

type GuardStatus string

type GuardStatusWithReason struct {
	// Status is the guard evaluation result.
	Status GuardStatus
	// Reason provides a human-readable explanation of why the guard is in this state.
	Reason string
}

type Guardable interface {
	// GuardStatus evaluates the resource's precondition and returns whether
	// the resource is ready to be applied.
	GuardStatus() (GuardStatusWithReason, error)
}

type Operational interface {
	ConvergingStatus(op ConvergingOperation) (OperationalStatusWithReason, error)
}

type OperationalStatus string

type OperationalStatusWithReason struct {
	// Status is the status of the resource while converging towards operational (can also be operational).
	Status OperationalStatus
	// Reason explains why the resource is currently 'Operational', 'Pending' or 'Failing'.
	// Examples:
	//  - With Status=Operational: Service load balancer IP address assigned.
	//  - With Status=Pending: Awaiting load balancer IP assignment.
	//  - With Status=Failing: Missing cloud provider annotation for load balancer assignment.
	Reason string
}

type Suspendable interface {
	// DeleteOnSuspend returns true if the resource should be deleted after suspension is complete.
	// Note: Suspend() and SuspensionStatus() are still called even if this returns true.
	// The resource must reach SuspensionStatusSuspended before it is actually deleted.
	// This allows for necessary cleanup or state persistence (e.g., ensuring disks are retained)
	// before the Kubernetes object is removed.
	DeleteOnSuspend() bool
	// Suspend applies suspension mutations to the resource's desired state.
	// The suspension intent MUST be stored in the wrapper's internal state and applied
	// during a subsequent Mutate() call.
	// Suspend MUST NOT mutate the Kubernetes cluster state directly.
	Suspend() error
	// SuspensionStatus returns the current progress of the suspension.
	// It is called after Suspend() to track when the resource has reached the desired state.
	SuspensionStatus() (SuspensionStatusWithReason, error)
}

type SuspensionStatus string

type SuspensionStatusWithReason struct {
	// Status is the status of the resource while converging towards Suspended (can also be Suspended)
	Status SuspensionStatus
	// Reason explains the reason why the Status is currently PendingSuspension, Suspending or Suspended.
	// Examples:
	//  - With Status=PendingSuspension (SuspensionStatusPending): Waiting for statefulset observed generation to match generation.
	//  - With Status=Suspending (SuspensionStatusSuspending): Replicas scaling down. 1/3 replicas running.
	//  - With Status=Suspended (SuspensionStatusSuspended): Replicas scaled down to 0.
	Reason string
}