go.opentelemetry.io/otel/trace v1.24.0: ParseTraceState

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/go.opentelemetry.io/otel/trace@v1.24.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.opentelemetry.io/otel/trace@v1.24.0
Demonstrate these symbols/APIs:
  - go.opentelemetry.io/otel/trace.ParseTraceState

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.

{"case":{"caseId":"case:sha256:7b48bd442d5a126e40426454cfd34714bff9177a444bb1d75ecbae21a94701b7","contract":["ParseTraceState parses valid W3C list-members into ordered key-value pairs while empty string returns empty TraceState","ParseTraceState rejects uppercase keys, missing delimiter, duplicate keys, and lists exceeding 32 members","TraceState Insert prepends new members to the list head, moves updated existing keys to the head, and evicts tail members beyond 32","TraceState Delete removes matching member preserving order, while deleting nonexistent key returns identical copy","TraceState Insert and Delete return new instances without mutating the original TraceState"],"goal":"verify pkg:golang/go.opentelemetry.io/otel/trace@v1.24.0","kind":"HOW","packages":["pkg:golang/go.opentelemetry.io/otel/trace@v1.24.0"],"schemaVersion":1,"symbols":["go.opentelemetry.io/otel/trace.ParseTraceState"]},"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/go.opentelemetry.io/otel/trace@v1.24.0"],"schemaVersion":1,"subject":"pkg:golang/go.opentelemetry.io/otel/trace@v1.24.0","symbols":["go.opentelemetry.io/otel/trace.ParseTraceState"],"verifierAdapter":"golang@1"}

module sample

go 1.22

require (
	go.opentelemetry.io/otel v1.24.0
	go.opentelemetry.io/otel/trace v1.24.0
)

go.opentelemetry.io/otel v1.24.0 h1:0LAOdjNmQeSTzGBzduGe/rU4tZhMwL5rWgtp9Ku5Jfo=
go.opentelemetry.io/otel v1.24.0/go.mod h1:W7b9Ozg4nkF5tWI5zsXkaKKDjdVjpD4oAt9Qi/MArHo=
go.opentelemetry.io/otel/trace v1.24.0 h1:CsKnnL4dUAr/0llH9FKuc698G04IrpWV0MQA/Y1YELI=
go.opentelemetry.io/otel/trace v1.24.0/go.mod h1:HPc3Xr/cOApsBI154IU0OI0HJexz+aw5uPdbs3UCjNU=

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/go.opentelemetry.io/otel/trace@v1.24.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.opentelemetry.io/otel/trace@v1.24.0"
  ],
  "symbols": [
    "go.opentelemetry.io/otel/trace.ParseTraceState"
  ]
}

package sample_test

import (
	"fmt"
	"strings"
	"testing"

	"go.opentelemetry.io/otel/trace"
)

func TestParseTraceState_ValidAndEmpty(t *testing.T) {
	// Empty string produces empty TraceState with zero length
	emptyTS, err := trace.ParseTraceState("")
	if err != nil {
		t.Fatalf("ParseTraceState(\"\") returned error: %v", err)
	}
	if emptyTS.Len() != 0 {
		t.Fatalf("expected length 0 for empty tracestate, got %d", emptyTS.Len())
	}
	if emptyTS.String() != "" {
		t.Fatalf("expected empty string representation, got %q", emptyTS.String())
	}

	// Valid W3C list members parsed in order
	ts, err := trace.ParseTraceState("rojo=1,congo=2")
	if err != nil {
		t.Fatalf("ParseTraceState failed on valid input: %v", err)
	}
	if ts.Len() != 2 {
		t.Fatalf("expected length 2, got %d", ts.Len())
	}
	if got := ts.Get("rojo"); got != "1" {
		t.Fatalf("expected rojo=1, got %q", got)
	}
	if got := ts.Get("congo"); got != "2" {
		t.Fatalf("expected congo=2, got %q", got)
	}
	if ts.String() != "rojo=1,congo=2" {
		t.Fatalf("expected String() to match 'rojo=1,congo=2', got %q", ts.String())
	}

	// Multi-tenant key syntax support
	tenantTS, err := trace.ParseTraceState("vendor@tenant=custom_val")
	if err != nil {
		t.Fatalf("ParseTraceState failed on multi-tenant key: %v", err)
	}
	if got := tenantTS.Get("vendor@tenant"); got != "custom_val" {
		t.Fatalf("expected vendor@tenant=custom_val, got %q", got)
	}
}

func TestParseTraceState_Rejections(t *testing.T) {
	// Rejection: Uppercase key names
	if _, err := trace.ParseTraceState("ROJO=1"); err == nil {
		t.Fatalf("expected ParseTraceState to reject uppercase key 'ROJO'")
	}

	// Rejection: Missing key-value delimiter '='
	if _, err := trace.ParseTraceState("rojo"); err == nil {
		t.Fatalf("expected ParseTraceState to reject member without delimiter")
	}

	// Rejection: Duplicate list-member keys
	if _, err := trace.ParseTraceState("rojo=1,rojo=2"); err == nil {
		t.Fatalf("expected ParseTraceState to reject duplicate keys")
	}

	// Rejection: Exceeding 32 list-members
	members := make([]string, 33)
	for i := 0; i < 33; i++ {
		members[i] = fmt.Sprintf("k%d=v%d", i, i)
	}
	exceedingStr := strings.Join(members, ",")
	if _, err := trace.ParseTraceState(exceedingStr); err == nil {
		t.Fatalf("expected ParseTraceState to reject tracestate with 33 members")
	}
}

