v1alpha1

type APIPhase string

type APISource struct {
	// Endpoint is the base API URL (without path)
	// The controller will append the appropriate paths:
	// Phase 1 (ToolHive API):
	//   - /v0/servers - List all servers (single response, no pagination)
	//   - /v0/servers/{name} - Get specific server (future)
	//   - /v0/info - Get registry metadata (future)
	// Example: "http://my-registry-api.default.svc.cluster.local/api"
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:Pattern="^https?://.*"
	Endpoint string `json:"endpoint"`
}

type APIStatus struct {
	// Phase represents the current API service phase
	// +kubebuilder:validation:Enum=NotStarted;Deploying;Ready;Unhealthy;Error
	Phase APIPhase `json:"phase"`

	// Message provides additional information about the API status
	// +optional
	Message string `json:"message,omitempty"`

	// Endpoint is the URL where the API is accessible
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// ReadySince is the timestamp when the API became ready
	// +optional
	ReadySince *metav1.Time `json:"readySince,omitempty"`
}

type AdvancedWorkflowStep struct {
	// RetryPolicy defines retry behavior for this step (Phase 2)
	// +optional
	RetryPolicy *RetryPolicy `json:"retryPolicy,omitempty"`

	// Transform defines output transformation template (Phase 2)
	// Allows mapping step output to different structure
	// +optional
	Transform string `json:"transform,omitempty"`

	// CacheKey defines a cache key template for result caching (Phase 2)
	// If specified and cache hit occurs, step is skipped
	// +optional
	CacheKey string `json:"cacheKey,omitempty"`
}

type AggregationConfig struct {
	// ConflictResolution defines the strategy for resolving tool name conflicts
	// - prefix: Automatically prefix tool names with workload identifier
	// - priority: First workload in priority order wins
	// - manual: Explicitly define overrides for all conflicts
	// +kubebuilder:validation:Enum=prefix;priority;manual
	// +kubebuilder:default=prefix
	// +optional
	ConflictResolution string `json:"conflictResolution,omitempty"`

	// ConflictResolutionConfig provides configuration for the chosen strategy
	// +optional
	ConflictResolutionConfig *ConflictResolutionConfig `json:"conflictResolutionConfig,omitempty"`

	// Tools defines per-workload tool filtering and overrides
	// References existing MCPToolConfig resources
	// +optional
	Tools []WorkloadToolConfig `json:"tools,omitempty"`
}

