core

type AZAwareData[Self any] interface {
	// List of permitted types. This is required for type inference, as explained here:
	// <https://stackoverflow.com/a/73851453>
	UsageData | CapacityData
	// contains filtered or unexported methods
}

type AutogrowQuotaDistributionConfiguration struct {
	AllowQuotaOvercommit     bool                         `yaml:"allow_quota_overcommit"`
	ProjectBaseQuota         uint64                       `yaml:"project_base_quota"`
	GrowthMultiplier         float64                      `yaml:"growth_multiplier"`
	GrowthMinimum            uint64                       `yaml:"growth_minimum"`
	UsageDataRetentionPeriod util.MarshalableTimeDuration `yaml:"usage_data_retention_period"`
}

type CapacitorConfiguration struct {
	ID         string              `yaml:"id"`
	PluginType string              `yaml:"type"`
	Parameters util.YamlRawMessage `yaml:"params"`
}

type CapacityData struct {
	//NOTE: The json tags are only relevant for the output of `limes test-scan-capacity`.
	Capacity      uint64  `json:"capacity"`
	Usage         *uint64 `json:"usage,omitempty"`         //NOTE: currently only relevant on AZ level, regional level uses the aggregation of project usages
	Subcapacities []any   `json:"subcapacities,omitempty"` // only if supported by plugin and enabled in config
}

type CapacityPlugin interface {
	pluggable.Plugin
	// Init is called before any other interface methods, and allows the plugin to
	// perform first-time initialization. If the plugin needs to access OpenStack
	// APIs, it needs to spawn the respective ServiceClients in this method and
	// retain them.
	//
	// Before Init is called, the `capacitors[].params` provided in the config
	// file will be yaml.Unmarshal()ed into the plugin object itself.
	Init(client *gophercloud.ProviderClient, eo gophercloud.EndpointOpts) error
	// Scrape queries the backend service(s) for the capacities of the resources
	// that this plugin is concerned with. The result is a two-dimensional map,
	// with the first key being the service type, and the second key being the
	// resource name. The capacity collector will ignore service types for which
	// there is no QuotaPlugin, and resources which are not advertised by that
	// QuotaPlugin.
	//
	// The serializedMetrics return value is persisted in the Limes DB and
	// supplied to all subsequent RenderMetrics calls.
	Scrape(backchannel CapacityPluginBackchannel, allAZs []limes.AvailabilityZone) (result map[limes.ServiceType]map[limesresources.ResourceName]PerAZ[CapacityData], serializedMetrics []byte, err error)

	// DescribeMetrics is called when Prometheus is scraping metrics from
	// limes-collect, to provide an opportunity to the plugin to emit its own
	// metrics.
	//
	// Together with CollectMetrics, this interface is roughly analogous to the
	// prometheus.Collector interface; cf. documentation over there.
	DescribeMetrics(ch chan<- *prometheus.Desc)
	// CollectMetrics is called when Prometheus is scraping metrics from
	// limes-collect, to provide an opportunity to the plugin to emit its own
	// metrics. The serializedMetrics argument contains the respective value
	// returned from the last Scrape call on the same project.
	//
	// Some plugins also emit metrics directly within Scrape. This newer interface
	// should be preferred since metrics emitted here won't be lost between
	// restarts of limes-collect.
	CollectMetrics(ch chan<- prometheus.Metric, serializedMetrics []byte) error
}

type CapacityPluginBackchannel interface {
	GetGlobalResourceDemand(serviceType limes.ServiceType, resourceName limesresources.ResourceName) (map[limes.AvailabilityZone]ResourceDemand, error)
	GetOvercommitFactor(serviceType limes.ServiceType, resourceName limesresources.ResourceName) (OvercommitFactor, error)
}

type Cluster struct {
	Config          ClusterConfiguration
	DiscoveryPlugin DiscoveryPlugin
	QuotaPlugins    map[limes.ServiceType]QuotaPlugin
	CapacityPlugins map[string]CapacityPlugin
	Authoritative   bool
	QuotaOverrides  map[string]map[string]map[limes.ServiceType]map[limesresources.ResourceName]uint64
}

