Introduce model translation and encoding interfaces

model/README.md

@@ -0,0 +1,9 @@
+# Protocols
+
+This package provides common ways for decoding serialized bytes into protocol-specific in-memory data models (e.g. Zipkin Span). These data models can then be translated to internal pdata representations. Similarly, pdata can be translated from a data model which can then be serialized into bytes.
+
+[serializer](serializer): Common interfaces for serializing/deserializing bytes from/to protocol-specific data models.
+
+[translator](translator): Common interfaces for translating protocol-specific data models from/to pdata.
+
+This package provides higher level APIs that do both encoding of bytes and data model if going directly pdata ⇔ bytes.

model/serializer/deserialize.go

@@ -0,0 +1,30 @@
+// 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 encoding
+
+// MetricsDeserializer decodes bytes into protocol-specific data model.
+type MetricsDeserializer interface {
+	DeserializeMetrics(bytes []byte) (interface{}, error)
+}
+
+// TracesDeserializer decodes bytes into protocol-specific data model.
+type TracesDeserializer interface {
+	DeserializeTraces(bytes []byte) (interface{}, error)
+}
+
+// LogsDeserializer decodes bytes into protocol-specific data model.
+type LogsDeserializer interface {
+	DeserializeLogs(bytes []byte) (interface{}, error)
+}

model/serializer/serialize.go

@@ -0,0 +1,30 @@
+// 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 encoding
+
+// MetricsSerializer encodes protocol-specific data model into bytes.
+type MetricsSerializer interface {
+	SerializeMetrics(model interface{}) ([]byte, error)
+}
+
+// TracesSerializer encodes protocol-specific data model into bytes.
+type TracesSerializer interface {
+	SerializeTraces(model interface{}) ([]byte, error)
+}
+
+// LogsSerializer encodes protocol-specific data model into bytes.
+type LogsSerializer interface {
+	SerializeLogs(model interface{}) ([]byte, error)
+}

model/serializer/serializer.go

@@ -0,0 +1,43 @@
+// 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 encoding
+
+import "fmt"
+
+// Encoding is the encoding format that a model is serialized to.
+type Encoding string
+
+const (
+	Protobuf Encoding = "protobuf"
+	JSON     Encoding = "json"
+	Thrift   Encoding = "thrift"
+)
+
+func (e Encoding) String() string {
+	return string(e)
+}
+
+// ErrUnavailableEncoding is returned when the requested encoding is not supported.
+type ErrUnavailableEncoding struct {
+	encoding Encoding
+}
+
+func (e *ErrUnavailableEncoding) Error() string {
+	return fmt.Sprintf("unsupported encoding %q", e.encoding)
+}
+
+func NewErrUnavailableEncoding(encoding Encoding) *ErrUnavailableEncoding {
+	return &ErrUnavailableEncoding{encoding: encoding}
+}

model/serializer/serializer_test.go

@@ -0,0 +1,31 @@
+// 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 encoding
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewErrUnavailableEncoding(t *testing.T) {
+	err := NewErrUnavailableEncoding("unknown")
+	assert.IsType(t, &ErrUnavailableEncoding{}, err)
+	assert.EqualError(t, err, `unsupported encoding "unknown"`)
+}
+
+func TestEncoding_String(t *testing.T) {
+	assert.Equal(t, "protobuf", Protobuf.String())
+}

model/translator/decoder.go

@@ -0,0 +1,38 @@
+// 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 translation
+
+import "go.opentelemetry.io/collector/consumer/pdata"
+
+type MetricsDecoder interface {
+	// ToMetrics converts a protocol-specific data model into pdata.
+	ToMetrics(src interface{}) (pdata.Metrics, error)
+	// NewModel returns an instance of the model.
+	NewModel() interface{}
+}
+
+type TracesDecoder interface {
+	// ToTraces converts a protocol-specific data model into pdata.
+	ToTraces(src interface{}) (pdata.Traces, error)
+	// NewModel returns an instance of the model.
+	NewModel() interface{}
+}
+
+type LogsDecoder interface {
+	// ToLogs converts a protocol-specific data model into pdata.
+	ToLogs(src interface{}) (pdata.Logs, error)
+	// NewModel returns an instance of the model.
+	NewModel() interface{}
+}

model/translator/encoder.go

@@ -0,0 +1,38 @@
+// 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 translation
+
+import "go.opentelemetry.io/collector/consumer/pdata"
+
+type MetricsEncoder interface {
+	// FromMetrics converts pdata to protocol-specific data model.
+	FromMetrics(md pdata.Metrics, out interface{}) error
+	// NewModel returns an instance of the model.
+	NewModel() interface{}
+}
+
+type TracesEncoder interface {
+	// FromTraces converts pdata to protocol-specific data model.
+	FromTraces(md pdata.Traces, out interface{}) error
+	// NewModel returns an instance of the model.
+	NewModel() interface{}
+}
+
+type LogsEncoder interface {
+	// FromLogs converts pdata to protocol-specific data model.
+	FromLogs(md pdata.Logs, out interface{}) error
+	// NewModel returns an instance of the model.
+	NewModel() interface{}
+}

model/translator/translator.go

@@ -0,0 +1,37 @@
+// 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 translation
+
+import (
+	"fmt"
+)
+
+// ErrIncompatibleType details a type conversion error during translation.
+type ErrIncompatibleType struct {
+	given    interface{}
+	expected interface{}
+}
+
+func (i *ErrIncompatibleType) Error() string {
+	return fmt.Sprintf("expected model type %T but given %T", i.expected, i.given)
+}
+
+// NewErrIncompatibleType returns ErrIncompatibleType instance
+func NewErrIncompatibleType(expected, given interface{}) *ErrIncompatibleType {
+	return &ErrIncompatibleType{
+		given:    given,
+		expected: expected,
+	}
+}

model/translator/translator_test.go

@@ -0,0 +1,28 @@
+// 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 translation
+
+import (
+	"testing"
+
+	zipkinmodel "github.com/openzipkin/zipkin-go/model"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewErrIncompatibleType(t *testing.T) {
+	err := NewErrIncompatibleType([]*zipkinmodel.SpanModel{}, "given")
+	assert.IsType(t, &ErrIncompatibleType{}, err)
+	assert.EqualError(t, err, "expected model type []*model.SpanModel but given string")
+}