type AuditConfig struct {
	// Enabled controls whether audit logging is enabled
	// When true, enables audit logging with default configuration
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`
}

type AuthzConfigRef struct {
	// Type is the type of authorization configuration
	// +kubebuilder:validation:Enum=configMap;inline
	// +kubebuilder:default=configMap
	Type string `json:"type"`

	// ConfigMap references a ConfigMap containing authorization configuration
	// Only used when Type is "configMap"
	// +optional
	ConfigMap *ConfigMapAuthzRef `json:"configMap,omitempty"`

	// Inline contains direct authorization configuration
	// Only used when Type is "inline"
	// +optional
	Inline *InlineAuthzConfig `json:"inline,omitempty"`
}

type BackendAuthConfig struct {
	// Type defines the authentication type
	// +kubebuilder:validation:Enum=discovered;external_auth_config_ref
	// +kubebuilder:validation:Required
	Type string `json:"type"`

	// ExternalAuthConfigRef references an MCPExternalAuthConfig resource
	// Only used when Type is "external_auth_config_ref"
	// +optional
	ExternalAuthConfigRef *ExternalAuthConfigRef `json:"externalAuthConfigRef,omitempty"`
}

type CircuitBreakerConfig struct {
	// Enabled controls whether circuit breaker is enabled
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// FailureThreshold is the number of failures before opening the circuit
	// +kubebuilder:default=5
	// +optional
	FailureThreshold int `json:"failureThreshold,omitempty"`

	// Timeout is the duration to wait before attempting to close the circuit
	// +kubebuilder:default="60s"
	// +optional
	Timeout string `json:"timeout,omitempty"`
}

type CompositeToolDefinitionRef struct {
	// Name is the name of the VirtualMCPCompositeToolDefinition resource in the same namespace
	// +kubebuilder:validation:Required
	Name string `json:"name"`
}

type CompositeToolSpec struct {
	// Name is the name of the composite tool
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Description describes the composite tool
	// +kubebuilder:validation:Required
	Description string `json:"description"`

	// Parameters defines the input parameter schema in JSON Schema format.
	// Should be a JSON Schema object with "type": "object" and "properties".
	// Per MCP specification, this should follow standard JSON Schema for tool inputSchema.
	// Example:
	//   {
	//     "type": "object",
	//     "properties": {
	//       "param1": {"type": "string", "default": "value"},
	//       "param2": {"type": "integer"}
	//     },
	//     "required": ["param2"]
	//   }
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Type=object
	Parameters *runtime.RawExtension `json:"parameters,omitempty"`

	// Steps defines the workflow steps
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	Steps []WorkflowStep `json:"steps"`

	// Timeout is the maximum execution time for the composite tool
	// +kubebuilder:default="30m"
	// +optional
	Timeout string `json:"timeout,omitempty"`

	// Output defines the structured output schema for the composite tool.
	// Specifies how to construct the final output from workflow step results.
	// If not specified, the workflow returns the last step's output (backward compatible).
	// +optional
	Output *OutputSpec `json:"output,omitempty"`
}

type ConfigMapAuthzRef struct {
	// Name is the name of the ConfigMap
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Key is the key in the ConfigMap that contains the authorization configuration
	// +kubebuilder:default=authz.json
	// +optional
	Key string `json:"key,omitempty"`
}

type ConfigMapOIDCRef struct {
	// Name is the name of the ConfigMap
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Key is the key in the ConfigMap that contains the OIDC configuration
	// +kubebuilder:default=oidc.json
	// +optional
	Key string `json:"key,omitempty"`
}

type ConflictResolutionConfig struct {
	// PrefixFormat defines the prefix format for the "prefix" strategy
	// Supports placeholders: {workload}, {workload}_, {workload}.
	// +kubebuilder:default="{workload}_"
	// +optional
	PrefixFormat string `json:"prefixFormat,omitempty"`

	// PriorityOrder defines the workload priority order for the "priority" strategy
	// +optional
	PriorityOrder []string `json:"priorityOrder,omitempty"`
}

type DiscoveredBackend struct {
	// Name is the name of the backend MCPServer
	Name string `json:"name"`

	// AuthConfigRef is the name of the discovered MCPExternalAuthConfig (if any)
	// +optional
	AuthConfigRef string `json:"authConfigRef,omitempty"`

	// AuthType is the type of authentication configured
	// +optional
	AuthType string `json:"authType,omitempty"`

	// Status is the current status of the backend (ready, degraded, unavailable)
	// +optional
	Status string `json:"status,omitempty"`

	// LastHealthCheck is the timestamp of the last health check
	// +optional
	LastHealthCheck metav1.Time `json:"lastHealthCheck,omitempty"`

	// URL is the URL of the backend MCPServer
	// +optional
	URL string `json:"url,omitempty"`
}

type ElicitationResponseHandler struct {
	// Action defines the action to take when the user declines or cancels
	// - skip_remaining: Skip remaining steps in the workflow
	// - abort: Abort the entire workflow execution
	// - continue: Continue to the next step
	// +kubebuilder:validation:Enum=skip_remaining;abort;continue
	// +kubebuilder:default=abort
	// +optional
	Action string `json:"action,omitempty"`
}

type ElicitationStep struct {
	// Message is the elicitation message to display to the user
	// Supports template expansion
	// +kubebuilder:validation:Required
	Message string `json:"message"`

	// Schema defines the expected response schema
	// Uses JSON Schema format
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Type=object
	Schema *runtime.RawExtension `json:"schema,omitempty"`

	// Timeout is the maximum time to wait for user input
	// +kubebuilder:default="5m"
	// +kubebuilder:validation:Pattern=`^([0-9]+(\.[0-9]+)?(ms|s|m|h))+$`
	// +optional
	Timeout string `json:"timeout,omitempty"`

	// DefaultResponse is the default response if user doesn't respond in time
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Type=object
	DefaultResponse *runtime.RawExtension `json:"defaultResponse,omitempty"`
}

type EnvVar struct {
	// Name of the environment variable
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Value of the environment variable
	// +kubebuilder:validation:Required
	Value string `json:"value"`
}

type ErrorHandling struct {
	// Action defines the action to take on error
	// +kubebuilder:validation:Enum=abort;continue;retry
	// +kubebuilder:default=abort
	// +optional
	Action string `json:"action,omitempty"`

	// MaxRetries is the maximum number of retries
	// Only used when Action is "retry"
	// +optional
	MaxRetries int `json:"maxRetries,omitempty"`

	// RetryDelay is the delay between retry attempts
	// Only used when Action is "retry"
	// +kubebuilder:validation:Pattern=`^([0-9]+(\.[0-9]+)?(ms|s|m))+$`
	// +optional
	RetryDelay string `json:"retryDelay,omitempty"`
}

type ExternalAuthConfigRef struct {
	// Name is the name of the MCPExternalAuthConfig resource
	// +kubebuilder:validation:Required
	Name string `json:"name"`
}

type ExternalAuthType string

type FailureHandlingConfig struct {
	// HealthCheckInterval is the interval between health checks
	// +kubebuilder:default="30s"
	// +optional
	HealthCheckInterval string `json:"healthCheckInterval,omitempty"`

	// UnhealthyThreshold is the number of consecutive failures before marking unhealthy
	// +kubebuilder:default=3
	// +optional
	UnhealthyThreshold int `json:"unhealthyThreshold,omitempty"`

	// PartialFailureMode defines behavior when some backends are unavailable
	// - fail: Fail entire request if any backend is unavailable
	// - best_effort: Continue with available backends
	// +kubebuilder:validation:Enum=fail;best_effort
	// +kubebuilder:default=fail
	// +optional
	PartialFailureMode string `json:"partialFailureMode,omitempty"`

	// CircuitBreaker configures circuit breaker behavior
	// +optional
	CircuitBreaker *CircuitBreakerConfig `json:"circuitBreaker,omitempty"`
}

type GitSource struct {
	// Repository is the Git repository URL (HTTP/HTTPS/SSH)
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:Pattern="^(file:///|https?://|git@|ssh://|git://).*"
	Repository string `json:"repository"`

	// Branch is the Git branch to use (mutually exclusive with Tag and Commit)
	// +kubebuilder:validation:MinLength=1
	// +optional
	Branch string `json:"branch,omitempty"`

	// Tag is the Git tag to use (mutually exclusive with Branch and Commit)
	// +kubebuilder:validation:MinLength=1
	// +optional
	Tag string `json:"tag,omitempty"`

	// Commit is the Git commit SHA to use (mutually exclusive with Branch and Tag)
	// +kubebuilder:validation:MinLength=1
	// +optional
	Commit string `json:"commit,omitempty"`

	// Path is the path to the registry file within the repository
	// +kubebuilder:validation:Pattern=^.*\.json$
	// +kubebuilder:default=registry.json
	// +optional
	Path string `json:"path,omitempty"`
}

type GroupRef struct {
	// Name is the name of the MCPGroup resource in the same namespace
	// +kubebuilder:validation:Required
	Name string `json:"name"`
}

type HeaderInjectionConfig struct {
	// HeaderName is the name of the HTTP header to inject
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	HeaderName string `json:"headerName"`

	// ValueSecretRef references a Kubernetes Secret containing the header value
	// +kubebuilder:validation:Required
	ValueSecretRef *SecretKeyRef `json:"valueSecretRef"`
}

type IncomingAuthConfig struct {
	// Type defines the authentication type: anonymous or oidc
	// When no authentication is required, explicitly set this to "anonymous"
	// +kubebuilder:validation:Enum=anonymous;oidc
	// +kubebuilder:validation:Required
	Type string `json:"type"`

	// OIDCConfig defines OIDC authentication configuration
	// Reuses MCPServer OIDC patterns
	// +optional
	OIDCConfig *OIDCConfigRef `json:"oidcConfig,omitempty"`

	// AuthzConfig defines authorization policy configuration
	// Reuses MCPServer authz patterns
	// +optional
	AuthzConfig *AuthzConfigRef `json:"authzConfig,omitempty"`
}

type InlineAuthzConfig struct {
	// Policies is a list of Cedar policy strings
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	Policies []string `json:"policies"`

	// EntitiesJSON is a JSON string representing Cedar entities
	// +kubebuilder:default="[]"
	// +optional
	EntitiesJSON string `json:"entitiesJson,omitempty"`
}

type InlineOIDCConfig struct {
	// Issuer is the OIDC issuer URL
	// +kubebuilder:validation:Required
	Issuer string `json:"issuer"`

	// Audience is the expected audience for the token
	// +optional
	Audience string `json:"audience,omitempty"`

	// JWKSURL is the URL to fetch the JWKS from
	// +optional
	JWKSURL string `json:"jwksUrl,omitempty"`

	// IntrospectionURL is the URL for token introspection endpoint
	// +optional
	IntrospectionURL string `json:"introspectionUrl,omitempty"`

	// ClientID is the OIDC client ID
	// +optional
	ClientID string `json:"clientId,omitempty"`

	// ClientSecret is the client secret for introspection (optional)
	// Deprecated: Use ClientSecretRef instead for better security
	// +optional
	ClientSecret string `json:"clientSecret,omitempty"`

	// ClientSecretRef is a reference to a Kubernetes Secret containing the client secret
	// If both ClientSecret and ClientSecretRef are provided, ClientSecretRef takes precedence
	// +optional
	ClientSecretRef *SecretKeyRef `json:"clientSecretRef,omitempty"`

	// ThvCABundlePath is the path to CA certificate bundle file for HTTPS requests
	// The file must be mounted into the pod (e.g., via ConfigMap or Secret volume)
	// +optional
	ThvCABundlePath string `json:"thvCABundlePath,omitempty"`

	// JWKSAuthTokenPath is the path to file containing bearer token for JWKS/OIDC requests
	// The file must be mounted into the pod (e.g., via Secret volume)
	// +optional
	JWKSAuthTokenPath string `json:"jwksAuthTokenPath,omitempty"`

	// JWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses
	// Use with caution - only enable for trusted internal IDPs
	// +kubebuilder:default=false
	// +optional
	JWKSAllowPrivateIP bool `json:"jwksAllowPrivateIP"`

	// ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses
	// Use with caution - only enable for trusted internal IDPs or testing
	// +kubebuilder:default=false
	// +optional
	ProtectedResourceAllowPrivateIP bool `json:"protectedResourceAllowPrivateIP"`

	// InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing
	// WARNING: This is insecure and should NEVER be used in production
	// Only enable for local development, testing, or trusted internal networks
	// +kubebuilder:default=false
	// +optional
	InsecureAllowHTTP bool `json:"insecureAllowHTTP"`

	// Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728)
	// If empty, defaults to ["openid"]
	// +optional
	Scopes []string `json:"scopes,omitempty"`
}

type KubernetesOIDCConfig struct {
	// ServiceAccount is the name of the service account to validate tokens for
	// If empty, uses the pod's service account
	// +optional
	ServiceAccount string `json:"serviceAccount,omitempty"`

	// Namespace is the namespace of the service account
	// If empty, uses the MCPServer's namespace
	// +optional
	Namespace string `json:"namespace,omitempty"`

	// Audience is the expected audience for the token
	// +kubebuilder:default=toolhive
	// +optional
	Audience string `json:"audience,omitempty"`

	// Issuer is the OIDC issuer URL
	// +kubebuilder:default="https://kubernetes.default.svc"
	// +optional
	Issuer string `json:"issuer,omitempty"`

	// JWKSURL is the URL to fetch the JWKS from
	// If empty, OIDC discovery will be used to automatically determine the JWKS URL
	// +optional
	JWKSURL string `json:"jwksUrl,omitempty"`

	// IntrospectionURL is the URL for token introspection endpoint
	// If empty, OIDC discovery will be used to automatically determine the introspection URL
	// +optional
	IntrospectionURL string `json:"introspectionUrl,omitempty"`

	// UseClusterAuth enables using the Kubernetes cluster's CA bundle and service account token
	// When true, uses /var/run/secrets/kubernetes.io/serviceaccount/ca.crt for TLS verification
	// and /var/run/secrets/kubernetes.io/serviceaccount/token for bearer token authentication
	// Defaults to true if not specified
	// +optional
	UseClusterAuth *bool `json:"useClusterAuth"`
}

type MCPExternalAuthConfig struct {
	metav1.TypeMeta   `json:",inline"` // nolint:revive
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   MCPExternalAuthConfigSpec   `json:"spec,omitempty"`
	Status MCPExternalAuthConfigStatus `json:"status,omitempty"`
}

type MCPExternalAuthConfigList struct {
	metav1.TypeMeta `json:",inline"` // nolint:revive
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []MCPExternalAuthConfig `json:"items"`
}

type MCPExternalAuthConfigSpec struct {
	// Type is the type of external authentication to configure
	// +kubebuilder:validation:Enum=tokenExchange;headerInjection;unauthenticated
	// +kubebuilder:validation:Required
	Type ExternalAuthType `json:"type"`

	// TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange
	// Only used when Type is "tokenExchange"
	// +optional
	TokenExchange *TokenExchangeConfig `json:"tokenExchange,omitempty"`

	// HeaderInjection configures custom HTTP header injection
	// Only used when Type is "headerInjection"
	// +optional
	HeaderInjection *HeaderInjectionConfig `json:"headerInjection,omitempty"`
}

type MCPExternalAuthConfigStatus struct {
	// ObservedGeneration is the most recent generation observed for this MCPExternalAuthConfig.
	// It corresponds to the MCPExternalAuthConfig's generation, which is updated on mutation by the API Server.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// ConfigHash is a hash of the current configuration for change detection
	// +optional
	ConfigHash string `json:"configHash,omitempty"`

	// ReferencingServers is a list of MCPServer resources that reference this MCPExternalAuthConfig
	// This helps track which servers need to be reconciled when this config changes
	// +optional
	ReferencingServers []string `json:"referencingServers,omitempty"`
}

type MCPGroup struct {
	metav1.TypeMeta   `json:",inline"` // nolint:revive
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   MCPGroupSpec   `json:"spec,omitempty"`
	Status MCPGroupStatus `json:"status,omitempty"`
}

type MCPGroupList struct {
	metav1.TypeMeta `json:",inline"` // nolint:revive
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []MCPGroup `json:"items"`
}

type MCPGroupPhase string

type MCPGroupSpec struct {
	// Description provides human-readable context
	// +optional
	Description string `json:"description,omitempty"`
}

type MCPGroupStatus struct {
	// Phase indicates current state
	// +optional
	// +kubebuilder:default=Pending
	Phase MCPGroupPhase `json:"phase,omitempty"`

	// Servers lists MCPServer names in this group
	// +optional
	Servers []string `json:"servers"`

	// ServerCount is the number of MCPServers
	// +optional
	ServerCount int `json:"serverCount"`

	// RemoteProxies lists MCPRemoteProxy names in this group
	// +optional
	RemoteProxies []string `json:"remoteProxies,omitempty"`

	// RemoteProxyCount is the number of MCPRemoteProxies
	// +optional
	RemoteProxyCount int `json:"remoteProxyCount,omitempty"`

	// Conditions represent observations
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type MCPRegistry struct {
	metav1.TypeMeta   `json:",inline"` // nolint:revive
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   MCPRegistrySpec   `json:"spec,omitempty"`
	Status MCPRegistryStatus `json:"status,omitempty"`
}

type MCPRegistryConfig struct {
	// Name is a unique identifier for this registry configuration within the MCPRegistry
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// Format is the data format (toolhive, upstream)
	// +kubebuilder:validation:Enum=toolhive;upstream
	// +kubebuilder:default=toolhive
	Format string `json:"format,omitempty"`

	// ConfigMapRef defines the ConfigMap source configuration
	// Mutually exclusive with Git, API, and PVCRef
	// +optional
	ConfigMapRef *corev1.ConfigMapKeySelector `json:"configMapRef,omitempty"`

	// Git defines the Git repository source configuration
	// Mutually exclusive with ConfigMapRef, API, and PVCRef
	// +optional
	Git *GitSource `json:"git,omitempty"`

	// API defines the API source configuration
	// Mutually exclusive with ConfigMapRef, Git, and PVCRef
	// +optional
	API *APISource `json:"api,omitempty"`

	// PVCRef defines the PersistentVolumeClaim source configuration
	// Mutually exclusive with ConfigMapRef, Git, and API
	// +optional
	PVCRef *PVCSource `json:"pvcRef,omitempty"`

	// SyncPolicy defines the automatic synchronization behavior for this registry.
	// If specified, enables automatic synchronization at the given interval.
	// Manual synchronization is always supported via annotation-based triggers
	// regardless of this setting.
	// +optional
	SyncPolicy *SyncPolicy `json:"syncPolicy,omitempty"`

	// Filter defines include/exclude patterns for registry content
	// +optional
	Filter *RegistryFilter `json:"filter,omitempty"`
}

type MCPRegistryDatabaseConfig struct {
	// Host is the database server hostname
	// +kubebuilder:default="postgres"
	// +optional
	Host string `json:"host,omitempty"`

	// Port is the database server port
	// +kubebuilder:default=5432
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +optional
	Port int `json:"port,omitempty"`

	// User is the application user (limited privileges: SELECT, INSERT, UPDATE, DELETE)
	// Credentials should be provided via pgpass file or environment variables
	// +kubebuilder:default="db_app"
	// +optional
	User string `json:"user,omitempty"`

	// MigrationUser is the migration user (elevated privileges: CREATE, ALTER, DROP)
	// Used for running database schema migrations
	// Credentials should be provided via pgpass file or environment variables
	// +kubebuilder:default="db_migrator"
	// +optional
	MigrationUser string `json:"migrationUser,omitempty"`

	// Database is the database name
	// +kubebuilder:default="registry"
	// +optional
	Database string `json:"database,omitempty"`

	// SSLMode is the SSL mode for the connection
	// Valid values: disable, allow, prefer, require, verify-ca, verify-full
	// +kubebuilder:validation:Enum=disable;allow;prefer;require;verify-ca;verify-full
	// +kubebuilder:default="prefer"
	// +optional
	SSLMode string `json:"sslMode,omitempty"`

	// MaxOpenConns is the maximum number of open connections to the database
	// +kubebuilder:default=10
	// +kubebuilder:validation:Minimum=1
	// +optional
	MaxOpenConns int `json:"maxOpenConns,omitempty"`

	// MaxIdleConns is the maximum number of idle connections in the pool
	// +kubebuilder:default=2
	// +kubebuilder:validation:Minimum=0
	// +optional
	MaxIdleConns int `json:"maxIdleConns,omitempty"`

	// ConnMaxLifetime is the maximum amount of time a connection may be reused (Go duration format)
	// Examples: "30m", "1h", "24h"
	// +kubebuilder:validation:Pattern=^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
	// +kubebuilder:default="30m"
	// +optional
	ConnMaxLifetime string `json:"connMaxLifetime,omitempty"`

	// DBAppUserPasswordSecretRef references a Kubernetes Secret containing the password for the application database user.
	// The operator will use this password along with DBMigrationUserPasswordSecretRef to generate a pgpass file
	// that is mounted to the registry API container.
	//
	// +kubebuilder:validation:Required
	DBAppUserPasswordSecretRef corev1.SecretKeySelector `json:"dbAppUserPasswordSecretRef"`

	// DBMigrationUserPasswordSecretRef references a Kubernetes Secret containing the password for the migration database user.
	// The operator will use this password along with DBAppUserPasswordSecretRef to generate a pgpass file
	// that is mounted to the registry API container.
	//
	// +kubebuilder:validation:Required
	DBMigrationUserPasswordSecretRef corev1.SecretKeySelector `json:"dbMigrationUserPasswordSecretRef"`
}

type MCPRegistryList struct {
	metav1.TypeMeta `json:",inline"` // nolint:revive
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []MCPRegistry `json:"items"`
}

type MCPRegistryPhase string

type MCPRegistrySpec struct {
	// DisplayName is a human-readable name for the registry
	// +optional
	DisplayName string `json:"displayName,omitempty"`

	// Registries defines the configuration for the registry data sources
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	Registries []MCPRegistryConfig `json:"registries"`

	// EnforceServers indicates whether MCPServers in this namespace must have their images
	// present in at least one registry in the namespace. When any registry in the namespace
	// has this field set to true, enforcement is enabled for the entire namespace.
	// MCPServers with images not found in any registry will be rejected.
	// When false (default), MCPServers can be deployed regardless of registry presence.
	// +kubebuilder:default=false
	// +optional
	EnforceServers bool `json:"enforceServers,omitempty"`

	// PodTemplateSpec defines the pod template to use for the registry API server
	// This allows for customizing the pod configuration beyond what is provided by the other fields.
	// Note that to modify the specific container the registry API server runs in, you must specify
	// the `registry-api` container name in the PodTemplateSpec.
	// This field accepts a PodTemplateSpec object as JSON/YAML.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Type=object
	PodTemplateSpec *runtime.RawExtension `json:"podTemplateSpec,omitempty"`

	// DatabaseConfig defines the PostgreSQL database configuration for the registry API server.
	// If not specified, defaults will be used:
	//   - Host: "postgres"
	//   - Port: 5432
	//   - User: "db_app"
	//   - MigrationUser: "db_migrator"
	//   - Database: "registry"
	//   - SSLMode: "prefer"
	//   - MaxOpenConns: 10
	//   - MaxIdleConns: 2
	//   - ConnMaxLifetime: "30m"
	// +optional
	DatabaseConfig *MCPRegistryDatabaseConfig `json:"databaseConfig,omitempty"`
}

type MCPRegistryStatus struct {
	// Phase represents the current overall phase of the MCPRegistry
	// Derived from sync and API status
	// +optional
	Phase MCPRegistryPhase `json:"phase,omitempty"`

	// Message provides additional information about the current phase
	// +optional
	Message string `json:"message,omitempty"`

	// SyncStatus provides detailed information about data synchronization
	// +optional
	SyncStatus *SyncStatus `json:"syncStatus,omitempty"`

	// APIStatus provides detailed information about the API service
	// +optional
	APIStatus *APIStatus `json:"apiStatus,omitempty"`

	// LastAppliedFilterHash is the hash of the last applied filter
	// +optional
	LastAppliedFilterHash string `json:"lastAppliedFilterHash,omitempty"`

	// StorageRef is a reference to the internal storage location
	// +optional
	StorageRef *StorageReference `json:"storageRef,omitempty"`

	// LastManualSyncTrigger tracks the last processed manual sync annotation value
	// Used to detect new manual sync requests via toolhive.stacklok.dev/sync-trigger annotation
	// +optional
	LastManualSyncTrigger string `json:"lastManualSyncTrigger,omitempty"`

	// Conditions represent the latest available observations of the MCPRegistry's state
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type MCPRemoteProxy struct {
	metav1.TypeMeta   `json:",inline"` // nolint:revive
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   MCPRemoteProxySpec   `json:"spec,omitempty"`
	Status MCPRemoteProxyStatus `json:"status,omitempty"`
}

type MCPRemoteProxyList struct {
	metav1.TypeMeta `json:",inline"` // nolint:revive
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []MCPRemoteProxy `json:"items"`
}

type MCPRemoteProxyPhase string

type MCPRemoteProxySpec struct {
	// RemoteURL is the URL of the remote MCP server to proxy
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^https?://`
	RemoteURL string `json:"remoteURL"`

	// Port is the port to expose the MCP proxy on
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +kubebuilder:default=8080
	Port int32 `json:"port,omitempty"`

	// Transport is the transport method for the remote proxy (sse or streamable-http)
	// +kubebuilder:validation:Enum=sse;streamable-http
	// +kubebuilder:default=streamable-http
	Transport string `json:"transport,omitempty"`

	// OIDCConfig defines OIDC authentication configuration for the proxy
	// This validates incoming tokens from clients. Required for proxy mode.
	// +kubebuilder:validation:Required
	OIDCConfig OIDCConfigRef `json:"oidcConfig"`

	// ExternalAuthConfigRef references a MCPExternalAuthConfig resource for token exchange.
	// When specified, the proxy will exchange validated incoming tokens for remote service tokens.
	// The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPRemoteProxy.
	// +optional
	ExternalAuthConfigRef *ExternalAuthConfigRef `json:"externalAuthConfigRef,omitempty"`

	// AuthzConfig defines authorization policy configuration for the proxy
	// +optional
	AuthzConfig *AuthzConfigRef `json:"authzConfig,omitempty"`

	// Audit defines audit logging configuration for the proxy
	// +optional
	Audit *AuditConfig `json:"audit,omitempty"`

	// ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming.
	// The referenced MCPToolConfig must exist in the same namespace as this MCPRemoteProxy.
	// Cross-namespace references are not supported for security and isolation reasons.
	// If specified, this allows filtering and overriding tools from the remote MCP server.
	// +optional
	ToolConfigRef *ToolConfigRef `json:"toolConfigRef,omitempty"`

	// Telemetry defines observability configuration for the proxy
	// +optional
	Telemetry *TelemetryConfig `json:"telemetry,omitempty"`

	// Resources defines the resource requirements for the proxy container
	// +optional
	Resources ResourceRequirements `json:"resources,omitempty"`

	// TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies
	// When enabled, the proxy will use X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port,
	// and X-Forwarded-Prefix headers to construct endpoint URLs
	// +kubebuilder:default=false
	// +optional
	TrustProxyHeaders bool `json:"trustProxyHeaders,omitempty"`

	// ResourceOverrides allows overriding annotations and labels for resources created by the operator
	// +optional
	ResourceOverrides *ResourceOverrides `json:"resourceOverrides,omitempty"`

	// GroupRef is the name of the MCPGroup this proxy belongs to
	// Must reference an existing MCPGroup in the same namespace
	// +optional
	GroupRef string `json:"groupRef,omitempty"`
}

