feat: Extend HeaderValue to provide access to/semantics of backing Bytes

This change adds (or makes public),
- `HeaderValue::from_shared[_unchecked]` which directly accept a `Bytes`
  object as an argument. This should allow for lwss copying when
  constructing `HeaderValue`s from pre-existing `Bytes` buffers.
- `HeaderValue::as_shared` which returns a clone of the `Bytes` object
  that backs the given `HeaderValue`.
- `HeaderValue::into_shared` which is a self-consuming version of the
  above.
- `HeaderValue::[try_]slice` which mirrors the `Bytes::slice` interface,
  and provides copy-free construction of sub-sliced `HeaderValue`s.
- `HeaderName::into_shared` which is a rename of the previously
  `pub(crate)` `.into_bytes` method. Allows access to a `Bytes`
  representation of a HeaderName, though it will usually copy via
  `Bytes::from_static`.
- `Uri::from_shared` which was previously `pub(crate)` and is now
  `pub` with an expanded doc comment.

Author: pyrrho

src/header/name.rs

@@ -1270,7 +1270,24 @@ impl HeaderName {
         }
     }
 
-    pub(super) fn into_bytes(self) -> Bytes {
+    /// Creates a [`Bytes`] object from this `HeaderName`.
+    ///
+    /// This function will _likely_ copy the standard string representation of
+    /// this `HeaderName` into a new `Bytes` object. If this `HeaderName` is a
+    /// non-standard header name (that just so happens to be backed by a `Bytes`
+    /// object), the copy may be elided in favor of claiming a reference-counted
+    /// borrow of the shared memory region that backs this `HeaderName`. Expect
+    /// the former behavior.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::header::*;
+    /// # use bytes::Bytes;
+    /// let hdr = HeaderName::from_static("content-length");
+    /// assert_eq!(hdr.into_shared(), Bytes::from_static(b"content-length"));
+    /// ```
+    pub fn into_shared(self) -> Bytes {
         self.inner.into()
     }
 }

src/header/value.rs

@@ -1,5 +1,6 @@
 use bytes::{Bytes, BytesMut};
 
+use core::ops::RangeBounds;
 use std::convert::TryFrom;
 use std::error::Error;
 use std::fmt::Write;
@@ -157,6 +158,62 @@ impl HeaderValue {
         HeaderValue::try_from_generic(src, Bytes::copy_from_slice, is_valid_ascii_or_opaque_byte)
     }
 
+    /// Convert a [`Bytes`] into a `HeaderValue`.
+    ///
+    /// This function will not perform any copying.
+    ///
+    /// If the argument contains invalid header value bytes, an error is
+    /// returned. Only byte values between 32 and 255 (inclusive) are permitted,
+    /// excluding byte 127 (DEL).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::header::HeaderValue;
+    /// # use bytes::Bytes;
+    /// let bytes = Bytes::from_static(b"hello\xfa");
+    /// let val = HeaderValue::from_shared(bytes).unwrap();
+    /// assert_eq!(val, &b"hello\xfa"[..]);
+    /// ```
+    pub fn from_shared(src: Bytes) -> Result<HeaderValue, InvalidHeaderValue> {
+        for &b in src.as_ref() {
+            if !is_valid_ascii_or_opaque_byte(b) {
+                return Err(InvalidHeaderValue { _priv: () });
+            }
+        }
+        Ok(HeaderValue {
+            inner: src,
+            is_sensitive: false,
+        })
+    }
+
+    /// Convert a [`Bytes`] directly into a `HeaderValue` without validating.
+    ///
+    /// This function does NOT validate that illegal bytes are not contained
+    /// within the buffer.
+    ///
+    /// ## Panics
+    /// In a debug build this will panic if `src` is not valid UTF-8.
+    ///
+    /// ## Safety
+    /// `src` must contain valid UTF-8. In a release build it is undefined
+    /// behaviour to call this with `src` that is not valid UTF-8.
+    pub unsafe fn from_shared_unchecked(src: Bytes) -> HeaderValue {
+        if cfg!(debug_assertions) {
+            match HeaderValue::from_shared(src) {
+                Ok(val) => val,
+                Err(_err) => {
+                    panic!("HeaderValue::from_shared_unchecked() with invalid bytes");
+                }
+            }
+        } else {
+            return HeaderValue {
+                inner: src,
+                is_sensitive: false,
+            };
+        }
+    }
+
     /// Attempt to convert a `Bytes` buffer to a `HeaderValue`.
     ///
     /// This will try to prevent a copy if the type passed is the type used