type ClusterConfiguration struct {
	AvailabilityZones []limes.AvailabilityZone `yaml:"availability_zones"`
	CatalogURL        string                   `yaml:"catalog_url"`
	Discovery         DiscoveryConfiguration   `yaml:"discovery"`
	Services          []ServiceConfiguration   `yaml:"services"`
	Capacitors        []CapacitorConfiguration `yaml:"capacitors"`
	// ^ Sorry for the stupid pun. Not.
	ResourceBehaviors        []ResourceBehavior                `yaml:"resource_behavior"`
	QuotaDistributionConfigs []*QuotaDistributionConfiguration `yaml:"quota_distribution_configs"`
}

type DiscoveryConfiguration struct {
	Method          string                `yaml:"method"`
	ExcludeDomainRx regexpext.PlainRegexp `yaml:"except_domains"`
	IncludeDomainRx regexpext.PlainRegexp `yaml:"only_domains"`
	Parameters      util.YamlRawMessage   `yaml:"params"`
}

type DiscoveryPlugin interface {
	pluggable.Plugin
	// Init is called before any other interface methods, and allows the plugin to
	// perform first-time initialization. If the plugin needs to access OpenStack
	// APIs, it needs to spawn the respective ServiceClients in this method and
	// retain them.
	//
	// Before Init is called, the `discovery.params` provided in the configuration
	// file will be yaml.Unmarshal()ed into the plugin object itself.
	Init(client *gophercloud.ProviderClient, eo gophercloud.EndpointOpts) error
	// ListDomains returns all Keystone domains in the cluster.
	ListDomains() ([]KeystoneDomain, error)
	// ListProjects returns all Keystone projects in the given domain.
	ListProjects(domain KeystoneDomain) ([]KeystoneProject, error)
}

type KeystoneDomain struct {
	UUID string `json:"id" yaml:"id"`
	Name string `json:"name" yaml:"name"`
}

type KeystoneProject struct {
	UUID       string         `json:"id" yaml:"id"`
	Name       string         `json:"name" yaml:"name"`
	ParentUUID string         `json:"parent_id,omitempty" yaml:"parent_id,omitempty"`
	Domain     KeystoneDomain `json:"domain" yaml:"domain"`
}

type OvercommitFactor float64

type PerAZ[D AZAwareData[D]] map[limes.AvailabilityZone]*D

type QuotaDistributionConfiguration struct {
	FullResourceNameRx regexpext.BoundedRegexp               `yaml:"resource"`
	Model              limesresources.QuotaDistributionModel `yaml:"model"`
	// options for AutogrowQuotaDistribution
	Autogrow *AutogrowQuotaDistributionConfiguration `yaml:"autogrow"`
}

type QuotaPlugin interface {
	pluggable.Plugin
	// Init is called before any other interface methods, and allows the plugin to
	// perform first-time initialization. If the plugin needs to access OpenStack
	// APIs, it needs to spawn the respective ServiceClients in this method and
	// retain them.
	//
	// Implementations can use it f.i. to discover the available Resources(). For
	// plugins that support subresource scraping, the final argument indicates
	// which resources to scrape (the keys are resource names).
	//
	// Before Init is called, the `services[].params` provided in the config
	// file will be yaml.Unmarshal()ed into the plugin object itself.
	Init(client *gophercloud.ProviderClient, eo gophercloud.EndpointOpts) error

	// ServiceInfo returns metadata for this service.
	//
	// This receives the `serviceType` as an argument because it needs to appear
	// in the ServiceInfo struct. But in general, a plugin cannot know which
	// serviceType it was instantiated for (esp. in unit tests, where the generic
	// test plugin is instantiated multiple times for different service types).
	ServiceInfo(serviceType limes.ServiceType) limes.ServiceInfo

	// Resources returns metadata for all the resources that this plugin scrapes
	// from the backend service.
	Resources() []limesresources.ResourceInfo
	// Scrape queries the backend service for the quota and usage data of all
	// known resources for the given project in the given domain. The string keys
	// in the result map must be identical to the resource names
	// from Resources().
	//
	// The `allAZs` list comes from the Limes config and should be used when
	// building AZ-aware usage data, to ensure that each AZ-aware resource reports
	// usage in all available AZs, even when the project in question does not have
	// usage in every AZ.
	//
	// The `serializedMetrics` return value is persisted in the Limes DB and
	// supplied to all subsequent RenderMetrics calls.
	Scrape(project KeystoneProject, allAZs []limes.AvailabilityZone) (result map[limesresources.ResourceName]ResourceData, serializedMetrics []byte, err error)
	// SetQuota updates the backend service's quotas for the given project in the
	// given domain to the values specified here. The map is guaranteed to contain
	// values for all resources defined by Resources().
	SetQuota(project KeystoneProject, quotas map[limesresources.ResourceName]uint64) error

	// Rates returns metadata for all the rates that this plugin scrapes
	// from the backend service.
	Rates() []limesrates.RateInfo
	// ScrapeRates queries the backend service for the usage data of all the rates
	// enumerated by Rates() for the given project in the given domain. The string
	// keys in the result map must be identical to the rate names from Rates().
	//
	// The serializedState return value is persisted in the Limes DB and returned
	// back to the next ScrapeRates() call for the same project in the
	// prevSerializedState argument. Besides that, this field is not interpreted
	// by the core application in any way. The plugin implementation can use this
	// field to carry state between ScrapeRates() calls, esp. to detect and handle
	// counter resets in the backend.
	ScrapeRates(project KeystoneProject, prevSerializedState string) (result map[limesrates.RateName]*big.Int, serializedState string, err error)

	// DescribeMetrics is called when Prometheus is scraping metrics from
	// limes-collect, to provide an opportunity to the plugin to emit its own
	// metrics.
	//
	// Together with CollectMetrics, this interface is roughly analogous to the
	// prometheus.Collector interface; cf. documentation over there.
	DescribeMetrics(ch chan<- *prometheus.Desc)
	// CollectMetrics is called when Prometheus is scraping metrics from
	// limes-collect, to provide an opportunity to the plugin to emit its own
	// metrics. The serializedMetrics argument contains the respective value
	// returned from the last Scrape call on the same project.
	//
	// Some plugins also emit metrics directly within Scrape. This newer interface
	// should be preferred since metrics emitted here won't be lost between
	// restarts of limes-collect.
	CollectMetrics(ch chan<- prometheus.Metric, project KeystoneProject, serializedMetrics []byte) error
}

