1// Copyright 2017, OpenCensus Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15// Package propagation implements the binary trace context format.
16package propagation // import "go.opencensus.io/trace/propagation"
17
18// TODO: link to external spec document.
19
20// BinaryFormat format:
21//
22// Binary value: <version_id><version_format>
23// version_id: 1 byte representing the version id.
24//
25// For version_id = 0:
26//
27// version_format: <field><field>
28// field_format: <field_id><field_format>
29//
30// Fields:
31//
32// TraceId: (field_id = 0, len = 16, default = "0000000000000000") - 16-byte array representing the trace_id.
33// SpanId: (field_id = 1, len = 8, default = "00000000") - 8-byte array representing the span_id.
34// TraceOptions: (field_id = 2, len = 1, default = "0") - 1-byte array representing the trace_options.
35//
36// Fields MUST be encoded using the field id order (smaller to higher).
37//
38// Valid value example:
39//
40// {0, 0, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 1, 97,
41// 98, 99, 100, 101, 102, 103, 104, 2, 1}
42//
43// version_id = 0;
44// trace_id = {64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79}
45// span_id = {97, 98, 99, 100, 101, 102, 103, 104};
46// trace_options = {1};
47
48import (
49	"net/http"
50
51	"go.opencensus.io/trace"
52)
53
54// Binary returns the binary format representation of a SpanContext.
55//
56// If sc is the zero value, Binary returns nil.
57func Binary(sc trace.SpanContext) []byte {
58	if sc == (trace.SpanContext{}) {
59		return nil
60	}
61	var b [29]byte
62	copy(b[2:18], sc.TraceID[:])
63	b[18] = 1
64	copy(b[19:27], sc.SpanID[:])
65	b[27] = 2
66	b[28] = uint8(sc.TraceOptions)
67	return b[:]
68}
69
70// FromBinary returns the SpanContext represented by b.
71//
72// If b has an unsupported version ID or contains no TraceID, FromBinary
73// returns with ok==false.
74func FromBinary(b []byte) (sc trace.SpanContext, ok bool) {
75	if len(b) == 0 || b[0] != 0 {
76		return trace.SpanContext{}, false
77	}
78	b = b[1:]
79	if len(b) >= 17 && b[0] == 0 {
80		copy(sc.TraceID[:], b[1:17])
81		b = b[17:]
82	} else {
83		return trace.SpanContext{}, false
84	}
85	if len(b) >= 9 && b[0] == 1 {
86		copy(sc.SpanID[:], b[1:9])
87		b = b[9:]
88	}
89	if len(b) >= 2 && b[0] == 2 {
90		sc.TraceOptions = trace.TraceOptions(b[1])
91	}
92	return sc, true
93}
94
95// HTTPFormat implementations propagate span contexts
96// in HTTP requests.
97//
98// SpanContextFromRequest extracts a span context from incoming
99// requests.
100//
101// SpanContextToRequest modifies the given request to include the given
102// span context.
103type HTTPFormat interface {
104	SpanContextFromRequest(req *http.Request) (sc trace.SpanContext, ok bool)
105	SpanContextToRequest(sc trace.SpanContext, req *http.Request)
106}
107
108// TODO(jbd): Find a more representative but short name for HTTPFormat.
109