@@ -210,10 +267,6 @@ impl HeaderValue {
         }
     }
 
-    fn from_shared(src: Bytes) -> Result<HeaderValue, InvalidHeaderValue> {
-        HeaderValue::try_from_generic(src, std::convert::identity, is_valid_ascii_or_opaque_byte)
-    }
-
     fn try_from_generic<T: AsRef<[u8]>, F: FnOnce(T) -> Bytes, V: Fn(u8) -> bool>(
         src: T,
         into: F,
@@ -308,6 +361,148 @@ impl HeaderValue {
         self.as_ref()
     }
 
+    /// Creates a new [`Bytes`] object from this `HeaderValue`.
+    ///
+    /// This function will not perform any copying. Rather, it allocates a new,
+    /// owned `Bytes` object (which will be, at the time of writing, roughly 4
+    /// pointers in size) which will claim a reference-counted borrow of the
+    /// shared memory region that backs this `HeaderValue`. Because of the
+    /// Arc-like semantics of `Bytes` and `HeaderValue`s, this `HeaderValue` and
+    /// the returned `Bytes` can be dropped in any order and the shared memory
+    /// region will remain valid for the other.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::header::HeaderValue;
+    /// # use bytes::Bytes;
+    /// let val = HeaderValue::from_static("hello");
+    /// assert_eq!(val.as_shared(), Bytes::from_static(b"hello"));
+    /// ```
+    #[inline]
+    pub fn as_shared(&self) -> Bytes {
+        self.inner.clone()
+    }
+
+    /// Return the inner [`Bytes`] object, consuming this `HeaderValue`.
+    ///
+    /// Unlike [`as_shared()`], this method will not increment the reference
+    /// count of the shared memory region that backs this `HeaderValue`. This
+    /// method consumes `self` to do so.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::header::HeaderValue;
+    /// # use bytes::Bytes;
+    /// let val = HeaderValue::from_static("hello");
+    /// assert_eq!(val.into_shared(), Bytes::from_static(b"hello"));
+    /// ```
+    ///
+    /// [`as_shared()`]: Self::as_shared()
+    #[inline]
+    pub fn into_shared(self) -> Bytes {
+        self.inner
+    }
+
+    /// Returns a slice of `self` over the provided range.
+    ///
+    ///
+    /// This function will not perform any copying. Rather, it allocates a new,
+    /// owned `HeaderValue` object (which will be, at the time of writing,
+    /// roughly 5 pointers in size) which will claim a reference-counted borrow
+    /// of the shared memory region that backs this `HeaderValue`. Because of the
+    /// Arc-like semantics of`HeaderValue`s, this and the resulting
+    /// `HeaderValue` can be dropped in any order and the shared memory region
+    /// will remain valid for the other.
+    ///
+    /// If the `range` would be out of bounds, this function will return `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::header::HeaderValue;
+    /// let val = HeaderValue::from_static(r#"W/"67ab43", "54ed21", "7892dd""#);
+    /// let slice_1 = val.try_slice(0..10).unwrap();
+    /// let slice_3 = val.try_slice(22..30).unwrap();
+    /// assert_eq!(slice_1, r#"W/"67ab43""#);
+    /// assert_eq!(slice_3, "\"7892dd\"");
+    /// assert!(val.try_slice(0..31).is_none());
+    /// ```
+    #[inline]
+    pub fn try_slice(&self, range: impl RangeBounds<usize>) -> Option<HeaderValue> {
+        use core::ops::Bound;
+
+        let len = self.len();
+
+        let begin = match range.start_bound() {
+            Bound::Included(&n) => n,
+            Bound::Excluded(&n) => {
+                if let Some(n) = n.checked_add(1) {
+                    n
+                } else {
+                    return None;
+                }
+            }
+            Bound::Unbounded => 0,
+        };
+
+        let end = match range.end_bound() {
+            Bound::Included(&n) => {
+                if let Some(n) = n.checked_add(1) {
+                    n
+                } else {
+                    return None;
+                }
+            }
+            Bound::Excluded(&n) => n,
+            Bound::Unbounded => len,
+        };
+
+        if begin > end {
+            return None;
+        }
+        if end > len {
+            return None;
+        }
+
+        Some(self.slice(range))
+    }
+
+    /// Returns a slice of `self` over the provided range.
+    ///
+    ///
+    /// This function will not perform any copying. Rather, it allocates a new,
+    /// owned `HeaderValue` object (which will be, at the time of writing,
+    /// roughly 5 pointers in size) which will claim a reference-counted borrow
+    /// of the shared memory region that backs this `HeaderValue`. Because of the
+    /// Arc-like semantics of`HeaderValue`s, this and the resulting
+    /// `HeaderValue` can be dropped in any order and the shared memory region
+    /// will remain valid for the other.
+    ///
+    /// # Panics
+    ///
+    /// Requires that `begin <= end` and `end <= self.len()`, otherwise slicing
+    /// will panic.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http::header::HeaderValue;
+    /// let val = HeaderValue::from_static(r#"W/"67ab43", "54ed21", "7892dd""#);
+    /// let slice_1 = val.slice(0..10);
+    /// let slice_3 = val.slice(22..30);
+    /// assert_eq!(slice_1, r#"W/"67ab43""#);
+    /// assert_eq!(slice_3, "\"7892dd\"");
+    /// ```
+    #[inline]
+    pub fn slice(&self, range: impl RangeBounds<usize>) -> HeaderValue {
+        let inner_slice = self.inner.slice(range);
+        // SAFETY: Any subslice of `self.inner` should be just as valid for use
+        // as a HeaderValue as the full `self.inner` buffer.
+        unsafe { HeaderValue::from_shared_unchecked(inner_slice) }
+    }
+
     /// Mark that the header value represents sensitive information.
     ///
     /// # Examples
@@ -398,7 +593,7 @@ impl From<HeaderName> for HeaderValue {
     #[inline]
     fn from(h: HeaderName) -> HeaderValue {
         HeaderValue {
-            inner: h.into_bytes(),
+            inner: h.into_shared(),
             is_sensitive: false,
         }
     }
@@ -561,6 +756,7 @@ mod try_from_header_name_tests {
     }
 }
 
+#[inline]
 const fn is_valid_ascii(b: u8) -> bool {
     b >= 32 && b < 127 || b == b'\t'
 }
@@ -569,7 +765,7 @@ const fn is_valid_ascii(b: u8) -> bool {
 // may contain opaque bytes, even though those bytes cannot be exposed by
 // `HeaderValue::to_str`.
 #[inline]
-fn is_valid_ascii_or_opaque_byte(b: u8) -> bool {
+const fn is_valid_ascii_or_opaque_byte(b: u8) -> bool {
     b >= 32 && b != 127 || b == b'\t'
 }
 

src/uri/mod.rs

@@ -289,19 +289,22 @@ impl Uri {
         Uri::try_from(src.as_ref())
     }
 
-    // Not public while `bytes` is unstable.
-    fn from_shared(s: Bytes) -> Result<Uri, InvalidUri> {
+    /// Convert a [`Bytes`] into a `Uri`.
+    ///
+    /// This function will not perform any copying, however the value will be
+    /// checked to ensure that it is valid.
+    pub fn from_shared(src: Bytes) -> Result<Uri, InvalidUri> {
         use self::ErrorKind::*;
 
-        if s.len() > MAX_LEN {
+        if src.len() > MAX_LEN {
             return Err(TooLong.into());
         }
 
-        match s.len() {
+        match src.len() {
             0 => {
                 return Err(Empty.into());
             }
-            1 => match s[0] {
+            1 => match src[0] {
                 b'/' => {
                     return Ok(Uri {
                         scheme: Scheme::empty(),
@@ -317,7 +320,7 @@ impl Uri {
                     });
                 }
                 _ => {
-                    let authority = Authority::from_shared(s)?;
+                    let authority = Authority::from_shared(src)?;
 
                     return Ok(Uri {
                         scheme: Scheme::empty(),
@@ -329,15 +332,15 @@ impl Uri {
             _ => {}
         }
 
-        if s[0] == b'/' {
+        if src[0] == b'/' {
             return Ok(Uri {
                 scheme: Scheme::empty(),
                 authority: Authority::empty(),
-                path_and_query: PathAndQuery::from_shared(s)?,
+                path_and_query: PathAndQuery::from_shared(src)?,
             });
         }
 
-        parse_full(s)
+        parse_full(src)
     }
 
     /// Convert a `Uri` from a static string.