types

type AdmissionResponse struct {
	// ID correlates this response with the original admission request identifier.
	// Used for tracking admission decisions through logs and audit trails, enabling
	// troubleshooting of cost allocation validation failures and policy enforcement.
	// Must match the ID from the corresponding AdmissionReview.
	ID string

	// Allowed indicates whether the CloudZero Agent permits this resource operation.
	// When false, the Kubernetes API server will reject the resource operation and
	// return the Message to the user. When true, the operation proceeds normally.
	//
	// Common reasons for rejection (Allowed=false):
	//   - Missing required cost allocation tags
	//   - Invalid cost center or team assignments
	//   - Policy violations (e.g., unapproved namespaces)
	//   - Resource quota or billing limit exceeded
	Allowed bool

	// Message provides detailed explanation for the admission decision.
	// When Allowed=false, this message is displayed to users explaining why
	// their resource was rejected and how to fix cost allocation issues.
	// When Allowed=true, this may contain informational text about cost allocation.
	//
	// Examples:
	//   - "Missing required cost allocation tag: cost-center"
	//   - "Invalid team assignment: 'marketing' not found in organization"
	//   - "Resource allowed with cost center 'engineering'"
	Message string

	// Warnings contain non-blocking advice about cost allocation best practices.
	// These are displayed to users even when Allowed=true, helping organizations
	// improve their cost allocation hygiene without blocking resource creation.
	//
	// Common warnings:
	//   - "Consider adding project-specific tags for better cost attribution"
	//   - "Namespace 'default' has no cost center assignment"
	//   - "Resource lacks owner information for cost allocation"
	Warnings []string
}

type AdmissionReview struct {
	// OriginalAdmissionReview holds the raw Kubernetes admission review object (v1 or v1beta1).
	// This field preserves the original request for debugging, audit logging, and response
	// generation that requires format-specific handling. Essential for troubleshooting
	// admission failures and maintaining compatibility with different API versions.
	OriginalAdmissionReview runtime.Object

	// ID is the unique identifier for this admission request from the Kubernetes API server.
	// Used for tracking admission requests through the CloudZero Agent processing pipeline,
	// correlating logs, and generating audit trails for cost allocation decisions.
	// Corresponds to the UID field in the original admission request.
	ID string

	// Name is the name of the Kubernetes resource being processed in this admission request.
	// Combined with Namespace, this provides the unique resource identifier within the cluster
	// for cost allocation tracking and resource metadata storage. May be empty for
	// cluster-scoped resources or during resource generation.
	Name string

	// Namespace is the namespace containing the resource being processed in this admission request.
	// Essential for cost allocation as many organizations use namespace-based cost attribution
	// and billing strategies. Empty for cluster-scoped resources like nodes, persistent volumes,
	// and custom resource definitions that don't belong to specific namespaces.
	Namespace string

	// Operation identifies the type of Kubernetes operation being performed (CREATE, UPDATE, DELETE, CONNECT).
	// The CloudZero Agent uses this field to apply appropriate cost allocation logic:
	// CREATE operations validate and inject cost tags, UPDATE operations track cost changes,
	// DELETE operations cleanup cost allocation metadata.
	Operation AdmissionReviewOp

	// Version identifies which admission review API version this request originated from (v1 or v1beta1).
	// Used for generating properly formatted responses and handling version-specific field availability.
	// Critical for maintaining compatibility across different Kubernetes cluster versions.
	Version AdmissionReviewVersion

	// RequestGVR identifies the Group/Version/Resource being operated on in this admission request.
	// Used by the CloudZero Agent to determine which cost allocation rules and validation
	// logic to apply based on resource type. Different resource types may require different
	// cost attribution strategies (e.g., pods vs services vs ingresses).
	RequestGVR *metav1.GroupVersionResource

	// RequestGVK identifies the Group/Version/Kind being operated on in this admission request.
	// Complements RequestGVR by providing the Kind information needed for resource-specific
	// cost allocation processing. Used for routing requests to appropriate resource handlers.
	RequestGVK *metav1.GroupVersionKind

	// OldObjectRaw contains the raw JSON of the resource before modification (for UPDATE operations).
	// The CloudZero Agent uses this field to detect changes in cost allocation metadata
	// and calculate billing impact when resources are modified. Empty for CREATE operations.
	// Essential for tracking cost center transfers and ownership changes.
	OldObjectRaw []byte

	// NewObjectRaw contains the raw JSON of the resource after modification or creation.
	// This is the primary field used by the CloudZero Agent to extract cost allocation
	// metadata, validate required tags, and inject missing cost attribution information.
	// Contains the complete resource specification for cost allocation analysis.
	NewObjectRaw []byte

	// DryRun indicates whether this is a dry-run request (kubectl apply --dry-run).
	// When true, the CloudZero Agent performs all validation and cost allocation analysis
	// but doesn't store resource metadata or trigger billing system updates.
	// Used for testing cost allocation policies without affecting production data.
	DryRun bool

	// UserInfo contains authentication information about the user or service account
	// making the resource request. The CloudZero Agent may use this information for:
	// - Audit logging of cost allocation changes
	// - Applying user-specific cost allocation policies
	// - Attribution of cost allocation decisions to specific users or teams
	UserInfo authenticationv1.UserInfo
}