func TestTraceState_Insert(t *testing.T) {
	initTS, err := trace.ParseTraceState("b=2")
	if err != nil {
		t.Fatalf("setup failed: %v", err)
	}

	// Prepend new member to the list head
	tsWithA, err := initTS.Insert("a", "1")
	if err != nil {
		t.Fatalf("Insert failed: %v", err)
	}
	if tsWithA.String() != "a=1,b=2" {
		t.Fatalf("expected 'a=1,b=2', got %q", tsWithA.String())
	}

	// Updating existing key moves it to the head with updated value
	tsUpdatedB, err := tsWithA.Insert("b", "99")
	if err != nil {
		t.Fatalf("Insert failed: %v", err)
	}
	if tsUpdatedB.String() != "b=99,a=1" {
		t.Fatalf("expected 'b=99,a=1', got %q", tsUpdatedB.String())
	}
	if got := tsUpdatedB.Get("b"); got != "99" {
		t.Fatalf("expected b=99, got %q", got)
	}

	// Evict tail members when exceeding 32 items
	currTS := trace.TraceState{}
	for i := 1; i <= 32; i++ {
		key := fmt.Sprintf("k%02d", i)
		val := fmt.Sprintf("%d", i)
		var insErr error
		currTS, insErr = currTS.Insert(key, val)
		if insErr != nil {
			t.Fatalf("Insert member %d failed: %v", i, insErr)
		}
	}
	if currTS.Len() != 32 {
		t.Fatalf("expected 32 members, got %d", currTS.Len())
	}
	// The oldest item inserted was k01, which is currently at the tail
	if currTS.Get("k01") != "1" {
		t.Fatalf("expected k01 to exist before eviction")
	}

	// Insert 33rd member: "k00", "0" -> should prepend k00 and evict k01 at the tail
	evictedTS, err := currTS.Insert("k00", "0")
	if err != nil {
		t.Fatalf("Insert on 32-member TraceState failed: %v", err)
	}
	if evictedTS.Len() != 32 {
		t.Fatalf("expected length to remain 32 after eviction, got %d", evictedTS.Len())
	}
	if got := evictedTS.Get("k00"); got != "0" {
		t.Fatalf("expected k00=0, got %q", got)
	}
	if got := evictedTS.Get("k01"); got != "" {
		t.Fatalf("expected tail member k01 to be evicted, got %q", got)
	}
}

func TestTraceState_Delete(t *testing.T) {
	ts, err := trace.ParseTraceState("a=1,b=2,c=3")
	if err != nil {
		t.Fatalf("setup failed: %v", err)
	}

	// Delete existing key preserves remaining order
	deletedTS := ts.Delete("b")
	if deletedTS.Len() != 2 {
		t.Fatalf("expected length 2 after delete, got %d", deletedTS.Len())
	}
	if deletedTS.String() != "a=1,c=3" {
		t.Fatalf("expected 'a=1,c=3', got %q", deletedTS.String())
	}
	if got := deletedTS.Get("b"); got != "" {
		t.Fatalf("expected empty value for deleted key, got %q", got)
	}

	// Deleting nonexistent key returns identical copy
	nonexistentTS := ts.Delete("nonexistent")
	if nonexistentTS.String() != ts.String() {
		t.Fatalf("expected string to match original after deleting nonexistent key: got %q, want %q", nonexistentTS.String(), ts.String())
	}
	if nonexistentTS.Len() != ts.Len() {
		t.Fatalf("expected length to match original: got %d, want %d", nonexistentTS.Len(), ts.Len())
	}
}

func TestTraceState_Immutability(t *testing.T) {
	orig, err := trace.ParseTraceState("x=10")
	if err != nil {
		t.Fatalf("setup failed: %v", err)
	}

	// Insert returns a new TraceState without mutating the original
	inserted, err := orig.Insert("y", "20")
	if err != nil {
		t.Fatalf("Insert failed: %v", err)
	}
	if orig.Len() != 1 || orig.String() != "x=10" {
		t.Fatalf("orig mutated during Insert: len=%d, str=%q", orig.Len(), orig.String())
	}
	if inserted.Len() != 2 || inserted.String() != "y=20,x=10" {
		t.Fatalf("inserted invalid: len=%d, str=%q", inserted.Len(), inserted.String())
	}

	// Delete returns a new TraceState without mutating the original
	deleted := inserted.Delete("x")
	if inserted.Len() != 2 || inserted.String() != "y=20,x=10" {
		t.Fatalf("inserted mutated during Delete: len=%d, str=%q", inserted.Len(), inserted.String())
	}
	if deleted.Len() != 1 || deleted.String() != "y=20" {
		t.Fatalf("deleted invalid: len=%d, str=%q", deleted.Len(), deleted.String())
	}
}