cachebackend_types.go

// SPDX-FileCopyrightText: 2026 The inference-cache Authors
//
// SPDX-License-Identifier: Apache-2.0

package v1alpha1

import (
	corev1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/api/resource"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
)

// +kubebuilder:validation:Enum=VLLM;SGLang

// CacheBackendRuntime identifies the inference runtime whose engine Pods are
// wired to this cache hierarchy.
type CacheBackendRuntime string

const (
	CacheBackendRuntimeVLLM   CacheBackendRuntime = "VLLM"
	CacheBackendRuntimeSGLang CacheBackendRuntime = "SGLang"
)

// +kubebuilder:validation:Enum=LMCache;SGLangHiCache

// CacheBackendType identifies the backing cache implementation.
type CacheBackendType string

const (
	CacheBackendTypeLMCache       CacheBackendType = "LMCache"
	CacheBackendTypeSGLangHiCache CacheBackendType = "SGLangHiCache"
)

// +kubebuilder:validation:Enum=Redis;LMCacheServer;Mooncake

// CacheBackendRemoteStorageProvider identifies the technology used for the
// optional shared/remote cache tier.
type CacheBackendRemoteStorageProvider string

const (
	CacheBackendRemoteStorageProviderRedis         CacheBackendRemoteStorageProvider = "Redis"
	CacheBackendRemoteStorageProviderLMCacheServer CacheBackendRemoteStorageProvider = "LMCacheServer"
	CacheBackendRemoteStorageProviderMooncake      CacheBackendRemoteStorageProvider = "Mooncake"
)

// +kubebuilder:validation:Enum=Managed;External

// CacheBackendRemoteStorageOwnership identifies who owns the remote provider's
// lifecycle.
type CacheBackendRemoteStorageOwnership string

const (
	CacheBackendRemoteStorageOwnershipManaged  CacheBackendRemoteStorageOwnership = "Managed"
	CacheBackendRemoteStorageOwnershipExternal CacheBackendRemoteStorageOwnership = "External"
)

// +kubebuilder:validation:Enum=Deployment;StatefulSet

// CacheBackendDeploymentKind identifies the Kubernetes workload kind used for managed backends.
type CacheBackendDeploymentKind string

const (
	CacheBackendDeploymentKindDeployment  CacheBackendDeploymentKind = "Deployment"
	CacheBackendDeploymentKindStatefulSet CacheBackendDeploymentKind = "StatefulSet"
)

// +kubebuilder:validation:Enum=ReadOnly;WriteOnly;ReadWrite

// CacheBackendIntegrationRole identifies how an engine should interact with the cache backend.
type CacheBackendIntegrationRole string

const (
	CacheBackendIntegrationRoleReadOnly  CacheBackendIntegrationRole = "ReadOnly"
	CacheBackendIntegrationRoleWriteOnly CacheBackendIntegrationRole = "WriteOnly"
	CacheBackendIntegrationRoleReadWrite CacheBackendIntegrationRole = "ReadWrite"
)

// +kubebuilder:validation:Enum=Offload;EventsOnly

// CacheBackendIntegrationMode selects which cache tiers an engine is wired for.
type CacheBackendIntegrationMode string

const (
	// CacheBackendIntegrationModeOffload is the default: the engine is wired for
	// cache-aware routing (tier-1) AND the configured offload tier (tier-2).
	// Server-backed adapters provision a managed backend; engine-local adapters
	// such as native SGLang HiCache configure the engine Pod directly.
	CacheBackendIntegrationModeOffload CacheBackendIntegrationMode = "Offload"
	// CacheBackendIntegrationModeEventsOnly wires the engine for cache-aware
	// routing (tier-1) ONLY: the kvevent-subscriber observation sidecar is
	// injected, but NO KV connector is loaded into the engine and NO backend
	// server is provisioned. This is the supported integration for
	// hybrid-attention models (Qwen3.6/Next gated-DeltaNet, Mamba/Jamba, KDA,
	// Falcon-H, Granite-hybrid, …): vLLM disables its hybrid KV-cache manager
	// the moment any KV connector is loaded (KV-spec unification then fails at
	// init), so they cannot take the tier-2 connector — but their KV events
	// coexist fine with the hybrid manager, so routing still works. Also a
	// lighter deployment for routing-only users who do not want an offload tier.
	CacheBackendIntegrationModeEventsOnly CacheBackendIntegrationMode = "EventsOnly"
)

// +kubebuilder:validation:Enum=write_back;write_through;write_through_selective

// SGLangHiCacheWritePolicy controls when SGLang copies KV pages to host memory.
type SGLangHiCacheWritePolicy string

const (
	SGLangHiCacheWriteBack             SGLangHiCacheWritePolicy = "write_back"
	SGLangHiCacheWriteThrough          SGLangHiCacheWritePolicy = "write_through"
	SGLangHiCacheWriteThroughSelective SGLangHiCacheWritePolicy = "write_through_selective"
)

// +kubebuilder:validation:Enum=direct;kernel;kernel_ascend

// SGLangHiCacheIOBackend selects SGLang's host/device transfer implementation.
type SGLangHiCacheIOBackend string

const (
	SGLangHiCacheIODirect       SGLangHiCacheIOBackend = "direct"
	SGLangHiCacheIOKernel       SGLangHiCacheIOBackend = "kernel"
	SGLangHiCacheIOKernelAscend SGLangHiCacheIOBackend = "kernel_ascend"
)

// +kubebuilder:validation:Enum=layer_first;page_first;page_first_direct;page_first_kv_split;page_head

