github.com/prometheus/common v0.67.5

# github.com/prometheus/common/model Data Structures and Validation

## Prior Knowledge Search
A query to search known solutions for `pkg:golang/github.com/prometheus/common@v0.67.5` returned `NO_SAFE_MATCH` for the `model` core API family. This sample establishes verified coverage for Prometheus core data structures, validation schemes, durations, fingerprints, and time conversions.

## Pinned Release
- `github.com/prometheus/common`: `v0.67.5`

## Proven Behaviors and Semantics

### 1. Metric and LabelSet Operations
- `model.Metric.String()` formats the metric with the metric name prefix before braces (e.g. `http_requests_total{handler="/api/v1/query", method="GET", status="200"}`).
- `model.Metric.Fingerprint()` and `model.Metric.FastFingerprint()` compute deterministic 64-bit FNV-1a hashes.
- `model.Metric.Clone()` creates a deep copy matching the original metric's equality and fingerprint.
- `model.LabelSet.Merge()` combines label sets with override precedence.
- `model.LabelSet.Validate()` validates all label names and values within the set, rejecting invalid UTF-8 sequences.

### 2. Validation Schemes and Label Values
- `model.LegacyValidation.IsValidLabelName` validates names against the classic Prometheus pattern `^[a-zA-Z_][a-zA-Z0-9_]*$`.
- `model.UTF8Validation.IsValidLabelName` permits modern UTF-8 label names introduced in Prometheus 3.0.
- `model.LegacyValidation.IsValidMetricName` enforces `^[a-zA-Z_:][a-zA-Z0-9_:]*$`.
- `model.LabelValue.IsValid()` checks valid UTF-8 string encoding.

### 3. Duration Parsing
- `model.ParseDuration` parses standard Prometheus duration strings (`"500ms"`, `"30s"`, `"5m"`, `"2h"`, `"3d"`, `"1w"`, `"1y"`, `"1h30m"`) to `time.Duration`.
- Returns an error on empty or malformed strings.

### 4. Fingerprint Parsing and Formatting
- `model.Fingerprint.String()` formats a 64-bit fingerprint as a 16-character hexadecimal string.
- `model.ParseFingerprint` and `model.FingerprintFromString` round-trip valid hex strings and reject invalid input.

### 5. Time Conversions and Sample Structures
- `model.TimeFromUnixNano` creates millisecond-precision `model.Time`, supporting `.Time()`, `.Unix()`, `.Add()`, `.Sub()`, `.Before()`, `.After()`.
- `model.Sample` pairs a `Metric`, `SampleValue`, and `Time`.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:golang/github.com/prometheus/common@v0.67.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/prometheus/common@v0.67.5

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

package main

import (
	"strings"
	"testing"
	"time"

	"github.com/prometheus/common/model"
)

func TestMetricAndLabelSet(t *testing.T) {
	// 1. Metric creation, string representation, cloning, equality and fingerprints
	metric := model.Metric{
		model.MetricNameLabel: "http_requests_total",
		"method":              "GET",
		"status":              "200",
		"handler":             "/api/v1/query",
	}

	str := metric.String()
	if !strings.HasPrefix(str, "http_requests_total{") ||
		!strings.Contains(str, `method="GET"`) ||
		!strings.Contains(str, `status="200"`) ||
		!strings.Contains(str, `handler="/api/v1/query"`) {
		t.Errorf("unexpected Metric.String() representation: %s", str)
	}

	cloned := metric.Clone()
	if !cloned.Equal(metric) {
		t.Errorf("cloned metric must equal original metric")
	}

	fp := metric.Fingerprint()
	if fp == 0 {
		t.Fatalf("expected non-zero Fingerprint")
	}
	if cloned.Fingerprint() != fp {
		t.Errorf("cloned metric fingerprint %v must match original %v", cloned.Fingerprint(), fp)
	}

	fastFp := metric.FastFingerprint()
	if fastFp == 0 {
		t.Fatalf("expected non-zero FastFingerprint")
	}
	if cloned.FastFingerprint() != fastFp {
		t.Errorf("cloned metric fast fingerprint %v must match original %v", cloned.FastFingerprint(), fastFp)
	}

	// 2. LabelSet validation and merge operations
	validSet := model.LabelSet{
		"job":      "prometheus",
		"instance": "localhost:9090",
	}
	if err := validSet.Validate(); err != nil {
		t.Errorf("expected valid LabelSet to pass validation: %v", err)
	}

	overrideSet := model.LabelSet{
		"instance": "10.0.0.1:9090",
		"env":      "prod",
	}
	merged := validSet.Merge(overrideSet)
	if merged["job"] != "prometheus" {
		t.Errorf("expected merged job='prometheus', got %q", merged["job"])
	}
	if merged["instance"] != "10.0.0.1:9090" {
		t.Errorf("expected merged instance='10.0.0.1:9090', got %q", merged["instance"])
	}
	if merged["env"] != "prod" {
		t.Errorf("expected merged env='prod', got %q", merged["env"])
	}

	invalidSet := model.LabelSet{
		model.LabelName("\xff\xfe"): "val",
	}
	if err := invalidSet.Validate(); err == nil {
		t.Errorf("expected invalid LabelSet with invalid UTF-8 name to fail validation, got nil")
	}
}