type MCPRemoteProxyStatus struct {
	// Phase is the current phase of the MCPRemoteProxy
	// +optional
	Phase MCPRemoteProxyPhase `json:"phase,omitempty"`

	// URL is the internal cluster URL where the proxy can be accessed
	// +optional
	URL string `json:"url,omitempty"`

	// ExternalURL is the external URL where the proxy can be accessed (if exposed externally)
	// +optional
	ExternalURL string `json:"externalURL,omitempty"`

	// ObservedGeneration reflects the generation of the most recently observed MCPRemoteProxy
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations of the MCPRemoteProxy's state
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ToolConfigHash stores the hash of the referenced ToolConfig for change detection
	// +optional
	ToolConfigHash string `json:"toolConfigHash,omitempty"`

	// ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec
	// +optional
	ExternalAuthConfigHash string `json:"externalAuthConfigHash,omitempty"`

	// Message provides additional information about the current phase
	// +optional
	Message string `json:"message,omitempty"`
}

type MCPServer struct {
	metav1.TypeMeta   `json:",inline"` // nolint:revive
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   MCPServerSpec   `json:"spec,omitempty"`
	Status MCPServerStatus `json:"status,omitempty"`
}

type MCPServerList struct {
	metav1.TypeMeta `json:",inline"` // nolint:revive
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []MCPServer `json:"items"`
}