// SGLangHiCacheMemoryLayout selects SGLang's host-memory tensor layout.
type SGLangHiCacheMemoryLayout string

const (
	SGLangHiCacheMemoryLayerFirst       SGLangHiCacheMemoryLayout = "layer_first"
	SGLangHiCacheMemoryPageFirst        SGLangHiCacheMemoryLayout = "page_first"
	SGLangHiCacheMemoryPageFirstDirect  SGLangHiCacheMemoryLayout = "page_first_direct"
	SGLangHiCacheMemoryPageFirstKVSplit SGLangHiCacheMemoryLayout = "page_first_kv_split"
	SGLangHiCacheMemoryPageHead         SGLangHiCacheMemoryLayout = "page_head"
)

// SGLangHiCacheSpec configures SGLang's native, engine-local host-memory cache.
// Exactly one of SizeGB and Ratio must be set. Optional tuning fields are
// passed to SGLang only when explicitly configured, so the engine version owns
// their defaults.
type SGLangHiCacheSpec struct {
	// SizeGB sets the host KV-cache pool size in decimal gigabytes.
	// Mutually exclusive with Ratio.
	// +optional
	// +kubebuilder:validation:Minimum=1
	SizeGB *int32 `json:"sizeGB,omitempty"`

	// Ratio sets the host KV-cache pool size relative to the device KV-cache
	// pool. It is a string because Kubernetes APIs avoid floating-point fields.
	// Admission requires a finite number greater than zero.
	// Mutually exclusive with SizeGB.
	// +optional
	Ratio string `json:"ratio,omitempty"`

	// WritePolicy maps to --hicache-write-policy.
	// +optional
	WritePolicy SGLangHiCacheWritePolicy `json:"writePolicy,omitempty"`

	// IOBackend maps to --hicache-io-backend.
	// +optional
	IOBackend SGLangHiCacheIOBackend `json:"ioBackend,omitempty"`

	// MemoryLayout maps to --hicache-mem-layout.
	// +optional
	MemoryLayout SGLangHiCacheMemoryLayout `json:"memoryLayout,omitempty"`
}

// CacheBackendHostMemorySpec configures engine-side host memory. Capacity is
// owned by the engine cache implementation and never sizes a remote provider.
type CacheBackendHostMemorySpec struct {
	// Capacity is the memory budget for the engine-side host cache.
	// +optional
	// +kubebuilder:validation:XValidation:rule="quantity(string(self)).isGreaterThan(quantity('0'))",message="capacity must be greater than zero"
	Capacity *resource.Quantity `json:"capacity,omitempty"`
}

// LMCacheEngineSpec configures the engine-side LMCache implementation. These
// fields apply to the connector or node-local MP worker, not to a remote
// storage provider.
type LMCacheEngineSpec struct {
	// ChunkSizeTokens is the number of tokens in an LMCache chunk.
	// +optional
	// +kubebuilder:validation:Minimum=1
	ChunkSizeTokens *int32 `json:"chunkSizeTokens,omitempty"`

	// HostMemory configures LMCache's engine-local host-memory tier.
	// +optional
	HostMemory *CacheBackendHostMemorySpec `json:"hostMemory,omitempty"`

	// WorkerImage overrides the node-local LMCache MP worker image when the
	// selected runtime uses multiprocess mode.
	// +optional
	WorkerImage string `json:"workerImage,omitempty"`

	// WorkerPort overrides the node-local LMCache MP worker port.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	WorkerPort *int32 `json:"workerPort,omitempty"`

	// RemoteSerde selects LMCache's serializer for a remote binding.
	// +optional
	RemoteSerde string `json:"remoteSerde,omitempty"`
}

// RedisRemoteStorageSpec configures a Redis remote-storage provider.
type RedisRemoteStorageSpec struct {
	// Image is used only when ownership is Managed.
	// +optional
	Image string `json:"image,omitempty"`

	// Resources are applied to the managed Redis container.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`
}

// LMCacheServerRemoteStorageSpec configures a standalone lmcache-server
// remote-storage provider.
type LMCacheServerRemoteStorageSpec struct {
	// Image is used only when ownership is Managed.
	// +optional
	Image string `json:"image,omitempty"`

	// Command overrides the managed server command and arguments.
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:items:MinLength=1
	Command []string `json:"command,omitempty"`

	// Resources are applied to the managed lmcache-server container.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`
}

// MooncakeRemoteStorageSpec configures a Mooncake remote-storage provider.
type MooncakeRemoteStorageSpec struct {
	// Image is used only when ownership is Managed.
	// +optional
	Image string `json:"image,omitempty"`

	// Command overrides the managed Mooncake master command and arguments.
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:items:MinLength=1
	Command []string `json:"command,omitempty"`

	// Resources are applied to the managed Mooncake master container.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`
}

// CacheBackendRemoteStorageSpec configures the optional shared/remote tier.
// Omitting this object in the canonical API requests an engine-local,
// host-only hierarchy and never implicitly provisions infrastructure.
type CacheBackendRemoteStorageSpec struct {
	// Provider identifies the remote-storage technology.
	Provider CacheBackendRemoteStorageProvider `json:"provider"`

	// Ownership identifies whether inference-cache manages the provider
	// workload or connects to operator-managed infrastructure.
	Ownership CacheBackendRemoteStorageOwnership `json:"ownership"`

	// Endpoint is required for External ownership and rejected for Managed
	// ownership, whose endpoint is controller-observed.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// Redis contains Redis-owned configuration.
	// +optional
	Redis *RedisRemoteStorageSpec `json:"redis,omitempty"`

	// LMCacheServer contains standalone lmcache-server-owned configuration.
	// +optional
	LMCacheServer *LMCacheServerRemoteStorageSpec `json:"lmCacheServer,omitempty"`

	// Mooncake contains Mooncake-owned configuration.
	// +optional
	Mooncake *MooncakeRemoteStorageSpec `json:"mooncake,omitempty"`
}

