liquid

type AZResourceCapacityReport struct {
	Capacity uint64 `json:"capacity"`

	// How much of the Capacity is used, or null if no usage data is available.
	//
	// This should only be reported if the service has an efficient way to obtain this number from the backend.
	// If you can only fill this by summing up usage across all projects, don't; Limes can already do that.
	// This is intended for consistency checks and to estimate how much usage cannot be attributed to OpenStack projects.
	// For example, for compute, this would allow estimating how many VMs are not managed by Nova.
	Usage *uint64 `json:"usage,omitempty"`

	// Only filled if the resource is able to report subcapacities in a useful way.
	Subcapacities []Subcapacity `json:"subcapacities,omitempty"`
}

type AZResourceUsageReport struct {
	// The amount of usage for this resource.
	Usage uint64 `json:"usage"`

	// The amount of physical usage for this resource.
	// Only reported if this notion makes sense for the particular resource.
	//
	// For example, consider the Manila resource "share_capacity".
	// If a project has 5 shares, each with 10 GiB size and each containing 1 GiB data, then Usage = 50 GiB and PhysicalUsage = 5 GiB.
	// It is not allowed to report 5 GiB as Usage in this situation, since the 50 GiB value is used when judging whether the Quota fits.
	PhysicalUsage *uint64 `json:"physicalUsage,omitempty"`

	// Only filled if the resource is able to report subresources for this usage in a useful way.
	Subresources []Subresource `json:"subresources,omitempty"`
}

type AvailabilityZone string

type Metric struct {
	Value float64 `json:"v"`

	// This label set does not include keys to avoid redundant encoding.
	// The slice must be of the same length as the LabelKeys slice in the respective MetricFamilyInfo instance in type ServiceInfo.
	// Each label value is implied to belong to the label key with the same slice index.
	// For example, LabelKeys = ["name","location"] and LabelValues = ["author","work"] represents the label set {name="author",location="work"}.
	LabelValues []string `json:"l"`
}

type MetricFamilyInfo struct {
	// The metric type.
	// The most common values are MetricTypeGauge and MetricTypeCounter.
	Type MetricType `json:"type"`

	// A brief description of the metric family for human consumption.
	// Should be short enough to be used as a tooltip.
	Help string `json:"help"`

	// All labels that will be present on each metric in this family.
	LabelKeys []string `json:"labelKeys"`
}

type MetricName string

type MetricType string

type OvercommitFactor float64

type ResourceCapacityReport struct {
	// For non-AZ-aware resources, the only entry shall be for AvailabilityZoneAny.
	// Use func InAnyAZ to quickly construct a suitable structure.
	//
	// For AZ-aware resources, there shall be an entry for each AZ mentioned in ServiceCapacityRequest.AllAZs.
	// Reports for AZ-aware resources may also include an entry for AvailabilityZoneUnknown as needed.
	PerAZ map[AvailabilityZone]*AZResourceCapacityReport `json:"perAZ"`
}

type ResourceDemand struct {
	// Demand values are provided in terms of effective capacity.
	// This factor can be applied to them in reverse to obtain values in terms of raw capacity.
	OvercommitFactor OvercommitFactor `json:"overcommitFactor,omitempty"`

	// The actual demand values are AZ-aware.
	// For non-AZ-aware resources, the only entry will be for AvailabilityZoneAny.
	PerAZ map[AvailabilityZone]ResourceDemandInAZ `json:"perAZ"`
}

type ResourceDemandInAZ struct {
	// Usage counts all existing usage.
	Usage uint64 `json:"usage"`

	// UnusedCommitments counts all commitments that are confirmed but not covered by existing usage.
	UnusedCommitments uint64 `json:"unusedCommitments"`

	// PendingCommitments counts all commitments that should be confirmed by now, but are not.
	PendingCommitments uint64 `json:"pendingCommitments"`
}

type ResourceInfo struct {
	// If omitted or empty, the resource is "countable" and any quota or usage values describe a number of objects.
	// If non-empty, the resource is "measured" and quota or usage values are measured in the given unit.
	// For example, the compute resource "cores" is countable, but the compute resource "ram" is measured, usually in MiB.
	Unit Unit `json:"unit,omitempty"`

	// Whether the liquid reports capacity for this resource on the cluster level.
	HasCapacity bool `json:"hasCapacity"`

	// Whether Limes needs to include demand statistics for this resource in its requests for a capacity report.
	NeedsResourceDemand bool `json:"needsResourceDemand"`

	// Whether the liquid reports quota for this resource on the project level.
	// If false, only usage is reported on the project level.
	// Limes will abstain from maintaining quota on such resources.
	HasQuota bool `json:"hasQuota"`
}

type ResourceName string

type ResourceQuotaRequest struct {
	Quota uint64 `json:"quota"`
}

type ResourceUsageReport struct {
	// If true, this project is forbidden from accessing this resource.
	// This has two consequences:
	//   - If the resource has quota, Limes will never try to assign quota for this resource to this project.
	//   - If the project has no usage in this resource, Limes will hide this resource from project reports.
	Forbidden bool `json:"forbidden"`

	// This shall be null if and only if the resource is declared with "HasQuota = false".
	// A negative value, usually -1, indicates "infinite quota" (i.e., the absence of a quota).
	Quota *int64 `json:"quota,omitempty"`

	// For non-AZ-aware resources, the only entry shall be for AvailabilityZoneAny.
	// Use func InAnyAZ to quickly construct a suitable structure.
	//
	// For AZ-aware resources, there shall be an entry for each AZ mentioned in ServiceUsageRequest.AllAZs.
	// Reports for AZ-aware resources may also include an entry for AvailabilityZoneUnknown as needed.
	// When starting from a non-AZ-aware usage number that is later broken down with AZ-aware data, use func PrepareForBreakdownInto.
	PerAZ map[AvailabilityZone]*AZResourceUsageReport `json:"perAZ"`
}

