Merge pull request #838 from zeenix/interface-gen-proxy

✨ zm: interface can now generate proxy for you

Author: zeenix

book/src/server.md

@@ -353,8 +353,81 @@ iface.greeter_name_changed(iface_ref.signal_context()).await?;
 # }
 ```
 
+## Proxy generation
+
+`interface` macro can also generate the client-side proxy code for you. It utilizes the [`proxy`]
+macro behind the scenes to achieve this. Here is how to use it:
+
+```rust
+use zbus::interface;
+
+struct Greeter {
+    name: String
+}
+
+#[interface(
+    name = "org.zbus.MyGreeter.WithProxy",
+    // Specifying the `proxy` attribute instructs `interface` to generate the
+    // client-side proxy. You can specify proxy-specific attributes
+    // (e.g `gen_blocking) here. All the attributes that are common between
+    // `proxy` and `interface` macros (e.g `name`) are automtically forwarded to
+    // the `proxy` macro.
+    proxy(
+        gen_blocking = false,
+        default_path = "/org/zbus/MyGreeter/WithProxy",
+        default_service = "org.zbus.MyGreeter.WithProxy",
+    ),
+)]
+impl Greeter {
+    #[zbus(property)]
+    async fn greeter_name(&self) -> String {
+        self.name.clone()
+    }
+
+    #[zbus(proxy(no_reply))]
+    async fn whatever(&self) {
+        println!("Whatever!");
+    }
+}
+
+# #[tokio::main]
+# async fn main() -> zbus::Result<()> {
+
+let greeter = Greeter { name: "GreeterName".to_string() };
+let connection = zbus::connection::Builder::session()?
+        .name("org.zbus.MyGreeter.WithProxy")?
+        .serve_at("/org/zbus/MyGreeter/WithProxy", greeter)?
+        .build()
+        .await?;
+let proxy = GreeterProxy::new(&connection).await?;
+assert_eq!(proxy.greeter_name().await?, "GreeterName");
+proxy.whatever().await?;
+
+# Ok(())
+# }
+```
+
+### Known Limitations
+
+While it's extremely useful to be able to generate the client-side proxy code directly from
+`interface` as it allows you to avoid duplicating code, there are some limitations to be aware of:
+
+* The trait bounds of the `proxy` macro methods' arguments and return value, now also apply to the
+  `interface` methods. For example, when only generating the server-side code, the method return
+  values need to implement `serde::Serialize` but when generating the client-side proxy code, the
+  method return values need to implement `serde::DeserializeOwned` as well.
+* Reference types in return values of `interface` methods won't work. As you may have noticed,
+  unlike the previous examples the `greeter_name` method in the example above returns a `String`
+  instead of a `&str`. This is because the methods in the `proxy` macro do not support reference
+  type to be returned from its methods.
+* Methods returning [`object_server::ResponseDispatchNotifier`] wrapper type will do the same for
+  proxy as well.
+* Only `interface` macro supports this feature, while the deprecated `dbus_interface` macro does
+  not. Still haven't switched to `interface` and want to use this feature? Time to switch!
+
 [D-Bus concepts]: concepts.html#bus-name--service-name
 [didoc]: https://docs.rs/zbus/4/zbus/attr.interface.html
 [`zbus::DBusError`]:https://docs.rs/zbus/4/zbus/trait.DBusError.html
 [`zbus::fdo::Error`]: https://docs.rs/zbus/4/zbus/fdo/enum.Error.html
 [`zbus::fdo::Error::UnknownProperty`]: https://docs.rs/zbus/4/zbus/fdo/enum.Error.html#variant.UnknownProperty
+[`proxy`]: https://docs.rs/zbus/4/zbus/attr.proxy.html

zbus/src/object_server/mod.rs

@@ -1,7 +1,7 @@
 //! The object server API.
 
 use event_listener::{Event, EventListener};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 use std::{
     collections::{hash_map::Entry, HashMap},
     fmt::Write,
@@ -856,6 +856,11 @@ impl<R> ResponseDispatchNotifier<R> {
             listener,
         )
     }
+
+    /// Get the response.
+    pub fn response(&self) -> &R {
+        &self.response
+    }
 }
 
 impl<R> Serialize for ResponseDispatchNotifier<R>
@@ -870,6 +875,21 @@ where
     }
 }
 
+impl<'de, R> Deserialize<'de> for ResponseDispatchNotifier<R>
+where
+    R: Deserialize<'de>,
+{
+    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        Ok(Self {
+            response: R::deserialize(deserializer)?,
+            event: None,
+        })
+    }
+}
+
 impl<R> Type for ResponseDispatchNotifier<R>
 where
     R: Type,