// CacheBackendObservationSpec configures KV-event observation independently
// from engine-cache wiring and remote-storage lifecycle.
type CacheBackendObservationSpec struct {
	// ModelID is attached to observed cache events.
	// +optional
	ModelID string `json:"modelID,omitempty"`

	// FirstEventTimeout bounds how long readiness waits for the first KV event.
	// +optional
	// +kubebuilder:default="5m"
	FirstEventTimeout *metav1.Duration `json:"firstEventTimeout,omitempty"`
}

// CacheBackendSpec defines the desired state of a cache backend.
//
// The autoscaling spec (spec.autoscaling) is reconciled into a
// HorizontalPodAutoscaler for managed backends.
type CacheBackendSpec struct {
	// Runtime identifies the inference runtime. Values are case-sensitive: use
	// VLLM or SGLang.
	Runtime CacheBackendRuntime `json:"runtime"`

	// Type identifies the engine-side cache implementation and defaults to
	// LMCache. Supported values are LMCache and SGLangHiCache. Provider
	// technology and ownership are selected independently through remoteStorage;
	// omitting remoteStorage requests a host-only hierarchy.
	// +optional
	// +kubebuilder:default=LMCache
	Type CacheBackendType `json:"type,omitempty"`

	// LMCache configures the engine-side LMCache implementation. It is valid
	// only when type=LMCache.
	// +optional
	LMCache *LMCacheEngineSpec `json:"lmCache,omitempty"`

	// RemoteStorage configures an optional shared/remote cache tier. Its
	// provider and ownership are independent from runtime and type. When this
	// field is omitted from the canonical API, no provider is provisioned.
	// +optional
	RemoteStorage *CacheBackendRemoteStorageSpec `json:"remoteStorage,omitempty"`

	// Observation configures KV-event observation independently from cache
	// offload and provider lifecycle.
	// +optional
	Observation *CacheBackendObservationSpec `json:"observation,omitempty"`

	// DeploymentKind identifies whether a managed backend is reconciled as a
	// Deployment or StatefulSet. Defaults to Deployment — the only kind the
	// Phase-1 reconciler templates; StatefulSet is reserved for future
	// per-replica-PVC topologies and is a no-op today.
	// +optional
	// +kubebuilder:default=Deployment
	DeploymentKind CacheBackendDeploymentKind `json:"deploymentKind,omitempty"`

	// Replicas is the desired number of backend workload replicas. Defaults
	// to 1 — a conservative single-replica deployment; operators opt into
	// horizontal scale via spec.autoscaling.
	//
	// When spec.autoscaling is set, the HPA owns the live replica count and
	// the autoscaling floor (spec.autoscaling.minReplicas) is auto-defaulted
	// to spec.replicas on FIRST APPLY ONLY by the admission defaulter.
	// Subsequent edits to spec.replicas do NOT move the autoscaling floor —
	// minReplicas is operator-owned (and operator-pinned via the apiserver
	// field manager) after first apply, matching the standard Kubernetes HPA
	// convention that scaling intent flows through HPA fields once an HPA
	// owns the workload. To widen or narrow the autoscaling band post-apply,
	// edit spec.autoscaling.minReplicas directly.
	// +optional
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=0
	Replicas *int32 `json:"replicas,omitempty"`

	// Autoscaling configures horizontal autoscaling for the managed backend
	// workload. When set, the controller reconciles a HorizontalPodAutoscaler
	// owned by this CacheBackend; the HPA then drives the underlying workload's
	// replica count, overriding spec.replicas.
	// +optional
	Autoscaling *CacheBackendAutoscalingSpec `json:"autoscaling,omitempty"`

	// Integration describes how inference engines should use the cache backend.
	// +optional
	Integration *CacheBackendIntegrationSpec `json:"integration,omitempty"`

	// EngineSelector selects which engine pods this CacheBackend claims via
	// equality-based label matching over the pod's labels: every key/value
	// in MatchLabels must be present on the pod. The full
	// metav1.LabelSelector surface (matchExpressions, operator-based
	// selection) is NOT exposed today — only MatchLabels.
	// Pods that match get runtime-adapter engine wiring injected by the
	// mutating Pod admission webhook at pod CREATE time. Server-backed
	// adapters require status.endpoint to be published first; the webhook
	// fail-opens when it is empty. Engine-local adapters such as native
	// SGLang HiCache, and the LMCache host-only path, explicitly require no
	// endpoint and inject immediately.
	// Admission is CREATE-only; recovery or a configuration update requires
	// recreating the pod (e.g. `kubectl rollout restart`), not editing its
	// live labels.
	//
	// This describes the default spec.integration.mode=Offload path. For
	// spec.integration.mode=EventsOnly no KV connector wiring (env vars +
	// CLI args) is injected and status.endpoint is neither required nor
	// published — the kvevent-subscriber observation sidecar alone is
	// injected (see below), so matched pods report cache state for routing
	// without offloading KV to a backend server.
	//
	// The kvevent-subscriber observation sidecar is appended in addition
	// to the engine wiring only when the controller is started with
	// --kvevent-subscriber-image set (empty by default) AND the matched
	// CacheBackend has a model id configured. Without those, the engine
	// is wired but no sidecar is added.
	//
	// In spec.integration.mode=EventsOnly the above "engine wiring" is
	// absent: no KV connector is injected, so the sidecar is the ONLY thing
	// the webhook adds. With the subscriber image or model id unset nothing
	// is wired at all and the pod carries no injected-by stamp (the webhook
	// admits it untouched).
	//
	// The match is evaluated once at pod CREATE — pods whose labels change
	// after creation are not re-evaluated; the wiring is sticky to the
	// life of the pod. To opt a specific pod out of injection regardless
	// of label match, set the annotation
	// `inferencecache.io/skip-inject: "true"` on the pod template.
	//
	// See docs/concepts/cachebackend-engine-binding.md for the full
	// lifecycle, an annotated example, and common failure modes.
	// +optional
	EngineSelector *CacheBackendEngineSelector `json:"engineSelector,omitempty"`

	// HiCache configures SGLang's native, engine-local hierarchical cache. It
	// is required for type=SGLangHiCache and rejected for other backend types.
	// The selected engine Pods own the host-memory allocation; no cache-server
	// workload or network endpoint is created.
	// +optional
	HiCache *SGLangHiCacheSpec `json:"hiCache,omitempty"`

	// Template provides pod-level overrides for managed backend workloads.
	// +optional
	Template *CacheBackendPodSpecOverride `json:"template,omitempty"`

	// AllowCrossNamespace opts the CacheBackend into referencing an Endpoint
	// that resolves into a Kubernetes Service in a different namespace from
	// this object. Without this opt-in admission rejects such Endpoints,
	// because a cross-namespace reference crosses a tenancy/RBAC boundary that
	// the cluster operator should explicitly acknowledge. Endpoints that are
	// not in-cluster Service DNS (external hostnames, IPs) are unaffected.
	// +optional
	AllowCrossNamespace bool `json:"allowCrossNamespace,omitempty"`
}

