Merge branch 'server-timings' of https://github.com/http-rs/http-types into server-timings

Author: yoshuawuyts

src/trace/mod.rs

@@ -13,5 +13,5 @@ pub mod server_timing;
 mod trace_context;
 
 #[doc(inline)]
-pub use server_timing::ServerTiming;
+pub use server_timing::{Metric, ServerTiming};
 pub use trace_context::TraceContext;

src/trace/server_timing/entry.rs renamed to src/trace/server_timing/metric.rs

@@ -2,7 +2,7 @@ use std::time::Duration;
 
 use crate::headers::HeaderValue;
 
-/// An individual `ServerTiming` entry.
+/// An individual entry into `ServerTiming`.
 //
 // # Implementation notes
 //
@@ -15,14 +15,14 @@ use crate::headers::HeaderValue;
 //
 // Multiple different entries per line are supported; separated with a `,`.
 #[derive(Debug, Clone, Eq, PartialEq)]
-pub struct Entry {
+pub struct Metric {
     pub(crate) name: String,
     pub(crate) dur: Option<Duration>,
     pub(crate) desc: Option<String>,
 }
 
-impl Entry {
-    /// Create a new instance of `Entry`.
+impl Metric {
+    /// Create a new instance of `Metric`.
     ///
     /// # Errors
     ///
@@ -52,8 +52,8 @@ impl Entry {
     }
 }
 
-impl From<Entry> for HeaderValue {
-    fn from(entry: Entry) -> HeaderValue {
+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.
@@ -85,16 +85,16 @@ mod test {
         let dur = Duration::from_secs(1);
         let desc = String::from("A server timing");
 
-        let val: HeaderValue = Entry::new(name.clone(), None, None)?.into();
+        let val: HeaderValue = Metric::new(name.clone(), None, None)?.into();
         assert_eq!(val, "Server");
 
-        let val: HeaderValue = Entry::new(name.clone(), Some(dur), None)?.into();
+        let val: HeaderValue = Metric::new(name.clone(), Some(dur), None)?.into();
         assert_eq!(val, "Server; dur=1000");
 
-        let val: HeaderValue = Entry::new(name.clone(), None, Some(desc.clone()))?.into();
+        let val: HeaderValue = Metric::new(name.clone(), None, Some(desc.clone()))?.into();
         assert_eq!(val, r#"Server; desc="A server timing""#);
 
-        let val: HeaderValue = Entry::new(name.clone(), Some(dur), Some(desc.clone()))?.into();
+        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(())
     }

src/trace/server_timing/mod.rs

@@ -1,9 +1,30 @@
 //! Metrics and descriptions for the given request-response cycle.
-
-mod entry;
+//!
+//! # Examples
+//!
+//! ```
+//! # fn main() -> http_types::Result<()> {
+//! #
+//! use http_types::Response;
+//! use http_types::trace::{ServerTiming, Metric};
+//!
+//! let mut timings = ServerTiming::new();
+//! timings.push(Metric::new("server".to_owned(), None, None)?);
+//!
+//! let mut res = Response::new(200);
+//! timings.apply(&mut res);
+//!
+//! let timings = ServerTiming::from_headers(res)?;
+//! let entry = timings.iter().next().unwrap();
+//! assert_eq!(entry.name(), "server");
+//! #
+//! # Ok(()) }
+//! ```
+
+mod metric;
 mod parse;
 
-pub use entry::Entry;
+pub use metric::Metric;
 use parse::parse_header;
 
 use std::convert::AsMut;
@@ -20,9 +41,30 @@ use crate::headers::{HeaderName, HeaderValue, Headers, ToHeaderValues, SERVER_TI
 /// 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).
+///
+/// # Examples
+///
+/// ```
+/// # fn main() -> http_types::Result<()> {
+/// #
+/// use http_types::Response;
+/// use http_types::trace::{ServerTiming, Metric};
+///
+/// let mut timings = ServerTiming::new();
+/// timings.push(Metric::new("server".to_owned(), None, None)?);
+///
+/// let mut res = Response::new(200);
+/// timings.apply(&mut res);
+///
+/// let timings = ServerTiming::from_headers(res)?;
+/// let entry = timings.iter().next().unwrap();
+/// assert_eq!(entry.name(), "server");
+/// #
+/// # Ok(()) }
+/// ```
 #[derive(Debug)]
 pub struct ServerTiming {
-    timings: Vec<Entry>,
+    timings: Vec<Metric>,
 }
 
 impl ServerTiming {
@@ -68,7 +110,7 @@ impl ServerTiming {
     }
 
     /// Push an entry into the list of entries.
-    pub fn push(&mut self, entry: Entry) {
+    pub fn push(&mut self, entry: Metric) {
         self.timings.push(entry);
     }
 
@@ -95,7 +137,7 @@ impl ServerTiming {
 }
 
 impl IntoIterator for ServerTiming {
-    type Item = Entry;
+    type Item = Metric;
     type IntoIter = IntoIter;
 
     #[inline]
@@ -105,7 +147,7 @@ impl IntoIterator for ServerTiming {
 }
 
 impl<'a> IntoIterator for &'a ServerTiming {
-    type Item = &'a Entry;
+    type Item = &'a Metric;
     type IntoIter = Iter<'a>;
 
     // #[inline]serv
@@ -115,7 +157,7 @@ impl<'a> IntoIterator for &'a ServerTiming {
 }
 
 impl<'a> IntoIterator for &'a mut ServerTiming {
-    type Item = &'a mut Entry;
+    type Item = &'a mut Metric;
     type IntoIter = IterMut<'a>;
 
     #[inline]
@@ -127,11 +169,11 @@ impl<'a> IntoIterator for &'a mut ServerTiming {
 /// A borrowing iterator over entries in `ServerTiming`.
 #[derive(Debug)]
 pub struct IntoIter {
-    inner: std::vec::IntoIter<Entry>,
+    inner: std::vec::IntoIter<Metric>,
 }
 
 impl Iterator for IntoIter {
-    type Item = Entry;
+    type Item = Metric;
 
     fn next(&mut self) -> Option<Self::Item> {
         self.inner.next()
@@ -146,11 +188,11 @@ impl Iterator for IntoIter {
 /// A lending iterator over entries in `ServerTiming`.
 #[derive(Debug)]
 pub struct Iter<'a> {
-    inner: slice::Iter<'a, Entry>,
+    inner: slice::Iter<'a, Metric>,
 }
 
 impl<'a> Iterator for Iter<'a> {
-    type Item = &'a Entry;
+    type Item = &'a Metric;
 
     fn next(&mut self) -> Option<Self::Item> {
         self.inner.next()
@@ -165,11 +207,11 @@ impl<'a> Iterator for Iter<'a> {
 /// A mutable iterator over entries in `ServerTiming`.
 #[derive(Debug)]
 pub struct IterMut<'a> {
-    inner: slice::IterMut<'a, Entry>,
+    inner: slice::IterMut<'a, Metric>,
 }
 
 impl<'a> Iterator for IterMut<'a> {
-    type Item = &'a mut Entry;
+    type Item = &'a mut Metric;
 
     fn next(&mut self) -> Option<Self::Item> {
         self.inner.next()
@@ -197,7 +239,7 @@ mod test {
     #[test]
     fn smoke() -> crate::Result<()> {
         let mut timings = ServerTiming::new();
-        timings.push(Entry::new("server".to_owned(), None, None)?);
+        timings.push(Metric::new("server".to_owned(), None, None)?);
 
         let mut headers = Headers::new();
         timings.apply(&mut headers);

src/trace/server_timing/parse.rs

@@ -1,13 +1,13 @@
 use std::time::Duration;
 
-use super::Entry;
+use super::Metric;
 use crate::Status;
 use crate::{ensure, format_err};
 
 /// Parse multiple entries from a single header.
 ///
 /// Each entry is comma-delimited.
-pub(super) fn parse_header(s: &str, entries: &mut Vec<Entry>) -> crate::Result<()> {
+pub(super) fn parse_header(s: &str, entries: &mut Vec<Metric>) -> crate::Result<()> {
     for part in s.trim().split(',') {
         let entry = parse_entry(part)?;
         entries.push(entry);
@@ -27,7 +27,7 @@ pub(super) fn parse_header(s: &str, entries: &mut Vec<Entry>) -> crate::Result<(
 /// ```
 //
 /// Source: https://w3c.github.io/server-timing/#the-server-timing-header-field
-fn parse_entry(s: &str) -> crate::Result<Entry> {
+fn parse_entry(s: &str) -> crate::Result<Metric> {
     let mut parts = s.trim().split(';');
 
     // Get the name. This is non-optional.
@@ -86,7 +86,7 @@ fn parse_entry(s: &str) -> crate::Result<Entry> {
         }
     }
 
-    Ok(Entry {
+    Ok(Metric {
         name: name.to_string(),
         dur,
         desc,