func TestValidationSchemesAndLabelValues(t *testing.T) {
	// Legacy validation scheme
	validLegacyNames := []string{"valid_name", "_private_metric", "A_123_b", "a"}
	for _, name := range validLegacyNames {
		if !model.LegacyValidation.IsValidLabelName(name) {
			t.Errorf("expected LegacyValidation.IsValidLabelName(%q) to be true", name)
		}
	}

	invalidLegacyNames := []string{"", "123num", "invalid-char", "has space", "@symbol"}
	for _, name := range invalidLegacyNames {
		if model.LegacyValidation.IsValidLabelName(name) {
			t.Errorf("expected LegacyValidation.IsValidLabelName(%q) to be false", name)
		}
	}

	// UTF-8 validation scheme accepts Unicode / modern names
	utf8Names := []string{"valid_name", "한국어_label", "http.status_code", "label-with-dash"}
	for _, name := range utf8Names {
		if !model.UTF8Validation.IsValidLabelName(name) {
			t.Errorf("expected UTF8Validation.IsValidLabelName(%q) to be true", name)
		}
	}

	// Metric name validation under Legacy scheme
	if !model.LegacyValidation.IsValidMetricName("http_requests:total") {
		t.Errorf("expected valid legacy metric name with colon to pass")
	}
	if model.LegacyValidation.IsValidMetricName("123_bad_metric") {
		t.Errorf("expected invalid legacy metric name to fail")
	}

	// Valid LabelValues (valid UTF-8 strings)
	for _, val := range []string{"", "hello-world", "12345", "한국어", "some / path / value"} {
		if !model.LabelValue(val).IsValid() {
			t.Errorf("expected LabelValue(%q).IsValid() to be true", val)
		}
	}

	// Invalid LabelValues (invalid UTF-8 bytes)
	invalidUTF8 := model.LabelValue("\xff\xfe\xfd")
	if invalidUTF8.IsValid() {
		t.Errorf("expected invalid UTF-8 LabelValue to be invalid")
	}
}

func TestParseDuration(t *testing.T) {
	cases := []struct {
		input    string
		expected time.Duration
	}{
		{"500ms", 500 * time.Millisecond},
		{"30s", 30 * time.Second},
		{"5m", 5 * time.Minute},
		{"2h", 2 * time.Hour},
		{"3d", 3 * 24 * time.Hour},
		{"1w", 7 * 24 * time.Hour},
		{"1y", 365 * 24 * time.Hour},
		{"1h30m", 90 * time.Minute},
	}

	for _, tc := range cases {
		d, err := model.ParseDuration(tc.input)
		if err != nil {
			t.Errorf("unexpected error parsing duration %q: %v", tc.input, err)
			continue
		}
		if time.Duration(d) != tc.expected {
			t.Errorf("ParseDuration(%q) = %v, expected %v", tc.input, time.Duration(d), tc.expected)
		}
	}

	// Invalid durations
	for _, inv := range []string{"", "invalid", "10x", "500", "m5"} {
		_, err := model.ParseDuration(inv)
		if err == nil {
			t.Errorf("expected error parsing invalid duration %q, got nil", inv)
		}
	}
}