// CacheBackendAutoscalingSpec configures horizontal autoscaling of the managed
// backend workload via a HorizontalPodAutoscaler. Cache-aware (custom-metric)
// autoscaling is deferred to a later module; Phase 1 supports a CPU-utilization
// target, which is sufficient to demonstrate scale-up under load.
//
// +kubebuilder:validation:XValidation:rule="!has(self.minReplicas) || self.minReplicas <= self.maxReplicas",message="minReplicas must not exceed maxReplicas"
type CacheBackendAutoscalingSpec struct {
	// MinReplicas is the lower bound for the HPA replica count. The
	// admission defaulter computes the default at write time from
	// spec.replicas (which itself defaults to 1) so the HPA's floor matches
	// the operator-declared baseline rather than a hard-coded constant. This
	// is a FIRST-APPLY-ONLY default: the defaulter never overwrites an
	// operator-set value, AND once stamped the field is owned by the
	// apiserver field manager — subsequent edits to spec.replicas do NOT
	// recompute or move minReplicas, matching the standard Kubernetes HPA
	// convention that scaling intent flows through HPA fields once an HPA
	// owns the workload. To widen or narrow the autoscaling band post-apply,
	// edit spec.autoscaling.minReplicas directly. Operators who want a
	// non-default floor on first apply set the field explicitly.
	// +optional
	// +kubebuilder:validation:Minimum=1
	MinReplicas *int32 `json:"minReplicas,omitempty"`

	// MaxReplicas is the upper bound for the HPA replica count.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=1
	MaxReplicas int32 `json:"maxReplicas"`

	// TargetCPUUtilizationPercent is the average per-pod CPU utilization the
	// HPA targets. Defaults to 80 when unset.
	// +optional
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=100
	TargetCPUUtilizationPercent *int32 `json:"targetCPUUtilizationPercent,omitempty"`
}

