Add oteltest TextMap propagator and carrier (#1259)

* Add oteltest text map propagator and carrier

* Add changes to CHANGELOG

* Add PR number to CHANGELOG

* Add test for empty newState

Gotta farm that codecov

CHANGELOG.md

@@ -8,6 +8,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added
+
+- A `TextMapPropagator` and associated `TextMapCarrier` are added to the `go.opentelemetry.io/otel/oteltest` package to test TextMap type propagators and their use. (#1259)
+
 ### Changed
 
 - Move the `go.opentelemetry.io/otel/api/trace` package into `go.opentelemetry.io/otel` with the following changes. (#1229)

oteltest/text_map_propagator.go

@@ -0,0 +1,208 @@
+// Copyright The OpenTelemetry 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.
+
+package oteltest
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+
+	"go.opentelemetry.io/otel"
+)
+
+type ctxKeyType string
+
+// TextMapCarrier provides a testing storage medium to for a
+// TextMapPropagator. It records all the operations it performs.
+type TextMapCarrier struct {
+	mtx sync.Mutex
+
+	gets []string
+	sets [][2]string
+	data map[string]string
+}
+
+// NewTextMapCarrier returns a new *TextMapCarrier populated with data.
+func NewTextMapCarrier(data map[string]string) *TextMapCarrier {
+	copied := make(map[string]string, len(data))
+	for k, v := range data {
+		copied[k] = v
+	}
+	return &TextMapCarrier{data: copied}
+}
+
+// Get returns the value associated with the passed key.
+func (c *TextMapCarrier) Get(key string) string {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	c.gets = append(c.gets, key)
+	return c.data[key]
+}
+
+// GotKey tests if c.Get has been called for key.
+func (c *TextMapCarrier) GotKey(t *testing.T, key string) bool {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	for _, k := range c.gets {
+		if k == key {
+			return true
+		}
+	}
+	t.Errorf("TextMapCarrier.Get(%q) has not been called", key)
+	return false
+}
+
+// GotN tests if n calls to c.Get have been made.
+func (c *TextMapCarrier) GotN(t *testing.T, n int) bool {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	if len(c.gets) != n {
+		t.Errorf("TextMapCarrier.Get was called %d times, not %d", len(c.gets), n)
+		return false
+	}
+	return true
+}
+
+// Set stores the key-value pair.
+func (c *TextMapCarrier) Set(key, value string) {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	c.sets = append(c.sets, [2]string{key, value})
+	c.data[key] = value
+}
+
+// SetKeyValue tests if c.Set has been called for the key-value pair.
+func (c *TextMapCarrier) SetKeyValue(t *testing.T, key, value string) bool {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	var vals []string
+	for _, pair := range c.sets {
+		if key == pair[0] {
+			if value == pair[1] {
+				return true
+			}
+			vals = append(vals, pair[1])
+		}
+	}
+	if len(vals) > 0 {
+		t.Errorf("TextMapCarrier.Set called with %q and %v values, but not %s", key, vals, value)
+	}
+	t.Errorf("TextMapCarrier.Set(%q,%q) has not been called", key, value)
+	return false
+}
+
+// SetN tests if n calls to c.Set have been made.
+func (c *TextMapCarrier) SetN(t *testing.T, n int) bool {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	if len(c.sets) != n {
+		t.Errorf("TextMapCarrier.Set was called %d times, not %d", len(c.gets), n)
+		return false
+	}
+	return true
+}
+
+// Reset zeros out the internal state recording of c.
+func (c *TextMapCarrier) Reset() {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+
+	c.gets = nil
+	c.sets = nil
+	c.data = make(map[string]string)
+}
+
+type state struct {
+	Injections  uint64
+	Extractions uint64
+}
+
+func newState(encoded string) state {
+	if encoded == "" {
+		return state{}
+	}
+	split := strings.SplitN(encoded, ",", 2)
+	injects, _ := strconv.ParseUint(split[0], 10, 64)
+	extracts, _ := strconv.ParseUint(split[1], 10, 64)
+	return state{
+		Injections:  injects,
+		Extractions: extracts,
+	}
+}
+
+func (s state) String() string {
+	return fmt.Sprintf("%d,%d", s.Injections, s.Extractions)
+}
+
+type TextMapPropagator struct {
+	Name   string
+	ctxKey ctxKeyType
+}
+
+func NewTextMapPropagator(name string) *TextMapPropagator {
+	return &TextMapPropagator{Name: name, ctxKey: ctxKeyType(name)}
+}
+
+func (p *TextMapPropagator) stateFromContext(ctx context.Context) state {
+	if v := ctx.Value(p.ctxKey); v != nil {
+		if s, ok := v.(state); ok {
+			return s
+		}
+	}
+	return state{}
+}
+
+func (p *TextMapPropagator) stateFromCarrier(carrier otel.TextMapCarrier) state {
+	return newState(carrier.Get(p.Name))
+}
+
+// Inject set cross-cutting concerns for p from the Context into the carrier.
+func (p *TextMapPropagator) Inject(ctx context.Context, carrier otel.TextMapCarrier) {
+	s := p.stateFromContext(ctx)
+	s.Injections++
+	carrier.Set(p.Name, s.String())
+}
+
+// InjectedN tests if p has made n injections to carrier.
+func (p *TextMapPropagator) InjectedN(t *testing.T, carrier *TextMapCarrier, n int) bool {
+	if actual := p.stateFromCarrier(carrier).Injections; actual != uint64(n) {
+		t.Errorf("TextMapPropagator{%q} injected %d times, not %d", p.Name, actual, n)
+		return false
+	}
+	return true
+}
+
+// Extract reads cross-cutting concerns for p from the carrier into a Context.
+func (p *TextMapPropagator) Extract(ctx context.Context, carrier otel.TextMapCarrier) context.Context {
+	s := p.stateFromCarrier(carrier)
+	s.Extractions++
+	return context.WithValue(ctx, p.ctxKey, s)
+}
+
+// ExtractedN tests if p has made n extractions from the lineage of ctx.
+// nolint (context is not first arg)
+func (p *TextMapPropagator) ExtractedN(t *testing.T, ctx context.Context, n int) bool {
+	if actual := p.stateFromContext(ctx).Extractions; actual != uint64(n) {
+		t.Errorf("TextMapPropagator{%q} extracted %d time, not %d", p.Name, actual, n)
+		return false
+	}
+	return true
+}
+
+// Fields returns p.Name as the key who's value is set with Inject.
+func (p *TextMapPropagator) Fields() []string { return []string{p.Name} }

oteltest/text_map_propagator_test.go

@@ -0,0 +1,124 @@
+// Copyright The OpenTelemetry 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.
+
+package oteltest
+
+import (
+	"context"
+	"testing"
+)
+
+var (
+	key, value = "test", "true"
+)
+
+func TestTextMapCarrierGet(t *testing.T) {
+	tmc := NewTextMapCarrier(map[string]string{key: value})
+	tmc.GotN(t, 0)
+	if got := tmc.Get("empty"); got != "" {
+		t.Errorf("TextMapCarrier.Get returned %q for an empty key", got)
+	}
+	tmc.GotKey(t, "empty")
+	tmc.GotN(t, 1)
+	if got := tmc.Get(key); got != value {
+		t.Errorf("TextMapCarrier.Get(%q) returned %q, want %q", key, got, value)
+	}
+	tmc.GotKey(t, key)
+	tmc.GotN(t, 2)
+}
+
+func TestTextMapCarrierSet(t *testing.T) {
+	tmc := NewTextMapCarrier(nil)
+	tmc.SetN(t, 0)
+	tmc.Set(key, value)
+	if got, ok := tmc.data[key]; !ok {
+		t.Errorf("TextMapCarrier.Set(%q,%q) failed to store pair", key, value)
+	} else if got != value {
+		t.Errorf("TextMapCarrier.Set(%q,%q) stored (%q,%q), not (%q,%q)", key, value, key, got, key, value)
+	}
+	tmc.SetKeyValue(t, key, value)
+	tmc.SetN(t, 1)
+}
+
+func TestTextMapCarrierReset(t *testing.T) {
+	tmc := NewTextMapCarrier(map[string]string{key: value})
+	tmc.GotN(t, 0)
+	tmc.SetN(t, 0)
+	tmc.Reset()
+	tmc.GotN(t, 0)
+	tmc.SetN(t, 0)
+	if got := tmc.Get(key); got != "" {
+		t.Error("TextMapCarrier.Reset() failed to clear initial data")
+	}
+	tmc.GotN(t, 1)
+	tmc.GotKey(t, key)
+	tmc.Set(key, value)
+	tmc.SetKeyValue(t, key, value)
+	tmc.SetN(t, 1)
+	tmc.Reset()
+	tmc.GotN(t, 0)
+	tmc.SetN(t, 0)
+	if got := tmc.Get(key); got != "" {
+		t.Error("TextMapCarrier.Reset() failed to clear data")
+	}
+}
+
+func TestTextMapPropagatorInjectExtract(t *testing.T) {
+	name := "testing"
+	ctx := context.Background()
+	carrier := NewTextMapCarrier(map[string]string{name: value})
+	propagator := NewTextMapPropagator(name)
+
+	propagator.Inject(ctx, carrier)
+	// Carrier value overridden with state.
+	if carrier.SetKeyValue(t, name, "1,0") {
+		// Ensure nothing has been extracted yet.
+		propagator.ExtractedN(t, ctx, 0)
+		// Test the injection was counted.
+		propagator.InjectedN(t, carrier, 1)
+	}
+
+	ctx = propagator.Extract(ctx, carrier)
+	v := ctx.Value(ctxKeyType(name))
+	if v == nil {
+		t.Error("TextMapPropagator.Extract failed to extract state")
+	}
+	if s, ok := v.(state); !ok {
+		t.Error("TextMapPropagator.Extract did not extract proper state")
+	} else if s.Extractions != 1 {
+		t.Error("TextMapPropagator.Extract did not increment state.Extractions")
+	}
+	if carrier.GotKey(t, name) {
+		// Test the extraction was counted.
+		propagator.ExtractedN(t, ctx, 1)
+		// Ensure no additional injection was recorded.
+		propagator.InjectedN(t, carrier, 1)
+	}
+}
+
+func TestTextMapPropagatorFields(t *testing.T) {
+	name := "testing"
+	propagator := NewTextMapPropagator(name)
+	if got := propagator.Fields(); len(got) != 1 {
+		t.Errorf("TextMapPropagator.Fields returned %d fields, want 1", len(got))
+	} else if got[0] != name {
+		t.Errorf("TextMapPropagator.Fields returned %q, want %q", got[0], name)
+	}
+}
+
+func TestNewStateEmpty(t *testing.T) {
+	if want, got := (state{}), newState(""); got != want {
+		t.Errorf("newState(\"\") returned %v, want %v", got, want)
+	}
+}