type MCPServerPhase string

type MCPServerSpec struct {
	// Image is the container image for the MCP server
	// +kubebuilder:validation:Required
	Image string `json:"image"`

	// Transport is the transport method for the MCP server (stdio, streamable-http or sse)
	// +kubebuilder:validation:Enum=stdio;streamable-http;sse
	// +kubebuilder:default=stdio
	Transport string `json:"transport,omitempty"`

	// ProxyMode is the proxy mode for stdio transport (sse or streamable-http)
	// This setting is only used when Transport is "stdio"
	// +kubebuilder:validation:Enum=sse;streamable-http
	// +kubebuilder:default=streamable-http
	// +optional
	ProxyMode string `json:"proxyMode,omitempty"`

	// Port is the port to expose the MCP server on
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +kubebuilder:default=8080
	// Deprecated: Use ProxyPort instead
	Port int32 `json:"port,omitempty"`

	// TargetPort is the port that MCP server listens to
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +optional
	// Deprecated: Use McpPort instead
	TargetPort int32 `json:"targetPort,omitempty"`

	// ProxyPort is the port to expose the proxy runner on
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +kubebuilder:default=8080
	ProxyPort int32 `json:"proxyPort,omitempty"`

	// McpPort is the port that MCP server listens to
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +optional
	McpPort int32 `json:"mcpPort,omitempty"`

	// Args are additional arguments to pass to the MCP server
	// +optional
	Args []string `json:"args,omitempty"`

	// Env are environment variables to set in the MCP server container
	// +optional
	Env []EnvVar `json:"env,omitempty"`

	// Volumes are volumes to mount in the MCP server container
	// +optional
	Volumes []Volume `json:"volumes,omitempty"`

	// Resources defines the resource requirements for the MCP server container
	// +optional
	Resources ResourceRequirements `json:"resources,omitempty"`

	// Secrets are references to secrets to mount in the MCP server container
	// +optional
	Secrets []SecretRef `json:"secrets,omitempty"`

	// ServiceAccount is the name of an already existing service account to use by the MCP server.
	// If not specified, a ServiceAccount will be created automatically and used by the MCP server.
	// +optional
	ServiceAccount *string `json:"serviceAccount,omitempty"`

	// PermissionProfile defines the permission profile to use
	// +optional
	PermissionProfile *PermissionProfileRef `json:"permissionProfile,omitempty"`

	// PodTemplateSpec defines the pod template to use for the MCP server
	// This allows for customizing the pod configuration beyond what is provided by the other fields.
	// Note that to modify the specific container the MCP server runs in, you must specify
	// the `mcp` container name in the PodTemplateSpec.
	// This field accepts a PodTemplateSpec object as JSON/YAML.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Type=object
	PodTemplateSpec *runtime.RawExtension `json:"podTemplateSpec,omitempty"`

	// ResourceOverrides allows overriding annotations and labels for resources created by the operator
	// +optional
	ResourceOverrides *ResourceOverrides `json:"resourceOverrides,omitempty"`

	// OIDCConfig defines OIDC authentication configuration for the MCP server
	// +optional
	OIDCConfig *OIDCConfigRef `json:"oidcConfig,omitempty"`

	// AuthzConfig defines authorization policy configuration for the MCP server
	// +optional
	AuthzConfig *AuthzConfigRef `json:"authzConfig,omitempty"`

	// Audit defines audit logging configuration for the MCP server
	// +optional
	Audit *AuditConfig `json:"audit,omitempty"`

	// ToolsFilter is the filter on tools applied to the MCP server
	// Deprecated: Use ToolConfigRef instead
	// +optional
	ToolsFilter []string `json:"tools,omitempty"`

	// ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming.
	// The referenced MCPToolConfig must exist in the same namespace as this MCPServer.
	// Cross-namespace references are not supported for security and isolation reasons.
	// If specified, this takes precedence over the inline ToolsFilter field.
	// +optional
	ToolConfigRef *ToolConfigRef `json:"toolConfigRef,omitempty"`

	// ExternalAuthConfigRef references a MCPExternalAuthConfig resource for external authentication.
	// The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServer.
	// +optional
	ExternalAuthConfigRef *ExternalAuthConfigRef `json:"externalAuthConfigRef,omitempty"`

	// Telemetry defines observability configuration for the MCP server
	// +optional
	Telemetry *TelemetryConfig `json:"telemetry,omitempty"`

	// TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies
	// When enabled, the proxy will use X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port,
	// and X-Forwarded-Prefix headers to construct endpoint URLs
	// +kubebuilder:default=false
	// +optional
	TrustProxyHeaders bool `json:"trustProxyHeaders,omitempty"`

	// GroupRef is the name of the MCPGroup this server belongs to
	// Must reference an existing MCPGroup in the same namespace
	// +optional
	GroupRef string `json:"groupRef,omitempty"`
}

