Reorganize propagation code (shrink PR 381) (#444)

* Rename distributedcontext package to correlation

Correlation is the name we agreed upon.

* Move trace propagators to api/trace

The trace propagators tests had to be moved to a testtrace subpackage
to avoid import cycles between api/trace and internal/trace.

Needed to shut up golint about stutter in trace.TraceContext -
TraceContext is a name of a W3C spec, so this stutter is
expected. It's certainly still better than golint's suggestion of
having trace.Context.

* Rename api/propagators to api/propagation

This package will not contain any propagators in the long run, just
the interface definitions.

Co-authored-by: Joshua MacDonald <jmacd@users.noreply.github.com>

api/correlation/context.go

@@ -0,0 +1,31 @@
+package correlation
+
+import (
+	"context"
+
+	"go.opentelemetry.io/otel/api/core"
+)
+
+type correlationsType struct{}
+
+var correlationsKey = &correlationsType{}
+
+// WithMap enters a Map into a new Context.
+func WithMap(ctx context.Context, m Map) context.Context {
+	return context.WithValue(ctx, correlationsKey, m)
+}
+
+// WithMap enters a key:value set into a new Context.
+func NewContext(ctx context.Context, keyvalues ...core.KeyValue) context.Context {
+	return WithMap(ctx, FromContext(ctx).Apply(MapUpdate{
+		MultiKV: keyvalues,
+	}))
+}
+
+// FromContext gets the current Map from a Context.
+func FromContext(ctx context.Context) Map {
+	if m, ok := ctx.Value(correlationsKey).(Map); ok {
+		return m
+	}
+	return NewEmptyMap()
+}

api/correlation/map.go

@@ -0,0 +1,96 @@
+// Copyright 2019, 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 correlation
+
+import (
+	"go.opentelemetry.io/otel/api/core"
+)
+
+// TODO Comments needed! This was formerly known as distributedcontext.Map
+
+type entry struct {
+	value core.Value
+}
+
+type rawMap map[core.Key]entry
+
+type Map struct {
+	m rawMap
+}
+
+type MapUpdate struct {
+	SingleKV core.KeyValue
+	MultiKV  []core.KeyValue
+}
+
+func newMap(raw rawMap) Map {
+	return Map{
+		m: raw,
+	}
+}
+
+func NewEmptyMap() Map {
+	return newMap(nil)
+}
+
+func NewMap(update MapUpdate) Map {
+	return NewEmptyMap().Apply(update)
+}
+
+func (m Map) Apply(update MapUpdate) Map {
+	r := make(rawMap, len(m.m)+len(update.MultiKV))
+	for k, v := range m.m {
+		r[k] = v
+	}
+	if update.SingleKV.Key.Defined() {
+		r[update.SingleKV.Key] = entry{
+			value: update.SingleKV.Value,
+		}
+	}
+	for _, kv := range update.MultiKV {
+		r[kv.Key] = entry{
+			value: kv.Value,
+		}
+	}
+	if len(r) == 0 {
+		r = nil
+	}
+	return newMap(r)
+}
+
+func (m Map) Value(k core.Key) (core.Value, bool) {
+	entry, ok := m.m[k]
+	return entry.value, ok
+}
+
+func (m Map) HasValue(k core.Key) bool {
+	_, has := m.Value(k)
+	return has
+}
+
+func (m Map) Len() int {
+	return len(m.m)
+}
+
+func (m Map) Foreach(f func(kv core.KeyValue) bool) {
+	for k, v := range m.m {
+		if !f(core.KeyValue{
+			Key:   k,
+			Value: v.value,
+		}) {
+			return
+		}
+	}
+}

api/correlation/map_test.go

@@ -0,0 +1,155 @@
+// Copyright 2019, 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 correlation
+
+import (
+	"fmt"
+	"testing"
+
+	"go.opentelemetry.io/otel/api/core"
+	"go.opentelemetry.io/otel/api/key"
+)
+
+func TestMap(t *testing.T) {
+	for _, testcase := range []struct {
+		name    string
+		value   MapUpdate
+		init    []int
+		wantKVs []core.KeyValue
+	}{
+		{
+			name: "NewMap with MultiKV",
+			value: MapUpdate{MultiKV: []core.KeyValue{
+				key.Int64("key1", 1),
+				key.String("key2", "val2")},
+			},
+			init: []int{},
+			wantKVs: []core.KeyValue{
+				key.Int64("key1", 1),
+				key.String("key2", "val2"),
+			},
+		},
+		{
+			name:  "NewMap with SingleKV",
+			value: MapUpdate{SingleKV: key.String("key1", "val1")},
+			init:  []int{},
+			wantKVs: []core.KeyValue{
+				key.String("key1", "val1"),
+			},
+		},
+		{
+			name: "NewMap with MapUpdate",
+			value: MapUpdate{SingleKV: key.Int64("key1", 3),
+				MultiKV: []core.KeyValue{
+					key.String("key1", ""),
+					key.String("key2", "val2")},
+			},
+			init: []int{},
+			wantKVs: []core.KeyValue{
+				key.String("key1", ""),
+				key.String("key2", "val2"),
+			},
+		},
+		{
+			name:    "NewMap with empty MapUpdate",
+			value:   MapUpdate{MultiKV: []core.KeyValue{}},
+			init:    []int{},
+			wantKVs: []core.KeyValue{},
+		},
+		{
+			name: "Map with MultiKV",
+			value: MapUpdate{MultiKV: []core.KeyValue{
+				key.Int64("key1", 1),
+				key.String("key2", "val2")},
+			},
+			init: []int{5},
+			wantKVs: []core.KeyValue{
+				key.Int64("key1", 1),
+				key.String("key2", "val2"),
+				key.Int("key5", 5),
+			},
+		},
+		{
+			name:  "Map with SingleKV",
+			value: MapUpdate{SingleKV: key.String("key1", "val1")},
+			init:  []int{5},
+			wantKVs: []core.KeyValue{
+				key.String("key1", "val1"),
+				key.Int("key5", 5),
+			},
+		},
+		{
+			name: "Map with MapUpdate",
+			value: MapUpdate{SingleKV: key.Int64("key1", 3),
+				MultiKV: []core.KeyValue{
+					key.String("key1", ""),
+					key.String("key2", "val2")},
+			},
+			init: []int{5},
+			wantKVs: []core.KeyValue{
+				key.String("key1", ""),
+				key.String("key2", "val2"),
+				key.Int("key5", 5),
+			},
+		},
+		{
+			name:  "Map with empty MapUpdate",
+			value: MapUpdate{MultiKV: []core.KeyValue{}},
+			init:  []int{5},
+			wantKVs: []core.KeyValue{
+				key.Int("key5", 5),
+			},
+		},
+	} {
+		t.Logf("Running test case %s", testcase.name)
+		var got Map
+		if len(testcase.init) > 0 {
+			got = makeTestMap(testcase.init).Apply(testcase.value)
+		} else {
+			got = NewMap(testcase.value)
+		}
+		for _, s := range testcase.wantKVs {
+			if ok := got.HasValue(s.Key); !ok {
+				t.Errorf("Expected Key %s to have Value", s.Key)
+			}
+			if g, ok := got.Value(s.Key); !ok || g != s.Value {
+				t.Errorf("+got: %v, -want: %v", g, s.Value)
+			}
+		}
+		// test Foreach()
+		got.Foreach(func(kv core.KeyValue) bool {
+			for _, want := range testcase.wantKVs {
+				if kv == want {
+					return false
+				}
+			}
+			t.Errorf("Expected kv %v, but not found", kv)
+			return true
+		})
+		if l, exp := got.Len(), len(testcase.wantKVs); l != exp {
+			t.Errorf("+got: %d, -want: %d", l, exp)
+		}
+	}
+}
+
+func makeTestMap(ints []int) Map {
+	r := make(rawMap, len(ints))
+	for _, v := range ints {
+		r[core.Key(fmt.Sprintf("key%d", v))] = entry{
+			value: core.Int(v),
+		}
+	}
+	return newMap(r)
+}