sdk: add support for blocking APIs

sdk/CHANGELOG.md

@@ -72,6 +72,7 @@
 - Add `Output::new` constructor and `Output::into_inner` method
 - Add idle timeout for negentropy sync (https://github.com/rust-nostr/nostr/pull/1131)
 - Add `GossipAllowedRelays` to `GossipOptions` to filter relays during selection (https://github.com/rust-nostr/nostr/pull/1128)
+- Add support for blocking APIs (https://github.com/rust-nostr/nostr/pull/1246)
 
 ## v0.44.1 - 2025/11/09
 

sdk/examples/blocking.rs

@@ -0,0 +1,57 @@
+use std::collections::HashMap;
+use std::time::Duration;
+
+use nostr_sdk::prelude::*;
+
+fn main() -> Result<()> {
+    tracing_subscriber::fmt::init();
+
+    let client: Client = Client::default();
+
+    client
+        .add_relay("wss://relay.damus.io")
+        .and_connect()
+        .blocking()?;
+
+    client
+        .add_relay("wss://relay.nostr.band")
+        .and_connect()
+        .blocking()?;
+
+    let public_key =
+        PublicKey::from_bech32("npub1080l37pfvdpyuzasyuy2ytjykjvq3ylr5jlqlg7tvzjrh9r8vn3sf5yaph")?;
+
+    // Example 1: Subscribe with a single filter (broadcast to all relays)
+    let filter = Filter::new().author(public_key).kind(Kind::Metadata);
+    let output = client.subscribe(filter).blocking()?;
+    println!("{:?}", output);
+
+    // Example 2: Subscribe with multiple filters
+    let filters = vec![
+        Filter::new().author(public_key).kind(Kind::TextNote),
+        Filter::new().author(public_key).kind(Kind::Metadata),
+    ];
+    let output = client.subscribe(filters).blocking()?;
+    println!("{:?}", output);
+
+    // Example 3: Targeted subscription with HashMap<&str, Filter>
+    let mut targets = HashMap::new();
+    targets.insert("wss://relay.damus.io", Filter::new().kind(Kind::TextNote));
+    targets.insert("wss://relay.nostr.band", Filter::new().kind(Kind::Metadata));
+    let output = client.subscribe(targets).blocking()?;
+    println!("{:?}", output);
+
+    // Example 4: Targeted subscription with HashMap<String, Vec<Filter>>
+    let mut targets = HashMap::new();
+    targets.insert(
+        "wss://relay.damus.io".to_string(),
+        vec![Filter::new().kind(Kind::TextNote)],
+    );
+    let output = client.subscribe(targets).blocking()?;
+
+    println!("{:?}", output);
+
+    loop {
+        std::thread::sleep(Duration::from_secs(60));
+    }
+}

sdk/src/blocking.rs

@@ -0,0 +1,101 @@
+/// Implements an inherent `blocking(self)` method for a type that already implements `IntoFuture`.
+///
+/// - On `wasm32`, the method is not generated (blocking the thread isn't supported).
+/// - The return type is inferred as `<Self as IntoFuture>::Output`.
+macro_rules! impl_blocking {
+    // ---- Generic form: accepts explicit generics (lifetimes, types, consts) ----
+    (for<$($gen:tt),+> $ty:ty where $($where:tt)+) => {
+        impl<$($gen),+> $ty
+        where
+            $($where)+
+        {
+            /// Execute the operation synchronously.
+            ///
+            /// # Important
+            ///
+            /// Avoid calling this from within an `async` context, as it may lead to
+            /// "resource starvation" or a deadlock. Prefer `.await` whenever possible.
+            ///
+            /// This is runtime-agnostic and uses a local executor to drive the future
+            /// to completion.
+            #[inline]
+            #[cfg(not(target_family = "wasm"))]
+            pub fn blocking(self) -> <Self as ::std::future::IntoFuture>::Output
+            where
+                Self: ::std::future::IntoFuture,
+            {
+                ::futures::executor::block_on(::std::future::IntoFuture::into_future(self))
+            }
+        }
+    };
+
+    (for<$($gen:tt),+> $ty:ty) => {
+        impl<$($gen),+> $ty {
+            /// Execute the operation synchronously.
+            ///
+            /// # Important
+            ///
+            /// Avoid calling this from within an `async` context, as it may lead to
+            /// "resource starvation" or a deadlock. Prefer `.await` whenever possible.
+            ///
+            /// This is runtime-agnostic and uses a local executor to drive the future
+            /// to completion.
+            #[inline]
+            #[cfg(not(target_family = "wasm"))]
+            pub fn blocking(self) -> <Self as ::std::future::IntoFuture>::Output
+            where
+                Self: ::std::future::IntoFuture,
+            {
+                ::futures::executor::block_on(::std::future::IntoFuture::into_future(self))
+            }
+        }
+    };
+
+    // ---- Non-generic form: works for concrete types or elided lifetimes ----
+    ($ty:ty where $($where:tt)+) => {
+        impl $ty
+        where
+            $($where)+
+        {
+            /// Execute the operation synchronously.
+            ///
+            /// # Important
+            ///
+            /// Avoid calling this from within an `async` context, as it may lead to
+            /// "resource starvation" or a deadlock. Prefer `.await` whenever possible.
+            ///
+            /// This is runtime-agnostic and uses a local executor to drive the future
+            /// to completion.
+            #[inline]
+            #[cfg(not(target_family = "wasm"))]
+            pub fn blocking(self) -> <Self as ::std::future::IntoFuture>::Output
+            where
+                Self: ::std::future::IntoFuture,
+            {
+                ::futures::executor::block_on(::std::future::IntoFuture::into_future(self))
+            }
+        }
+    };
+
+    ($ty:ty) => {
+        impl $ty {
+            /// Execute the operation synchronously.
+            ///
+            /// # Important
+            ///
+            /// Avoid calling this from within an `async` context, as it may lead to
+            /// "resource starvation" or a deadlock. Prefer `.await` whenever possible.
+            ///
+            /// This is runtime-agnostic and uses a local executor to drive the future
+            /// to completion.
+            #[inline]
+            #[cfg(not(target_family = "wasm"))]
+            pub fn blocking(self) -> <Self as ::std::future::IntoFuture>::Output
+            where
+                Self: ::std::future::IntoFuture,
+            {
+                ::futures::executor::block_on(::std::future::IntoFuture::into_future(self))
+            }
+        }
+    };
+}

sdk/src/client/api/add.rs

@@ -158,6 +158,8 @@ where
     }
 }
 
+impl_blocking!(for<'client, 'url> AddRelay<'client, 'url> where 'url: 'client);
+
 #[cfg(test)]
 mod tests {
     use super::*;

sdk/src/client/api/connect.rs

@@ -47,3 +47,5 @@ impl<'client> IntoFuture for Connect<'client> {
         })
     }
 }
