Add resource package

resource/resource.go

@@ -0,0 +1,169 @@
+// Copyright 2018, OpenCensus 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 resource defines the resource type and provides helpers to derive them as well
+// as the generic population through environment variables.
+package resource
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+const (
+	envVarType = "OC_RESOURCE_TYPE"
+	envVarTags = "OC_RESOURCE_TAGS"
+)
+
+// Resource describes an entity about which identifying information and metadata is exposed.
+// For example, a type "k8s.io/container" may hold tags describing the pod name and namespace.
+type Resource struct {
+	Type string
+	Tags map[string]string
+}
+
+// EncodeTags encodes a tags map to a string as provided via the OC_RESOURCE_TAGS environment variable.
+func EncodeTags(tags map[string]string) string {
+	sortedKeys := make([]string, 0, len(tags))
+	for k := range tags {
+		sortedKeys = append(sortedKeys, k)
+	}
+	sort.Strings(sortedKeys)
+
+	s := ""
+	for i, k := range sortedKeys {
+		if i > 0 {
+			s += ","
+		}
+		s += k + "=" + strconv.Quote(tags[k])
+	}
+	return s
+}
+
+var tagRegex = regexp.MustCompile(`\s*([a-zA-Z0-9-_./]+)=(?:(".*?")|([^\s="]+))\s*,`)
+
+// DecodeTags decodes a serialized tag map as used in the OC_RESOURCE_TAGS variable.
+// A list of tags of the form `<key1>=<value1>,<key2>=<value2>,...` is accepted.
+// Domain names and paths are accepted as tag keys. Values may be quoted or unquoted in general.
+// If a value contains whitespaces, =, or " characters, it must always be quoted.
+func DecodeTags(s string) (map[string]string, error) {
+	m := map[string]string{}
+	// Ensure a trailing comma, which allows us to keep the regex simpler
+	s = strings.TrimRight(strings.TrimSpace(s), ",") + ","
+
+	for len(s) > 0 {
+		match := tagRegex.FindStringSubmatch(s)
+		if len(match) == 0 {
+			return nil, fmt.Errorf("invalid tag formatting, remainder: %s", s)
+		}
+		v := match[2]
+		if v == "" {
+			v = match[3]
+		} else {
+			var err error
+			if v, err = strconv.Unquote(v); err != nil {
+				return nil, fmt.Errorf("invalid tag formatting, remainder: %s, err: %s", s, err)
+			}
+		}
+		m[match[1]] = v
+
+		s = s[len(match[0]):]
+	}
+	return m, nil
+}
+
+// FromEnv is a detector that loads resource information from the OC_RESOURCE_TYPE
+// and OC_RESOURCE_TAGS environment variables.
+func FromEnv(context.Context) (*Resource, error) {
+	res := &Resource{
+		Type: strings.TrimSpace(os.Getenv(envVarType)),
+	}
+	tags := strings.TrimSpace(os.Getenv(envVarTags))
+	if tags == "" {
+		return res, nil
+	}
+	var err error
+	if res.Tags, err = DecodeTags(tags); err != nil {
+		return nil, err
+	}
+	return res, nil
+}
+
+var _ Detector = FromEnv
+
+// Merge resource information from b into a. In case of a collision, a takes precedence.
+func Merge(a, b *Resource) *Resource {
+	if a == nil {
+		return b
+	}
+	if b == nil {
+		return a
+	}
+	res := &Resource{
+		Type: a.Type,
+		Tags: map[string]string{},
+	}
+	if res.Type == "" {
+		res.Type = b.Type
+	}
+	for k, v := range b.Tags {
+		res.Tags[k] = v
+	}
+	// Tags from resource a overwrite tags from resource b.
+	for k, v := range a.Tags {
+		res.Tags[k] = v
+	}
+	return res
+}
+
+// Detector attempts to detect resource information.
+// If the detector cannot find resource information, the returned resource is nil but no
+// error is returned.
+// An error is only returned on unexpected failures.
+type Detector func(context.Context) (*Resource, error)
+
+// NewDetectorFromResource returns a detector that will always return resource r.
+func NewDetectorFromResource(r *Resource) Detector {
+	return func(context.Context) (*Resource, error) {
+		return r, nil
+	}
+}
+
+// ChainedDetector returns a Detector that calls all input detectors sequentially an
+// merges each result with the previous one.
+// It returns on the first error that a sub-detector encounters.
+func ChainedDetector(detectors ...Detector) Detector {
+	return func(ctx context.Context) (*Resource, error) {
+		return detectAll(ctx, detectors...)
+	}
+}
+
+// detectall calls all input detectors sequentially an merges each result with the previous one.
+// It returns on the first error that a sub-detector encounters.
+func detectAll(ctx context.Context, detectors ...Detector) (*Resource, error) {
+	var res *Resource
+	for _, d := range detectors {
+		r, err := d(ctx)
+		if err != nil {
+			return nil, err
+		}
+		res = Merge(res, r)
+	}
+	return res, nil
+}