type ServiceCapacityReport struct {
	// The same version number that is reported in the Version field of a GET /v1/info response.
	// This is used to signal to Limes to refetch GET /v1/info after configuration changes.
	InfoVersion int64 `json:"infoVersion"`

	// Must contain an entry for each resource that was declared in type ServiceInfo with "HasCapacity = true".
	Resources map[ResourceName]*ResourceCapacityReport `json:"resources"`

	// Must contain an entry for each metric family that was declared for capacity metrics in type ServiceInfo.
	Metrics map[MetricName][]Metric `json:"metrics"`
}

type ServiceCapacityRequest struct {
	// All AZs known to Limes.
	// Many liquids need this information to ensure that:
	//   - AZ-aware capacity is reported for all known AZs, and
	//   - capacity belonging to an invalid AZ is grouped into AvailabilityZoneUnknown.
	// Limes provides this list here to reduce the number of places where this information needs to be maintained manually.
	AllAZs []AvailabilityZone `json:"allAZs"`

	// Must contain an entry for each resource that was declared in type ServiceInfo with "NeedsResourceDemand = true".
	DemandByResource map[ResourceName]ResourceDemand `json:"demandByResource"`
}

type ServiceInfo struct {
	// This version number shall be increased whenever any part of the ServiceInfo changes.
	//
	// The metadata version is also reported on most other API responses.
	// Limes uses this version number to discover when the metadata has changed and needs to be queried again.
	//
	// There is no prescribed semantics to the value of the version number, except that:
	//   - Changes in ServiceInfo must lead to a monotonic increase of the Version.
	//   - If the contents of ServiceInfo do not change, the Version too shall not change.
	//
	// Our recommendation is to use the UNIX timestamp of the most recent change.
	// If you run multiple replicas of the liquid, take care to ensure that they agree on the Version value.
	Version int64 `json:"version"`

	// Info for each resource that this service provides.
	Resources map[ResourceName]ResourceInfo `json:"resources"`

	// Info for each metric family that is included in a response to a query for cluster capacity.
	CapacityMetricFamilies map[MetricName]MetricFamilyInfo `json:"capacityMetricFamilies"`

	// Info for each metric family that is included in a response to a query for project quota and usage.
	UsageMetricFamilies map[MetricName]MetricFamilyInfo `json:"usageMetricFamilies"`
}

type ServiceQuotaRequest struct {
	Resources map[ResourceName]ResourceQuotaRequest `json:"resources"`
}

type ServiceUsageReport struct {
	// The same version number that is reported in the Version field of a GET /v1/info response.
	// This is used to signal to Limes to refetch GET /v1/info after configuration changes.
	InfoVersion int64 `json:"infoVersion"`

	// Must contain an entry for each resource that was declared in type ServiceInfo.
	Resources map[ResourceName]*ResourceUsageReport `json:"resources"`

	// Must contain an entry for each metric family that was declared for usage metrics in type ServiceInfo.
	Metrics map[MetricName][]Metric `json:"metrics"`
}

type ServiceUsageRequest struct {
	// All AZs known to Limes.
	// Many liquids need this information to ensure that:
	//   - AZ-aware usage is reported for all known AZs, and
	//   - usage belonging to an invalid AZ is grouped into AvailabilityZoneUnknown.
	// Limes provides this list here to reduce the number of places where this information needs to be maintained manually.
	AllAZs []AvailabilityZone `json:"allAZs"`
}

type Subcapacity struct {
	// A machine-readable unique identifier for this subcapacity, if there is one.
	ID string `json:"id,omitempty"`

	// A human-readable unique identifier for this subcapacity, if there is one.
	Name string `json:"name,omitempty"`

	// The amount of capacity in this subcapacity.
	Capacity uint64 `json:"capacity"`

	// How much of the Capacity is used, or null if no usage data is available.
	Usage *uint64 `json:"usage,omitempty"`

	// Additional resource-specific attributes.
	// This must be shaped like a map[string]any, but is typed as a raw JSON message.
	// Limes does not touch these attributes and will just pass them on into its users without deserializing it at all.
	Attributes json.RawMessage `json:"attributes,omitempty"`
}

type SubcapacityBuilder[A any] struct {
	ID         string
	Name       string
	Capacity   uint64
	Usage      *uint64
	Attributes A
}

type Subresource struct {
	// A machine-readable unique identifier for this subresource, if there is one.
	ID string `json:"id,omitempty"`

	// A human-readable identifier for this subresource, if there is one.
	// Must be unique at least within its project.
	Name string `json:"name,omitempty"`

	// Must be null for counted resources (for which each subresource must be one of the things that is counted).
	// Must be non-null for measured resources, and contain the subresource's size in terms of the resource's unit.
	Usage *uint64 `json:"usage,omitempty"`

	// Additional resource-specific attributes.
	// This must be shaped like a map[string]any, but is typed as a raw JSON message.
	// Limes does not touch these attributes and will just pass them on into its users without deserializing it at all.
	Attributes json.RawMessage `json:"attributes,omitempty"`
}

type SubresourceBuilder[A any] struct {
	ID         string
	Name       string
	Usage      *uint64
	Attributes A
}

type Unit string