+
+impl_blocking!(Connect<'_>);

sdk/src/client/api/fetch_events.rs

@@ -92,3 +92,5 @@ where
         })
     }
 }
+
+impl_blocking!(for<'client, 'url> FetchEvents<'client, 'url> where 'url: 'client);

sdk/src/client/api/relays.rs

@@ -69,6 +69,8 @@ impl<'client> IntoFuture for GetRelays<'client> {
     }
 }
 
+impl_blocking!(GetRelays<'_>);
+
 #[cfg(test)]
 mod tests {
     use super::*;

sdk/src/client/api/remove.rs

@@ -49,6 +49,8 @@ where
     }
 }
 
+impl_blocking!(for<'client, 'url> RemoveRelay<'client, 'url> where 'url: 'client);
+
 #[cfg(test)]
 mod tests {
     use super::*;

sdk/src/client/api/remove_all.rs

@@ -38,6 +38,8 @@ impl<'client> IntoFuture for RemoveAllRelays<'client> {
     }
 }
 
+impl_blocking!(RemoveAllRelays<'_>);
+
 #[cfg(test)]
 mod tests {
     use super::*;

sdk/src/client/api/send_event.rs

@@ -370,6 +370,8 @@ where
     }
 }
 
+impl_blocking!(for<'client, 'event, 'url> SendEvent<'client, 'event, 'url> where 'event: 'client, 'url: 'client);
+
 #[cfg(test)]
 mod tests {
     use nostr::prelude::*;

sdk/src/client/api/send_msg.rs

@@ -109,6 +109,8 @@ where
     }
 }
 
