Modernize invertergui: MQTT write support, HA integration, UI updates

vendor/github.com/prometheus/common/model/metric.go

@@ -14,30 +14,49 @@
 package model
 
 import (
+	"encoding/json"
+	"errors"
 	"fmt"
 	"regexp"
 	"sort"
+	"strconv"
 	"strings"
 	"unicode/utf8"
 
 	dto "github.com/prometheus/client_model/go"
+	"go.yaml.in/yaml/v2"
 	"google.golang.org/protobuf/proto"
 )
 
 var (
-	// NameValidationScheme determines the method of name validation to be used by
-	// all calls to IsValidMetricName() and LabelName IsValid(). Setting UTF-8 mode
-	// in isolation from other components that don't support UTF-8 may result in
-	// bugs or other undefined behavior. This value is intended to be set by
-	// UTF-8-aware binaries as part of their startup. To avoid need for locking,
-	// this value should be set once, ideally in an init(), before multiple
-	// goroutines are started.
-	NameValidationScheme = LegacyValidation
+	// NameValidationScheme determines the global default method of the name
+	// validation to be used by all calls to IsValidMetricName() and LabelName
+	// IsValid().
+	//
+	// Deprecated: This variable should not be used and might be removed in the
+	// far future. If you wish to stick to the legacy name validation use
+	// `IsValidLegacyMetricName()` and `LabelName.IsValidLegacy()` methods
+	// instead. This variable is here as an escape hatch for emergency cases,
+	// given the recent change from `LegacyValidation` to `UTF8Validation`, e.g.,
+	// to delay UTF-8 migrations in time or aid in debugging unforeseen results of
+	// the change. In such a case, a temporary assignment to `LegacyValidation`
+	// value in the `init()` function in your main.go or so, could be considered.
+	//
+	// Historically we opted for a global variable for feature gating different
+	// validation schemes in operations that were not otherwise easily adjustable
+	// (e.g. Labels yaml unmarshaling). That could have been a mistake, a separate
+	// Labels structure or package might have been a better choice. Given the
+	// change was made and many upgraded the common already, we live this as-is
+	// with this warning and learning for the future.
+	NameValidationScheme = UTF8Validation
 
-	// NameEscapingScheme defines the default way that names will be
-	// escaped when presented to systems that do not support UTF-8 names. If the
-	// Content-Type "escaping" term is specified, that will override this value.
-	NameEscapingScheme = ValueEncodingEscaping
+	// NameEscapingScheme defines the default way that names will be escaped when
+	// presented to systems that do not support UTF-8 names. If the Content-Type
+	// "escaping" term is specified, that will override this value.
+	// NameEscapingScheme should not be set to the NoEscaping value. That string
+	// is used in content negotiation to indicate that a system supports UTF-8 and
+	// has that feature enabled.
+	NameEscapingScheme = UnderscoreEscaping
 )
 
 // ValidationScheme is a Go enum for determining how metric and label names will