type MCPServerStatus struct {
	// Conditions represent the latest available observations of the MCPServer's state
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ToolConfigHash stores the hash of the referenced ToolConfig for change detection
	// +optional
	ToolConfigHash string `json:"toolConfigHash,omitempty"`

	// ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec
	// +optional
	ExternalAuthConfigHash string `json:"externalAuthConfigHash,omitempty"`

	// URL is the URL where the MCP server can be accessed
	// +optional
	URL string `json:"url,omitempty"`

	// Phase is the current phase of the MCPServer
	// +optional
	Phase MCPServerPhase `json:"phase,omitempty"`

	// Message provides additional information about the current phase
	// +optional
	Message string `json:"message,omitempty"`
}

type MCPToolConfig struct {
	metav1.TypeMeta   `json:",inline"` // nolint:revive
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   MCPToolConfigSpec   `json:"spec,omitempty"`
	Status MCPToolConfigStatus `json:"status,omitempty"`
}

type MCPToolConfigList struct {
	metav1.TypeMeta `json:",inline"` // nolint:revive
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []MCPToolConfig `json:"items"`
}

type MCPToolConfigSpec struct {
	// ToolsFilter is a list of tool names to filter (allow list).
	// Only tools in this list will be exposed by the MCP server.
	// If empty, all tools are exposed.
	// +optional
	ToolsFilter []string `json:"toolsFilter,omitempty"`

	// ToolsOverride is a map from actual tool names to their overridden configuration.
	// This allows renaming tools and/or changing their descriptions.
	// +optional
	ToolsOverride map[string]ToolOverride `json:"toolsOverride,omitempty"`
}

type MCPToolConfigStatus struct {
	// ObservedGeneration is the most recent generation observed for this MCPToolConfig.
	// It corresponds to the MCPToolConfig's generation, which is updated on mutation by the API Server.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// ConfigHash is a hash of the current configuration for change detection
	// +optional
	ConfigHash string `json:"configHash,omitempty"`

	// ReferencingServers is a list of MCPServer resources that reference this MCPToolConfig
	// This helps track which servers need to be reconciled when this config changes
	// +optional
	ReferencingServers []string `json:"referencingServers,omitempty"`
}

type NameFilter struct {
	// Include is a list of glob patterns to include
	// +optional
	Include []string `json:"include,omitempty"`

	// Exclude is a list of glob patterns to exclude
	// +optional
	Exclude []string `json:"exclude,omitempty"`
}

type NetworkPermissions struct {
	// Mode specifies the network mode for the container (e.g., "host", "bridge", "none")
	// When empty, the default container runtime network mode is used
	// +optional
	Mode string `json:"mode,omitempty"`

	// Outbound defines the outbound network permissions
	// +optional
	Outbound *OutboundNetworkPermissions `json:"outbound,omitempty"`
}

type OIDCConfigRef struct {
	// Type is the type of OIDC configuration
	// +kubebuilder:validation:Enum=kubernetes;configMap;inline
	// +kubebuilder:default=kubernetes
	Type string `json:"type"`

	// ResourceURL is the explicit resource URL for OAuth discovery endpoint (RFC 9728)
	// If not specified, defaults to the in-cluster Kubernetes service URL
	// +optional
	ResourceURL string `json:"resourceUrl,omitempty"`

	// Kubernetes configures OIDC for Kubernetes service account token validation
	// Only used when Type is "kubernetes"
	// +optional
	Kubernetes *KubernetesOIDCConfig `json:"kubernetes,omitempty"`

	// ConfigMap references a ConfigMap containing OIDC configuration
	// Only used when Type is "configmap"
	// +optional
	ConfigMap *ConfigMapOIDCRef `json:"configMap,omitempty"`

	// Inline contains direct OIDC configuration
	// Only used when Type is "inline"
	// +optional
	Inline *InlineOIDCConfig `json:"inline,omitempty"`
}

type OpenTelemetryConfig struct {
	// Enabled controls whether OpenTelemetry is enabled
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// Endpoint is the OTLP endpoint URL for tracing and metrics
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// ServiceName is the service name for telemetry
	// If not specified, defaults to the MCPServer name
	// +optional
	ServiceName string `json:"serviceName,omitempty"`

	// Headers contains authentication headers for the OTLP endpoint
	// Specified as key=value pairs
	// +optional
	Headers []string `json:"headers,omitempty"`

	// Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint
	// +kubebuilder:default=false
	// +optional
	Insecure bool `json:"insecure,omitempty"`

	// Metrics defines OpenTelemetry metrics-specific configuration
	// +optional
	Metrics *OpenTelemetryMetricsConfig `json:"metrics,omitempty"`

	// Tracing defines OpenTelemetry tracing configuration
	// +optional
	Tracing *OpenTelemetryTracingConfig `json:"tracing,omitempty"`
}