type AdmissionReviewOp string

type AdmissionReviewVersion string

type Annotations = map[string]string

type Bus interface {
	// Subscribe creates a new subscription to receive all events published to the bus.
	// Returns a subscription that can be used to receive events asynchronously.
	Subscribe() *Subscription

	// Unsubscribe removes an active subscription from the bus and cleans up resources.
	// Should be called when a component no longer needs to receive events.
	Unsubscribe(*Subscription) error

	// Publish sends an event to all active subscribers on the bus.
	// Events are delivered asynchronously to prevent blocking the publisher.
	Publish(event Event)
}

type Creator[Model any] interface {
	// Create persists a new record in the underlying storage system.
	// The method may modify the input Model during the creation process, typically to:
	// - Set auto-generated primary key IDs for database records
	// - Populate creation timestamps and audit fields
	// - Apply default values defined by the storage schema
	//
	// Used throughout the agent for persisting new metric data, configuration changes,
	// and operational state records. The generic type parameter enables type-safe
	// operations while maintaining a consistent interface across different model types.
	//
	// Returns an error if the creation operation fails due to:
	// - Database connectivity issues or transaction conflicts
	// - Constraint violations (unique keys, foreign keys, check constraints)
	// - Storage capacity limits or disk space exhaustion
	// - Invalid model data that fails validation during persistence
	Create(ctx context.Context, it *Model) error
}

type Deleter[ID comparable] interface {
	// Delete removes a record from the underlying storage system by its unique identifier.
	// The generic ID parameter supports various identifier types (string, int64, UUID)
	// matching the corresponding Reader interface for consistency.
	//
	// Used throughout the agent for:
	// - Removing processed metric files after successful upload to CloudZero
	// - Cleaning up expired configuration entries during system maintenance
	// - Deleting temporary operational state data after processing completion
	//
	// The operation should be idempotent - deleting a non-existent record
	// should not return an error to simplify cleanup logic and retry scenarios.
	//
	// Returns an error if the deletion operation fails due to:
	// - Database connectivity issues preventing the delete operation
	// - Foreign key constraints that prevent cascade deletion
	// - Storage system errors (disk full, permissions, corruption)
	// - Context cancellation interrupting the deletion process
	//
	// Implementations should handle referential integrity appropriately,
	// either through cascade deletion or by returning descriptive errors
	// when deletion would violate data consistency requirements.
	//
	// For systems requiring audit trails, implementations may perform
	// "soft deletes" (marking records as deleted) rather than physical removal.
	Delete(ctx context.Context, id ID) error
}

type Event = partybus.Event