type RateLimitConfiguration struct {
	Name   limesrates.RateName `yaml:"name"`
	Unit   limes.Unit          `yaml:"unit"`
	Limit  uint64              `yaml:"limit"`
	Window limesrates.Window   `yaml:"window"`
}

type ResourceBehavior struct {
	FullResourceNameRx       regexpext.BoundedRegexp             `yaml:"resource"`
	ScopeRx                  regexpext.BoundedRegexp             `yaml:"scope"`
	OvercommitFactor         OvercommitFactor                    `yaml:"overcommit_factor"`
	ScalesWith               ResourceRef                         `yaml:"scales_with"`
	ScalingFactor            float64                             `yaml:"scaling_factor"`
	MinNonZeroProjectQuota   uint64                              `yaml:"min_nonzero_project_quota"`
	CommitmentDurations      []limesresources.CommitmentDuration `yaml:"commitment_durations"`
	CommitmentIsAZAware      bool                                `yaml:"commitment_is_az_aware"`
	CommitmentMinConfirmDate *time.Time                          `yaml:"commitment_min_confirm_date"`
	Annotations              map[string]any                      `yaml:"annotations"`
}

type ResourceData struct {
	Quota     int64   // negative values indicate infinite quota
	MinQuota  *uint64 // if set, indicates that SetQuota will reject values below this level
	MaxQuota  *uint64 // if set, indicates that SetQuota will reject values above this level
	UsageData PerAZ[UsageData]
}

type ResourceDemand struct {
	Usage uint64 `yaml:"usage"`
	// UnusedCommitments counts all commitments that are confirmed but not covered by existing usage.
	UnusedCommitments uint64 `yaml:"unused_commitments"`
	// PendingCommitments counts all commitments that should be confirmed by now, but are not.
	PendingCommitments uint64 `yaml:"pending_commitments"`
}

type ResourceRef struct {
	ServiceType  limes.ServiceType
	ResourceName limesresources.ResourceName
}

type ServiceConfiguration struct {
	ServiceType limes.ServiceType `yaml:"service_type"`
	PluginType  string            `yaml:"type"`
	// RateLimits describes the global rate limits (all requests for to a backend) and default project level rate limits.
	RateLimits ServiceRateLimitConfiguration `yaml:"rate_limits"`
	Parameters util.YamlRawMessage           `yaml:"params"`
}

type ServiceRateLimitConfiguration struct {
	Global         []RateLimitConfiguration `yaml:"global"`
	ProjectDefault []RateLimitConfiguration `yaml:"project_default"`
}

type UsageData struct {
	Usage         uint64
	PhysicalUsage *uint64 // only supported by some plugins
	Subresources  []any   // only if supported by plugin and enabled in config
}