Add build tag to build without deprecated global name validation scheme

.circleci/config.yml

@@ -12,6 +12,9 @@ jobs:
       use_gomod_cache:
         type: boolean
         default: true
+      build_tags:
+        type: string
+        default: ""
     docker:
       - image: cimg/go:<< parameters.go_version >>
     environment:
@@ -24,7 +27,12 @@ jobs:
           steps:
             - go/load-cache:
                 key: v1-go<< parameters.go_version >>
-      - run: make test
+      - run: |
+          if [ -n "<< parameters.build_tags >>" ]; then
+            make test GOOPTS="-tags=<< parameters.build_tags >>"
+          else
+            make test
+          fi
       - when:
           condition: << parameters.use_gomod_cache >>
           steps:
@@ -89,12 +97,15 @@ workflows:
     jobs:
       # Supported Go versions are synced with github.com/prometheus/client_golang.
       - test:
-          name: go-<< matrix.go_version >>
+          name: go-<< matrix.go_version >><<# matrix.build_tags >>-<< matrix.build_tags >><</matrix.build_tags >>
           matrix:
             parameters:
               go_version:
                 - "1.23"
                 - "1.24"
+              build_tags:
+                - ""
+                - "localvalidationscheme"
       - test-assets:
           name: assets-go-<< matrix.go_version >>
           matrix:

README.md

