WIP: Span

opentracing-api/src/lib.rs

@@ -1,9 +1,13 @@
 #![doc(html_root_url = "https://docs.rs/opentracing-api/0.1.0")]
 
 mod context;
-mod tag;
 mod field;
+mod reference;
+mod span;
+mod tag;
 
 pub use context::SpanContext;
-pub use tag::{ParseTagsError, Tags};
 pub use field::{Fields, ParseFieldsError};
+pub use reference::{ParseReferencesError, References};
+pub use span::{FinishedSpan, Span};
+pub use tag::{ParseTagsError, TagValue, Tags};

opentracing-api/src/reference.rs

@@ -0,0 +1,102 @@
+use std::fmt;
+use std::error::Error;
+use std::str::FromStr;
+
+const REF_CHILD_OF: &str = "child_of";
+const REF_FOLLOWS_FROM: &str = "follows_from";
+
+/// References provide a namespace for official OpenTracing reference types.
+#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
+pub enum References {
+    /// See http://opentracing.io/spec/#causal-span-references for
+    /// more information about ChildOf references.
+    ChildOf,
+    /// See http://opentracing.io/spec/#causal-span-references for
+    /// more information about FollowsFrom references.
+    FollowsFrom,
+}
+
+impl References {
+    /// Returns the string representation for the enum reference variant.
+    pub fn as_str(&self) -> &'static str {
+        match *self {
+            References::ChildOf => REF_CHILD_OF,
+            References::FollowsFrom => REF_FOLLOWS_FROM,
+        }
+    }
+}
+
+impl fmt::Display for References {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}", self.as_str())
+    }
+}
+
+impl FromStr for References {
+    type Err = ParseReferencesError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            REF_CHILD_OF => Ok(References::ChildOf),
+            REF_FOLLOWS_FROM => Ok(References::FollowsFrom),
+            _ => Err(ParseReferencesError::UnknownReference),
+        }
+    }
+}
+
+/// Describes errors which can happen while parsing into the `References` enum.
+#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
+pub enum ParseReferencesError {
+    /// The provided reference is not known.
+    UnknownReference,
+}
+
+impl Error for ParseReferencesError {
+    fn description(&self) -> &str {
+        match *self {
+            ParseReferencesError::UnknownReference => "Unknown Reference",
+        }
+    }
+
+    fn cause(&self) -> Option<&Error> {
+        None
+    }
+}
+
+impl fmt::Display for ParseReferencesError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}", self.description())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+
+    use super::*;
+
+    #[test]
+    fn test_reference_as_str() {
+        assert_eq!("child_of", References::ChildOf.as_str());
+        assert_eq!("follows_from", References::FollowsFrom.as_str());
+    }
+
+    #[test]
+    fn test_reference_as_string() {
+        assert_eq!(String::from("child_of"), References::ChildOf.to_string());
+        assert_eq!(
+            String::from("follows_from"),
+            References::FollowsFrom.to_string()
+        );
+    }
+
+    #[test]
+    fn test_reference_from_string() {
+        assert_eq!(Ok(References::ChildOf), References::from_str("child_of"));
+        assert_eq!(Ok(References::FollowsFrom), "follows_from".parse());
+        assert_eq!(
+            Err(ParseReferencesError::UnknownReference),
+            References::from_str("some_other_field")
+        );
+    }
+
+}

opentracing-api/src/span.rs

@@ -0,0 +1,83 @@
+use SpanContext;
+use TagValue;
+
+/// The `Span` represents the OpenTracing specification's Span contract.
+pub trait Span<'a> {
+    /// The associated `SpanContext`.
+    type Context: SpanContext<'a>;
+
+    /// Retrieve the associated `SpanContext`.
+    ///
+    /// This may be called any time, including after `finish`.
+    fn context(&self) -> &Self::Context;
+
+    /// Sets a key:value tag on the `Span`.
+    fn set_tag<S>(&mut self, key: S, value: TagValue)
+    where
+        S: Into<String>;
+
+    /// Allows to unset a tag based on the given key. Noop if
+    /// it doesn't exist.
+    fn unset_tag<S>(&mut self, key: S)
+    where
+        S: Into<String>;
+
+    /// Returns a tag value if set, none otherwise
+    fn tag<S>(&self, key: S) -> Option<&TagValue>
+    where
+        S: Into<String>;
+
+    /// Record an event at the current walltime timestamp.
+    fn log(&mut self, event: String);
+
+    /// Record an event at the given walltime timestamp.
+    fn log_at(&mut self, timestamp: u64, event: String);
+
+    /// Sets a baggage item in the Span (and its SpanContext) as a key/value pair.
+    fn set_baggage_item<S>(&mut self, key: S, value: String)
+    where
+        S: Into<String>;
+
+    /// Allows to unset a baggage item based on the given key. Noop if
+    /// it doesn't exist.
+    fn unset_baggage_item<S>(&mut self, key: S)
+    where
+        S: Into<String>;
+
+    /// the value of the baggage item identified by the given key, or None if no such item
+    /// could be found.
+    fn baggage_item<S>(&self, key: S) -> Option<&String>
+    where
+        S: Into<String>;
+
+    /// Sets the string name for the logical operation this span represents.
+    fn set_operation_name<S>(&mut self, name: S)
+    where
+        S: Into<String>;
+
+    /// Returns the operation name if set, None otherwise.
+    fn operation_name(&self) -> &String;
+
+    /// Sets the end timestamp to now and finishes (records) the span.
+    fn finish(self) -> FinishedSpan<Self::Context>;
+
+    /// Sets an explicit end timestamp and finishes (records) the span.
+    fn finish_at(self, timestamp: u64) -> FinishedSpan<Self::Context>;
+}
+
+pub struct FinishedSpan<C> {
+    context: C,
+}
+
+impl<'a, C> FinishedSpan<C>
+where
+    C: SpanContext<'a>,
+{
+    pub fn new(context: C) -> Self {
+        FinishedSpan { context }
+    }
+
+    pub fn context(&self) -> &C {
+        &self.context
+    }
+}

opentracing-api/src/tag.rs

@@ -171,6 +171,26 @@ impl fmt::Display for ParseTagsError {
     }
 }
 
+/// Tags Values per spec can be Strings, Booleans or Numerics.
+///
+/// Note that isize and usize are not included here since they
+/// are only meant to be used as pointers-sized types only.
+#[derive(Clone, PartialEq, PartialOrd, Debug)]
+pub enum TagValue {
+    String(String),
+    Boolean(bool),
+    I8(i8),
+    I16(i16),
+    I32(i32),
+    I64(i64),
+    U8(u8),
+    U16(u16),
+    U32(u32),
+    U64(u64),
+    F32(f32),
+    F64(f64),
+}
+
 #[cfg(test)]
 mod tests {