Add general shape of timing APIs

Author: yoshuawuyts

src/trace/mod.rs

@@ -1,29 +1,16 @@
-//! 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);
-//! ```
+//! - [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)
 
 mod server_timing;
 mod trace_context;
 
-pub use server_timing::ServerTiming;
+pub use server_timing::{ServerTiming, TimingEntry};
 pub use trace_context::TraceContext;

src/trace/server_timing.rs

@@ -1,19 +1,71 @@
-/// Communicate one or more metrics and descriptions for the given request-response cycle.
-///
-/// This is an implementation of the W3C [Server
-/// Timing](https://w3c.github.io/server-timing/#the-server-timing-header-field)
-/// header spec. Read more on
-/// [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing)
-pub struct ServerTiming;
+use std::time::Duration;
 
+/// An individual [`ServerTiming`] entry.
+//
+// # Implementation notes
+//
 // Four different cases are valid:
 //
 // 1. metric name only       cache
-// 2. metric + metric        cache;dur=2.4
-// 3. metric + description   cache;desc="Cache Read"
+// 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)]
+pub struct TimingEntry {
+    name: String,
+    dur: Option<Duration>,
+    desc: Option<String>,
+}
+
+impl TimingEntry {
+    /// Create a new instance of `TimingEntry`.
+    pub fn new(name: String, dur: Option<Duration>, desc: Option<String>) -> Self {
+        Self { name, dur, desc }
+    }
+
+    /// The timing name.
+    pub fn name(&self) -> &String {
+        &self.name
+    }
+
+    /// Set the timing name.
+    pub fn set_name(&mut self, name: String) {
+        self.name = name;
+    }
+
+    /// The timing duration.
+    pub fn duration(&self) -> Option<Duration> {
+        self.dur
+    }
+
+    /// Set the timing name.
+    pub fn set_duration(&mut self, dur: Option<Duration>) {
+        self.dur = dur;
+    }
+
+    /// The timing description.
+    pub fn description(&self) -> Option<&String> {
+        self.desc.as_ref()
+    }
+
+    /// Set the timing description.
+    pub fn set_description(&mut self, desc: Option<String>) {
+        self.desc = desc;
+    }
+}
+
+/// Communicate one or more metrics and descriptions for the given request-response cycle.
+///
+/// This is an implementation of the W3C [Server
+/// Timing](https://w3c.github.io/server-timing/#the-server-timing-header-field)
+/// header spec. Read more on
+/// [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing).
+#[derive(Debug)]
+pub struct ServerTiming {
+    timings: Vec<TimingEntry>,
+}
 
 mod test {
     const CASE1: &str =

src/trace/trace_context.rs

@@ -1,33 +1,31 @@
-//! Extract and inject [trace context](https://w3c.github.io/trace-context/) headers.
-//!
-//! ## 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);
-//! ```
-
 use rand::Rng;
 use std::fmt;
 
 use crate::Headers;
 
-/// A TraceContext object
+/// Extract and inject [Trace-Context](https://w3c.github.io/trace-context/) headers.
+///
+/// ## 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);
+/// ```
 #[derive(Debug)]
 pub struct TraceContext {
     id: u64,