sandboxpool

type IdleNotifier interface {
	// NotifyIdleAvailable is called whenever a Pod successfully transitions to
	// the Idle phase (Stopping → Idle via MarkUpdateCompleted). Wakes any
	// waiting Create requests for the corresponding pool.
	NotifyIdleAvailable(namespace, poolName string)

	// OnSandboxReleased is called at the same Stopping → Idle transition,
	// carrying the sandbox ID that was just released. Implementations should
	// invalidate any cached mapping keyed on sandboxID (e.g. the ExtProc
	// route cache) so subsequent router queries return NotFound instead of
	// briefly hitting a stale entry.
	OnSandboxReleased(ctx context.Context, sandboxID string)
}

type IdleTimeoutReconciler struct {
	// contains filtered or unexported fields
}

type LastActiveSource interface {
	GetLastActive(ctx context.Context) (map[string]time.Time, error)
}

type PodDiagnosticEvent struct {
	// Reason is the event reason, e.g. "Failed", "BackOff", "ErrImagePull".
	Reason string
	// Message is the human-readable event message.
	Message string
	// LastTimestamp is the RFC3339 time of the most recent occurrence.
	LastTimestamp string
	// Count is the total number of times this event fired.
	Count int32
}

type PodStatusDetail struct {
	// PodName is the name of the pod.
	PodName string
	// Phase is the agentbox pod phase label value (starting, failed, …).
	Phase string
	// Reason is a machine-readable cause extracted from the Pod spec, e.g.
	// "Pulling", "ImagePullBackOff", "ErrImagePull", "CrashLoopBackOff", "OOMKilled".
	Reason string
	// Message is a human-readable description derived from the Pod spec.
	Message string
	// Events contains Warning events fetched from the Kubernetes API (only
	// populated by Get, never by List).
	Events []PodDiagnosticEvent
}

type PoolExpectations struct {
	// contains filtered or unexported fields
}

type ReleaseSandboxPodOptions struct {
	StopReason     agentsv1alpha1.SandboxStopReason // "Completed" | "Released" | "Failed" | "Canceled"; defaults to "Completed"
	TerminatedAt   string                           // RFC3339; defaults to time.Now().UTC() if empty
	FailureReason  string                           // e.g. "IdleTimeout", "OOMKilled"
	FailureMessage string                           // human-readable
	ExitCode       *int32                           // container exit code for Failed sandboxes

	ExpectedCurrentSandboxPhase string

	// DisableRetry, when true, skips the retry-on-conflict loop in the
	// underlying TriggerUpdateWithOptions call. Use this for opportunistic
	// release paths (e.g. unexpected-restart detection) where retrying on a
	// stale pod view could misfire; the caller should skip and let the next
	// Reconcile re-observe before acting.
	DisableRetry bool
}

type SandboxPoolReconciler struct {
	client.Client
	Scheme        *runtime.Scheme
	Recorder      events.EventRecorder   // for publishing Phase-transition events
	Clientset     kubernetes.Interface   // nil means Event-based diagnostics disabled
	SandboxStore  store.SandboxStore     // nil means history recording disabled
	PluginManager *plugins.PluginManager // nil means lifecycle plugins disabled
	// IdleNotifier is called whenever a Pod transitions Stopping → Idle.
	// When non-nil, it wakes the per-pool claim scheduler immediately so
	// pending Create requests can be dispatched without a poll-timer delay.
	// nil = disabled (no notification sent).
	IdleNotifier IdleNotifier
	// SandboxReadyHook is called (in a goroutine) after a Starting pod is
	// successfully marked Running via MarkUpdateCompleted. nil = disabled.
	SandboxReadyHook SandboxReadyHook
	// DigestResolver resolves image tags to content digests for in-place
	// update completion detection. nil = disabled (digest-based comparison
	// will fail and updates may not complete).
	DigestResolver imageresolver.DigestResolver
	// contains filtered or unexported fields
}

type SandboxReadyHook interface {
	OnSandboxReady(ctx context.Context, pod *corev1.Pod)
}