type OpenTelemetryMetricsConfig struct {
	// Enabled controls whether OTLP metrics are sent
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`
}

type OpenTelemetryTracingConfig struct {
	// Enabled controls whether OTLP tracing is sent
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// SamplingRate is the trace sampling rate (0.0-1.0)
	// +kubebuilder:default="0.05"
	// +optional
	SamplingRate string `json:"samplingRate,omitempty"`
}

type OperationalConfig struct {
	// LogLevel sets the logging level for the Virtual MCP server.
	// Set to "debug" to enable debug logging. When not set, defaults to info level.
	// +kubebuilder:validation:Enum=debug
	// +optional
	LogLevel string `json:"logLevel,omitempty"`

	// Timeouts configures timeout settings
	// +optional
	Timeouts *TimeoutConfig `json:"timeouts,omitempty"`

	// FailureHandling configures failure handling behavior
	// +optional
	FailureHandling *FailureHandlingConfig `json:"failureHandling,omitempty"`
}

type OutboundNetworkPermissions struct {
	// InsecureAllowAll allows all outbound network connections (not recommended)
	// +kubebuilder:default=false
	// +optional
	InsecureAllowAll bool `json:"insecureAllowAll,omitempty"`

	// AllowHost is a list of hosts to allow connections to
	// +optional
	AllowHost []string `json:"allowHost,omitempty"`

	// AllowPort is a list of ports to allow connections to
	// +optional
	AllowPort []int32 `json:"allowPort,omitempty"`
}

type OutgoingAuthConfig struct {
	// Source defines how backend authentication configurations are determined
	// - discovered: Automatically discover from backend's MCPServer.spec.externalAuthConfigRef
	// - inline: Explicit per-backend configuration in VirtualMCPServer
	// +kubebuilder:validation:Enum=discovered;inline
	// +kubebuilder:default=discovered
	// +optional
	Source string `json:"source,omitempty"`

	// Default defines default behavior for backends without explicit auth config
	// +optional
	Default *BackendAuthConfig `json:"default,omitempty"`

	// Backends defines per-backend authentication overrides
	// Works in all modes (discovered, inline)
	// +optional
	Backends map[string]BackendAuthConfig `json:"backends,omitempty"`
}

type OutputPropertySpec struct {
	// Type is the JSON Schema type: "string", "integer", "number", "boolean", "object", "array"
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Enum=string;integer;number;boolean;object;array
	Type string `json:"type"`

	// Description is a human-readable description exposed to clients and models
	// +optional
	Description string `json:"description,omitempty"`

	// Value is a template string for constructing the runtime value
	// Supports template syntax: {{.steps.step_id.output.field}}, {{.params.param_name}}
	// For object types, this can be a JSON string that will be deserialized
	// +optional
	Value string `json:"value,omitempty"`

	// Properties defines nested properties for object types
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	Properties map[string]OutputPropertySpec `json:"properties,omitempty"`

	// Default is the fallback value if template expansion fails
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	Default *runtime.RawExtension `json:"default,omitempty"`
}

type OutputSpec struct {
	// Properties defines the output properties
	// Map key is the property name, value is the property definition
	// +optional
	Properties map[string]OutputPropertySpec `json:"properties,omitempty"`

	// Required lists property names that must be present in the output
	// +optional
	Required []string `json:"required,omitempty"`
}

type PVCSource struct {
	// ClaimName is the name of the PersistentVolumeClaim
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	ClaimName string `json:"claimName"`

	// Path is the relative path to the registry file within the PVC.
	// The PVC is mounted at /config/registry/{registryName}/.
	// The full file path becomes: /config/registry/{registryName}/{path}
	//
	// This design:
	// - Each registry gets its own mount point (consistent with ConfigMap sources)
	// - Multiple registries can share the same PVC by mounting it at different paths
	// - Users control PVC organization freely via the path field
	//
	// Examples:
	//   Registry "production" using PVC "shared-data" with path "prod/registry.json":
	//     PVC contains /prod/registry.json → accessed at /config/registry/production/prod/registry.json
	//
	//   Registry "development" using SAME PVC "shared-data" with path "dev/registry.json":
	//     PVC contains /dev/registry.json → accessed at /config/registry/development/dev/registry.json
	//     (Same PVC, different mount path)
	//
	//   Registry "staging" using DIFFERENT PVC "other-pvc" with path "registry.json":
	//     PVC contains /registry.json → accessed at /config/registry/staging/registry.json
	//     (Different PVC, independent mount)
	//
	//   Registry "team-a" with path "v1/servers.json":
	//     PVC contains /v1/servers.json → accessed at /config/registry/team-a/v1/servers.json
	//     (Subdirectories allowed in path)
	// +kubebuilder:validation:Pattern=^.*\.json$
	// +kubebuilder:default=registry.json
	// +optional
	Path string `json:"path,omitempty"`
}

type PermissionProfileRef struct {
	// Type is the type of permission profile reference
	// +kubebuilder:validation:Enum=builtin;configmap
	// +kubebuilder:default=builtin
	Type string `json:"type"`

	// Name is the name of the permission profile
	// If Type is "builtin", Name must be one of: "none", "network"
	// If Type is "configmap", Name is the name of the ConfigMap
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Key is the key in the ConfigMap that contains the permission profile
	// Only used when Type is "configmap"
	// +optional
	Key string `json:"key,omitempty"`
}

type PermissionProfileSpec struct {
	// Read is a list of paths that the MCP server can read from
	// +optional
	Read []string `json:"read,omitempty"`

	// Write is a list of paths that the MCP server can write to
	// +optional
	Write []string `json:"write,omitempty"`

	// Network defines the network permissions for the MCP server
	// +optional
	Network *NetworkPermissions `json:"network,omitempty"`
}

type PrometheusConfig struct {
	// Enabled controls whether Prometheus metrics endpoint is exposed
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`
}

type ProxyDeploymentOverrides struct {
	// ResourceMetadataOverrides is embedded to inherit annotations and labels fields
	ResourceMetadataOverrides `json:",inline"` // nolint:revive

	PodTemplateMetadataOverrides *ResourceMetadataOverrides `json:"podTemplateMetadataOverrides,omitempty"`

	// Env are environment variables to set in the proxy container (thv run process)
	// These affect the toolhive proxy itself, not the MCP server it manages
	// Use TOOLHIVE_DEBUG=true to enable debug logging in the proxy
	// +optional
	Env []EnvVar `json:"env,omitempty"`
}

type RegistryFilter struct {
	// NameFilters defines name-based filtering
	// +optional
	NameFilters *NameFilter `json:"names,omitempty"`

	// Tags defines tag-based filtering
	// +optional
	Tags *TagFilter `json:"tags,omitempty"`
}

type ResourceList struct {
	// CPU is the CPU limit in cores (e.g., "500m" for 0.5 cores)
	// +optional
	CPU string `json:"cpu,omitempty"`

	// Memory is the memory limit in bytes (e.g., "64Mi" for 64 megabytes)
	// +optional
	Memory string `json:"memory,omitempty"`
}

type ResourceMetadataOverrides struct {
	// Annotations to add or override on the resource
	// +optional
	Annotations map[string]string `json:"annotations,omitempty"`

	// Labels to add or override on the resource
	// +optional
	Labels map[string]string `json:"labels,omitempty"`
}

type ResourceOverrides struct {
	// ProxyDeployment defines overrides for the Proxy Deployment resource (toolhive proxy)
	// +optional
	ProxyDeployment *ProxyDeploymentOverrides `json:"proxyDeployment,omitempty"`

	// ProxyService defines overrides for the Proxy Service resource (points to the proxy deployment)
	// +optional
	ProxyService *ResourceMetadataOverrides `json:"proxyService,omitempty"`
}

type ResourceRequirements struct {
	// Limits describes the maximum amount of compute resources allowed
	// +optional
	Limits ResourceList `json:"limits,omitempty"`

	// Requests describes the minimum amount of compute resources required
	// +optional
	Requests ResourceList `json:"requests,omitempty"`
}

type RetryPolicy struct {
	// MaxRetries is the maximum number of retry attempts
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=10
	// +kubebuilder:default=3
	// +optional
	MaxRetries int `json:"maxRetries,omitempty"`

	// BackoffStrategy defines the backoff strategy
	// - fixed: Fixed delay between retries
	// - exponential: Exponential backoff
	// +kubebuilder:validation:Enum=fixed;exponential
	// +kubebuilder:default=exponential
	// +optional
	BackoffStrategy string `json:"backoffStrategy,omitempty"`

	// InitialDelay is the initial delay before first retry
	// +kubebuilder:default="1s"
	// +kubebuilder:validation:Pattern=`^([0-9]+(\.[0-9]+)?(ms|s|m))+$`
	// +optional
	InitialDelay string `json:"initialDelay,omitempty"`

	// MaxDelay is the maximum delay between retries
	// +kubebuilder:default="30s"
	// +kubebuilder:validation:Pattern=`^([0-9]+(\.[0-9]+)?(ms|s|m))+$`
	// +optional
	MaxDelay string `json:"maxDelay,omitempty"`

	// RetryableErrors defines which errors should trigger retry
	// If empty, all errors are retryable
	// Supports regex patterns
	// +optional
	RetryableErrors []string `json:"retryableErrors,omitempty"`
}