// CacheBackendIntegrationSpec describes engine integration behavior.
//
// Per-namespace lookup tuning lives on CachePolicy, not here: the lookup
// deadline and the minimum-prefix-token gate are configured via
// CachePolicy.spec.lookupTimeoutMs and CachePolicy.spec.minimumPrefixTokens,
// which are the surfaces actually wired into the server's ResolvedPolicy.
type CacheBackendIntegrationSpec struct {
	// Mode selects which cache tiers the engine is wired for. Defaults to
	// Offload — cache-aware routing (tier-1) PLUS the KV-offload connector
	// (tier-2), with a controller-provisioned backend server. EventsOnly wires
	// routing only: the kvevent-subscriber sidecar is injected, but no KV
	// connector is loaded into the engine and no backend server is provisioned.
	// Mode takes precedence over engine-cache configuration: when EventsOnly is
	// selected, spec.lmCache and other host-tier settings are not injected into
	// the engine. Operators should omit them to avoid implying an active tier.
	// EventsOnly is the supported integration for hybrid-attention models that
	// cannot take a vLLM KV connector (and a lighter routing-only deployment for
	// anyone who does not want an offload tier). Because EventsOnly provisions
	// no server, status.endpoint stays empty and the autoscaling spec is
	// rejected at admission; Ready is still gated on the first observed KV event.
	// SGLangHiCache supports Offload only and is rejected with EventsOnly.
	// See the CacheBackendIntegrationMode godoc.
	// +optional
	// +kubebuilder:default=Offload
	Mode CacheBackendIntegrationMode `json:"mode,omitempty"`

	// Role controls whether the engine reads from, writes to, or fully
	// participates in the cache. Defaults to ReadWrite — full participation.
	// ReadOnly / WriteOnly are specialised producer/consumer roles operators
	// opt into explicitly.
	//
	// Engine support is per-adapter: vLLM maps the role onto its LMCache
	// connector's kv_role (ReadOnly→kv_consumer, WriteOnly→kv_producer,
	// ReadWrite→kv_both). The SGLang LMCache integration has no kv_role split
	// (--enable-lmcache always both stores and retrieves), so a (sglang,
	// LMCache) backend supports only ReadWrite — admission rejects ReadOnly /
	// WriteOnly there rather than silently ignoring them.
	// +optional
	// +kubebuilder:default=ReadWrite
	Role CacheBackendIntegrationRole `json:"role,omitempty"`

	// FailOpen controls whether the engine treats cache lookups as a soft
	// dependency. When true (the default), an unreachable or degraded cache
	// backend MUST fall back to local prefill and never fail a serving
	// request — the cache is an optimization, not a serving dependency. When
	// explicitly set to false the engine fails requests on cache
	// unreachability ("fail-closed"); the cache becomes a serving
	// dependency, which is loud and visible via a Warning Event on the
	// owning CacheBackend.
	//
	// The flag is plumbed by the engine adapter as INFERENCECACHE_FAIL_OPEN
	// (both shipping LMCache adapters — vLLM+LMCache and SGLang+LMCache —
	// inject it). Per-request fail-open enforcement at the engine level is the
	// engine/connector's responsibility; the cache plane surfaces the bit so
	// the engine can honor it.
	// SGLangHiCache accepts only the default true value and does not inject this
	// env var because native HiCache exposes no equivalent fail-closed control.
	// +optional
	// +kubebuilder:default=true
	FailOpen *bool `json:"failOpen,omitempty"`

	// EngineOverrides lets the operator amend the non-reserved args / env
	// the pod-mutating webhook injects into the engine container, on top
	// of what the runtime adapter would otherwise inject. Useful for
	// tuning adapter-injected knobs (e.g. CPU-vLLM running against the
	// LMCache integration with non-default chunk size / serdes / model
	// length) and for future engines that surface their own non-reserved
	// flags through the same adapter interface.
	//
	// EngineOverrides does NOT turn the integration off: every reserved
	// arg/env the adapter declares is hard-rejected at admission, so an
	// operator who wants to skip injection entirely on a particular pod
	// should use the inferencecache.io/skip-inject pod annotation instead.
	//
	// Admission rejects overrides that overlap the adapter's reserved
	// args/env (the ones strictly required for the integration to
	// function); the operator gets a field-scoped error naming the
	// offending flag/env and the adapter rather than discovering it via a
	// crashed engine. See the package doc for the rationale.
	// +optional
	EngineOverrides *EngineInjectionOverrides `json:"engineOverrides,omitempty"`

	// EngineHostNetwork opts engine pods bound to this backend into host
	// networking. It exists for exactly one backend today: Mooncake, whose
	// transfer engine is a peer-to-peer mesh — the engine dials a real node IP
	// on a dynamically negotiated port, which a CNI overlay pod IP cannot do.
	// Without this the backend reconciles Ready and transfers zero KV, and
	// admission warns as much on every apply.
	//
	// This is opt-in, and deliberately not a default, because it rewrites the
	// networking of a pod the operator owns:
	//   - hostNetwork is a privilege. A Pod Security "restricted" namespace
	//     rejects such a pod, and because mutating webhooks run BEFORE Pod
	//     Security validation, silently injecting it would turn a working engine
	//     pod into a rejected one — with an error that names Pod Security, not
	//     this controller.
	//   - The pod's ports move onto the node's interfaces, outside the pod
	//     network. NetworkPolicy selects pods by pod IP and therefore stops
	//     constraining them (see docs/design/cachebackend-api.md).
	//
	// Admission rejects this on any backend type that does not need it, so it
	// can never sit inert on a CacheBackend.
	//
	// +optional
	EngineHostNetwork bool `json:"engineHostNetwork,omitempty"`
}