type File interface {
	// io.ReadWriteCloser provides standard I/O operations for reading, writing, and resource cleanup.
	// Implementations must handle proper buffering and flushing for performance optimization.
	io.ReadWriteCloser

	// UniqueID returns a stable identifier for this file across operations.
	// Used for tracking files through the collection, compression, and upload pipeline.
	// Must remain consistent even if the file is moved or renamed.
	UniqueID() string

	// Location returns the current full path of the file in the filesystem.
	// This path may change if the file is moved during processing operations.
	Location() string

	// Rename moves the file to a new location in the filesystem.
	// Used during the metric processing pipeline to move files between stages
	// (e.g., from temporary to processed to uploaded directories).
	// Returns error if the rename operation fails due to permissions or filesystem issues.
	Rename(new string) error

	// Size returns the current size of the file in bytes.
	// Used for storage monitoring, upload progress tracking, and batch processing decisions.
	// Returns error if the file size cannot be determined (e.g., file deleted, permissions).
	Size() (int64, error)
}

type FileChanged struct {
	// Name is the full path of the modified file.
	Name string
}

type FileCreated struct {
	// Name is the full path of the newly created file.
	Name string
}

type FileDeleted struct {
	// Name is the full path of the deleted file.
	Name string
}

type FileRenamed struct {
	// Name is the new full path of the renamed file.
	Name string
}

type InputData struct {
	// TimeSeries contains all metric series in the remote_write batch.
	TimeSeries []TimeSeries `json:"timeseries"` //nolint:tagliatelle // matches Prometheus remote_write format
}

type K8sObject interface {
	metav1.Object
	runtime.Object
}

type Label struct {
	// Name is the label key, following Prometheus naming conventions (__name__, node, etc.).
	Name string `json:"name"`

	// Value is the label value, containing the actual metadata for cost allocation analysis.
	Value string `json:"value"`
}

type Labels = map[string]string

type Metric struct {
	// ID is a unique identifier for this metric record, generated during collection.
	ID uuid.UUID

	// ClusterName identifies the Kubernetes cluster this metric originated from.
	ClusterName string

	// CloudAccountID identifies the cloud provider account for cost allocation.
	CloudAccountID string

	// MetricName is the Prometheus metric name, typically extracted from the __name__ label.
	MetricName string

	// NodeName identifies the specific node where this metric was collected, if applicable.
	NodeName string

	// CreatedAt is when this metric record was created in the CloudZero Agent system.
	CreatedAt time.Time

	// TimeStamp is the original metric observation time from the Prometheus sample.
	TimeStamp time.Time

	// Labels contains all metric labels excluding those hoisted to dedicated fields (like __name__, node).
	Labels map[string]string

	// Value is the metric value as a string to preserve precision during serialization.
	Value string
}

type MetricRange struct {
	// Metrics contains the current page of metric records.
	Metrics []Metric `json:"metrics"`

	// Next is an optional pagination token for retrieving the next page of results.
	Next *string `json:"next,omitempty"`
}

type MetricTransformer interface {
	// Transform processes a slice of metrics, converting vendor-specific metrics
	// into standardized formats while passing through all other metrics unchanged.
	//
	// The transformation is idempotent - metrics that are already in standardized
	// format or are not recognized pass through without modification.
	//
	// Parameters:
	//   - ctx: Request context for cancellation and tracing
	//   - metrics: Input metrics from Prometheus remote_write decode
	//
	// Returns:
	//   - Transformed metrics with GPU metrics in standardized format
	//   - Error if transformation fails (context cancellation, invalid data, etc.)
	//
	// The returned slice may have a different length than the input if transformation
	// results in metric expansion (e.g., one input metric generating multiple output
	// metrics for different resource attribution).
	Transform(ctx context.Context, metrics []Metric) ([]Metric, error)
}

type ObjectCreator interface {
	// NewObject decodes the provided raw runtime-encoded byte slice into a K8sObject.
	// It extracts and captures the necessary metadata from the object.
	// Returns the constructed K8sObject or an error if decoding fails.
	NewObject(raw []byte) (K8sObject, error)
}