type SecretKeyRef struct {
	// Name is the name of the secret
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Key is the key within the secret
	// +kubebuilder:validation:Required
	Key string `json:"key"`
}

type SecretRef struct {
	// Name is the name of the secret
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Key is the key in the secret itself
	// +kubebuilder:validation:Required
	Key string `json:"key"`

	// TargetEnvName is the environment variable to be used when setting up the secret in the MCP server
	// If left unspecified, it defaults to the key
	// +optional
	TargetEnvName string `json:"targetEnvName,omitempty"`
}

type StorageReference struct {
	// Type is the storage type (configmap)
	// +kubebuilder:validation:Enum=configmap
	Type string `json:"type"`

	// ConfigMapRef is a reference to a ConfigMap storage
	// Only used when Type is "configmap"
	// +optional
	ConfigMapRef *corev1.LocalObjectReference `json:"configMapRef,omitempty"`
}

type SyncPhase string

type SyncPolicy struct {
	// Interval is the sync interval for automatic synchronization (Go duration format)
	// Examples: "1h", "30m", "24h"
	// +kubebuilder:validation:Pattern=^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
	// +kubebuilder:validation:Required
	Interval string `json:"interval"`
}

type SyncStatus struct {
	// Phase represents the current synchronization phase
	// +kubebuilder:validation:Enum=Syncing;Complete;Failed
	Phase SyncPhase `json:"phase"`

	// Message provides additional information about the sync status
	// +optional
	Message string `json:"message,omitempty"`

	// LastAttempt is the timestamp of the last sync attempt
	// +optional
	LastAttempt *metav1.Time `json:"lastAttempt,omitempty"`

	// AttemptCount is the number of sync attempts since last success
	// +optional
	// +kubebuilder:validation:Minimum=0
	AttemptCount int `json:"attemptCount,omitempty"`

	// LastSyncTime is the timestamp of the last successful sync
	// +optional
	LastSyncTime *metav1.Time `json:"lastSyncTime,omitempty"`

	// LastSyncHash is the hash of the last successfully synced data
	// Used to detect changes in source data
	// +optional
	LastSyncHash string `json:"lastSyncHash,omitempty"`

	// ServerCount is the total number of servers in the registry
	// +optional
	// +kubebuilder:validation:Minimum=0
	ServerCount int `json:"serverCount,omitempty"`
}

type TagFilter struct {
	// Include is a list of tags to include
	// +optional
	Include []string `json:"include,omitempty"`

	// Exclude is a list of tags to exclude
	// +optional
	Exclude []string `json:"exclude,omitempty"`
}

type TelemetryConfig struct {
	// OpenTelemetry defines OpenTelemetry configuration
	// +optional
	OpenTelemetry *OpenTelemetryConfig `json:"openTelemetry,omitempty"`

	// Prometheus defines Prometheus-specific configuration
	// +optional
	Prometheus *PrometheusConfig `json:"prometheus,omitempty"`
}

type TimeoutConfig struct {
	// Default is the default timeout for backend requests
	// +kubebuilder:default="30s"
	// +optional
	Default string `json:"default,omitempty"`

	// PerWorkload defines per-workload timeout overrides
	// +optional
	PerWorkload map[string]string `json:"perWorkload,omitempty"`
}

type TokenExchangeConfig struct {
	// TokenURL is the OAuth 2.0 token endpoint URL for token exchange
	// +kubebuilder:validation:Required
	TokenURL string `json:"tokenUrl"`

	// ClientID is the OAuth 2.0 client identifier
	// Optional for some token exchange flows (e.g., Google Cloud Workforce Identity)
	// +optional
	ClientID string `json:"clientId,omitempty"`

	// ClientSecretRef is a reference to a secret containing the OAuth 2.0 client secret
	// Optional for some token exchange flows (e.g., Google Cloud Workforce Identity)
	// +optional
	ClientSecretRef *SecretKeyRef `json:"clientSecretRef,omitempty"`

	// Audience is the target audience for the exchanged token
	// +kubebuilder:validation:Required
	Audience string `json:"audience"`

	// Scopes is a list of OAuth 2.0 scopes to request for the exchanged token
	// +optional
	Scopes []string `json:"scopes,omitempty"`

	// SubjectTokenType is the type of the incoming subject token.
	// Accepts short forms: "access_token" (default), "id_token", "jwt"
	// Or full URNs: "urn:ietf:params:oauth:token-type:access_token",
	//               "urn:ietf:params:oauth:token-type:id_token",
	//               "urn:ietf:params:oauth:token-type:jwt"
	// For Google Workload Identity Federation with OIDC providers (like Okta), use "id_token"
	// +kubebuilder:validation:Pattern=`^(access_token|id_token|jwt|urn:ietf:params:oauth:token-type:(access_token|id_token|jwt))?$`
	// +optional
	SubjectTokenType string `json:"subjectTokenType,omitempty"`

	// ExternalTokenHeaderName is the name of the custom header to use for the exchanged token.
	// If set, the exchanged token will be added to this custom header (e.g., "X-Upstream-Token").
	// If empty or not set, the exchanged token will replace the Authorization header (default behavior).
	// +optional
	ExternalTokenHeaderName string `json:"externalTokenHeaderName,omitempty"`
}

type ToolConfigRef struct {
	// Name is the name of the MCPToolConfig resource in the same namespace
	// +kubebuilder:validation:Required
	Name string `json:"name"`
}

type ToolOverride struct {
	// Name is the redefined name of the tool
	// +optional
	Name string `json:"name,omitempty"`

	// Description is the redefined description of the tool
	// +optional
	Description string `json:"description,omitempty"`
}

type ValidationStatus string

type VirtualMCPCompositeToolDefinition struct {
	metav1.TypeMeta   `json:",inline"` // nolint:revive
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   VirtualMCPCompositeToolDefinitionSpec   `json:"spec,omitempty"`
	Status VirtualMCPCompositeToolDefinitionStatus `json:"status,omitempty"`
}

type VirtualMCPCompositeToolDefinitionList struct {
	metav1.TypeMeta `json:",inline"` // nolint:revive
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []VirtualMCPCompositeToolDefinition `json:"items"`
}

