Add support for escaping values

This is helpful when you have untrusted input being used for tag values
and you want to explicitly escape them.

Author: mattrobenolt

flake.lock

@@ -2,7 +2,12 @@ package metrics
 
 import "unicode/utf8"
 
-var utf8ValidString = utf8.ValidString
+var (
+	utf8ValidString    = utf8.ValidString
+	decodeRuneInString = utf8.DecodeRuneInString
+)
+
+const runeError = utf8.RuneError
 
 // replaceUTF8ValidStringHook is meant to be hijacked by a go:linkname
 // directive to replace the utf8 validation implementation.
@@ -11,3 +16,11 @@ var utf8ValidString = utf8.ValidString
 func replaceUTF8ValidStringHook(fn func(string) bool) {
 	utf8ValidString = fn
 }
+
+// replaceDecodeRuneInStringHook is meant to be hijacked by a go:linkname
+// directive to replace the utf8 rune decoding implementation.
+//
+//nolint:unused
+func replaceDecodeRuneInStringHook(fn func(string) (rune, int)) {
+	decodeRuneInString = fn
+}

speedups.go

@@ -28,6 +28,11 @@ func MustTag(label, value string) Tag {
 	}
 }
 
+// NewTag creates a Tag from an already-validated Label and Value.
+func NewTag(label Label, value Value) Tag {
+	return Tag{label: label, value: value}
+}
+
 // UnsafeValue creates a Value, but does not validate it.
 func UnsafeValue(s string) Value {
 	return Value{s}
@@ -45,6 +50,107 @@ func MustValue(s string) Value {
 	return Value{s}
 }
 
+// SanitizeValue escapes a string to be a valid tag value.
+// Backslashes, double-quotes, and line feeds are escaped.
+// Invalid UTF-8 sequences are replaced with the Unicode replacement character.
+//
+// If the input is already valid, it is returned without allocation.
+func SanitizeValue(s string) Value {
+	// Fast path for valid UTF-8: just check for escape characters
+	if utf8ValidString(s) {
+		n := 0
+		for i := range len(s) {
+			switch s[i] {
+			case '\\', '"', '\n':
+				n++
+			}
+		}
+		if n == 0 {
+			return Value{s}
+		}
+		// Valid UTF-8 but needs escaping
+		b := make([]byte, 0, len(s)+n)
+		last := 0
+		for i := range len(s) {
+			var esc byte
+			switch s[i] {
+			case '\\':
+				esc = '\\'
+			case '"':
+				esc = '"'
+			case '\n':
+				esc = 'n'
+			default:
+				continue
+			}
+			b = append(b, s[last:i]...)
+			b = append(b, '\\', esc)
+			last = i + 1
+		}
+		b = append(b, s[last:]...)
+		return Value{string(b)}
+	}
+
+	// Slow path: invalid UTF-8, need to scan and replace
+	extra := 0
+	for i := 0; i < len(s); {
+		c := s[i]
+		if c < 0x80 {
+			switch c {
+			case '\\', '"', '\n':
+				extra++
+			}
+			i++
+			continue
+		}
+		r, size := decodeRuneInString(s[i:])
+		if r == runeError && size == 1 {
+			extra += 2 // replacement char is 3 bytes, invalid is 1
+			i++
+		} else {
+			i += size
+		}
+	}
+
+	b := make([]byte, 0, len(s)+extra)
+	last := 0
+	for i := 0; i < len(s); {
+		c := s[i]
+		if c < 0x80 {
+			var esc byte
+			switch c {
+			case '\\':
+				esc = '\\'
+			case '"':
+				esc = '"'
+			case '\n':
+				esc = 'n'
+			default:
+				i++
+				continue
+			}
+			b = append(b, s[last:i]...)
+			b = append(b, '\\', esc)
+			i++
+			last = i
+			continue
+		}
+
+		r, size := decodeRuneInString(s[i:])
+		if r == runeError && size == 1 {
+			b = append(b, s[last:i]...)
+			b = append(b, "\uFFFD"...)
+			i++
+			last = i
+		} else {
+			i += size
+		}
+	}
+	b = append(b, s[last:]...)
+
+	return Value{string(b)}
+}
+
 // MustTags converts label value pairs into Tags.
 //
 // This will panic if s is an invalid tag value.

validator.go

@@ -65,6 +65,59 @@ func TestValidateValueError(t *testing.T) {
 	}
 }
 
+func TestNewTag(t *testing.T) {
+	tag := NewTag(MustLabel("foo"), SanitizeValue("bar"))
+	assert.Equal(t, tag.String(), `foo="bar"`)
+}
+
+func TestSanitizeValue(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		// Already valid - no escaping needed
+		{"", ""},
+		{"hello", "hello"},
+		{"foo_bar", "foo_bar"},
+		{"ü", "ü"},
+		{"🍖", "🍖"},
+
+		// Needs escaping
+		{`\`, `\\`},
+		{`"`, `\"`},
+		{"\n", `\n`},
+		{`foo\bar`, `foo\\bar`},
+		{`foo"bar`, `foo\"bar`},
+		{"foo\nbar", `foo\nbar`},
+		{`a\b"c` + "\n" + `d`, `a\\b\"c\nd`},
+
+		// Invalid UTF-8 replaced with replacement character
+		{"\xff", "\uFFFD"},
+		{"hello\xffworld", "hello\uFFFDworld"},
+		// Invalid UTF-8 combined with escaping
+		{"\xff\n\xfe", "\uFFFD\\n\uFFFD"},
+		{"\xff\\\"\xfe", "\uFFFD\\\\\\\"\uFFFD"},
+		// Invalid UTF-8 mixed with valid multi-byte UTF-8
+		{"\xffü\xfe", "\uFFFDü\uFFFD"},
+	}
+
+	for _, tt := range tests {
+		got := SanitizeValue(tt.input)
+		assert.Equal(t, got.String(), tt.want)
+		// Verify the result passes validation
+		assert.Equal(t, MustValue(got.String()).String(), tt.want)
+	}
+}
+
+func TestSanitizeValueNoAlloc(t *testing.T) {
+	// Valid strings should not allocate
+	valid := "hello_world_123"
+	allocs := testing.AllocsPerRun(100, func() {
+		_ = SanitizeValue(valid)
+	})
+	assert.Equal(t, allocs, float64(0))
+}
+
 func BenchmarkValidate(b *testing.B) {
 	b.Run("MustIdent", func(b *testing.B) {
 		b.ReportAllocs()
@@ -86,4 +139,18 @@ func BenchmarkValidate(b *testing.B) {
 			MustValue(`some.other.value`)
 		}
 	})
+
+	b.Run("SanitizeValue/clean", func(b *testing.B) {
+		b.ReportAllocs()
+		for b.Loop() {
+			SanitizeValue(`some.other.value`)
+		}
+	})
+
+	b.Run("SanitizeValue/escape", func(b *testing.B) {
+		b.ReportAllocs()
+		for b.Loop() {
+			SanitizeValue("foo\nbar\"baz\\qux")
+		}
+	})
 }