type ParquetMetric struct {
	// ClusterName identifies the source Kubernetes cluster for cost allocation.
	ClusterName string `parquet:"cluster_name"`

	// CloudAccountID identifies the cloud provider account for billing analysis.
	CloudAccountID string `parquet:"cloud_account_id"`

	// Year provides time-based partitioning for efficient data warehouse queries.
	Year string `parquet:"year"`

	// Month provides monthly partitioning for billing cycle analysis.
	Month string `parquet:"month"`

	// Day provides daily partitioning for fine-grained cost tracking.
	Day string `parquet:"day"`

	// Hour provides hourly partitioning for detailed usage analysis.
	Hour string `parquet:"hour"`

	// MetricName is the Prometheus metric identifier for data classification.
	MetricName string `parquet:"metric_name"`

	// NodeName identifies the source node for infrastructure cost attribution.
	NodeName string `parquet:"node_name"`

	// CreatedAt is the metric creation timestamp in Unix milliseconds for efficient storage.
	CreatedAt int64 `parquet:"created_at,timestamp"`

	// TimeStamp is the original observation timestamp in Unix milliseconds.
	TimeStamp int64 `parquet:"timestamp,timestamp"`

	// Labels contains all metric metadata serialized as JSON for flexible querying.
	Labels string `parquet:"labels"`

	// Value is the metric measurement preserved as string for precision.
	Value string `parquet:"value"`
}

type ReadableStore interface {
	StoreMonitor

	// GetFiles returns the list of files in the store. `paths` can be used to add a specific location
	GetFiles(paths ...string) ([]string, error)

	// ListFiles gives a list of `[]os.DirEntry` for a given store. `paths` can be used to add a specific location
	ListFiles(paths ...string) ([]os.DirEntry, error)

	// Walk runs a `proccess` on the file loc of the implementation store
	Walk(loc string, process filepath.WalkFunc) error

	// Find searches for files recursively starting from a given directory with optional filename and extension filters.
	Find(ctx context.Context, filterName string, filterExtension string) ([]string, error)
}

type Reader[Model any, ID comparable] interface {
	// Get retrieves a single record from the storage system by its unique identifier.
	// The generic ID parameter supports various identifier types (string, int64, UUID)
	// depending on the specific model and storage backend requirements.
	//
	// Used throughout the agent for:
	// - Loading specific metric records for analysis or reprocessing
	// - Retrieving configuration entries by key for runtime behavior
	// - Fetching operational state data for system monitoring
	//
	// Returns a pointer to the requested Model instance if found, or an error if:
	// - The record with the specified ID does not exist (types.ErrNotFound)
	// - Database connectivity issues prevent the query from executing
	// - Storage corruption or schema migration issues affect data access
	// - Context cancellation interrupts the retrieval operation
	//
	// The returned Model pointer should not be modified without proper synchronization
	// if the storage backend uses shared data structures or caching mechanisms.
	Get(ctx context.Context, id ID) (*Model, error)
}

type RemoteWriteHistory struct {
	// LastRemoteWriteTime is the timestamp of the most recent successful remote_write request.
	// Used for monitoring metric collection continuity and detecting collection interruptions.
	LastRemoteWriteTime time.Time
}

