improve typed header macro (#2481)

actix-http/src/header/shared/charset.rs

@@ -7,7 +7,7 @@ use self::Charset::*;
 /// The string representation is normalized to upper case.
 ///
 /// See <http://www.iana.org/assignments/character-sets/character-sets.xhtml>.
-#[derive(Clone, Debug, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 #[allow(non_camel_case_types)]
 pub enum Charset {
     /// US ASCII

actix-http/src/header/shared/extended.rs

@@ -31,7 +31,7 @@ pub struct ExtendedValue {
 ///
 /// ## ABNF
 ///
-/// ```text
+/// ```plain
 /// ext-value     = charset  "'" [ language ] "'" value-chars
 ///               ; like RFC 2231's <extended-initial-value>
 ///               ; (see [RFC 2231 §7])

actix-http/src/header/shared/http_date.rs

@@ -8,7 +8,7 @@ use crate::{
     helpers::MutWriter,
 };
 
-/// A timestamp with HTTP formatting and parsing.
+/// A timestamp with HTTP-style formatting and parsing.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub struct HttpDate(SystemTime);
 

actix-http/src/header/shared/quality_item.rs

@@ -27,7 +27,7 @@ const MAX_FLOAT_QUALITY: f32 = 1.0;
 ///
 /// [RFC 7231 §5.3.1](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.1) gives more
 /// information on quality values in HTTP header fields.
-#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Quality(u16);
 
 impl Quality {
@@ -80,7 +80,7 @@ impl TryFrom<f32> for Quality {
 
 /// Represents an item with a quality value as defined
 /// in [RFC 7231 §5.3.1](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.1).
-#[derive(Clone, PartialEq, Debug)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct QualityItem<T> {
     /// The wrapped contents of the field.
     pub item: T,

actix-web-codegen/src/lib.rs

@@ -66,7 +66,7 @@ mod route;
 /// Creates resource handler, allowing multiple HTTP method guards.
 ///
 /// # Syntax
-/// ```text
+/// ```plain
 /// #[route("path", method="HTTP_METHOD"[, attributes])]
 /// ```
 ///
@@ -112,7 +112,7 @@ concat!("
 Creates route handler with `actix_web::guard::", stringify!($variant), "`.
 
 # Syntax
-```text
+```plain
 #[", stringify!($method), r#"("path"[, attributes])]
 ```
 

src/http/header/accept.rs

@@ -16,7 +16,7 @@ crate::http::header::common_header! {
     /// in-line image
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Accept = #( media-range [ accept-params ] )
     ///
     /// media-range    = ( "*/*"

src/http/header/accept_charset.rs

@@ -12,7 +12,7 @@ crate::http::header::common_header! {
     /// those charsets.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Accept-Charset = 1#( ( charset / "*" ) [ weight ] )
     /// ```
     ///

src/http/header/accept_encoding.rs

@@ -1,3 +1,5 @@
+// TODO: reinstate module
+
 use header::{Encoding, QualityItem};
 
 header! {
@@ -11,7 +13,7 @@ header! {
     /// preferred.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Accept-Encoding  = #( codings [ weight ] )
     /// codings          = content-coding / "identity" / "*"
     /// ```
@@ -59,15 +61,17 @@ header! {
     ///     ])
     /// );
     /// ```
-    (AcceptEncoding, "Accept-Encoding") => (QualityItem<Encoding>)*
+    (AcceptEncoding, header::ACCEPT_ENCODING) => (QualityItem<Encoding>)*
 
     test_parse_and_format {
         // From the RFC
         crate::http::header::common_header_test!(test1, vec![b"compress, gzip"]);
         crate::http::header::common_header_test!(test2, vec![b""], Some(AcceptEncoding(vec![])));
         crate::http::header::common_header_test!(test3, vec![b"*"]);
+
         // Note: Removed quality 1 from gzip
         crate::http::header::common_header_test!(test4, vec![b"compress;q=0.5, gzip"]);
+
         // Note: Removed quality 1 from gzip
         crate::http::header::common_header_test!(test5, vec![b"gzip, identity; q=0.5, *;q=0"]);
     }

src/http/header/accept_language.rs

@@ -15,7 +15,7 @@ common_header! {
     /// ranges defined in [RFC 4647 §2.1](https://datatracker.ietf.org/doc/html/rfc4647#section-2.1).
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Accept-Language = 1#( language-range [ weight ] )
     /// language-range  = (1*8ALPHA *("-" 1*8alphanum)) / "*"
     /// alphanum        = ALPHA / DIGIT
@@ -57,7 +57,7 @@ common_header! {
     /// ```
     (AcceptLanguage, header::ACCEPT_LANGUAGE) => (QualityItem<Preference<LanguageTag>>)*
 
-    parse_and_fmt_tests {
+    test_parse_and_format {
         common_header_test!(no_headers, vec![b""; 0], Some(AcceptLanguage(vec![])));
 
         common_header_test!(empty_header, vec![b""; 1], Some(AcceptLanguage(vec![])));

src/http/header/allow.rs

@@ -12,7 +12,7 @@ crate::http::header::common_header! {
     /// with the resource.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Allow = #method
     /// ```
     ///

src/http/header/any_or_some.rs

@@ -0,0 +1,70 @@
+use std::{
+    fmt::{self, Write as _},
+    str,
+};
+
+/// A wrapper for types used in header values where wildcard (`*`) items are allowed but the
+/// underlying type does not support them.
+///
+/// For example, we use the `language-tags` crate for the [`AcceptLanguage`](super::AcceptLanguage)
+/// typed header but it does parse `*` successfully. On the other hand, the `mime` crate, used for
+/// [`Accept`](super::Accept), has first-party support for wildcard items so this wrapper is not
+/// used in those header types.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Hash)]
+pub enum AnyOrSome<T> {
+    /// A wildcard value.
+    Any,
+
+    /// A valid `T`.
+    Item(T),
+}
+
+impl<T> AnyOrSome<T> {
+    /// Returns true if item is wildcard (`*`) variant.
+    pub fn is_any(&self) -> bool {
+        matches!(self, Self::Any)
+    }
+
+    /// Returns true if item is a valid item (`T`) variant.
+    pub fn is_item(&self) -> bool {
+        matches!(self, Self::Item(_))
+    }
+
+    /// Returns reference to value in `Item` variant, if it is set.
+    pub fn item(&self) -> Option<&T> {
+        match self {
+            AnyOrSome::Item(ref item) => Some(item),
+            AnyOrSome::Any => None,
+        }
+    }
+
+    /// Consumes the container, returning the value in the `Item` variant, if it is set.
+    pub fn into_item(self) -> Option<T> {
+        match self {
+            AnyOrSome::Item(item) => Some(item),
+            AnyOrSome::Any => None,
+        }
+    }
+}
+
+impl<T: fmt::Display> fmt::Display for AnyOrSome<T> {
+    #[inline]
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AnyOrSome::Any => f.write_char('*'),
+            AnyOrSome::Item(item) => fmt::Display::fmt(item, f),
+        }
+    }
+}
+
+impl<T: str::FromStr> str::FromStr for AnyOrSome<T> {
+    type Err = T::Err;
+
+    #[inline]
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.trim() {
+            "*" => Ok(Self::Any),
+            other => other.parse().map(AnyOrSome::Item),
+        }
+    }
+}

src/http/header/cache_control.rs

@@ -1,6 +1,8 @@
 use std::fmt::{self, Write};
 use std::str::FromStr;
 
+use derive_more::{Deref, DerefMut};
+
 use super::{fmt_comma_delimited, from_comma_delimited, Header, IntoHeaderValue, Writer};
 
 use crate::http::header;
@@ -14,7 +16,7 @@ use crate::http::header;
 /// not imply that the same directive is to be given in the response.
 ///
 /// # ABNF
-/// ```text
+/// ```plain
 /// Cache-Control   = 1#cache-directive
 /// cache-directive = token [ "=" ( token / quoted-string ) ]
 /// ```
@@ -46,11 +48,9 @@ use crate::http::header;
 ///     CacheDirective::Extension("foo".to_owned(), Some("bar".to_owned())),
 /// ]));
 /// ```
-#[derive(PartialEq, Clone, Debug)]
+#[derive(Debug, Clone, PartialEq, Eq, Deref, DerefMut)]
 pub struct CacheControl(pub Vec<CacheDirective>);
 
-crate::http::header::common_header_deref!(CacheControl => Vec<CacheDirective>);
-
 // TODO: this could just be the crate::http::header::common_header! macro
 impl Header for CacheControl {
     fn name() -> header::HeaderName {
@@ -88,7 +88,7 @@ impl IntoHeaderValue for CacheControl {
 }
 
 /// `CacheControl` contains a list of these directives.
-#[derive(PartialEq, Clone, Debug)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub enum CacheDirective {
     /// "no-cache"
     NoCache,

src/http/header/content_disposition.rs

@@ -220,7 +220,7 @@ impl DispositionParam {
 /// itself, *Content-Disposition* has no effect.
 ///
 /// # ABNF
-/// ```text
+/// ```plain
 /// content-disposition = "Content-Disposition" ":"
 ///                       disposition-type *( ";" disposition-parm )
 ///

src/http/header/content_language.rs

@@ -1,7 +1,8 @@
-use super::{QualityItem, CONTENT_LANGUAGE};
 use language_tags::LanguageTag;
 
-crate::http::header::common_header! {
+use super::{common_header, QualityItem, CONTENT_LANGUAGE};
+
+common_header! {
     /// `Content-Language` header, defined
     /// in [RFC 7231 §3.1.3.2](https://datatracker.ietf.org/doc/html/rfc7231#section-3.1.3.2)
     ///
@@ -11,7 +12,7 @@ crate::http::header::common_header! {
     /// representation.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Content-Language = 1#language-tag
     /// ```
     ///

src/http/header/content_range.rs

@@ -75,7 +75,7 @@ crate::http::header::common_header! {
 /// in [RFC 7233 §4.2](https://datatracker.ietf.org/doc/html/rfc7233#section-4.2)
 ///
 /// # ABNF
-/// ```text
+/// ```plain
 /// Content-Range       = byte-content-range
 ///                     / other-content-range
 ///
@@ -91,7 +91,7 @@ crate::http::header::common_header! {
 /// other-content-range = other-range-unit SP other-range-resp
 /// other-range-resp    = *CHAR
 /// ```
-#[derive(PartialEq, Clone, Debug)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ContentRangeSpec {
     /// Byte range
     Bytes {

src/http/header/content_type.rs

@@ -18,7 +18,7 @@ crate::http::header::common_header! {
     /// this is an issue, it's possible to implement `Header` on a custom struct.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Content-Type = media-type
     /// ```
     ///
@@ -110,5 +110,3 @@ impl ContentType {
         ContentType(mime::APPLICATION_OCTET_STREAM)
     }
 }
-
-impl Eq for ContentType {}

src/http/header/date.rs

@@ -9,7 +9,7 @@ crate::http::header::common_header! {
     /// message was originated.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Date = HTTP-date
     /// ```
     ///

src/http/header/entity.rs

@@ -26,7 +26,7 @@ fn check_slice_validity(slice: &str) -> bool {
 /// `W/"xyzzy"`.
 ///
 /// # ABNF
-/// ```text
+/// ```plain
 /// entity-tag = [ weak ] opaque-tag
 /// weak       = %x57.2F ; "W/", case-sensitive
 /// opaque-tag = DQUOTE *etagc DQUOTE

src/http/header/etag.rs

@@ -15,7 +15,7 @@ crate::http::header::common_header! {
     /// prefixed by a weakness indicator.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// ETag       = entity-tag
     /// ```
     ///

src/http/header/expires.rs

@@ -12,7 +12,7 @@ crate::http::header::common_header! {
     /// time.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Expires = HTTP-date
     /// ```
     ///

src/http/header/if_match.rs

@@ -1,6 +1,6 @@
-use super::{EntityTag, IF_MATCH};
+use super::{common_header, EntityTag, IF_MATCH};
 
-crate::http::header::common_header! {
+common_header! {
     /// `If-Match` header, defined
     /// in [RFC 7232 §3.1](https://datatracker.ietf.org/doc/html/rfc7232#section-3.1)
     ///
@@ -17,7 +17,7 @@ crate::http::header::common_header! {
     /// there have been any changes to the representation data.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// If-Match = "*" / 1#entity-tag
     /// ```
     ///

src/http/header/if_modified_since.rs

@@ -11,7 +11,7 @@ crate::http::header::common_header! {
     /// data has not changed.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// If-Unmodified-Since = HTTP-date
     /// ```
     ///

src/http/header/if_none_match.rs

@@ -16,7 +16,7 @@ crate::http::header::common_header! {
     /// the representation data.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// If-None-Match = "*" / 1#entity-tag
     /// ```
     ///

src/http/header/if_range.rs

@@ -25,7 +25,7 @@ use crate::HttpMessage;
 /// in Range; otherwise, send me the entire representation.
 ///
 /// # ABNF
-/// ```text
+/// ```plain
 /// If-Range = entity-tag / HTTP-date
 /// ```
 ///
@@ -107,10 +107,11 @@ impl IntoHeaderValue for IfRange {
 }
 
 #[cfg(test)]
-mod test_if_range {
+mod test_parse_and_format {
+    use std::str;
+
     use super::IfRange as HeaderField;
     use crate::http::header::*;
-    use std::str;
 
     crate::http::header::common_header_test!(test1, vec![b"Sat, 29 Oct 1994 19:43:31 GMT"]);
     crate::http::header::common_header_test!(test2, vec![b"\"abc\""]);

src/http/header/if_unmodified_since.rs

@@ -11,7 +11,7 @@ crate::http::header::common_header! {
     /// the user agent does not have an entity-tag for the representation.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// If-Unmodified-Since = HTTP-date
     /// ```
     ///

src/http/header/last_modified.rs

@@ -10,7 +10,7 @@ crate::http::header::common_header! {
     /// conclusion of handling the request.
     ///
     /// # ABNF
-    /// ```text
+    /// ```plain
     /// Expires = HTTP-date
     /// ```
     ///

src/http/header/macros.rs

@@ -1,25 +1,3 @@
-// TODO: replace with derive_more impl
-macro_rules! common_header_deref {
-    ($from:ty => $to:ty) => {
-        impl ::core::ops::Deref for $from {
-            type Target = $to;
-
-            #[inline]
-            fn deref(&self) -> &Self::Target {
-                &self.0
-            }
-        }
-
-        impl ::core::ops::DerefMut for $from {
-            #[inline]
-            fn deref_mut(&mut self) -> &mut Self::Target {
-                &mut self.0
-            }
-        }
-    };
-}
-
-/// Sets up a test module with some useful imports for use with [`common_header_test!`].
 macro_rules! common_header_test_module {
     ($id:ident, $tm:ident{$($tf:item)*}) => {
         #[cfg(test)]
@@ -87,10 +65,6 @@ macro_rules! common_header_test {
             let val = HeaderField::parse(&req);
             let exp: Option<HeaderField> = $exp;
 
-            println!("req: {:?}", &req);
-            println!("val: {:?}", &val);
-            println!("exp: {:?}", &exp);
-
             // test parsing
             assert_eq!(val.ok(), exp);
 
@@ -114,17 +88,17 @@ macro_rules! common_header_test {
 
 macro_rules! common_header {
     // TODO: these docs are wrong, there's no $n or $nn
-    // $a:meta: Attributes associated with the header item (usually docs)
+    // $attrs:meta: Attributes associated with the header item (usually docs)
     // $id:ident: Identifier of the header
     // $n:expr: Lowercase name of the header
     // $nn:expr: Nice name of the header
 
     // List header, zero or more items
-    ($(#[$a:meta])*($id:ident, $name:expr) => ($item:ty)*) => {
-        $(#[$a])*
-        #[derive(Clone, Debug, PartialEq)]
+    ($(#[$attrs:meta])*($id:ident, $name:expr) => ($item:ty)*) => {
+        $(#[$attrs])*
+        #[derive(Debug, Clone, PartialEq, Eq, ::derive_more::Deref, ::derive_more::DerefMut)]
         pub struct $id(pub Vec<$item>);
-        crate::http::header::common_header_deref!($id => Vec<$item>);
+
         impl $crate::http::header::Header for $id {
             #[inline]
             fn name() -> $crate::http::header::HeaderName {
@@ -158,13 +132,11 @@ macro_rules! common_header {
     };
 
     // List header, one or more items
-    ($(#[$a:meta])*($id:ident, $name:expr) => ($item:ty)+) => {
-        $(#[$a])*
-        #[derive(Clone, Debug, PartialEq)]
+    ($(#[$attrs:meta])*($id:ident, $name:expr) => ($item:ty)+) => {
+        $(#[$attrs])*
+        #[derive(Debug, Clone, PartialEq, Eq, ::derive_more::Deref, ::derive_more::DerefMut)]
         pub struct $id(pub Vec<$item>);
 
-        crate::http::header::common_header_deref!($id => Vec<$item>);
-
         impl $crate::http::header::Header for $id {
             #[inline]
             fn name() -> $crate::http::header::HeaderName {
@@ -197,13 +169,11 @@ macro_rules! common_header {
     };
 
     // Single value header
-    ($(#[$a:meta])*($id:ident, $name:expr) => [$value:ty]) => {
-        $(#[$a])*
-        #[derive(Clone, Debug, PartialEq)]
+    ($(#[$attrs:meta])*($id:ident, $name:expr) => [$value:ty]) => {
+        $(#[$attrs])*
+        #[derive(Debug, Clone, PartialEq, Eq, ::derive_more::Deref, ::derive_more::DerefMut)]
         pub struct $id(pub $value);
 
-        crate::http::header::common_header_deref!($id => $value);
-
         impl $crate::http::header::Header for $id {
             #[inline]
             fn name() -> $crate::http::header::HeaderName {
@@ -234,8 +204,8 @@ macro_rules! common_header {
     };
 
     // List header, one or more items with "*" option
-    ($(#[$a:meta])*($id:ident, $name:expr) => {Any / ($item:ty)+}) => {
-        $(#[$a])*
+    ($(#[$attrs:meta])*($id:ident, $name:expr) => {Any / ($item:ty)+}) => {
+        $(#[$attrs])*
         #[derive(Clone, Debug, PartialEq)]
         pub enum $id {
             /// Any value is a match
@@ -291,32 +261,32 @@ macro_rules! common_header {
     };
 
     // optional test module
-    ($(#[$a:meta])*($id:ident, $name:expr) => ($item:ty)* $tm:ident{$($tf:item)*}) => {
+    ($(#[$attrs:meta])*($id:ident, $name:expr) => ($item:ty)* $tm:ident{$($tf:item)*}) => {
         crate::http::header::common_header! {
-            $(#[$a])*
+            $(#[$attrs])*
             ($id, $name) => ($item)*
         }
 
         crate::http::header::common_header_test_module! { $id, $tm { $($tf)* }}
     };
-    ($(#[$a:meta])*($id:ident, $n:expr) => ($item:ty)+ $tm:ident{$($tf:item)*}) => {
+    ($(#[$attrs:meta])*($id:ident, $n:expr) => ($item:ty)+ $tm:ident{$($tf:item)*}) => {
         crate::http::header::common_header! {
-            $(#[$a])*
+            $(#[$attrs])*
             ($id, $n) => ($item)+
         }
 
         crate::http::header::common_header_test_module! { $id, $tm { $($tf)* }}
     };
-    ($(#[$a:meta])*($id:ident, $name:expr) => [$item:ty] $tm:ident{$($tf:item)*}) => {
+    ($(#[$attrs:meta])*($id:ident, $name:expr) => [$item:ty] $tm:ident{$($tf:item)*}) => {
         crate::http::header::common_header! {
-            $(#[$a])* ($id, $name) => [$item]
+            $(#[$attrs])* ($id, $name) => [$item]
         }
 
         crate::http::header::common_header_test_module! { $id, $tm { $($tf)* }}
     };
-    ($(#[$a:meta])*($id:ident, $name:expr) => {Any / ($item:ty)+} $tm:ident{$($tf:item)*}) => {
+    ($(#[$attrs:meta])*($id:ident, $name:expr) => {Any / ($item:ty)+} $tm:ident{$($tf:item)*}) => {
         crate::http::header::common_header! {
-            $(#[$a])*
+            $(#[$attrs])*
             ($id, $name) => {Any / ($item)+}
         }
 
@@ -324,7 +294,7 @@ macro_rules! common_header {
     };
 }
 
-pub(crate) use {common_header, common_header_deref, common_header_test_module};
+pub(crate) use {common_header, common_header_test_module};
 
 #[cfg(test)]
 pub(crate) use common_header_test;

src/http/header/mod.rs

@@ -44,7 +44,7 @@ mod preference;
 
 #[cfg(test)]
 pub(crate) use macros::common_header_test;
-pub(crate) use macros::{common_header, common_header_deref, common_header_test_module};
+pub(crate) use macros::{common_header, common_header_test_module};
 
 pub use self::accept_charset::AcceptCharset;
 //pub use self::accept_encoding::AcceptEncoding;

src/http/header/range.rs

@@ -1,8 +1,11 @@
-use std::fmt::{self, Display};
-use std::str::FromStr;
+// TODO: reinstate module
 
-use super::parsing::from_one_raw_str;
-use super::{Header, Raw};
+use std::{
+    fmt::{self, Display},
+    str::FromStr,
+};
+
+use super::{parsing::from_one_raw_str, Header, Raw};
 
 /// `Range` header, defined
 /// in [RFC 7233 §3.1](https://datatracker.ietf.org/doc/html/rfc7233#section-3.1)
@@ -12,7 +15,7 @@ use super::{Header, Raw};
 /// representation data.
 ///
 /// # ABNF
-/// ```text
+/// ```plain
 /// Range =	byte-ranges-specifier / other-ranges-specifier
 /// other-ranges-specifier = other-range-unit "=" other-range-set
 /// other-range-set = 1*VCHAR