Standardize trace headers

Brings it in line with the naming of other headers we have; sets us up to remove the unstable feature gate.

Author: yoshuawuyts

src/headers/constants.rs

@@ -143,6 +143,9 @@ pub const SERVER_TIMING: HeaderName = HeaderName::from_lowercase_str("server-tim
 ///  The `Te` Header
 pub const TE: HeaderName = HeaderName::from_lowercase_str("te");
 
+///  The `Traceparent` Header
+pub const TRACEPARENT: HeaderName = HeaderName::from_lowercase_str("traceparent");
+
 ///  The `Trailer` Header
 pub const TRAILER: HeaderName = HeaderName::from_lowercase_str("trailer");
 

src/trace/trace_context.rs

@@ -1,9 +1,9 @@
 use rand::Rng;
 use std::fmt;
 
-use crate::Headers;
+use crate::headers::{HeaderName, HeaderValue, Headers, TRACEPARENT};
 
-/// Extract and inject [Trace-Context](https://w3c.github.io/trace-context/) headers.
+/// Extract and apply [Trace-Context](https://w3c.github.io/trace-context/) headers.
 ///
 /// ## Examples
 ///
@@ -13,11 +13,11 @@ use crate::Headers;
 /// let mut res = http_types::Response::new(200);
 ///
 /// res.insert_header(
-///     "traceparent",
+///     TRACEPARENT,
 ///     "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
 /// );
 ///
-/// let context = TraceContext::extract(&res).unwrap();
+/// let context = TraceContext::from_headers(&res).unwrap();
 ///
 /// let trace_id = u128::from_str_radix("0af7651916cd43dd8448eb211c80319c", 16);
 /// let parent_id = u64::from_str_radix("00f067aa0ba902b7", 16);
@@ -36,6 +36,32 @@ pub struct TraceContext {
 }
 
 impl TraceContext {
+    /// Generate a new TraceContect object without a parent.
+    ///
+    /// By default root TraceContext objects are sampled.
+    /// To mark it unsampled, call `context.set_sampled(false)`.
+    ///
+    /// ## Examples
+    /// ```
+    /// use http_types::trace::TraceContext;
+    ///
+    /// let context = TraceContext::new();
+    ///
+    /// assert_eq!(context.parent_id(), None);
+    /// assert_eq!(context.sampled(), true);
+    /// ```
+    pub fn new() -> Self {
+        let mut rng = rand::thread_rng();
+
+        Self {
+            id: rng.gen(),
+            version: 0,
+            trace_id: rng.gen(),
+            parent_id: None,
+            flags: 1,
+        }
+    }
+
     /// Create and return TraceContext object based on `traceparent` HTTP header.
     ///
     /// ## Examples
@@ -44,11 +70,11 @@ impl TraceContext {
     ///
     /// let mut res = http_types::Response::new(200);
     /// res.insert_header(
-    ///   "traceparent",
+    ///   TRACEPARENT,
     ///   "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
     /// );
     ///
-    /// let context = TraceContext::extract(&res).unwrap();
+    /// let context = TraceContext::from_headers(&res).unwrap();
     ///
     /// let trace_id = u128::from_str_radix("0af7651916cd43dd8448eb211c80319c", 16);
     /// let parent_id = u64::from_str_radix("00f067aa0ba902b7", 16);
@@ -57,13 +83,13 @@ impl TraceContext {
     /// assert_eq!(context.parent_id(), parent_id.ok());
     /// assert_eq!(context.sampled(), true);
     /// ```
-    pub fn extract(headers: impl AsRef<Headers>) -> crate::Result<Self> {
+    pub fn from_headers(headers: impl AsRef<Headers>) -> crate::Result<Self> {
         let headers = headers.as_ref();
         let mut rng = rand::thread_rng();
 
-        let traceparent = match headers.get("traceparent") {
+        let traceparent = match headers.get(TRACEPARENT) {
             Some(header) => header.as_str(),
-            None => return Ok(Self::new_root()),
+            None => return Ok(Self::new()),
         };
 
         let parts: Vec<&str> = traceparent.split('-').collect();
@@ -77,32 +103,6 @@ impl TraceContext {
         })
     }
 
-    /// Generate a new TraceContect object without a parent.
-    ///
-    /// By default root TraceContext objects are sampled.
-    /// To mark it unsampled, call `context.set_sampled(false)`.
-    ///
-    /// ## Examples
-    /// ```
-    /// use http_types::trace::TraceContext;
-    ///
-    /// let context = TraceContext::new_root();
-    ///
-    /// assert_eq!(context.parent_id(), None);
-    /// assert_eq!(context.sampled(), true);
-    /// ```
-    pub fn new_root() -> Self {
-        let mut rng = rand::thread_rng();
-
-        Self {
-            id: rng.gen(),
-            version: 0,
-            trace_id: rng.gen(),
-            parent_id: None,
-            flags: 1,
-        }
-    }
-
     /// Add the traceparent header to the http headers
     ///
     /// ## Examples
@@ -112,24 +112,35 @@ impl TraceContext {
     ///
     /// let mut req = Request::new(Method::Get, Url::parse("https://example.com").unwrap());
     /// req.insert_header(
-    ///   "traceparent",
+    ///   TRACEPARENT,
     ///   "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
     /// );
     ///
-    /// let parent = TraceContext::extract(&req).unwrap();
+    /// let parent = TraceContext::from_headers(&req).unwrap();
     ///
     /// let mut res = Response::new(200);
-    /// parent.inject(&mut res);
+    /// parent.apply(&mut res);
     ///
-    /// let child = TraceContext::extract(&res).unwrap();
+    /// let child = TraceContext::from_headers(&res).unwrap();
     ///
     /// assert_eq!(child.version(), parent.version());
     /// assert_eq!(child.trace_id(), parent.trace_id());
     /// assert_eq!(child.parent_id(), Some(parent.id()));
     /// ```
-    pub fn inject(&self, mut headers: impl AsMut<Headers>) {
+    pub fn apply(&self, mut headers: impl AsMut<Headers>) {
         let headers = headers.as_mut();
-        headers.insert("traceparent", format!("{}", self));
+        headers.insert(TRACEPARENT, self.value());
+    }
+
+    /// Get the `HeaderName`.
+    pub fn name(&self) -> HeaderName {
+        TRACEPARENT
+    }
+
+    /// Get the `HeaderValue`.
+    pub fn value(&self) -> HeaderValue {
+        let output = format!("{}", self);
+        unsafe { HeaderValue::from_bytes_unchecked(output.into()) }
     }
 
     /// Generate a child of the current TraceContext and return it.
@@ -182,8 +193,8 @@ impl TraceContext {
     /// use http_types::Response;
     ///
     /// let mut res = Response::new(200);
-    /// res.insert_header("traceparent", "00-00000000000000000000000000000001-0000000000000002-01");
-    /// let context = TraceContext::extract(&res).unwrap();
+    /// res.insert_header(TRACEPARENT, "00-00000000000000000000000000000001-0000000000000002-01");
+    /// let context = TraceContext::from_headers(&res).unwrap();
     /// assert_eq!(context.sampled(), true);
     /// ```
     pub fn sampled(&self) -> bool {
@@ -197,7 +208,7 @@ impl TraceContext {
     /// ```
     /// use http_types::trace::TraceContext;
     ///
-    /// let mut context = TraceContext::new_root();
+    /// let mut context = TraceContext::new();
     /// assert_eq!(context.sampled(), true);
     /// context.set_sampled(false);
     /// assert_eq!(context.sampled(), false);
@@ -225,8 +236,8 @@ mod test {
     #[test]
     fn default() -> crate::Result<()> {
         let mut headers = crate::Headers::new();
-        headers.insert("traceparent", "00-01-deadbeef-00");
-        let context = TraceContext::extract(&mut headers)?;
+        headers.insert(TRACEPARENT, "00-01-deadbeef-00");
+        let context = TraceContext::from_headers(&mut headers)?;
         assert_eq!(context.version(), 0);
         assert_eq!(context.trace_id(), 1);
         assert_eq!(context.parent_id().unwrap(), 3735928559);
@@ -238,7 +249,7 @@ mod test {
     #[test]
     fn no_header() -> crate::Result<()> {
         let mut headers = crate::Headers::new();
-        let context = TraceContext::extract(&mut headers)?;
+        let context = TraceContext::from_headers(&mut headers)?;
         assert_eq!(context.version(), 0);
         assert_eq!(context.parent_id(), None);
         assert_eq!(context.flags, 1);
@@ -249,17 +260,17 @@ mod test {
     #[test]
     fn not_sampled() -> crate::Result<()> {
         let mut headers = crate::Headers::new();
-        headers.insert("traceparent", "00-01-02-00");
-        let context = TraceContext::extract(&mut headers)?;
+        headers.insert(TRACEPARENT, "00-01-02-00");
+        let context = TraceContext::from_headers(&mut headers)?;
         assert_eq!(context.sampled(), false);
         Ok(())
     }
 
     #[test]
     fn sampled() -> crate::Result<()> {
         let mut headers = crate::Headers::new();
-        headers.insert("traceparent", "00-01-02-01");
-        let context = TraceContext::extract(&mut headers)?;
+        headers.insert(TRACEPARENT, "00-01-02-01");
+        let context = TraceContext::from_headers(&mut headers)?;
         assert_eq!(context.sampled(), true);
         Ok(())
     }