liquid, limes: add support for non-standard units

Until now, only a fixed enumeration of units was supported in Limes.
For example, the units "MiB", "GiB" and "TiB" were supported, but
nothing inbetween those.

Compute raised a demand to us to be able to have resources with more
granular units in order to express RAM quota for flavor groups. Suppose
that there is a flavor group where the smallest flavor is 128 GiB and all
other flavors are an integer multiple of that, quota should only be
given out and commitments only be made in 128 GiB increments. Since,
within LIQUID and Limes, all amounts (quota, usage, capacity,
commitments) are taken to be integer multiples of the resource's defined
unit, it is therefore desirable to declare this resource with a unit of
"128 GiB".

I considered the option of retaining Unit with the basic definition of
`type Unit string`, but found the idea of having to parse a Unit of e.g.
"128 GiB" into a structured value for each operation to be undesirable.
Therefore, Unit had to become a struct (even though that introduces its
own set of pain points like having to manage the zero value).

Because the parsing and serialization logic for Unit values ended up
having significant functional overlap with the existing parsing and
serialization for ValueWithUnit, I created a new base type Amount to
avoid code duplication. Unit now holds just an instance of type Amount,
and provides its own choices for parsing and serialization on top.
ValueWithUnit retains its current structure because of backwards
compatibility requirements, but defers most of its work into Amount.

I had to move all those types (Amount, Unit, ValueWithUnit) into a
single internal package because they need to access API within each
other that I do not want to expose publicly. Specifically,
ValueWithUnit needs to reach the Amount value hidden within type Unit.
Amount is not an exported type and remains an implementation detail.

Unit gained some new interface implementations to cover things that were
previously handled by it being a plain string:

- `encoding/json.Marshaler` for JSON serialization
- `database/sql.Scanner` for SQL deserialization
- `database/sql/driver.Valuer` for SQL serialization

While moving things around, I also took the opportunity to remove
several unused pieces from the public API:

- `UnitUnspecified` has (de facto) been replaced by `Option[Unit]`
- `FractionalValueError` and `IncompatibleUnitsError` are not explicitly
  used by any callers and have been replaced by `fmt.Errorf`

**Testing done:** I have vendored this branch into both limes and
limesctl, and got the tests to pass with only minimal changes:

- Casts of the form `string(unit)` had to be replaced with `unit.String()`.
- Where `Unit` was used as a struct field with `json:",omitempty"`,
  the linter reminded me to make those into `omitzero`.

Author: majewsky

internal/testhelper/testhelper.go

@@ -18,6 +18,25 @@ func AssertNoErr(t *testing.T, err error) {
 	}
 }
 