resource/resource_test.go

@@ -0,0 +1,174 @@
+// Copyright 2018, OpenCensus 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 resource
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"reflect"
+	"testing"
+)
+
+func TestMerge(t *testing.T) {
+	cases := []struct {
+		a, b, want *Resource
+	}{
+		{
+			a: &Resource{
+				Type: "t1",
+				Tags: map[string]string{"a": "1", "b": "2"},
+			},
+			b: &Resource{
+				Type: "t2",
+				Tags: map[string]string{"a": "1", "b": "3", "c": "4"},
+			},
+			want: &Resource{
+				Type: "t1",
+				Tags: map[string]string{"a": "1", "b": "2", "c": "4"},
+			},
+		},
+		{
+			a: nil,
+			b: &Resource{
+				Type: "t1",
+				Tags: map[string]string{"a": "1"},
+			},
+			want: &Resource{
+				Type: "t1",
+				Tags: map[string]string{"a": "1"},
+			},
+		},
+		{
+			a: &Resource{
+				Type: "t1",
+				Tags: map[string]string{"a": "1"},
+			},
+			b: nil,
+			want: &Resource{
+				Type: "t1",
+				Tags: map[string]string{"a": "1"},
+			},
+		},
+	}
+	for i, c := range cases {
+		t.Run(fmt.Sprintf("case-%d", i), func(t *testing.T) {
+			res := Merge(c.a, c.b)
+			if !reflect.DeepEqual(res, c.want) {
+				t.Fatalf("unwanted result: want %+v, got %+v", c.want, res)
+			}
+		})
+	}
+}
+
+func TestDecodeTags(t *testing.T) {
+	cases := []struct {
+		encoded  string
+		wantTags map[string]string
+		wantFail bool
+	}{
+		{
+			encoded:  `example.org/test-1="test ¥ \"" ,un=quøted,  Abc=Def`,
+			wantTags: map[string]string{"example.org/test-1": "test ¥ \"", "un": "quøted", "Abc": "Def"},
+		}, {
+			encoded:  `single=key`,
+			wantTags: map[string]string{"single": "key"},
+		},
+		{encoded: `invalid-char-ü=test`, wantFail: true},
+		{encoded: `missing="trailing-quote`, wantFail: true},
+		{encoded: `missing=leading-quote"`, wantFail: true},
+		{encoded: `extra=chars, a`, wantFail: true},
+		{encoded: `a, extra=chars`, wantFail: true},
+	}
+	for i, c := range cases {
+		t.Run(fmt.Sprintf("case-%d", i), func(t *testing.T) {
+			res, err := DecodeTags(c.encoded)
+			if err != nil && !c.wantFail {
+				t.Fatalf("unwanted error: %s", err)
+			}
+			if c.wantFail && err == nil {
+				t.Fatalf("wanted failure but got none, result: %v", res)
+			}
+			if !reflect.DeepEqual(res, c.wantTags) {
+				t.Fatalf("wanted result %v, got %v", c.wantTags, res)
+			}
+		})
+	}
+}
+
+func TestEncodeTags(t *testing.T) {
+	got := EncodeTags(map[string]string{
+		"example.org/test-1": "test ¥ \"",
+		"un":                 "quøted",
+		"Abc":                "Def",
+	})
+	if want := `Abc="Def",example.org/test-1="test ¥ \"",un="quøted"`; got != want {
+		t.Fatalf("got %q, want %q", got, want)
+	}
+}
+
+func TestNewDetectorFromResource(t *testing.T) {
+	got, err := NewDetectorFromResource(&Resource{
+		Type: "t",
+		Tags: map[string]string{"a": "1", "b": "2"},
+	})(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %s", err)
+	}
+	want := &Resource{
+		Type: "t",
+		Tags: map[string]string{"a": "1", "b": "2"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected resource: want %v, got %v", want, got)
+	}
+}
+
+func TestChainedDetector(t *testing.T) {
+	got, err := ChainedDetector(
+		NewDetectorFromResource(&Resource{
+			Type: "t1",
+			Tags: map[string]string{"a": "1", "b": "2"},
+		}),
+		NewDetectorFromResource(&Resource{
+			Type: "t2",
+			Tags: map[string]string{"a": "11", "c": "3"},
+		}),
+	)(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %s", err)
+	}
+	want := &Resource{
+		Type: "t1",
+		Tags: map[string]string{"a": "1", "b": "2", "c": "3"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected resource: want %v, got %v", want, got)
+	}
+
+	wantErr := errors.New("err1")
+	got, err = ChainedDetector(
+		NewDetectorFromResource(&Resource{
+			Type: "t1",
+			Tags: map[string]string{"a": "1", "b": "2"},
+		}),
+		func(context.Context) (*Resource, error) {
+			return nil, wantErr
+		},
+	)(context.Background())
+	if err != wantErr {
+		t.Fatalf("unexpected error: want %v, got %v", wantErr, err)
+	}
+}