Support deserializing paths to sequences for multi-component (eg. tail) matches (#3432)

* Support deserializing paths to sequences for multi-component (eg. tail) matches

* Support deserializing paths to sequences: use "/{tail}*" syntax

* some fixes

* make `size_hint` work properly

* fix for tuple struct

---------

Co-authored-by: Yuki Okushi <huyuumi.dev@gmail.com>

actix-router/CHANGES.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Add support for extracting multi-component path params into a sequence (Vec, tuple, ...). [#3432]
+
+[#3432]: https://github.com/actix/actix-web/pull/3432
+
 ## 0.5.4
 
 - Minimum supported Rust version (MSRV) is now 1.88.

actix-router/src/de.rs

@@ -399,11 +399,25 @@ impl<'de> Deserializer<'de> for Value<'de> {
         visitor.visit_newtype_struct(self)
     }
 
-    fn deserialize_tuple<V>(self, _: usize, _: V) -> Result<V::Value, Self::Error>
+    fn deserialize_tuple<V>(self, len: usize, visitor: V) -> Result<V::Value, Self::Error>
     where
         V: Visitor<'de>,
     {
-        Err(de::value::Error::custom("unsupported type: tuple"))
+        let value_seq = ValueSeq::new(self.value);
+        if len == value_seq.len() {
+            visitor.visit_seq(value_seq)
+        } else {
+            Err(de::value::Error::custom(
+                "path and tuple lengths don't match",
+            ))
+        }
+    }
+
+    fn deserialize_seq<V>(self, visitor: V) -> Result<V::Value, Self::Error>
+    where
+        V: Visitor<'de>,
+    {
+        visitor.visit_seq(ValueSeq::new(self.value))
     }
 
     fn deserialize_struct<V>(
@@ -421,13 +435,13 @@ impl<'de> Deserializer<'de> for Value<'de> {
     fn deserialize_tuple_struct<V>(
         self,
         _: &'static str,
-        _: usize,
-        _: V,
+        len: usize,
+        visitor: V,
     ) -> Result<V::Value, Self::Error>
     where
         V: Visitor<'de>,
     {
-        Err(de::value::Error::custom("unsupported type: tuple struct"))
+        self.deserialize_tuple(len, visitor)
     }
 
     fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
@@ -463,7 +477,6 @@ impl<'de> Deserializer<'de> for Value<'de> {
         }
     }
 
-    unsupported_type!(deserialize_seq, "seq");
     unsupported_type!(deserialize_map, "map");
     unsupported_type!(deserialize_identifier, "identifier");
 }
@@ -533,6 +546,43 @@ impl<'de> de::VariantAccess<'de> for UnitVariant {
     }
 }
 
+struct ValueSeq<'de> {
+    elems: std::str::Split<'de, char>,
+}
+
+impl<'de> ValueSeq<'de> {
+    fn new(value: &'de str) -> Self {
+        Self {
+            elems: value.split('/'),
+        }
+    }
+
+    fn len(&self) -> usize {
+        self.elems.clone().filter(|s| !s.is_empty()).count()
+    }
+}
+
+impl<'de> de::SeqAccess<'de> for ValueSeq<'de> {
+    type Error = de::value::Error;
+
+    fn next_element_seed<T>(&mut self, seed: T) -> Result<Option<T::Value>, Self::Error>
+    where
+        T: de::DeserializeSeed<'de>,
+    {
+        for elem in &mut self.elems {
+            if !elem.is_empty() {
+                return seed.deserialize(Value { value: elem }).map(Some);
+            }
+        }
+
+        Ok(None)
+    }
+
+    fn size_hint(&self) -> Option<usize> {
+        Some(self.len())
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use serde::Deserialize;
@@ -567,6 +617,24 @@ mod tests {
         val: TestEnum,
     }
 
+    #[derive(Debug, Deserialize)]
+    struct TestSeq1 {
+        tail: Vec<String>,
+    }
+
+    #[derive(Debug, Deserialize)]
+    struct TestSeq2 {
+        tail: (String, String, String),
+    }
+
+    #[derive(Debug, Deserialize)]
+    struct TestSeq3 {
+        tail: TestTupleStruct,
+    }
+
+    #[derive(Debug, Deserialize, PartialEq)]
+    struct TestTupleStruct(String, String, String);
+
     #[test]
     fn test_request_extract() {
         let mut router = Router::<()>::build();
@@ -662,6 +730,62 @@ mod tests {
         assert!(format!("{:?}", i).contains("unknown variant"));
     }
 
+    #[test]
+    fn test_extract_seq() {
+        let mut router = Router::<()>::build();
+        router.path("/path/to/{tail}*", ());
+        let router = router.finish();
+
+        let mut path = Path::new("/path/to/tail/with/slash%2fes");
+        assert!(router.recognize(&mut path).is_some());
+
+        let i: (String,) = de::Deserialize::deserialize(PathDeserializer::new(&path)).unwrap();
+        assert_eq!(i.0, String::from("tail/with/slash/es"));
+
+        let i: TestSeq1 = de::Deserialize::deserialize(PathDeserializer::new(&path)).unwrap();
+        assert_eq!(
+            i.tail,
+            vec![
+                String::from("tail"),
+                String::from("with"),
+                String::from("slash/es")
+            ]
+        );
+
+        let i: TestSeq2 = de::Deserialize::deserialize(PathDeserializer::new(&path)).unwrap();
+        assert_eq!(
+            i.tail,
+            (
+                String::from("tail"),
+                String::from("with"),
+                String::from("slash/es")
+            )
+        );
+
+        let i: TestSeq3 = de::Deserialize::deserialize(PathDeserializer::new(&path)).unwrap();
+        assert_eq!(
+            i.tail,
+            TestTupleStruct(
+                String::from("tail"),
+                String::from("with"),
+                String::from("slash/es")
+            )
+        );
+    }
+
+    #[test]
+    fn test_value_seq_size_hint_counts_remaining_elements() {
+        use serde::de::SeqAccess as _;
+
+        let mut seq = ValueSeq::new("tail/with/slash");
+
+        assert_eq!(seq.size_hint(), Some(3));
+
+        let elem = seq.next_element::<String>().unwrap();
+        assert_eq!(elem.as_deref(), Some("tail"));
+        assert_eq!(seq.size_hint(), Some(2));
+    }
+
     #[test]
     fn test_extract_errors() {
         let mut router = Router::<()>::build();

actix-web/src/types/path.rs

@@ -53,6 +53,26 @@ use crate::{
 ///     format!("Welcome {}!", info.name)
 /// }
 /// ```
+///
+/// Segments matching multiple path components can be deserialized
+/// into a `Vec<_>` to percent-decode the components individually. Empty
+/// path components are ignored.
+///
+/// ```
+/// use actix_web::{get, web};
+/// use serde::Deserialize;
+///
+/// #[derive(Deserialize)]
+/// struct Tail {
+///     tail: Vec<String>,
+/// }
+///
+/// // extract `Tail` from a path using serde
+/// #[get("/path/to/{tail}*")]
+/// async fn index(info: web::Path<Tail>) -> String {
+///     format!("Navigating to {}!", info.tail.join(" :: "))
+/// }
+/// ```
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Deref, DerefMut, AsRef, Display, From)]
 pub struct Path<T>(T);