type ResourceStore interface {
	// StorageCommon provides transaction support and bulk operations for resource metadata.
	// These operations ensure data consistency across multiple resource updates and
	// enable efficient batch processing during resource discovery and validation.
	StorageCommon

	// Storage provides CRUD operations for ResourceTags entities with string-based identifiers.
	// The string ID typically represents the unique resource identifier within Kubernetes
	// (namespace/name format) enabling efficient resource lookups and updates.
	Storage[ResourceTags, string]

	// FindFirstBy retrieves the first ResourceTags entity matching the specified query conditions.
	// This method supports complex queries for resource discovery and validation operations.
	//
	// Common usage patterns:
	//   - Finding resources by specific label combinations for cost attribution
	//   - Locating resources within specific namespaces for scope validation
	//   - Discovering resources with specific ownership or team assignments
	//
	// The conditions parameter accepts ORM-style query conditions (field=value, field IN (values))
	// enabling flexible resource lookup without complex SQL construction.
	//
	// Returns nil if no matching resource is found, enabling safe handling of optional lookups.
	// Returns error if the query fails due to database connectivity or malformed conditions.
	FindFirstBy(ctx context.Context, conds ...interface{}) (*ResourceTags, error)

	// FindAllBy retrieves all ResourceTags entities matching the specified query conditions.
	// This method enables bulk resource discovery and batch processing operations essential
	// for cost allocation calculations and resource lifecycle management.
	//
	// Common usage patterns:
	//   - Finding all resources belonging to a specific team or cost center
	//   - Discovering resources with missing or incomplete cost allocation tags
	//   - Retrieving resources for bulk cost calculation and reporting operations
	//   - Implementing resource cleanup based on lifecycle policies
	//
	// The conditions parameter supports the same query syntax as FindFirstBy but returns
	// multiple results in a slice format for efficient batch processing.
	//
	// Returns empty slice if no matching resources are found, enabling safe iteration.
	// Returns error if the query fails due to database issues or invalid query conditions.
	//
	// Performance considerations:
	//   - Large result sets may require pagination in production environments
	//   - Consider using transaction context for consistency during bulk operations
	//   - Index key fields used in conditions for optimal query performance
	FindAllBy(ctx context.Context, conds ...interface{}) ([]*ResourceTags, error)
}

type ResourceTags struct {
	// ID is a unique database identifier for this resource metadata record.
	ID string `gorm:"unique;autoIncrement"`

	// Type identifies the Kubernetes resource type (deployment, pod, node, etc.) for cost categorization.
	Type config.ResourceType `gorm:"primaryKey"`

	// Name is the Kubernetes resource name, forming part of the composite primary key.
	Name string `gorm:"primaryKey"`

	// Namespace is the Kubernetes namespace containing this resource, nullable for cluster-scoped resources.
	Namespace *string `gorm:"primaryKey"`

	// MetricLabels contains Prometheus-style labels extracted from the resource for metric correlation.
	MetricLabels *config.MetricLabels `gorm:"serializer:json"`

	// Labels contains the Kubernetes resource labels used for cost allocation and resource grouping.
	Labels *config.MetricLabelTags `gorm:"serializer:json"`

	// Annotations contains the Kubernetes resource annotations with additional cost allocation metadata.
	Annotations *config.MetricLabelTags `gorm:"serializer:json"`

	// RecordCreated is when this metadata record was first created in the local database.
	RecordCreated time.Time

	// RecordUpdated is when this record was last updated due to resource label/annotation changes.
	RecordUpdated time.Time

	// SentAt tracks when this record was successfully transmitted to the CloudZero API, null if pending.
	SentAt *time.Time

	// Size is a computed field showing the total byte size of this record for storage monitoring.
	Size int `` /* 174-byte string literal not displayed */
}

type Runnable interface {
	// Run starts the runnable component and blocks until completion or error.
	// Implementations should handle graceful startup and be prepared for shutdown signals.
	Run() error

	// IsRunning returns true if the component is currently active and processing.
	// This method provides status information for health checks and monitoring.
	IsRunning() bool

	// Shutdown initiates graceful shutdown of the component.
	// Implementations should clean up resources, flush pending data, and return promptly.
	Shutdown() error
}

type Sample struct {
	// Value is the metric value as a float64 pointer to support null values in time series data.
	Value *float64 `json:"value"`

	// Timestamp is the Unix timestamp in milliseconds when the metric was observed, stored as string for JSON compatibility.
	Timestamp string `json:"timestamp"`
}

type Set[T comparable] struct {
	// contains filtered or unexported fields
}

type Storage[Model any, ID comparable] interface {
	// Creator provides record creation capabilities for new data entities.
	Creator[Model]

	// Reader provides record retrieval capabilities for existing data lookup.
	Reader[Model, ID]

	// Updater provides record modification capabilities for data maintenance.
	Updater[Model]

	// Deleter provides record removal capabilities for data lifecycle management.
	Deleter[ID]
}

