Merge pull request #203 from http-rs/server-timings

Add trace::ServerTiming

Author: yoshuawuyts

src/headers/constants.rs

@@ -137,6 +137,9 @@ pub const RETRY_AFTER: HeaderName = HeaderName::from_lowercase_str("retry-after"
 ///  The `Server` Header
 pub const SERVER: HeaderName = HeaderName::from_lowercase_str("server");
 
+///  The `Server` Header
+pub const SERVER_TIMING: HeaderName = HeaderName::from_lowercase_str("server-timing");
+
 ///  The `Te` Header
 pub const TE: HeaderName = HeaderName::from_lowercase_str("te");
 

src/trace/mod.rs

@@ -1,268 +1,17 @@
-//! Extract and inject [trace context](https://w3c.github.io/trace-context/) headers.
+//! HTTP timings and traces.
 //!
-//! ## Examples
+//! This module implements parsers and serializers for timing-related headers.
+//! These headers enable tracing and timing requests, and help answer the
+//! question of: _"Where is my program spending its time?"_
 //!
-//! ```
-//! use http_types::trace::TraceContext;
+//! # Specifications
 //!
-//! let mut res = http_types::Response::new(200);
-//!
-//! res.insert_header(
-//!     "traceparent",
-//!     "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
-//! );
-//!
-//! let context = TraceContext::extract(&res).unwrap();
-//!
-//! let trace_id = u128::from_str_radix("0af7651916cd43dd8448eb211c80319c", 16);
-//! let parent_id = u64::from_str_radix("00f067aa0ba902b7", 16);
-//!
-//! assert_eq!(context.trace_id(), trace_id.unwrap());
-//! assert_eq!(context.parent_id(), parent_id.ok());
-//! assert_eq!(context.sampled(), true);
-//! ```
-
-use rand::Rng;
-use std::fmt;
-
-use crate::Headers;
-
-/// A TraceContext object
-#[derive(Debug)]
-pub struct TraceContext {
-    id: u64,
-    version: u8,
-    trace_id: u128,
-    parent_id: Option<u64>,
-    flags: u8,
-}
-
-impl TraceContext {
-    /// Create and return TraceContext object based on `traceparent` HTTP header.
-    ///
-    /// ## Examples
-    /// ```
-    /// use http_types::trace::TraceContext;
-    ///
-    /// let mut res = http_types::Response::new(200);
-    /// res.insert_header(
-    ///   "traceparent",
-    ///   "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
-    /// );
-    ///
-    /// let context = TraceContext::extract(&res).unwrap();
-    ///
-    /// let trace_id = u128::from_str_radix("0af7651916cd43dd8448eb211c80319c", 16);
-    /// let parent_id = u64::from_str_radix("00f067aa0ba902b7", 16);
-    ///
-    /// assert_eq!(context.trace_id(), trace_id.unwrap());
-    /// assert_eq!(context.parent_id(), parent_id.ok());
-    /// assert_eq!(context.sampled(), true);
-    /// ```
-    pub fn extract(headers: impl AsRef<Headers>) -> crate::Result<Self> {
-        let headers = headers.as_ref();
-        let mut rng = rand::thread_rng();
-
-        let traceparent = match headers.get("traceparent") {
-            Some(header) => header.as_str(),
-            None => return Ok(Self::new_root()),
-        };
-
-        let parts: Vec<&str> = traceparent.split('-').collect();
-
-        Ok(Self {
-            id: rng.gen(),
-            version: u8::from_str_radix(parts[0], 16)?,
-            trace_id: u128::from_str_radix(parts[1], 16)?,
-            parent_id: Some(u64::from_str_radix(parts[2], 16)?),
-            flags: u8::from_str_radix(parts[3], 16)?,
-        })
-    }
-
-    /// 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
-    /// ```
-    /// use http_types::trace::TraceContext;
-    /// use http_types::{Request, Response, Url, Method};
-    ///
-    /// let mut req = Request::new(Method::Get, Url::parse("https://example.com").unwrap());
-    /// req.insert_header(
-    ///   "traceparent",
-    ///   "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
-    /// );
-    ///
-    /// let parent = TraceContext::extract(&req).unwrap();
-    ///
-    /// let mut res = Response::new(200);
-    /// parent.inject(&mut res);
-    ///
-    /// let child = TraceContext::extract(&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>) {
-        let headers = headers.as_mut();
-        headers.insert("traceparent", format!("{}", self));
-    }
-
-    /// Generate a child of the current TraceContext and return it.
-    ///
-    /// The child will have a new randomly genrated `id` and its `parent_id` will be set to the
-    /// `id` of this TraceContext.
-    pub fn child(&self) -> Self {
-        let mut rng = rand::thread_rng();
-
-        Self {
-            id: rng.gen(),
-            version: self.version,
-            trace_id: self.trace_id,
-            parent_id: Some(self.id),
-            flags: self.flags,
-        }
-    }
-
-    /// Return the id of the TraceContext.
-    pub fn id(&self) -> u64 {
-        self.id
-    }
-
-    /// Return the version of the TraceContext spec used.
-    ///
-    /// You probably don't need this.
-    pub fn version(&self) -> u8 {
-        self.version
-    }
-
-    /// Return the trace id of the TraceContext.
-    ///
-    /// All children will have the same `trace_id`.
-    pub fn trace_id(&self) -> u128 {
-        self.trace_id
-    }
-
-    /// Return the id of the parent TraceContext.
-    #[inline]
-    pub fn parent_id(&self) -> Option<u64> {
-        self.parent_id
-    }
-
-    /// Returns true if the trace is sampled
-    ///
-    /// ## Examples
-    ///
-    /// ```
-    /// use http_types::trace::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();
-    /// assert_eq!(context.sampled(), true);
-    /// ```
-    pub fn sampled(&self) -> bool {
-        (self.flags & 0b00000001) == 1
-    }
-
-    /// Change sampled flag
-    ///
-    /// ## Examples
-    ///
-    /// ```
-    /// use http_types::trace::TraceContext;
-    ///
-    /// let mut context = TraceContext::new_root();
-    /// assert_eq!(context.sampled(), true);
-    /// context.set_sampled(false);
-    /// assert_eq!(context.sampled(), false);
-    /// ```
-    pub fn set_sampled(&mut self, sampled: bool) {
-        let x = sampled as u8;
-        self.flags ^= (x ^ self.flags) & (1 << 0);
-    }
-}
-
-impl fmt::Display for TraceContext {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(
-            f,
-            "{:02x}-{:032x}-{:016x}-{:02x}",
-            self.version, self.trace_id, self.id, self.flags
-        )
-    }
-}
-
-#[cfg(test)]
-mod test {
-    use super::*;
-
-    #[test]
-    fn default() -> crate::Result<()> {
-        let mut headers = crate::Headers::new();
-        headers.insert("traceparent", "00-01-deadbeef-00");
-        let context = TraceContext::extract(&mut headers)?;
-        assert_eq!(context.version(), 0);
-        assert_eq!(context.trace_id(), 1);
-        assert_eq!(context.parent_id().unwrap(), 3735928559);
-        assert_eq!(context.flags, 0);
-        assert_eq!(context.sampled(), false);
-        Ok(())
-    }
-
-    #[test]
-    fn no_header() -> crate::Result<()> {
-        let mut headers = crate::Headers::new();
-        let context = TraceContext::extract(&mut headers)?;
-        assert_eq!(context.version(), 0);
-        assert_eq!(context.parent_id(), None);
-        assert_eq!(context.flags, 1);
-        assert_eq!(context.sampled(), true);
-        Ok(())
-    }
+//! - [W3C Trace-Context headers](https://w3c.github.io/trace-context/)
+//! - [W3C Server-Timing headers](https://w3c.github.io/server-timing/#the-server-timing-header-field)
 
-    #[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)?;
-        assert_eq!(context.sampled(), false);
-        Ok(())
-    }
+pub mod server_timing;
+mod trace_context;
 