func TestFingerprintParsingAndFormatting(t *testing.T) {
	fp := model.Fingerprint(0x1234567890abcdef)
	hexStr := fp.String()
	if hexStr != "1234567890abcdef" {
		t.Errorf("expected Fingerprint.String() = '1234567890abcdef', got %q", hexStr)
	}

	parsed, err := model.ParseFingerprint(hexStr)
	if err != nil {
		t.Fatalf("unexpected error parsing fingerprint: %v", err)
	}
	if parsed != fp {
		t.Errorf("parsed fingerprint %v does not match original %v", parsed, fp)
	}

	fromStr, err := model.FingerprintFromString(hexStr)
	if err != nil {
		t.Fatalf("unexpected error FingerprintFromString: %v", err)
	}
	if fromStr != fp {
		t.Errorf("FingerprintFromString %v does not match original %v", fromStr, fp)
	}

	// Invalid fingerprint strings
	for _, inv := range []string{"", "short", "zzzzzzzzzzzzzzzz", "1234567890abcdef123"} {
		_, err := model.ParseFingerprint(inv)
		if err == nil {
			t.Errorf("expected error parsing invalid fingerprint string %q, got nil", inv)
		}
	}
}

func TestTimeAndSample(t *testing.T) {
	now := time.Now().Truncate(time.Millisecond)
	promTime := model.TimeFromUnixNano(now.UnixNano())

	if promTime.Unix() != now.Unix() {
		t.Errorf("promTime.Unix() %d != now.Unix() %d", promTime.Unix(), now.Unix())
	}

	converted := promTime.Time()
	if !converted.Equal(now) {
		t.Errorf("converted time %v != original %v", converted, now)
	}

	added := promTime.Add(5 * time.Minute)
	if !added.After(promTime) {
		t.Errorf("expected added time to be after original time")
	}
	if added.Sub(promTime) != 5*time.Minute {
		t.Errorf("expected sub to equal 5m, got %v", added.Sub(promTime))
	}

	// Sample structure
	sample := model.Sample{
		Metric: model.Metric{
			model.MetricNameLabel: "cpu_usage",
		},
		Value:     model.SampleValue(99.9),
		Timestamp: promTime,
	}

	if sample.Value != 99.9 {
		t.Errorf("expected sample value 99.9, got %v", sample.Value)
	}
	if sample.Timestamp != promTime {
		t.Errorf("expected timestamp %v, got %v", promTime, sample.Timestamp)
	}
	if sample.Metric[model.MetricNameLabel] != "cpu_usage" {
		t.Errorf("expected metric name 'cpu_usage', got %q", sample.Metric[model.MetricNameLabel])
	}
}

{"case":{"caseId":"case:sha256:8a72a8e11a03a444a7259a98f9e5d07d5dee694ff856e36f45c49a52c597feec","contract":["Metric.String formats the metric with name prefix before braces, and Metric.Fingerprint computes deterministic 64-bit hashes.","Metric.Clone produces a deep copy satisfying equality and preserving fingerprints.","LabelSet.Merge combines label sets with override precedence, and LabelSet.Validate checks valid UTF-8 encoding.","LegacyValidation and UTF8Validation validate label and metric names under classic and modern Prometheus rules.","model.ParseDuration parses standard Prometheus duration strings into time.Duration and rejects malformed strings.","FingerprintFromString and ParseFingerprint parse 16-character hexadecimal strings to model.Fingerprint.","TimeFromUnixNano produces millisecond-precision model.Time supporting time math and comparison operations."],"goal":"verify pkg:golang/github.com/prometheus/common@v0.67.5","kind":"HOW","packages":["pkg:golang/github.com/prometheus/common@v0.67.5"],"schemaVersion":1},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/prometheus/common@v0.67.5"],"schemaVersion":1,"subject":"pkg:golang/github.com/prometheus/common@v0.67.5","verifierAdapter":"golang@1"}

module example.com/csx-prometheus-common-sample

go 1.26.6

require github.com/prometheus/common v0.67.5

require (
	github.com/kr/pretty v0.3.1 // indirect
	github.com/prometheus/client_model v0.6.2 // indirect
	go.yaml.in/yaml/v2 v2.4.3 // indirect
	google.golang.org/protobuf v1.36.11 // indirect
)

github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
github.com/prometheus/common v0.67.5 h1:pIgK94WWlQt1WLwAC5j2ynLaBRDiinoAb86HZHTUGI4=
github.com/prometheus/common v0.67.5/go.mod h1:SjE/0MzDEEAyrdr5Gqc6G+sXI67maCxzaT3A2+HqjUw=
github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=
go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/prometheus/common@v0.67.5",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/prometheus/common@v0.67.5"
  ]
}