// EngineInjectionOverrides is the in-between knob between "take the
// adapter's canonical injection" and "skip injection entirely" (the latter
// owned by the inferencecache.io/skip-inject pod annotation). The four
// primitives compose: Env upserts by Name and SuppressEnv removes by Name;
// Args replaces by leading flag token or appends, and SuppressArgs removes
// by leading flag token. Suppress runs before merge, so suppress-then-re-add
// is a supported pattern for overriding a non-reserved adapter-owned flag
// value. For adapter-backed Spec.Type values (LMCache and the future
// adapter-backed types), entries that overlap the runtime adapter's
// ReservedArgs() or ReservedEnv() are hard-rejected at admission with a
// field-scoped error naming the offending token and the adapter, so a
// misconfiguration fails at kubectl apply rather than as a crashed engine
// pod later. Spec.Type=External does not consult an adapter (no canonical
// injection happens), so the override surface there is structurally
// meaningless and the reserved-overlap check is skipped.
//
// See docs/concepts/cachebackend-engine-overrides.md for the baseline
// canonical injection (annotated RESERVED / TUNABLE), five worked
// before/after examples, and the "when NOT to use this" guidance.
//
// The override surface is SCOPED to entries the runtime adapter itself
// contributes (added or modified) during InjectEngineConfig — user
// pod-template args / env that the adapter does not touch are protected,
// and a Suppress or Override naming them is a silent no-op. This keeps the
// CR from mutating engine-pod-template state the engine-pod owner did not
// invite the CacheBackend to touch.
//
// Known-fragile: nothing here is type-checked against the engine binary, so
// an override on an adapter-owned non-reserved value can still break the
// engine in subtle ways the validator can't catch (e.g. an aggressive
// `--max-model-len` OOMing the engine). Admission only blocks overrides
// that overlap the adapter's reserved set — the args/env strictly required
// for the integration itself to function.
type EngineInjectionOverrides struct {
	// Args injected into the engine container, in addition to what the
	// adapter would inject. Merged by leading flag token (e.g.
	// "--max-model-len"): an override entry whose leading token matches
	// an adapter-owned canonical entry replaces it; entries whose token
	// is in neither the adapter-owned set nor the user pod-template are
	// appended; entries colliding with a user-template flag the adapter
	// did not touch are a silent no-op. Order is preserved.
	//
	// Admission rejects entries whose leading flag token overlaps
	// the adapter's ReservedArgs().
	// +optional
	Args []string `json:"args,omitempty"`

	// SuppressArgs lists leading flag names (e.g. "--some-tunable-flag")
	// the adapter MUST NOT inject. Admission rejects entries that overlap
	// the adapter's ReservedArgs(). A suppressed flag is removed from the
	// adapter's canonical contribution before Args merges in, so
	// suppress-then-re-add is a supported pattern for overriding a
	// non-reserved adapter-owned flag's value. Suppress does NOT touch
	// user pod-template flags the adapter did not inject.
	// +optional
	SuppressArgs []string `json:"suppressArgs,omitempty"`

	// Env upserted into the engine container by Name, scoped to
	// adapter-owned canonical entries. A Name matching an adapter-owned
	// entry is replaced; a Name not seen on the user pod-template is
	// appended; a Name colliding with a user-template env the adapter
	// did not touch is a silent no-op. Admission rejects entries whose
	// Name overlaps the adapter's ReservedEnv().
	// +optional
	Env []corev1.EnvVar `json:"env,omitempty"`

	// SuppressEnv lists env var Names the adapter MUST NOT inject.
	// Admission rejects entries that overlap the adapter's ReservedEnv().
	// Suppress does NOT touch user pod-template env the adapter did not
	// inject.
	// +optional
	SuppressEnv []string `json:"suppressEnv,omitempty"`
}

// IntegrationFailOpen returns the effective fail-open behavior for a
// CacheBackend integration spec. Missing spec or nil field defaults to true,
// matching the API default — the cache is an optimization, never a serving
// dependency. Engine adapters consult this helper to set the engine connector
// flags consistently across the spec→adapter path.
func IntegrationFailOpen(spec *CacheBackendIntegrationSpec) bool {
	if spec == nil || spec.FailOpen == nil {
		return true
	}
	return *spec.FailOpen
}

// IntegrationMode returns the effective integration mode for a CacheBackend
// integration spec. Missing spec or empty field defaults to Offload, matching
// the API default — full routing plus the selected offload tier. The
// admission defaulter materialises the field on submitted objects; this helper
// is the read-time fallback for callers that bypass the apiserver (raw-struct
// test invocation, partial deserialization).
func IntegrationMode(spec *CacheBackendIntegrationSpec) CacheBackendIntegrationMode {
	if spec == nil || spec.Mode == "" {
		return CacheBackendIntegrationModeOffload
	}
	return spec.Mode
}

// IsEventsOnly reports whether the backend is wired for events-only (tier-1
// routing) integration — no KV connector, no provisioned server. It is the
// single predicate the adapter, webhook, controller, and validator share so the
// mode's three-layer wiring (inject / reconcile / admit) stays in lockstep.
func (s *CacheBackendSpec) IsEventsOnly() bool {
	return IntegrationMode(s.Integration) == CacheBackendIntegrationModeEventsOnly
}

// CacheBackendEngineSelector selects engines by labels.
type CacheBackendEngineSelector struct {
	// MatchLabels is a map of labels that selected engines must match.
	// +optional
	MatchLabels map[string]string `json:"matchLabels,omitempty"`
}