type StorageCommon interface {
	// Tx executes a block of operations within a database transaction for atomicity.
	// The provided context includes transaction state that must be passed to all operations within the block.
	// Used for complex operations involving multiple tables or ensuring data consistency across operations.
	Tx(ctx context.Context, block func(ctxTx context.Context) error) error

	// Count returns the total number of records in the associated table.
	// Used for capacity monitoring, pagination calculations, and storage usage reporting.
	Count(ctx context.Context) (int, error)

	// DeleteAll removes all records from the associated table.
	// Used for data cleanup operations, testing teardown, and maintenance procedures.
	// Should be used with extreme caution in production environments.
	DeleteAll(ctx context.Context) error
}

type Store interface {
	WritableStore
	ReadableStore
}

type StoreMonitor interface {
	// GetUsage returns a complete snapshot of the store usage.
	// optional `paths` can be defined which will be used as `filepath.Join(paths...)`
	GetUsage(limit uint64, paths ...string) (*StoreUsage, error)
}

type StoreUsage struct {
	// Total is the total storage capacity in bytes of the monitored filesystem.
	Total uint64 `json:"total"`

	// Available is the available storage space in bytes for new data.
	Available uint64 `json:"available"`

	// Used is the currently utilized storage in bytes, computed as Total - Available.
	Used uint64 `json:"used"`

	// PercentUsed is the utilization percentage, computed as (Used / Total) * 100.
	// This field is used with StoreWarning thresholds to determine alert levels.
	PercentUsed float64 `json:"percentUsed"`

	// BlockSize is the underlying filesystem block size in bytes for storage efficiency calculations.
	BlockSize uint32 `json:"blockSize"`
}

type StoreWarning int

type Subscription = partybus.Subscription

type TimeProvider interface {
	// GetCurrentTime returns the current system time.
	// In production, this returns time.Now(). In tests, this can return controlled timestamps
	// to validate time-dependent logic such as metric timestamping and data retention.
	GetCurrentTime() time.Time
}

type TimeSeries struct {
	// Labels contains all metric labels including __name__, resource identifiers, and custom tags.
	Labels []Label `json:"labels"`

	// Samples contains the time series data points with timestamps and values.
	Samples []Sample `json:"samples"`
}

type Updater[Model any] interface {
	// Update modifies an existing record in the underlying storage system.
	// The method may modify the input Model during the update process, typically to:
	// - Set modification timestamps and audit trail information
	// - Apply version increments for optimistic locking mechanisms
	// - Normalize or validate field values according to business rules
	//
	// Used throughout the agent for:
	// - Updating metric processing status and classification results
	// - Modifying configuration settings during runtime reconfiguration
	// - Updating operational state data for system health monitoring
	//
	// The generic type parameter enables type-safe update operations while
	// maintaining interface consistency across different model types.
	//
	// Returns an error if the update operation fails due to:
	// - Record not found (the target record no longer exists)
	// - Concurrent modification conflicts (optimistic locking failures)
	// - Database connectivity issues or transaction rollback conditions
	// - Constraint violations resulting from the updated field values
	// - Storage capacity limits preventing the update from completing
	//
	// Implementations should ensure atomicity of updates and proper error
	// reporting to enable appropriate retry and recovery strategies.
	Update(ctx context.Context, it *Model) error
}

type WritableStore interface {
	// All retrieves all metrics. It takes a context and an optional string pointer as parameters.
	// Returns a MetricRange and an error.
	All(context.Context, string) (MetricRange, error)

	// Put appends one or more metrics to the storage, handling buffering internally.
	Put(context.Context, ...Metric) error

	// Flush writes all buffered data to persistent storage.
	// This can be used to force a write without reaching the row limit.
	Flush() error

	// Pending returns the number of rows currently buffered and not yet written to disk.
	// This can be used to monitor when a flush may be needed.
	Pending() int
}