refactor to include interface and mock example (#129)

src/OpenTracing/Mock/Propagators.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.IO;
 using OpenTracing.Propagation;
 
 namespace OpenTracing.Mock
@@ -9,6 +10,8 @@ public static class Propagators
         public static readonly IPropagator Console = new ConsolePropagator();
 
         public static readonly IPropagator TextMap = new TextMapPropagator();
+
+        public static readonly IPropagator Binary = new BinaryPropagator();
     }
 
     /// <summary>
@@ -21,6 +24,82 @@ public interface IPropagator
         MockSpanContext Extract<TCarrier>(IFormat<TCarrier> format, TCarrier carrier);
     }
 
+    public sealed class BinaryPropagator : IPropagator
+    {
+        public class BinaryContext
+        {
+            public string TraceId { get; set; }
+            public string SpanId { get; set; }
+        }
+
+        public void Inject<TCarrier>(MockSpanContext context, IFormat<TCarrier> format, TCarrier carrier)
+        {
+            if (carrier is IBinary stream)
+            {
+                var contextObject = new BinaryContext
+                {
+                    SpanId = context.SpanId, TraceId = context.TraceId
+                };
+                var serialContext = Serialize(contextObject);
+                stream.Set(serialContext);
+            }
+            else
+            {
+                throw new InvalidOperationException($"Unknown carrier [{carrier.GetType()}]");
+            }
+        }
+
+        public MockSpanContext Extract<TCarrier>(IFormat<TCarrier> format, TCarrier carrier)
+        {
+            string traceId = "";
+            string spanId = "";
+
+            if (carrier is IBinary stream)
+            {
+                var ctx = Deserialize(stream.Get());
+                traceId = ctx.TraceId;
+                spanId = ctx.SpanId;
+            }
+            else
+            {
+                throw new InvalidOperationException($"Unknown carrier [{carrier.GetType()}]");
+            }
+
+            if (!string.IsNullOrEmpty(traceId) && !string.IsNullOrEmpty(spanId))
+            {
+                return new MockSpanContext(traceId, spanId, null);
+            }
+
+            return null;
+        }
+
+        public MemoryStream Serialize(BinaryContext ctx)
+        {
+            using (var ms = new MemoryStream())
+            {
+                using (var writer = new BinaryWriter(ms))
+                {
+                    writer.Write(ctx.SpanId);
+                    writer.Write(ctx.TraceId);
+                }
+
+                return ms;
+            }
+        }
+
+        public BinaryContext Deserialize(MemoryStream stream)
+        {
+            var res = new BinaryContext();
+            using (var reader = new BinaryReader(stream))
+            {
+                res.SpanId = reader.ReadString();
+                res.TraceId = reader.ReadString();
+            }
+
+            return res;
+        }
+    }
+
     public sealed class ConsolePropagator : IPropagator
     {
         public void Inject<TCarrier>(MockSpanContext context, IFormat<TCarrier> format, TCarrier carrier)

src/OpenTracing/Propagation/BinaryExtractAdapter.cs

@@ -0,0 +1,34 @@
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+
+namespace OpenTracing.Propagation
+{
+    /// <summary>
+    /// A <see cref="IBinary"/> carrier for use with <see cref="ITracer.Extract{TCarrier}"/> only. It cannot be mutated, only read.
+    /// </summary>
+    /// <seealso cref="ITracer.Extract{TCarrier}"/>
+    public class BinaryExtractAdapter : IBinary
+    {
+        private readonly MemoryStream _stream;
+
+        public BinaryExtractAdapter(MemoryStream stream)
+        {
+            _stream = stream;
+        }
+
+        /// <inheritdoc />
+        public void Set(MemoryStream stream)
+        {
+            throw new NotSupportedException($"{nameof(BinaryExtractAdapter)} should only be used with {nameof(ITracer)}.{nameof(ITracer.Extract)}");
+        }
+
+        /// <inheritdoc />
+        public MemoryStream Get()
+        {
+            return _stream;
+        }
+    }
+}

src/OpenTracing/Propagation/BinaryInjectAdapter.cs

@@ -0,0 +1,32 @@
+using System;
+using System.IO;
+
+namespace OpenTracing.Propagation
+{
+    /// <summary>
+    /// A <see cref="IBinary"/> carrier for use with <see cref="ITracer.Inject{TCarrier}"/> only. It cannot be read, only set.
+    /// </summary>
+    /// <seealso cref="ITracer.Extract{TCarrier}"/>
+    public class BinaryInjectAdapter : IBinary
+    {
+        private MemoryStream _stream;
+
+        public BinaryInjectAdapter(MemoryStream stream)
+        {
+            _stream = stream;
+        }
+
+        /// <inheritdoc />
+        public void Set(MemoryStream stream)
+        {
+            _stream = stream;
+        }
+
+        /// <inheritdoc />
+        public MemoryStream Get()
+        {
+            throw new NotSupportedException($"{nameof(BinaryInjectAdapter)} should only be used with {nameof(ITracer)}.{nameof(ITracer.Inject)}");
+        }
+
+    }
+}

src/OpenTracing/Propagation/BuiltinFormats.cs

@@ -30,13 +30,12 @@ public static class BuiltinFormats
         /// <summary>
         /// The 'Binary' format allows for unconstrained byte encoding of <see cref="ISpanContext"/> state
         /// for <see cref="ITracer.Inject{TCarrier}"/> and <see cref="ITracer.Extract{TCarrier}"/> using a <see cref="MemoryStream"/>.
-        /// Note that this should be considered experimental, and subject to change.
         /// </summary>
         /// <seealso cref="ITracer.Inject{TCarrier}"/>
         /// <seealso cref="ITracer.Extract{TCarrier}"/>
         /// <seealso cref="IFormat{TCarrier}"/>
         /// <seealso cref="byte"/>
-        public static readonly IFormat<Stream> Binary = new Builtin<Stream>("BINARY");
+        public static readonly IFormat<IBinary> Binary = new Builtin<IBinary>("BINARY");
 
         private struct Builtin<TCarrier> : IFormat<TCarrier>
         {

src/OpenTracing/Propagation/IBinary.cs

@@ -0,0 +1,26 @@
+using System.Collections.Generic;
+using System.IO;
+
+namespace OpenTracing.Propagation
+{
+    /// <summary>
+    /// <see cref="IBinary"/> is a built-in carrier for <see cref="ITracer.Inject{TCarrier}"/> and
+    /// <see cref="ITracer.Extract{TCarrier}"/>. IBinary implementations allow for the reading and writing of arbitrary streams.
+    /// </summary>
+    /// <seealso cref="ITracer.Inject{TCarrier}"/>
+    /// <seealso cref="ITracer.Extract{TCarrier}"/>
+    public interface IBinary
+    {
+        /// <summary>
+        /// Sets the backing MemoryStream of an <see cref="IBinary"/> store.
+        /// </summary>
+        /// <param name="stream">A memory-backed stream.</param>
+        void Set(MemoryStream stream);
+
+        /// <summary>
+        /// Gets the backing MemoryStream of an <see cref="IBinary"/> store.
+        /// </summary>
+        /// <returns></returns>
+        MemoryStream Get();
+    }
+}