@@ -45,16 +64,151 @@ var (
 type ValidationScheme int
 
 const (
-	// LegacyValidation is a setting that requirets that metric and label names
+	// UnsetValidation represents an undefined ValidationScheme.
+	// Should not be used in practice.
+	UnsetValidation ValidationScheme = iota
+
+	// LegacyValidation is a setting that requires that all metric and label names
 	// conform to the original Prometheus character requirements described by
 	// MetricNameRE and LabelNameRE.
-	LegacyValidation ValidationScheme = iota
+	LegacyValidation
 
 	// UTF8Validation only requires that metric and label names be valid UTF-8
 	// strings.
 	UTF8Validation
 )
 
+var _ interface {
+	yaml.Marshaler
+	yaml.Unmarshaler
+	json.Marshaler
+	json.Unmarshaler
+	fmt.Stringer
+} = new(ValidationScheme)
+
+// String returns the string representation of s.
+func (s ValidationScheme) String() string {
+	switch s {
+	case UnsetValidation:
+		return "unset"
+	case LegacyValidation:
+		return "legacy"
+	case UTF8Validation:
+		return "utf8"
+	default:
+		panic(fmt.Errorf("unhandled ValidationScheme: %d", s))
+	}
+}
+
+// MarshalYAML implements the yaml.Marshaler interface.
+func (s ValidationScheme) MarshalYAML() (any, error) {
+	switch s {
+	case UnsetValidation:
+		return "", nil
+	case LegacyValidation, UTF8Validation:
+		return s.String(), nil
+	default:
+		panic(fmt.Errorf("unhandled ValidationScheme: %d", s))
+	}
+}
+
+// UnmarshalYAML implements the yaml.Unmarshaler interface.
+func (s *ValidationScheme) UnmarshalYAML(unmarshal func(any) error) error {
+	var scheme string
+	if err := unmarshal(&scheme); err != nil {
+		return err
+	}
+	return s.Set(scheme)
+}
+
+// MarshalJSON implements the json.Marshaler interface.
+func (s ValidationScheme) MarshalJSON() ([]byte, error) {
+	switch s {
+	case UnsetValidation:
+		return json.Marshal("")
+	case UTF8Validation, LegacyValidation:
+		return json.Marshal(s.String())
+	default:
+		return nil, fmt.Errorf("unhandled ValidationScheme: %d", s)
+	}
+}
+
+// UnmarshalJSON implements the json.Unmarshaler interface.
+func (s *ValidationScheme) UnmarshalJSON(bytes []byte) error {
+	var repr string
+	if err := json.Unmarshal(bytes, &repr); err != nil {
+		return err
+	}
+	return s.Set(repr)
+}
+
+// Set implements the pflag.Value interface.
+func (s *ValidationScheme) Set(text string) error {
+	switch text {
+	case "":
+		// Don't change the value.
+	case LegacyValidation.String():
+		*s = LegacyValidation
+	case UTF8Validation.String():
+		*s = UTF8Validation
+	default:
+		return fmt.Errorf("unrecognized ValidationScheme: %q", text)
+	}
+	return nil
+}
+
+// IsValidMetricName returns whether metricName is valid according to s.
+func (s ValidationScheme) IsValidMetricName(metricName string) bool {
+	switch s {
+	case LegacyValidation:
+		if len(metricName) == 0 {
+			return false
+		}
+		for i, b := range metricName {
+			if !isValidLegacyRune(b, i) {
+				return false
+			}
+		}
+		return true
+	case UTF8Validation:
+		if len(metricName) == 0 {
+			return false
+		}
+		return utf8.ValidString(metricName)
+	default:
+		panic(fmt.Sprintf("Invalid name validation scheme requested: %s", s.String()))
+	}
+}
+
+// IsValidLabelName returns whether labelName is valid according to s.
+func (s ValidationScheme) IsValidLabelName(labelName string) bool {
+	switch s {
+	case LegacyValidation:
+		if len(labelName) == 0 {
+			return false
+		}
+		for i, b := range labelName {
+			// TODO: Apply De Morgan's law. Make sure there are tests for this.
+			if !((b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z') || b == '_' || (b >= '0' && b <= '9' && i > 0)) { //nolint:staticcheck
+				return false
+			}
+		}
+		return true
+	case UTF8Validation:
+		if len(labelName) == 0 {
+			return false
+		}
+		return utf8.ValidString(labelName)
+	default:
+		panic(fmt.Sprintf("Invalid name validation scheme requested: %s", s))
+	}
+}
+
+// Type implements the pflag.Value interface.
+func (ValidationScheme) Type() string {
+	return "validationScheme"
+}
+
 type EscapingScheme int
 
 const (
@@ -84,7 +238,7 @@ const (
 	// Accept header, the default NameEscapingScheme will be used.
 	EscapingKey = "escaping"
 
-	// Possible values for Escaping Key:
+	// Possible values for Escaping Key.
 	AllowUTF8         = "allow-utf-8" // No escaping required.
 	EscapeUnderscores = "underscores"
 	EscapeDots        = "dots"
@@ -158,34 +312,22 @@ func (m Metric) FastFingerprint() Fingerprint {
 // IsValidMetricName returns true iff name matches the pattern of MetricNameRE
 // for legacy names, and iff it's valid UTF-8 if the UTF8Validation scheme is
 // selected.
+//
+// Deprecated: This function should not be used and might be removed in the future.
+// Use [ValidationScheme.IsValidMetricName] instead.
 func IsValidMetricName(n LabelValue) bool {
-	switch NameValidationScheme {
-	case LegacyValidation:
-		return IsValidLegacyMetricName(n)
-	case UTF8Validation:
-		if len(n) == 0 {
-			return false
-		}
-		return utf8.ValidString(string(n))
-	default:
-		panic(fmt.Sprintf("Invalid name validation scheme requested: %d", NameValidationScheme))
-	}
+	return NameValidationScheme.IsValidMetricName(string(n))
 }
 
 // IsValidLegacyMetricName is similar to IsValidMetricName but always uses the
 // legacy validation scheme regardless of the value of NameValidationScheme.
 // This function, however, does not use MetricNameRE for the check but a much
 // faster hardcoded implementation.
-func IsValidLegacyMetricName(n LabelValue) bool {
-	if len(n) == 0 {
-		return false
-	}
-	for i, b := range n {
-		if !isValidLegacyRune(b, i) {
-			return false
-		}
-	}
-	return true
+//
+// Deprecated: This function should not be used and might be removed in the future.
+// Use [LegacyValidation.IsValidMetricName] instead.
+func IsValidLegacyMetricName(n string) bool {
+	return LegacyValidation.IsValidMetricName(n)
 }
 
 // EscapeMetricFamily escapes the given metric names and labels with the given
@@ -208,7 +350,7 @@ func EscapeMetricFamily(v *dto.MetricFamily, scheme EscapingScheme) *dto.MetricF
 	}
 
 	// If the name is nil, copy as-is, don't try to escape.
-	if v.Name == nil || IsValidLegacyMetricName(LabelValue(v.GetName())) {
+	if v.Name == nil || IsValidLegacyMetricName(v.GetName()) {
 		out.Name = v.Name
 	} else {
 		out.Name = proto.String(EscapeName(v.GetName(), scheme))
@@ -230,7 +372,7 @@ func EscapeMetricFamily(v *dto.MetricFamily, scheme EscapingScheme) *dto.MetricF
 
 		for _, l := range m.Label {
 			if l.GetName() == MetricNameLabel {
-				if l.Value == nil || IsValidLegacyMetricName(LabelValue(l.GetValue())) {
+				if l.Value == nil || IsValidLegacyMetricName(l.GetValue()) {
 					escaped.Label = append(escaped.Label, l)
 					continue
 				}
@@ -240,7 +382,7 @@ func EscapeMetricFamily(v *dto.MetricFamily, scheme EscapingScheme) *dto.MetricF
 				})
 				continue
 			}
-			if l.Name == nil || IsValidLegacyMetricName(LabelValue(l.GetName())) {
+			if l.Name == nil || IsValidLegacyMetricName(l.GetName()) {
 				escaped.Label = append(escaped.Label, l)
 				continue
 			}
@@ -256,20 +398,16 @@ func EscapeMetricFamily(v *dto.MetricFamily, scheme EscapingScheme) *dto.MetricF
 
 func metricNeedsEscaping(m *dto.Metric) bool {
 	for _, l := range m.Label {
-		if l.GetName() == MetricNameLabel && !IsValidLegacyMetricName(LabelValue(l.GetValue())) {
+		if l.GetName() == MetricNameLabel && !IsValidLegacyMetricName(l.GetValue()) {
 			return true
 		}
-		if !IsValidLegacyMetricName(LabelValue(l.GetName())) {
+		if !IsValidLegacyMetricName(l.GetName()) {
 			return true
 		}
 	}
 	return false
 }
 
-const (
-	lowerhex = "0123456789abcdef"
-)
-
 // EscapeName escapes the incoming name according to the provided escaping
 // scheme. Depending on the rules of escaping, this may cause no change in the
 // string that is returned. (Especially NoEscaping, which by definition is a
@@ -283,7 +421,7 @@ func EscapeName(name string, scheme EscapingScheme) string {
 	case NoEscaping:
 		return name
 	case UnderscoreEscaping:
-		if IsValidLegacyMetricName(LabelValue(name)) {
+		if IsValidLegacyMetricName(name) {
 			return name
 		}
 		for i, b := range name {
@@ -297,38 +435,34 @@ func EscapeName(name string, scheme EscapingScheme) string {
 	case DotsEscaping:
 		// Do not early return for legacy valid names, we still escape underscores.
 		for i, b := range name {
-			if b == '_' {
+			switch {
+			case b == '_':
 				escaped.WriteString("__")
-			} else if b == '.' {
+			case b == '.':
 				escaped.WriteString("_dot_")
-			} else if isValidLegacyRune(b, i) {
+			case isValidLegacyRune(b, i):
 				escaped.WriteRune(b)
-			} else {
-				escaped.WriteRune('_')
+			default:
+				escaped.WriteString("__")
 			}
 		}
 		return escaped.String()
 	case ValueEncodingEscaping:
-		if IsValidLegacyMetricName(LabelValue(name)) {
+		if IsValidLegacyMetricName(name) {
 			return name
 		}
 		escaped.WriteString("U__")
 		for i, b := range name {
-			if isValidLegacyRune(b, i) {
+			switch {
+			case b == '_':
+				escaped.WriteString("__")
+			case isValidLegacyRune(b, i):
 				escaped.WriteRune(b)
-			} else if !utf8.ValidRune(b) {
+			case !utf8.ValidRune(b):
 				escaped.WriteString("_FFFD_")
-			} else if b < 0x100 {
+			default:
 				escaped.WriteRune('_')
-				for s := 4; s >= 0; s -= 4 {
-					escaped.WriteByte(lowerhex[b>>uint(s)&0xF])
-				}
-				escaped.WriteRune('_')
-			} else if b < 0x10000 {
-				escaped.WriteRune('_')
-				for s := 12; s >= 0; s -= 4 {
-					escaped.WriteByte(lowerhex[b>>uint(s)&0xF])
-				}
+				escaped.WriteString(strconv.FormatInt(int64(b), 16))
 				escaped.WriteRune('_')
 			}
 		}
@@ -338,7 +472,7 @@ func EscapeName(name string, scheme EscapingScheme) string {
 	}
 }
 
-// lower function taken from strconv.atoi
+// lower function taken from strconv.atoi.
 func lower(c byte) byte {
 	return c | ('x' - 'X')
 }
@@ -386,8 +520,9 @@ func UnescapeName(name string, scheme EscapingScheme) string {
 			// We think we are in a UTF-8 code, process it.
 			var utf8Val uint
 			for j := 0; i < len(escapedName); j++ {
-				// This is too many characters for a utf8 value.
-				if j > 4 {
+				// This is too many characters for a utf8 value based on the MaxRune
+				// value of '\U0010FFFF'.
+				if j >= 6 {
 					return name
 				}
 				// Found a closing underscore, convert to a rune, check validity, and append.
@@ -401,11 +536,12 @@ func UnescapeName(name string, scheme EscapingScheme) string {
 				}
 				r := lower(escapedName[i])
 				utf8Val *= 16
-				if r >= '0' && r <= '9' {
+				switch {
+				case r >= '0' && r <= '9':
 					utf8Val += uint(r) - '0'
-				} else if r >= 'a' && r <= 'f' {
+				case r >= 'a' && r <= 'f':
 					utf8Val += uint(r) - 'a' + 10
-				} else {
+				default:
 					return name
 				}
 				i++
@@ -440,7 +576,7 @@ func (e EscapingScheme) String() string {
 
 func ToEscapingScheme(s string) (EscapingScheme, error) {
 	if s == "" {
-		return NoEscaping, fmt.Errorf("got empty string instead of escaping scheme")
+		return NoEscaping, errors.New("got empty string instead of escaping scheme")
 	}
 	switch s {
 	case AllowUTF8:
@@ -452,6 +588,6 @@ func ToEscapingScheme(s string) (EscapingScheme, error) {
 	case EscapeValues:
 		return ValueEncodingEscaping, nil
 	default:
-		return NoEscaping, fmt.Errorf("unknown format scheme " + s)
+		return NoEscaping, fmt.Errorf("unknown format scheme %s", s)
 	}
 }