webhook

type WebhookController interface {
	// GetSupported returns the complete registry of supported Kubernetes resource types for cost allocation.
	// This method provides a comprehensive map of Group/Version/Kind combinations that the CloudZero Agent
	// webhook can process, enabling dynamic discovery of supported resources and API version compatibility.
	//
	// The nested map structure enables efficient lookup and iteration:
	//   - First key (string): API group (apps, core, batch, networking, gateway-api, storage, extensions)
	//   - Second key (string): API version (v1, v1beta1, v1beta2) for backward compatibility
	//   - Third key (string): Resource kind (deployment, pod, service, ingress, job, etc.)
	//   - Value (metav1.Object): Prototype object for the resource type, used for deserialization
	//
	// Used by:
	//   - HTTP handlers to validate incoming admission requests against supported resources
	//   - Configuration systems to generate webhook configuration YAML with proper GVK declarations
	//   - Monitoring dashboards to display webhook coverage and supported resource inventory
	//   - Testing frameworks to verify handler registration for all supported resource combinations
	//
	// The returned map reflects the current handler registry and updates dynamically as handlers
	// are registered during webhook controller initialization or runtime reconfiguration.
	GetSupported() map[string]map[string]map[string]metav1.Object

	// IsSupported checks whether a specific Group-Version-Kind (GVK)
	// combination is supported for GET operations by the webhook controller.
	//
	// Parameters:
	//   - g: The API group of the resource.
	//   - v: The API version of the resource.
	//   - k: The kind of the resource.
	//
	// Returns:
	//   - bool: True if the specified GVK combination is supported for GET operations,
	//     otherwise false.
	IsSupported(g, v, k string) bool

	// GetConfigurationAccessor retrieves the configuration accessor for a specific
	// Group-Version-Kind (GVK) combination, if it is registered.
	//
	// Parameters:
	//   - g: The API group of the resource.
	//   - v: The API version of the resource.
	//   - k: The kind of the resource.
	//
	// Returns:
	//   - config.ConfigAccessor: The configuration accessor for the specified GVK,
	//     or nil if the GVK is not registered.
	GetConfigurationAccessor(g, v, k string) config.ConfigAccessor

	// Review executes the core admission control logic for CloudZero cost allocation validation.
	// This method is the primary entry point for processing Kubernetes admission requests,
	// orchestrating the complete cost allocation pipeline from resource validation to metadata storage.
	//
	// Processing pipeline:
	//   1. Extract Group/Version/Kind from admission request for handler selection
	//   2. Record webhook event metrics for operational monitoring and analysis
	//   3. Route to resource-specific handler or default allow-all handler
	//   4. Execute cost allocation validation, policy enforcement, and metadata injection
	//   5. Store resource metadata for billing attribution and cost optimization
	//   6. Return admission decision with detailed explanations and warnings
	//
	// Resource-specific handlers implement specialized logic for different Kubernetes resource types:
	//   - Pods: Validate required cost tags, inject missing labels, track resource requests
	//   - Deployments: Enforce team assignments, validate cost center policies
	//   - Services: Apply network cost allocation rules, validate ingress configurations
	//   - PVCs: Implement storage cost attribution, validate retention policies
	//   - Jobs: Apply batch workload cost tracking, validate resource quotas
	//
	// Default handler behavior (unknown resources):
	//   - Allow admission without modification to prevent blocking legitimate workloads
	//   - Log unknown resource types for potential handler development
	//   - Record metrics for monitoring webhook coverage gaps
	//
	// Error handling and resilience:
	//   - Admission failures are logged with detailed context for troubleshooting
	//   - Network timeouts and context cancellation are handled gracefully
	//   - Configuration errors result in admission denial with clear user guidance
	//   - Handler panics are recovered to prevent webhook service disruption
	//
	// Performance considerations:
	//   - Request processing latency is tracked via Prometheus metrics
	//   - Handler selection uses efficient map lookup (O(1) complexity)
	//   - Resource deserialization is optimized for common resource types
	//   - Database operations are batched where possible for efficiency
	//
	// Returns admission response with:
	//   - Allowed: Boolean decision whether to permit the resource operation
	//   - Message: Detailed explanation for denials or informational guidance
	//   - Warnings: Non-blocking advice about cost allocation best practices
	//   - ID: Request correlation ID for audit trails and troubleshooting
	Review(ctx context.Context, ar *types.AdmissionReview) (*types.AdmissionResponse, error)

	// Settings returns the configuration settings for the webhook controller.
	//
	// Returns:
	//   - *config.Settings: The settings instance containing webhook configuration.
	Settings() *config.Settings
}