+func AssertErr(t *testing.T, expected string, actual error) {
+	t.Helper()
+	switch {
+	case actual == nil:
+		t.Errorf("expected error %q, but got no error", expected)
+	case actual.Error() != expected:
+		t.Errorf("expected error: %s", expected)
+		t.Errorf(" but got error: %s", actual.Error())
+	}
+}
+
+func CheckEquals[V comparable](t *testing.T, expected, actual V) {
+	t.Helper()
+	if expected != actual {
+		t.Errorf("expected value: %#v", expected)
+		t.Errorf(" but got value: %#v", actual)
+	}
+}
+
 func CheckDeepEquals(t *testing.T, expected, actual any) {
 	t.Helper()
 	if !reflect.DeepEqual(expected, actual) {

internal/units/amount.go

@@ -0,0 +1,190 @@
+// SPDX-FileCopyrightText: 2017-2026 SAP SE or an SAP affiliate company
+// SPDX-License-Identifier: Apache-2.0
+
+package units
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// Amount describes an amount of a countable or measurable resource in terms of a base unit.
+// This type provides basic serialization and deserialization for unit strings,
+// e.g. between "1 KiB" and Amount{"B", 1024}.
+type Amount struct {
+	Base   BaseUnit
+	Factor uint64
+}
+
+// BaseUnit enumerates relevant base units for units and values that appear in
+// the Limes and LIQUID APIs.
+type BaseUnit string
+
+const (
+	// BaseUnitNone is used for countable (rather than measurable) resources.
+	BaseUnitNone BaseUnit = ""
+	// BaseUnitBytes is used for resources that are measured in bytes or any multiple thereof.
+	BaseUnitBytes BaseUnit = "B"
+)
+
+// Format is a bitfield enumerating permissible formats for describing amounts.
+// It is used by ParseAmount() and FormatAmount() to select which formats to accept/generate.
+type Format int
+
+const (
+	// EmptyFormat allows the empty string (denoting BaseUnitNone).
+	EmptyFormat Format = 1 << iota
+	// NumberOnlyFormat allows bare numbers like "42". Only positive integers are accepted.
+	NumberOnlyFormat
+	// UnitOnlyFormat allows bare units like "B" or "KiB". This does not include BareUnitNone.
+	UnitOnlyFormat
+	// NumberWithUnitFormat allows numbers with units, e.g. "23 MiB" or "1 B". This does not include BareUnitNone.
+	NumberWithUnitFormat
+)
+
+var bareUnitDefs = []struct {
+	Symbol string
+	Amount Amount
+}{
+	// the algorithm in String() relies on this list being sorted in descending order of amount
+	{"EiB", Amount{BaseUnitBytes, 1 << 60}},
+	{"PiB", Amount{BaseUnitBytes, 1 << 50}},
+	{"TiB", Amount{BaseUnitBytes, 1 << 40}},
+	{"GiB", Amount{BaseUnitBytes, 1 << 30}},
+	{"MiB", Amount{BaseUnitBytes, 1 << 20}},
+	{"KiB", Amount{BaseUnitBytes, 1 << 10}},
+	{"B", Amount{BaseUnitBytes, 1}},
+}
+
+// ParseAmount parses a string representation of an amount, in one of the following forms:
+//   - "<amount>", e.g. "42" (for BaseUnitNone)
+//   - "<amount> <unit>", e.g. "23 MiB"
+//   - "<unit>", e.g. "KiB" (only with allowBareUnit = true)
+func ParseAmount(input string, formats Format) (Amount, error) {
+	acceptEmpty := (formats & EmptyFormat) == EmptyFormat
+	acceptNumberOnly := (formats & NumberOnlyFormat) == NumberOnlyFormat
+	acceptUnitOnly := (formats & UnitOnlyFormat) == UnitOnlyFormat
+	acceptNumberWithUnit := (formats & NumberWithUnitFormat) == NumberWithUnitFormat
+
+	fields := strings.Fields(input)
+	switch len(fields) {
+	case 0:
+		if acceptEmpty {
+			return Amount{BaseUnitNone, 1}, nil
+		}
+
+	case 1:
+		if acceptUnitOnly {
+			for _, def := range bareUnitDefs {
+				if def.Symbol == fields[0] {
+					return def.Amount, nil
+				}
+			}
+			if !acceptNumberOnly {
+				return Amount{}, fmt.Errorf("invalid value %q: not a known unit name", input)
+			}
+		}
+
+		if acceptNumberOnly {
+			number, err := strconv.ParseUint(fields[0], 10, 64)
+			if err != nil {
+				if acceptUnitOnly {
+					return Amount{}, fmt.Errorf("invalid value %q: not a known unit name, and parsing as number failed with: %w", input, err)
+				} else {
+					return Amount{}, fmt.Errorf("invalid value %q: %w", input, err)
+				}
+			}
+			return Amount{BaseUnitNone, number}, nil
+		}
+
+	case 2:
+		if acceptNumberWithUnit {
+			number, err := strconv.ParseUint(fields[0], 10, 64)
+			if err != nil {
+				return Amount{}, fmt.Errorf("invalid value %q: %w", input, err)
+			}
+			for _, def := range bareUnitDefs {
+				if def.Symbol == fields[1] {
+					return def.Amount.MultiplyBy(number)
+				}
+			}
+			return Amount{}, fmt.Errorf("invalid value %q: no such unit", input)
+		}
+	}
+
+	formatsDisplay := make([]string, 0, 4)
+	if acceptEmpty {
+		formatsDisplay = append(formatsDisplay, `""`)
+	}
+	if acceptNumberOnly {
+		formatsDisplay = append(formatsDisplay, `"<number>"`)
+	}
+	if acceptUnitOnly {
+		formatsDisplay = append(formatsDisplay, `"<unit>"`)
+	}
+	if acceptNumberWithUnit {
+		formatsDisplay = append(formatsDisplay, `"<number> <unit>"`)
+	}
+	if len(formatsDisplay) == 1 {
+		return Amount{}, fmt.Errorf(`value %q does not match expected format (%s)`, input, formatsDisplay[0])
+	} else {
+		return Amount{}, fmt.Errorf(`value %q does not match any expected format (%s)`, input, strings.Join(formatsDisplay, " or "))
+	}
+}
+
+// MultiplyBy multiplies this amount by the given factor.
+//
+// Returns an error on integer overflow, e.g. when a bytes-based unit is larger than 2^64 bytes (16 EiB).
+func (a Amount) MultiplyBy(factor uint64) (Amount, error) {
+	if factor == 0 {
+		return Amount{Base: a.Base, Factor: 0}, nil
+	}
+	product := a.Factor * factor
+	if product/factor != a.Factor {
+		return Amount{}, fmt.Errorf("overflow while multiplying %s x %d", a.Format(NumberOnlyFormat|NumberWithUnitFormat), factor)
+	}
+	return Amount{Base: a.Base, Factor: product}, nil
+}
+
+// Format serializes this Amount into a string representation.
+// Out of the given formats, the shortest possible format will be used.
+// Panics if none of the allowed formats can represent this Amount.
+func (a Amount) Format(formats Format) string {
+	// for measured units, find the best unit to display them in without loss of precision
+	// e.g. Amount{BaseUnitBytes, 524288} -> "512 KiB" (not "0.5 MiB" because amounts do not support fractional numbers)
+	//
+	// NOTE: This relies on `bareUnitDefs` being sorted such that the first match is always the best.
+	unitSymbol, number := string(a.Base), a.Factor
+	for _, def := range bareUnitDefs {
+		if def.Amount.Base == a.Base && a.Factor%def.Amount.Factor == 0 {
+			unitSymbol, number = def.Symbol, a.Factor/def.Amount.Factor
+			break
+		}
+	}
+
+	// generate the most compact format that the caller allows
+	if (formats & EmptyFormat) == EmptyFormat {
+		if number == 1 && unitSymbol == "" {
+			return ""
+		}
+	}
+	if (formats & NumberOnlyFormat) == NumberOnlyFormat {
+		if unitSymbol == "" {
+			return strconv.FormatUint(number, 10)
+		}
+	}
+	if (formats & UnitOnlyFormat) == UnitOnlyFormat {
+		if number == 1 {
+			return unitSymbol
+		}
+	}
+	if (formats & NumberWithUnitFormat) == NumberWithUnitFormat {
+		if unitSymbol != "" {
+			return strconv.FormatUint(number, 10) + " " + unitSymbol
+		}
+	}
+
+	// caller has not allowed us to use any format that could display this amount
+	panic(fmt.Sprintf("cannot display %#v with formats = 0x%x", a, formats))
+}

internal/units/limesv1.go

@@ -0,0 +1,106 @@
+// SPDX-FileCopyrightText: 2017-2026 SAP SE or an SAP affiliate company
+// SPDX-License-Identifier: Apache-2.0
+
+package units
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// ParseInUnit parses the string representation of a value with this unit
+// (or any unit that can be converted to it).
+//
+//	ParseInUnit(UnitMebibytes, "10 MiB") -> 10
+//	ParseInUnit(UnitMebibytes, "10 GiB") -> 10240
+//	ParseInUnit(UnitMebibytes, "10 KiB") -> error: incompatible unit
+//	ParseInUnit(UnitMebibytes, "10")     -> error: missing unit
+//	ParseInUnit(UnitNone, "42")          -> 42
+//	ParseInUnit(UnitNone, "42 MiB")      -> error: unexpected unit
+func ParseInUnit(u Unit, str string) (uint64, error) {
+	amount, err := ParseAmount(str, NumberOnlyFormat|NumberWithUnitFormat)
+	if err != nil {
+		return 0, err
+	}
+	value := LimesV1ValueWithUnit{
+		Value: amount.Factor,
+		Unit:  Unit{Amount{Base: amount.Base, Factor: 1}},
+	}
+	converted, err := value.ConvertTo(u)
+	return converted.Value, err
+}
+
+// LimesV1ValueWithUnit is used to represent values with units in subresources.
+// As the name implies, this type is only exposed in the Limes v1 API.
+type LimesV1ValueWithUnit struct {
+	Value uint64 `json:"value"`
+	Unit  Unit   `json:"unit"`
+}
+
+// String implements the fmt.Stringer interface.
+// The value is serialized with the most appropriate unit:
+//
+//	// prints: 1000000 MiB
+//	fmt.Println(LimesV1ValueWithUnit{1000000,UnitMebibytes})
+//	// prints: 1 TiB
+//	fmt.Println(LimesV1ValueWithUnit{1048576,UnitMebibytes})
+func (v LimesV1ValueWithUnit) String() string {
+	amount, err := v.Unit.amount.MultiplyBy(v.Value)
+	if err == nil {
+		return amount.Format(NumberOnlyFormat | NumberWithUnitFormat)
+	}
+
+	// fallback: if converting to the base unit would overflow, print without conversion
+	valueStr := strconv.FormatUint(v.Value, 10)
+	if v.Unit == UnitNone {
+		// defense in depth: not reachable in practice because LimesV1ValueWithUnit with
+		// UnitNone would not be able to overflow MultiplyBy() above
+		return valueStr
+	} else {
+		unitStr := v.Unit.amount.Format(UnitOnlyFormat | NumberWithUnitFormat)
+		if strings.Contains(unitStr, " ") { // unit has a numeric multiplier by itself, e.g. "4 MiB"
+			return valueStr + " x " + unitStr // e.g. "20 x 4 MiB"
+		} else {
+			return valueStr + " " + unitStr // e.g. "20 MiB"
+		}
+	}
+}
+
+// ConvertTo returns an equal value in the given Unit. An error is returned if:
+//   - the source unit cannot be converted to the target unit, or
+//   - the conversion does not yield an integer value in the new unit.
+func (v LimesV1ValueWithUnit) ConvertTo(u Unit) (LimesV1ValueWithUnit, error) {
+	if v.Unit == u {
+		return v, nil
+	}
+
+	base, sourceMultiple := v.Unit.Base()
+	base2, targetMultiple := u.Base()
+	if base != base2 {
+		return LimesV1ValueWithUnit{}, fmt.Errorf(
+			"cannot convert value %q to %s because units are incompatible",
+			v.String(), toStringForError(u),
+		)
+	}
+
+	valueInBase := v.Value * sourceMultiple
+	if valueInBase%targetMultiple != 0 {
+		return LimesV1ValueWithUnit{}, fmt.Errorf(
+			"value %q cannot be represented as integer number of %s",
+			v.String(), toStringForError(u),
+		)
+	}
+
+	return LimesV1ValueWithUnit{
+		Value: valueInBase / targetMultiple,
+		Unit:  u,
+	}, nil
+}
+
+func toStringForError(u Unit) string {
+	if u == UnitNone {
+		return "<count>"
+	}
+	return u.String()
+}

internal/units/limesv1_test.go

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2017-2026 SAP SE or an SAP affiliate company
+// SPDX-License-Identifier: Apache-2.0
+
+package units
+
+import (
+	"testing"
+
+	th "github.com/sapcc/go-api-declarations/internal/testhelper"
+)
+
+func TestParseInUnit(t *testing.T) {
+	// This executes all the examples from the docstring of func ParseInUnit().
+	// Since ParseInUnit() calls ConvertTo(), this also provides coverage for ConvertTo().
+
+	value, err := ParseInUnit(UnitMebibytes, "10 MiB")
+	th.AssertNoErr(t, err)
+	th.CheckEquals(t, 10, value)
+
+	value, err = ParseInUnit(UnitMebibytes, "10 GiB")
+	th.AssertNoErr(t, err)
+	th.CheckEquals(t, 10240, value)
+
+	_, err = ParseInUnit(UnitMebibytes, "10 KiB")
+	th.AssertErr(t, `value "10 KiB" cannot be represented as integer number of MiB`, err)
+
+	_, err = ParseInUnit(UnitMebibytes, "10")
+	th.AssertErr(t, `cannot convert value "10" to MiB because units are incompatible`, err)
+
+	value, err = ParseInUnit(UnitNone, "42")
+	th.AssertNoErr(t, err)
+	th.CheckEquals(t, 42, value)
+
+	_, err = ParseInUnit(UnitNone, "42 MiB")
+	th.AssertErr(t, `cannot convert value "42 MiB" to <count> because units are incompatible`, err)
+}
+
+func TestValueWithUnitToString(t *testing.T) {
+	// check behavior LimesV1ValueWithUnit.String() esp. with non-standard units and integer overflows
+
+	v := LimesV1ValueWithUnit{
+		Value: 128,
+		Unit:  UnitKibibytes,
+	}
+	th.CheckEquals(t, "128 KiB", v.String())
+
+	v = LimesV1ValueWithUnit{
+		Value: 128,
+		Unit:  mustMultiply(UnitKibibytes, 32),
+	}
+	th.CheckEquals(t, "4 MiB", v.String()) // uses nice formatting, i.e. neither "128 x 32 KiB" nor "4096 KiB"
+
+	v = LimesV1ValueWithUnit{
+		// this value is equal to 2^75 bytes and overflows type Amount
+		Value: 32768,
+		Unit:  UnitExbibytes,
+	}
+	th.CheckEquals(t, "32768 EiB", v.String()) // printed via fallback logic
+
+	v = LimesV1ValueWithUnit{
+		// same value, but this time the fallback printing logic is more obvious
+		Value: 16384,
+		Unit:  mustMultiply(UnitExbibytes, 2),
+	}
+	th.CheckEquals(t, "16384 x 2 EiB", v.String())
+}