// CacheBackendPodSpecOverride defines optional pod-level overrides applied to managed backend pods.
type CacheBackendPodSpecOverride struct {
	// NodeSelector constrains backend pods to nodes with matching labels.
	// +optional
	NodeSelector map[string]string `json:"nodeSelector,omitempty"`

	// Affinity configures backend pod scheduling affinity.
	// +optional
	Affinity *corev1.Affinity `json:"affinity,omitempty"`

	// Tolerations allow backend pods to schedule onto tainted nodes.
	// +optional
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`

	// TopologySpreadConstraints configures backend pod spreading across topology domains.
	// +optional
	TopologySpreadConstraints []corev1.TopologySpreadConstraint `json:"topologySpreadConstraints,omitempty"`

	// ImagePullSecrets references secrets used to pull backend pod images.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// ServiceAccountName is the service account used by backend pods.
	// +optional
	ServiceAccountName string `json:"serviceAccountName,omitempty"`

	// SecurityContext configures pod-level security settings for backend pods.
	// +optional
	SecurityContext *corev1.PodSecurityContext `json:"securityContext,omitempty"`

	// PriorityClassName is the priority class assigned to backend pods.
	// +optional
	PriorityClassName string `json:"priorityClassName,omitempty"`

	// SchedulerName selects the scheduler used for backend pods.
	// +optional
	SchedulerName string `json:"schedulerName,omitempty"`

	// RuntimeClassName selects the runtime class used for backend pods.
	// +optional
	RuntimeClassName *string `json:"runtimeClassName,omitempty"`

	// TerminationGracePeriodSeconds configures graceful shutdown for backend pods.
	// +optional
	// +kubebuilder:validation:Minimum=0
	TerminationGracePeriodSeconds *int64 `json:"terminationGracePeriodSeconds,omitempty"`
}

// CacheBackendStatus defines the observed state of a cache backend.
type CacheBackendStatus struct {
	// Endpoint is the observed endpoint clients should use for this backend.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// MatchedEnginePods is the number of pods in this CacheBackend's namespace
	// whose labels match spec.engineSelector at the last reconcile. The field
	// is a pointer so nil ("not yet computed") is distinguishable from 0
	// ("computed and zero current matches"). 0 covers any current
	// zero-match state — the engine Deployment has not been created
	// yet, it has been scaled to zero, or the selector and the engine
	// Deployment's pod labels have drifted apart. (Pods carrying a
	// `deletionTimestamp` are NOT filtered out today; the count is a
	// raw List of matching pods.) When engine pods are expected and 0
	// persists, label drift
	// is the most likely diagnosis: the mutating Pod webhook silently
	// no-ops on pods whose labels miss the selector, so the engine
	// runs uncached.
	//
	// This is a snapshot at reconcile time, not a real-time counter: it
	// is not updated on every pod birth/death. For per-pod real-time
	// visibility, watch the K8s `InjectedByCacheBackend` Event for
	// injected pods and `SkippedByOperator` / `inferencecache.io/inject-skipped`
	// for pods that explicitly opted out (visible in `kubectl describe pod`).
	// +optional
	// +kubebuilder:validation:Minimum=0
	MatchedEnginePods *int32 `json:"matchedEnginePods,omitempty"`

	// EngineSelectorMessage explains the current engineSelector matching
	// observation when it needs operator attention. It is set when
	// spec.engineSelector.matchLabels is configured but matchedEnginePods is
	// observed as 0 while engine pods are expected, and cleared once at least
	// one pod matches, the matching Deployment is intentionally scaled to zero,
	// or the selector is removed. The message echoes the selector so an operator
	// can compare it directly with engine Deployment pod-template labels.
	// +optional
	EngineSelectorMessage string `json:"engineSelectorMessage,omitempty"`

	// FailOpen mirrors the effective spec.integration.failOpen value the
	// controller most recently observed. Surfaced so operators can confirm
	// whether the cache is currently a soft optimization (true) or a
	// serving dependency (false) without re-reading the integration spec.
	// +optional
	FailOpen *bool `json:"failOpen,omitempty"`

	// ObservedGeneration is the .metadata.generation last reconciled by the controller.
	// +optional
	// +kubebuilder:validation:Minimum=0
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// FirstKVEventObservedAt latches the first time the KV-event readiness
	// gate observed status.indexParticipation.lastEventAt populated for this
	// backend. It is the durable "have we EVER seen a KV event" signal the
	// gate needs: lastEventAt itself is a current-view projection the
	// CacheIndex poller legitimately clears when a backend's replicas drain
	// (scale-down, prefixes TTL'd), so reading it alone would let a backend
	// that already passed the gate regress to AwaitingFirstKVEvent. Written
	// write-once by the controller and never cleared (a monotonic marker; the
	// gate is a first-event startup probe, not an ongoing liveness check). It
	// is inert while the backend is not managed (External / unsupported
	// runtime), and remains set so a return to the managed path stays Ready
	// without re-gating — consistent with the "ever observed" contract.
	// +optional
	FirstKVEventObservedAt *metav1.Time `json:"firstKVEventObservedAt,omitempty"`

	// FirstAvailableAt is the stable anchor for the firstEventTimeout clock.
	// It latches one of two events depending on the integration mode:
	//   - Offload (managed): the first time the managed cache-backend
	//     workload was observed Available — there is a workload to wait on.
	//   - EventsOnly: the first reconcile. A server-less backend has no
	//     workload to become Available, so it is "up" the moment it exists
	//     and the firstEventTimeout clock starts immediately.
	// In both cases it is a latched timestamp rather than a live condition's
	// LastTransitionTime: a live condition resets on an availability flap,
	// which would restart the timeout window and let a backend that already
	// breached the timeout (Degraded / NoKVEventsObserved) bounce back to
	// AwaitingFirstKVEvent without any KV event — contradicting the "once
	// Degraded, stays Degraded until an event arrives" contract. Anchoring on
	// this latched value keeps the elapsed window monotonic WITHIN a serving
	// mode, so Degraded is sticky. It survives availability flaps and a
	// recreated managed Deployment (the gate re-evaluates from the prior
	// anchor, safe because a cache-server restart does not change the engine
	// event source). It is NOT immortal across a mode change, though: a
	// server-bearing→EventsOnly flip re-anchors it to the flip moment (and also
	// bypasses the sticky NoKVEventsObserved reason) so the flip gets a fresh
	// first-event window instead of inheriting the old mode's availability time
	// or timed-out verdict; and an unmanaged transition clears it so a later
	// managed/events-only re-entry starts fresh. (Inert only on an Offload
	// backend that has not yet reported Available; on the EventsOnly path it is
	// set on the first reconcile.)
	// +optional
	FirstAvailableAt *metav1.Time `json:"firstAvailableAt,omitempty"`

	// ObservedServerInstance is the controller's cascade-decision
	// baseline — a stable identifier for the Ready cache-server pod
	// set the controller last anchored against. NOT a live current-
	// pod-set view: the controller intentionally pins this through
	// transient rolling-update midpoints and through no-Ready
	// windows so the cascade does not fire on rollbacks or transient
	// outages. For the live pod inventory, operators should consult
	// status.matchedEnginePods (engine side) and `kubectl get pod`
	// (cache-server side).
	//
	// Shape: `<pod-uid>:<restart-sum>` per Ready pod, comma-joined
	// and lex-sorted by pod name. restart-sum is the per-pod
	// containerStatuses[].RestartCount summed across cache-server
	// containers (the names from the owned Deployment's pod
	// template; foreign sidecars are excluded). Inert and cleared
	// for External backends and unsupported-runtime backends.
	//
	// Operator-side recovery for the upstream LMCache
	// LMServerConnector EPIPE-on-restart bug. See
	// docs/design/cachebackend-api.md for the cascade contract,
	// transition rules (which changes do / do not cascade), and
	// rate-limit / no-Ready / rollback / scale-up rationale.
	// +optional
	ObservedServerInstance string `json:"observedServerInstance,omitempty"`

	// IndexParticipation summarizes this CacheBackend's contribution to the
	// cluster-wide cache index — populated by the CacheIndex poller (it groups
	// the server's /snapshot replicas by the owning CacheBackend and projects
	// the per-backend slice here). nil until the poller has observed at least
	// one snapshot; absence of data on a single scrape never clears it.
	// +optional
	IndexParticipation *CacheBackendIndexParticipation `json:"indexParticipation,omitempty"`

	// Conditions describe the latest observations of the backend.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// CacheBackendIndexParticipation is the per-backend slice of the cluster-wide
// CacheIndex, projected from the server's /snapshot replicas[]. The poller
// resolves each replica to its engine pod by (tenant, replica_id) and then
// attributes it to the owning CacheBackend — either via the engine pod's
// `inferencecache.io/injected-by` annotation (the authoritative wiring
// signal stamped by the pod webhook) or, for pods that bypassed the
// webhook, via a deterministic first-match on `spec.engineSelector.
// matchLabels`. The poller writes write-only-on-change and never clears
// it on a single failed scrape (soft state).
type CacheBackendIndexParticipation struct {
	// PrefixCount is the sum of distinct prefix entries currently attributed
	// to this backend's replicas. Zero is a valid observed value — it means
	// the backend is up but holds no warm prefixes yet.
	// +kubebuilder:validation:Minimum=0
	PrefixCount int64 `json:"prefixCount"`

	// LastEventAt is the most recent KV-event timestamp observed for any of
	// this backend's replicas. nil until the first event arrives; downstream
	// readiness gates (e.g. "ready once at least one event seen") MUST treat
	// nil as "not yet observed" rather than zero time.
	// +optional
	LastEventAt *metav1.Time `json:"lastEventAt,omitempty"`

	// HitRate is the prefix-count-weighted average cache hit rate across this
	// backend's replicas, formatted as a decimal string in [0,1] (matching
	// the cluster-wide CacheIndex.status.replicas[].hitRate convention — see
	// CRD-codegen note on floats in CRDs). nil until the replica stats
	// reporter emits per-replica hitRate into the index; do not interpret a
	// missing value as 0.
	// +optional
	HitRate *string `json:"hitRate,omitempty"`

	// T2HitRate is the query-weighted reload hit-rate of the tier-2 (external
	// offload, e.g. LMCache) cache across this backend's replicas, formatted as
	// a decimal string in [0,1]. Sourced from the engines'
	// vllm:external_prefix_cache_{hits,queries}_total counters and projected by
	// the CacheIndex poller.
	//
	// Presence is load-bearing here: nil means the tier-2 cache has NOT been
	// exercised yet (no external lookups across any replica) — distinct from
	// "0". A value of "0" means the tier WAS queried but served zero reloads:
	// tier-2 is wired but not actually helping. That is the operator-visible
	// signature of a silently-degraded offload tier — a store/connection
	// failure, an under-sized remote server, or a scheduler/worker hash
	// mismatch all surface here as "0" rather than as nothing at all. A
	// healthy reusing workload reads well above 0.
	// +optional
	T2HitRate *string `json:"t2HitRate,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:scope=Namespaced,shortName=cb
// +kubebuilder:printcolumn:name="Type",type=string,JSONPath=`.spec.type`
// +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
// +kubebuilder:printcolumn:name="Matched",type=integer,JSONPath=`.status.matchedEnginePods`
// +kubebuilder:printcolumn:name="Endpoint",type=string,JSONPath=`.status.endpoint`
// +kubebuilder:printcolumn:name="Prefixes",type=integer,JSONPath=`.status.indexParticipation.prefixCount`
// +kubebuilder:printcolumn:name="LastEvent",type=date,JSONPath=`.status.indexParticipation.lastEventAt`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

// CacheBackend is the Schema for the cachebackends API.
type CacheBackend struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   CacheBackendSpec   `json:"spec,omitempty"`
	Status CacheBackendStatus `json:"status,omitempty"`
}

// +kubebuilder:object:root=true

// CacheBackendList contains a list of CacheBackend.
type CacheBackendList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []CacheBackend `json:"items"`
}

func init() {
	SchemeBuilder.Register(func(s *runtime.Scheme) error {
		s.AddKnownTypes(GroupVersion, &CacheBackend{}, &CacheBackendList{})
		return nil
	})
}