+impl_blocking!(for<'client, 'msg, 'url> SendMessage<'client, 'msg, 'url> where 'msg: 'client, 'url: 'client);
+
 #[cfg(test)]
 mod tests {
     use nostr::prelude::*;

sdk/src/client/api/subscribe.rs

@@ -66,3 +66,5 @@ where
         })
     }
 }
+
+impl_blocking!(for<'client, 'url> Subscribe<'client, 'url> where 'url: 'client);

sdk/src/client/api/sync.rs

@@ -190,3 +190,5 @@ where
         })
     }
 }
+
+impl_blocking!(for<'client, 'url> SyncEvents<'client, 'url> where 'url: 'client);

sdk/src/client/api/try_connect.rs

@@ -43,3 +43,5 @@ impl<'client> IntoFuture for TryConnect<'client> {
         Box::pin(async move { self.client.pool.try_connect(self.timeout).await })
     }
 }
+
+impl_blocking!(TryConnect<'_>);

sdk/src/client/api/unsubscribe.rs

@@ -35,3 +35,5 @@ where
         })
     }
 }
+
+impl_blocking!(for<'client, 'id> Unsubscribe<'client, 'id> where 'id: 'client);

sdk/src/client/api/unsubscribe_all.rs

@@ -29,3 +29,5 @@ impl<'client> IntoFuture for UnsubscribeAll<'client> {
         })
     }
 }
+
+impl_blocking!(UnsubscribeAll<'_>);

sdk/src/lib.rs

@@ -7,6 +7,8 @@
 #![allow(clippy::mutable_key_type)] // TODO: remove when possible. Needed to suppress false positive for `BTreeSet<Event>`
 #![doc = include_str!("../README.md")]
 
+#[macro_use]
+mod blocking;
 pub mod client;
 pub mod monitor;
 pub mod policy;

sdk/src/relay/api/fetch_events.rs

@@ -91,6 +91,8 @@ impl<'relay> IntoFuture for FetchEvents<'relay> {
     }
 }
 
+impl_blocking!(FetchEvents<'_>);
+
 #[cfg(test)]
 mod tests {
     use nostr::message::MachineReadablePrefix;

sdk/src/relay/api/send_event.rs

@@ -143,6 +143,8 @@ where
     }
 }
 
+impl_blocking!(for<'relay, 'event> SendEvent<'relay, 'event> where 'event: 'relay);
+
 #[cfg(test)]
 mod tests {
     use std::time::Duration;

sdk/src/relay/api/send_msg.rs

@@ -53,3 +53,5 @@ where
         })
     }
 }
+
+impl_blocking!(for<'relay, 'msg> SendMessage<'relay, 'msg> where 'msg: 'relay);

sdk/src/relay/api/subscribe.rs

@@ -136,6 +136,8 @@ impl<'relay> IntoFuture for Subscribe<'relay> {
     }
 }
 
+impl_blocking!(Subscribe<'_>);
+
 #[cfg(test)]
 mod tests {
     use std::time::Duration;

sdk/src/relay/api/sync.rs

@@ -614,6 +614,8 @@ impl<'relay> IntoFuture for SyncEvents<'relay> {
     }
 }
 
+impl_blocking!(SyncEvents<'_>);
+
 #[cfg(test)]
 mod tests {
     use std::collections::{HashMap, HashSet};

sdk/src/relay/api/try_connect.rs

@@ -78,6 +78,8 @@ impl<'relay> IntoFuture for TryConnect<'relay> {
     }
 }
 
+impl_blocking!(TryConnect<'_>);
+
 #[cfg(test)]
 mod tests {
     use async_utility::time;

sdk/src/relay/api/unsubscribe.rs

@@ -30,3 +30,5 @@ where
         Box::pin(async move { self.relay.inner.unsubscribe(self.id).await })
     }
 }
+
+impl_blocking!(for<'relay, 'id> Unsubscribe<'relay, 'id> where 'id: 'relay);

sdk/src/relay/api/unsubscribe_all.rs

@@ -24,3 +24,5 @@ impl<'relay> IntoFuture for UnsubscribeAll<'relay> {
         Box::pin(async move { self.relay.inner.unsubscribe_all().await })
     }
 }
+
+impl_blocking!(UnsubscribeAll<'_>);