Add PropagatorInterface and HttpHeaderPropagator (#3)

* Add PropagationFormatterInterface and HttpHeaderFormatter

* Dependency injection for TraceContext propagator

* Code style fix

* HttpHeaderFormatter tests

* Add GrpcMetadataFormatter test (skipped for now)

* RequestHandler now requires a PropagationFormatterInterface.

The RequestTracer new provides the default value.

* Code style for multi-line function declaration.

* Remove extra doc line

* Rename PropagationFormatterInterface -> PropagatorInterface

Also rename Formatter -> Propagator.

* Update documentation for the Propagator classes

Author: chingor13

src/Trace/Propagator/GrpcMetadataPropagator.php

@@ -0,0 +1,71 @@
+<?php
+/**
+ * Copyright 2017 Google Inc. All Rights Reserved.
+ *
+ * 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.
+ */
+
+namespace OpenCensus\Trace\Propagator;
+
+use OpenCensus\Trace\TraceContext;
+
+/**
+ * This propagator will contain the canonical method for propagating
+ * TraceContext over grpc. The specification is not finalized yet. The
+ * current design uses a metadata key `grpc-trace-bin` with a binary
+ * encoding. Do not use this propagator until it's implemented.
+ *
+ * @experimental
+ */
+class GrpcMetadataPropagator implements PropagatorInterface
+{
+    const METADATA_KEY = 'grpc-trace-bin';
+
+    /**
+     * Generate a TraceContext object from the all the HTTP headers
+     *
+     * @param array $metadata
+     * @return TraceContext
+     */
+    public function parse($metadata)
+    {
+        if (array_key_exists(self::METADATA_KEY, $metadata)) {
+            return self::deserialize($metadata[self::METADATA_KEY]);
+        }
+        return new TraceContext();
+    }
+
+    /**
+     * Generate a TraceContext object from the Trace Context header
+     *
+     * @param string $header
+     * @return TraceContext
+     */
+    public function deserialize($bin)
+    {
+        // TODO: implement when spec is finalized
+        return new TraceContext();
+    }
+
+    /**
+     * Convert a TraceContext to header string
+     *
+     * @param TraceContext $context
+     * @return string
+     */
+    public function serialize(TraceContext $context)
+    {
+        // TODO: implement when spec is finalized
+        return '';
+    }
+}

src/Trace/Propagator/HttpHeaderPropagator.php

@@ -0,0 +1,90 @@
+<?php
+/**
+ * Copyright 2017 Google Inc. All Rights Reserved.
+ *
+ * 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.
+ */
+
+namespace OpenCensus\Trace\Propagator;
+
+use OpenCensus\Trace\TraceContext;
+
+/**
+ * This propagator uses HTTP headers to propagate TraceContext over HTTP.
+ * There are two possible headers `X-Cloud-Trace-Context` and `Trace-Context`.
+ * This class handles both formats.
+ *
+ * The current format of the header is <trace-id>[/<span-id>][;o=<options>].
+ * The options are a bitmask of options. Currently the only option is the
+ * least significant bit which signals whether the request was traced or not
+ * (1 = traced, 0 = not traced).
+ */
+class HttpHeaderPropagator implements PropagatorInterface
+{
+    const HTTP_HEADERS = [
+        'HTTP_X_CLOUD_TRACE_CONTEXT',
+        'HTTP_TRACE_CONTEXT'
+    ];
+    const CONTEXT_HEADER_FORMAT = '/([0-9a-f]{32})(?:\/(\d+))?(?:;o=(\d+))?/';
+
+    /**
+     * Generate a TraceContext object from the all the HTTP headers
+     *
+     * @param array $headers
+     * @return TraceContext
+     */
+    public function parse($headers)
+    {
+        foreach (self::HTTP_HEADERS as $header) {
+            if (array_key_exists($header, $headers)) {
+                return self::deserialize($headers[$header]);
+            }
+        }
+        return new TraceContext();
+    }
+
+    /**
+     * Generate a TraceContext object from the Trace Context header
+     *
+     * @param string $header
+     * @return TraceContext
+     */
+    public function deserialize($header)
+    {
+        if (preg_match(self::CONTEXT_HEADER_FORMAT, $header, $matches)) {
+            return new TraceContext(
+                $matches[1],
+                array_key_exists(2, $matches) ? $matches[2] : null,
+                array_key_exists(3, $matches) ? $matches[3] == '1' : null,
+                true
+            );
+        }
+        return new TraceContext();
+    }
+
+    /**
+     * Convert a TraceContext to header string
+     *
+     * @param TraceContext $context
+     * @return string
+     */
+    public function serialize(TraceContext $context)
+    {
+        $ret = '' . $context->traceId();
+        if ($context->spanId()) {
+            $ret .= '/' . $context->spanId();
+        }
+        $ret .= ';o=' . ($context->enabled() ? '1' : '0');
+        return $ret;
+    }
+}

src/Trace/Propagator/PropagatorInterface.php

@@ -0,0 +1,50 @@
+<?php
+/**
+ * Copyright 2017 Google Inc. All Rights Reserved.
+ *
+ * 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.
+ */
+
+namespace OpenCensus\Trace\Propagator;
+
+use OpenCensus\Trace\TraceContext;
+
+/**
+ * This interface lets us define separate TraceContext Propagator formats.
+ */
+interface PropagatorInterface
+{
+    /**
+     * Generate a TraceContext object from the provided container
+     *
+     * @param mixed $container
+     * @return TraceContext
+     */
+    public function parse($container);
+
+    /**
+     * Generate a TraceContext object from the Trace Context header
+     *
+     * @param string $header
+     * @return TraceContext
+     */
+    public function deserialize($header);
+
+    /**
+     * Convert a TraceContext to header string
+     *
+     * @param TraceContext $context
+     * @return string
+     */
+    public function serialize(TraceContext $context);
+}

src/Trace/RequestHandler.php

@@ -24,6 +24,7 @@
 use OpenCensus\Trace\Tracer\ExtensionTracer;
 use OpenCensus\Trace\Tracer\NullTracer;
 use OpenCensus\Trace\Tracer\TracerInterface;
+use OpenCensus\Trace\Propagator\PropagatorInterface;
 
 /**
  * This class manages the logic for sampling and reporting a trace within a
@@ -76,20 +77,26 @@ class RequestHandler
      *
      * @param ReporterInterface $reporter How to report the trace at the end of the request
      * @param SamplerInterface $sampler Which sampler to use for sampling requests
+     * @param PropagatorInterface $propagator TraceContext propagator
      * @param array $options [optional] {
      *      Configuration options. See
      *      {@see OpenCensus\Trace\TraceSpan::__construct()} for the other available options.
      *
      *      @type array $headers Optional array of headers to use in place of $_SERVER
      * }
      */
-    public function __construct(ReporterInterface $reporter, SamplerInterface $sampler, array $options = [])
-    {
+    public function __construct(
+        ReporterInterface $reporter,
+        SamplerInterface $sampler,
+        PropagatorInterface $propagator,
+        array $options = []
+    ) {
         $this->reporter = $reporter;
         $headers = array_key_exists('headers', $options)
             ? $options['headers']
             : $_SERVER;
-        $context = TraceContext::fromHeaders($headers);
+
+        $context = $propagator->parse($headers);
 
         // If the context force disables tracing, don't consult the $sampler.
         if ($context->enabled() !== false) {
@@ -99,7 +106,9 @@ public function __construct(ReporterInterface $reporter, SamplerInterface $sampl
         // If the request was provided with a trace context header, we need to send it back with the response
         // including whether the request was sampled or not.
         if ($context->fromHeader()) {
-            $this->persistContextHeader($context);
+            if (!headers_sent()) {
+                header('X-Cloud-Trace-Context: ' . $propagator->serialize($context));
+            }
         }
 
         $this->tracer = $context->enabled()
@@ -254,11 +263,4 @@ private function detectKey(array $keys, array $array)
         }
         return null;
     }
-
-    private function persistContextHeader($context)
-    {
-        if (!headers_sent()) {
-            header('X-Cloud-Trace-Context: ' . $context);
-        }
-    }
 }

src/Trace/RequestTracer.php

@@ -20,6 +20,8 @@
 use OpenCensus\Trace\Sampler\SamplerFactory;
 use OpenCensus\Trace\Sampler\SamplerInterface;
 use OpenCensus\Trace\Reporter\ReporterInterface;
+use OpenCensus\Trace\Propagator\PropagatorInterface;
+use OpenCensus\Trace\Propagator\HttpHeaderPropagator;
 
 /**
  * This class provides static functions to give you access to the current
@@ -115,6 +117,8 @@ class RequestTracer
      *
      *      @type SamplerInterface|array $sampler Sampler or sampler factory build arguments. See
      *          {@see OpenCensus\Trace\Sampler\SamplerFactory::build()} for the available options.
+     *      @type PropagatorInterface $propagator TraceContext propagator. **Defaults to**
+     *            a new `HttpHeaderPropagator` instance
      *      @type array $headers Optional array of headers to use in place of $_SERVER
      * }
      * @return RequestHandler
@@ -128,7 +132,12 @@ public static function start(ReporterInterface $reporter, array $options = [])
             ? $samplerOptions
             : SamplerFactory::build($samplerOptions);
 
-        return self::$instance = new RequestHandler($reporter, $sampler, $options);
+        $propagator = array_key_exists('propagator', $options)
+            ? $options['propagator']
+            : new HttpHeaderPropagator();
+        unset($options['propagator']);
+
+        return self::$instance = new RequestHandler($reporter, $sampler, $propagator, $options);
     }
 
     /**

src/Trace/TraceContext.php

@@ -34,9 +34,6 @@ class TraceContext
 {
     use IdGeneratorTrait;
 
-    const HTTP_HEADER = 'HTTP_X_CLOUD_TRACE_CONTEXT';
-    const CONTEXT_HEADER_FORMAT = '/([0-9a-f]{32})(?:\/(\d+))?(?:;o=(\d+))?/';
-
     /**
      * @var string The current traceId.
      */
@@ -52,26 +49,6 @@ class TraceContext
      */
     private $enabled;
 
-    /**
-     * Parses a headers array (normally the $_SERVER variable) and builds a TraceContext objects
-     *
-     * @param  array $headers The headers array (normally the $_SERVER variable)
-     * @return TraceContext
-     */
-    public static function fromHeaders($headers)
-    {
-        if (array_key_exists(self::HTTP_HEADER, $headers) &&
-            preg_match(self::CONTEXT_HEADER_FORMAT, $headers[self::HTTP_HEADER], $matches)) {
-            return new static(
-                $matches[1],
-                array_key_exists(2, $matches) ? $matches[2] : null,
-                array_key_exists(3, $matches) ? $matches[3] == '1' : null,
-                true
-            );
-        }
-        return new static();
-    }
-
     /**
      * Creates a new TraceContext instance
      *
@@ -147,20 +124,4 @@ public function fromHeader()
     {
         return $this->fromHeader;
     }
-
-    /**
-     * Returns a string form of the TraceContext. This is the format of the Trace Context Header
-     * and should be forwarded to downstream requests as the X-Cloud-Trace-Context header.
-     *
-     * @return string
-     */
-    public function __toString()
-    {
-        $ret = '' . $this->traceId;
-        if ($this->spanId) {
-            $ret .= '/' . $this->spanId;
-        }
-        $ret .= ';o=' . ($this->enabled ? '1' : '0');
-        return $ret;
-    }
 }