-    #[test]
-    fn sampled() -> crate::Result<()> {
-        let mut headers = crate::Headers::new();
-        headers.insert("traceparent", "00-01-02-01");
-        let context = TraceContext::extract(&mut headers)?;
-        assert_eq!(context.sampled(), true);
-        Ok(())
-    }
-}
+#[doc(inline)]
+pub use server_timing::{Metric, ServerTiming};
+pub use trace_context::TraceContext;

src/trace/server_timing/metric.rs

@@ -0,0 +1,101 @@
+use std::time::Duration;
+
+use crate::headers::HeaderValue;
+
+/// An individual entry into `ServerTiming`.
+//
+// # Implementation notes
+//
+// Four different cases are valid:
+//
+// 1. metric name only       cache
+// 2. metric + value         cache;dur=2.4
+// 3. metric + desc          cache;desc="Cache Read"
+// 4. metric + value + desc  cache;desc="Cache Read";dur=23.2
+//
+// Multiple different entries per line are supported; separated with a `,`.
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub struct Metric {
+    pub(crate) name: String,
+    pub(crate) dur: Option<Duration>,
+    pub(crate) desc: Option<String>,
+}
+
+impl Metric {
+    /// Create a new instance of `Metric`.
+    ///
+    /// # Errors
+    ///
+    /// An error will be returned if the string values are invalid ASCII.
+    pub fn new(name: String, dur: Option<Duration>, desc: Option<String>) -> crate::Result<Self> {
+        crate::ensure!(name.is_ascii(), "Name should be valid ASCII");
+        if let Some(desc) = desc.as_ref() {
+            crate::ensure!(desc.is_ascii(), "Description should be valid ASCII");
+        };
+
+        Ok(Self { name, dur, desc })
+    }
+
+    /// The timing name.
+    pub fn name(&self) -> &String {
+        &self.name
+    }
+
+    /// The timing duration.
+    pub fn duration(&self) -> Option<Duration> {
+        self.dur
+    }
+
+    /// The timing description.
+    pub fn description(&self) -> Option<&str> {
+        self.desc.as_ref().map(|s| s.as_str())
+    }
+}
+
+impl From<Metric> for HeaderValue {
+    fn from(entry: Metric) -> HeaderValue {
+        let mut string = entry.name;
+
+        // Format a `Duration` into the format that the spec expects.
+        let f = |d: Duration| d.as_secs_f64() * 1000.0;
+
+        match (entry.dur, entry.desc) {
+            (Some(dur), Some(desc)) => {
+                string.push_str(&format!("; dur={}; desc=\"{}\"", f(dur), desc))
+            }
+            (Some(dur), None) => string.push_str(&format!("; dur={}", f(dur))),
+            (None, Some(desc)) => string.push_str(&format!("; desc=\"{}\"", desc)),
+            (None, None) => {}
+        };
+
+        // SAFETY: we validate that the values are valid ASCII on creation.
+        unsafe { HeaderValue::from_bytes_unchecked(string.into_bytes()) }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use crate::headers::HeaderValue;
+    use std::time::Duration;
+
+    #[test]
+    fn encode() -> crate::Result<()> {
+        let name = String::from("Server");
+        let dur = Duration::from_secs(1);
+        let desc = String::from("A server timing");
+
+        let val: HeaderValue = Metric::new(name.clone(), None, None)?.into();
+        assert_eq!(val, "Server");
+
+        let val: HeaderValue = Metric::new(name.clone(), Some(dur), None)?.into();
+        assert_eq!(val, "Server; dur=1000");
+
+        let val: HeaderValue = Metric::new(name.clone(), None, Some(desc.clone()))?.into();
+        assert_eq!(val, r#"Server; desc="A server timing""#);
+
+        let val: HeaderValue = Metric::new(name.clone(), Some(dur), Some(desc.clone()))?.into();
+        assert_eq!(val, r#"Server; dur=1000; desc="A server timing""#);
+        Ok(())
+    }
+}