type VirtualMCPCompositeToolDefinitionSpec struct {
	// Name is the workflow name exposed as a composite tool
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=64
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$`
	Name string `json:"name"`

	// Description is a human-readable description of the workflow
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Description string `json:"description"`

	// Parameters defines the input parameter schema for the workflow in JSON Schema format.
	// Should be a JSON Schema object with "type": "object" and "properties".
	// Per MCP specification, this should follow standard JSON Schema for tool inputSchema.
	// Example:
	//   {
	//     "type": "object",
	//     "properties": {
	//       "param1": {"type": "string", "default": "value"},
	//       "param2": {"type": "integer"}
	//     },
	//     "required": ["param2"]
	//   }
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Type=object
	Parameters *runtime.RawExtension `json:"parameters,omitempty"`

	// Steps defines the workflow step definitions
	// Steps are executed sequentially in Phase 1
	// Phase 2 will support DAG execution via dependsOn
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	Steps []WorkflowStep `json:"steps"`

	// Timeout is the overall workflow timeout
	// Defaults to 30m if not specified
	// +kubebuilder:default="30m"
	// +kubebuilder:validation:Pattern=`^([0-9]+(\.[0-9]+)?(ms|s|m|h))+$`
	// +optional
	Timeout string `json:"timeout,omitempty"`

	// FailureMode defines the failure handling strategy
	// - abort: Stop execution on first failure (default)
	// - continue: Continue executing remaining steps
	// +kubebuilder:validation:Enum=abort;continue
	// +kubebuilder:default=abort
	// +optional
	FailureMode string `json:"failureMode,omitempty"`

	// Output defines the structured output schema for the composite tool.
	// Specifies how to construct the final output from workflow step results.
	// If not specified, the workflow returns the last step's output (backward compatible).
	// +optional
	Output *OutputSpec `json:"output,omitempty"`
}

type VirtualMCPCompositeToolDefinitionStatus struct {
	// ValidationStatus indicates the validation state of the workflow
	// - Valid: Workflow structure is valid
	// - Invalid: Workflow has validation errors
	// +optional
	ValidationStatus ValidationStatus `json:"validationStatus,omitempty"`

	// ValidationErrors contains validation error messages if ValidationStatus is Invalid
	// +optional
	ValidationErrors []string `json:"validationErrors,omitempty"`

	// ReferencingVirtualServers lists VirtualMCPServer resources that reference this workflow
	// This helps track which servers need to be reconciled when this workflow changes
	// +optional
	ReferencingVirtualServers []string `json:"referencingVirtualServers,omitempty"`

	// ObservedGeneration is the most recent generation observed for this VirtualMCPCompositeToolDefinition
	// It corresponds to the resource's generation, which is updated on mutation by the API Server
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations of the workflow's state
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type VirtualMCPServer struct {
	metav1.TypeMeta   `json:",inline"` // nolint:revive
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   VirtualMCPServerSpec   `json:"spec,omitempty"`
	Status VirtualMCPServerStatus `json:"status,omitempty"`
}

type VirtualMCPServerList struct {
	metav1.TypeMeta `json:",inline"` // nolint:revive
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []VirtualMCPServer `json:"items"`
}

type VirtualMCPServerPhase string

type VirtualMCPServerSpec struct {
	// GroupRef references an existing MCPGroup that defines backend workloads
	// The referenced MCPGroup must exist in the same namespace
	// +kubebuilder:validation:Required
	GroupRef GroupRef `json:"groupRef"`

	// IncomingAuth configures authentication for clients connecting to the Virtual MCP server
	// Must be explicitly set - use "anonymous" type when no authentication is required
	// +kubebuilder:validation:Required
	IncomingAuth *IncomingAuthConfig `json:"incomingAuth"`

	// OutgoingAuth configures authentication from Virtual MCP to backend MCPServers
	// +optional
	OutgoingAuth *OutgoingAuthConfig `json:"outgoingAuth,omitempty"`

	// Aggregation defines tool aggregation and conflict resolution strategies
	// +optional
	Aggregation *AggregationConfig `json:"aggregation,omitempty"`

	// CompositeTools defines inline composite tool definitions
	// For complex workflows, reference VirtualMCPCompositeToolDefinition resources instead
	// +optional
	CompositeTools []CompositeToolSpec `json:"compositeTools,omitempty"`

	// CompositeToolRefs references VirtualMCPCompositeToolDefinition resources
	// for complex, reusable workflows
	// +optional
	CompositeToolRefs []CompositeToolDefinitionRef `json:"compositeToolRefs,omitempty"`

	// Operational defines operational settings like timeouts and health checks
	// +optional
	Operational *OperationalConfig `json:"operational,omitempty"`

	// ServiceType specifies the Kubernetes service type for the Virtual MCP server
	// +kubebuilder:validation:Enum=ClusterIP;NodePort;LoadBalancer
	// +kubebuilder:default=ClusterIP
	// +optional
	ServiceType string `json:"serviceType,omitempty"`

	// PodTemplateSpec defines the pod template to use for the Virtual MCP server
	// This allows for customizing the pod configuration beyond what is provided by the other fields.
	// Note that to modify the specific container the Virtual MCP server runs in, you must specify
	// the 'vmcp' container name in the PodTemplateSpec.
	// This field accepts a PodTemplateSpec object as JSON/YAML.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Type=object
	PodTemplateSpec *runtime.RawExtension `json:"podTemplateSpec,omitempty"`

	// Telemetry configures OpenTelemetry-based observability for the Virtual MCP server
	// including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint
	// +optional
	Telemetry *TelemetryConfig `json:"telemetry,omitempty"`
}

type VirtualMCPServerStatus struct {
	// Conditions represent the latest available observations of the VirtualMCPServer's state
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ObservedGeneration is the most recent generation observed for this VirtualMCPServer
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase is the current phase of the VirtualMCPServer
	// +optional
	// +kubebuilder:default=Pending
	Phase VirtualMCPServerPhase `json:"phase,omitempty"`

	// Message provides additional information about the current phase
	// +optional
	Message string `json:"message,omitempty"`

	// URL is the URL where the Virtual MCP server can be accessed
	// +optional
	URL string `json:"url,omitempty"`

	// DiscoveredBackends lists discovered backend configurations from the MCPGroup
	// +optional
	DiscoveredBackends []DiscoveredBackend `json:"discoveredBackends,omitempty"`

	// BackendCount is the number of discovered backends
	// +optional
	BackendCount int `json:"backendCount,omitempty"`
}

type Volume struct {
	// Name is the name of the volume
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// HostPath is the path on the host to mount
	// +kubebuilder:validation:Required
	HostPath string `json:"hostPath"`

	// MountPath is the path in the container to mount to
	// +kubebuilder:validation:Required
	MountPath string `json:"mountPath"`

	// ReadOnly specifies whether the volume should be mounted read-only
	// +kubebuilder:default=false
	// +optional
	ReadOnly bool `json:"readOnly,omitempty"`
}

type WorkflowStep struct {
	// ID is the unique identifier for this step
	// +kubebuilder:validation:Required
	ID string `json:"id"`

	// Type is the step type (tool, elicitation, etc.)
	// +kubebuilder:validation:Enum=tool;elicitation
	// +kubebuilder:default=tool
	// +optional
	Type string `json:"type,omitempty"`

	// Tool is the tool to call (format: "workload.tool_name")
	// Only used when Type is "tool"
	// +optional
	Tool string `json:"tool,omitempty"`

	// Arguments is a map of argument values with template expansion support.
	// Supports Go template syntax with .params and .steps for string values.
	// Non-string values (integers, booleans, arrays, objects) are passed as-is.
	// Note: the templating is only supported on the first level of the key-value pairs.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Type=object
	Arguments *runtime.RawExtension `json:"arguments,omitempty"`

	// Message is the elicitation message
	// Only used when Type is "elicitation"
	// +optional
	Message string `json:"message,omitempty"`

	// Schema defines the expected response schema for elicitation
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Type=object
	Schema *runtime.RawExtension `json:"schema,omitempty"`

	// OnDecline defines the action to take when the user explicitly declines the elicitation
	// Only used when Type is "elicitation"
	// +optional
	OnDecline *ElicitationResponseHandler `json:"onDecline,omitempty"`

	// OnCancel defines the action to take when the user cancels/dismisses the elicitation
	// Only used when Type is "elicitation"
	// +optional
	OnCancel *ElicitationResponseHandler `json:"onCancel,omitempty"`

	// DependsOn lists step IDs that must complete before this step
	// +optional
	DependsOn []string `json:"dependsOn,omitempty"`

	// Condition is a template expression that determines if the step should execute
	// +optional
	Condition string `json:"condition,omitempty"`

	// OnError defines error handling behavior
	// +optional
	OnError *ErrorHandling `json:"onError,omitempty"`

	// Timeout is the maximum execution time for this step
	// +optional
	Timeout string `json:"timeout,omitempty"`

	// DefaultResults provides fallback output values when this step is skipped
	// (due to condition evaluating to false) or fails (when onError.action is "continue").
	// Each key corresponds to an output field name referenced by downstream steps.
	// Required if the step may be skipped AND downstream steps reference this step's output.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	DefaultResults map[string]runtime.RawExtension `json:"defaultResults,omitempty"`
}

type WorkloadToolConfig struct {
	// Workload is the name of the backend MCPServer workload
	// +kubebuilder:validation:Required
	Workload string `json:"workload"`

	// ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming
	// If specified, Filter and Overrides are ignored
	// +optional
	ToolConfigRef *ToolConfigRef `json:"toolConfigRef,omitempty"`

	// Filter is an inline list of tool names to allow (allow list)
	// Only used if ToolConfigRef is not specified
	// +optional
	Filter []string `json:"filter,omitempty"`

	// Overrides is an inline map of tool overrides
	// Only used if ToolConfigRef is not specified
	// +optional
	Overrides map[string]ToolOverride `json:"overrides,omitempty"`
}