@@ -15,3 +15,17 @@ any stability guarantees for external usage.
 * **route**: A routing wrapper around [httprouter](https://github.com/julienschmidt/httprouter) using `context.Context`
 * **server**: Common servers
 * **version**: Version information and metrics
+
+## Metric/label name validation scheme
+
+The libraries in this Go module share a notion of metric and label name validation scheme.
+There are two different schemes to choose from:
+* `model.LegacyValidation` => Metric and label names have to conform to the original Prometheus character requirements
+* `model.UTF8Validation` => Metric and label names are only required to be valid UTF-8 strings
+
+The active name validation scheme is normally implicitly controlled via the global variable `model.NameValidationScheme`.
+It's used by functions such as `model.IsValidMetricName` and `model.LabelName.IsValid`.
+_However_, if building with the _experimental_ build tag `localvalidationscheme`, the `model.NameValidationScheme` global is removed, and the API changes to accept the name validation scheme as an explicit parameter.
+`model.NameValidationScheme` is deprecated, and at some point, the API currently controlled by the build tag `localvalidationscheme` becomes standard.
+All users of this library will be expected to move to the new API, and there will be an announcement in the changelog when the global is removed.
+For the time being, the `localvalidationscheme` build tag is experimental and the API enabled by it may change.

expfmt/decode.go

@@ -14,7 +14,6 @@
 package expfmt
 
 import (
-	"bufio"
 	"fmt"
 	"io"
 	"math"
@@ -70,21 +69,6 @@ func ResponseFormat(h http.Header) Format {
 	return FmtUnknown
 }
 
-// NewDecoder returns a new decoder based on the given input format.
-// If the input format does not imply otherwise, a text format decoder is returned.
-func NewDecoder(r io.Reader, format Format) Decoder {
-	switch format.FormatType() {
-	case TypeProtoDelim:
-		return &protoDecoder{r: bufio.NewReader(r)}
-	}
-	return &textDecoder{r: r}
-}
-
-// protoDecoder implements the Decoder interface for protocol buffers.
-type protoDecoder struct {
-	r protodelim.Reader
-}
-
 // Decode implements the Decoder interface.
 func (d *protoDecoder) Decode(v *dto.MetricFamily) error {
 	opts := protodelim.UnmarshalOptions{
@@ -93,7 +77,7 @@ func (d *protoDecoder) Decode(v *dto.MetricFamily) error {
 	if err := opts.UnmarshalFrom(d.r, v); err != nil {
 		return err
 	}
-	if !model.IsValidMetricName(model.LabelValue(v.GetName())) {
+	if !d.isValidMetricName(v.GetName()) {
 		return fmt.Errorf("invalid metric name %q", v.GetName())
 	}
 	for _, m := range v.GetMetric() {
@@ -107,7 +91,7 @@ func (d *protoDecoder) Decode(v *dto.MetricFamily) error {
 			if !model.LabelValue(l.GetValue()).IsValid() {
 				return fmt.Errorf("invalid label value %q", l.GetValue())
 			}
-			if !model.LabelName(l.GetName()).IsValid() {
+			if !d.isValidLabelName(l.GetName()) {
 				return fmt.Errorf("invalid label name %q", l.GetName())
 			}
 		}

expfmt/decode_globalvalidationscheme.go

@@ -0,0 +1,48 @@
+// Copyright 2025 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build !localvalidationscheme
+
+package expfmt
+
+import (
+	"bufio"
+	"io"
+
+	"google.golang.org/protobuf/encoding/protodelim"
+
+	"github.com/prometheus/common/model"
+)
+
+// protoDecoder implements the Decoder interface for protocol buffers.
+type protoDecoder struct {
+	r protodelim.Reader
+}
+
+// NewDecoder returns a new decoder based on the given input format.
+// If the input format does not imply otherwise, a text format decoder is returned.
+func NewDecoder(r io.Reader, format Format) Decoder {
+	switch format.FormatType() {
+	case TypeProtoDelim:
+		return &protoDecoder{r: bufio.NewReader(r)}
+	}
+	return &textDecoder{r: r}
+}
+
+func (d *protoDecoder) isValidMetricName(name string) bool {
+	return model.IsValidMetricName(model.LabelValue(name))
+}
+
+func (d *protoDecoder) isValidLabelName(name string) bool {
+	return model.LabelName(name).IsValid()
+}

expfmt/decode_globalvalidationscheme_test.go

@@ -0,0 +1,36 @@
+// Copyright 2025 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build !localvalidationscheme
+
+package expfmt
+
+import (
+	"io"
+	"testing"
+
+	"github.com/prometheus/common/model"
+)
+
+func newDecoder(t *testing.T, r io.Reader, format Format, scheme model.ValidationScheme) Decoder {
+	//nolint:staticcheck // NameValidationScheme is being phased out.
+	origScheme := model.NameValidationScheme
+	t.Cleanup(func() {
+		//nolint:staticcheck // NameValidationScheme is being phased out.
+		model.NameValidationScheme = origScheme
+	})
+	//nolint:staticcheck // NameValidationScheme is being phased out.
+	model.NameValidationScheme = scheme
+
+	return NewDecoder(r, format)
+}

expfmt/decode_localvalidationscheme.go

@@ -0,0 +1,52 @@
+// Copyright 2025 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build localvalidationscheme
+
+package expfmt
+
+import (
+	"bufio"
+	"io"
+
+	"google.golang.org/protobuf/encoding/protodelim"
+
+	"github.com/prometheus/common/model"
+)
+
+// protoDecoder implements the Decoder interface for protocol buffers.
+type protoDecoder struct {
+	r                protodelim.Reader
+	validationScheme model.ValidationScheme
+}
+
+// NewDecoder returns a new decoder based on the given input format.
+// If the input format does not imply otherwise, a text format decoder is returned.
+func NewDecoder(r io.Reader, format Format, validationScheme model.ValidationScheme) Decoder {
+	switch format.FormatType() {
+	case TypeProtoDelim:
+		return &protoDecoder{
+			r:                bufio.NewReader(r),
+			validationScheme: validationScheme,
+		}
+	}
+	return &textDecoder{r: r}
+}
+
+func (d *protoDecoder) isValidMetricName(name string) bool {
+	return model.IsValidMetricName(model.LabelValue(name), d.validationScheme)
+}
+
+func (d *protoDecoder) isValidLabelName(name string) bool {
+	return model.LabelName(name).IsValid(d.validationScheme)
+}

expfmt/decode_localvalidationscheme_test.go

@@ -0,0 +1,27 @@
+// Copyright 2025 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build localvalidationscheme
+
+package expfmt
+
+import (
+	"io"
+	"testing"
+
+	"github.com/prometheus/common/model"
+)
+
+func newDecoder(_ *testing.T, r io.Reader, format Format, scheme model.ValidationScheme) Decoder {
+	return NewDecoder(r, format, scheme)
+}

expfmt/decode_test.go

@@ -23,6 +23,7 @@ import (
 	"os"
 	"reflect"
 	"sort"
+	"strconv"
 	"strings"
 	"testing"
 
@@ -360,46 +361,46 @@ func TestProtoDecoder(t *testing.T) {
 	}
 
 	for i, scenario := range scenarios {
-		dec := &SampleDecoder{
-			Dec: &protoDecoder{r: strings.NewReader(scenario.in)},
-			Opts: &DecodeOptions{
-				Timestamp: testTime,
-			},
-		}
-
-		var all model.Vector
-		for {
-			model.NameValidationScheme = model.LegacyValidation //nolint:staticcheck
-			var smpls model.Vector
-			err := dec.Decode(&smpls)
-			if err != nil && errors.Is(err, io.EOF) {
-				break
+		t.Run(strconv.Itoa(i), func(t *testing.T) {
+			dec := &SampleDecoder{
+				Dec: newDecoder(t, strings.NewReader(scenario.in), FmtProtoDelim, model.LegacyValidation),
+				Opts: &DecodeOptions{
+					Timestamp: testTime,
+				},
 			}
-			if scenario.legacyNameFail {
-				require.Errorf(t, err, "Expected error when decoding without UTF-8 support enabled but got none")
-				model.NameValidationScheme = model.UTF8Validation //nolint:staticcheck
-				dec = &SampleDecoder{
-					Dec: &protoDecoder{r: strings.NewReader(scenario.in)},
-					Opts: &DecodeOptions{
-						Timestamp: testTime,
-					},
+
+			var all model.Vector
+			for {
+				var smpls model.Vector
+				err := dec.Decode(&smpls)
+				if err != nil && errors.Is(err, io.EOF) {
+					break
+				}
+				if scenario.legacyNameFail {
+					require.Errorf(t, err, "Expected error when decoding without UTF-8 support enabled but got none")
+					dec = &SampleDecoder{
+						Dec: newDecoder(t, strings.NewReader(scenario.in), FmtProtoDelim, model.UTF8Validation),
+						Opts: &DecodeOptions{
+							Timestamp: testTime,
+						},
+					}
+					err = dec.Decode(&smpls)
+					if errors.Is(err, io.EOF) {
+						break
+					}
+					require.NoErrorf(t, err, "Unexpected error when decoding with UTF-8 support: %v", err)
 				}
-				err = dec.Decode(&smpls)
-				if errors.Is(err, io.EOF) {
+				if scenario.fail {
+					require.Errorf(t, err, "Expected error but got none")
 					break
 				}
-				require.NoErrorf(t, err, "Unexpected error when decoding with UTF-8 support: %v", err)
+				require.NoError(t, err)
+				all = append(all, smpls...)
 			}
-			if scenario.fail {
-				require.Errorf(t, err, "Expected error but got none")
-				break
-			}
-			require.NoError(t, err)
-			all = append(all, smpls...)
-		}
-		sort.Sort(all)
-		sort.Sort(scenario.expected)
-		require.Truef(t, reflect.DeepEqual(all, scenario.expected), "%d. output does not match, want: %#v, got %#v", i, scenario.expected, all)
+			sort.Sort(all)
+			sort.Sort(scenario.expected)
+			require.Truef(t, reflect.DeepEqual(all, scenario.expected), "%d. output does not match, want: %#v, got %#v", i, scenario.expected, all)
+		})
 	}
 }
 
@@ -408,7 +409,7 @@ func TestProtoMultiMessageDecoder(t *testing.T) {
 	require.NoErrorf(t, err, "Reading file failed: %v", err)
 
 	buf := bytes.NewReader(data)
-	decoder := NewDecoder(buf, FmtProtoDelim)
+	decoder := newDecoder(t, buf, FmtProtoDelim, model.UTF8Validation)
 	var metrics []*dto.MetricFamily
 	for {
 		var mf dto.MetricFamily
@@ -557,7 +558,7 @@ func TestTextDecoderWithBufioReader(t *testing.T) {
 
 	var decoded bool
 	r := bufio.NewReader(strings.NewReader(example))
-	dec := NewDecoder(r, FmtText)
+	dec := newDecoder(t, r, FmtText, model.UTF8Validation)
 	for {
 		var mf dto.MetricFamily
 		if err := dec.Decode(&mf); err != nil {

go.mod

@@ -25,8 +25,8 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/jpillora/backoff v1.0.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/prometheus/client_golang v1.20.4 // indirect
-	github.com/prometheus/procfs v0.15.1 // indirect
+	github.com/prometheus/client_golang v1.22.1-0.20250714095417-1649bc88444a // indirect
+	github.com/prometheus/procfs v0.16.1 // indirect
 	github.com/rogpeppe/go-internal v1.10.0 // indirect
 	github.com/xhit/go-str2duration/v2 v2.1.0 // indirect
 	golang.org/x/sys v0.33.0 // indirect