feat(allow-block-list): add getters and return results (#5572)

## Description

Small changes to improve usability of the `allow-block-list` Behaviour.
When trying to use it, we found ourselves wanting to known:
- which were the current allowed or blocked peers: hence the new methods
`allowed_peers` and `blocked_peers`
- if the peer was already present in the set when adding or removing it
from the set: that is why `allow/disallow_peer` and `block/unblock_peer`
methods now return a boolean, allowing the end user the know if there
was a change or not (in our case, we needed it in order to log
something).

## Notes & open questions

<!--
Any notes, remarks or open questions you have to make about the PR which
don't need to go into the final commit message.
-->

## Change checklist

<!-- Please add a Changelog entry in the appropriate crates and bump the
crate versions if needed. See
<https://github.com/libp2p/rust-libp2p/blob/master/docs/release.md#development-between-releases>-->

- [x] I have performed a self-review of my own code
- [x] I have made corresponding changes to the documentation
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] A changelog entry has been made in the appropriate crates

Cargo.toml

@@ -76,7 +76,7 @@ asynchronous-codec = { version = "0.7.0" }
 futures-bounded = { version = "0.2.4" }
 futures-rustls = { version = "0.26.0", default-features = false }
 libp2p = { version = "0.54.1", path = "libp2p" }
-libp2p-allow-block-list = { version = "0.4.0", path = "misc/allow-block-list" }
+libp2p-allow-block-list = { version = "0.4.1", path = "misc/allow-block-list" }
 libp2p-autonat = { version = "0.13.0", path = "protocols/autonat" }
 libp2p-connection-limits = { version = "0.4.0", path = "misc/connection-limits" }
 libp2p-core = { version = "0.42.0", path = "core" }

misc/allow-block-list/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.4.1
+
+- Add getters & setters for the allowed/blocked peers.
+  Return a `bool` for every "insert/remove" function, informing if a change was performed.
+  See [PR 5572](https://github.com/libp2p/rust-libp2p/pull/5572).
+
 ## 0.4.0
 
 <!-- Update to libp2p-swarm v0.45.0 -->

misc/allow-block-list/Cargo.toml

@@ -3,7 +3,7 @@ name = "libp2p-allow-block-list"
 edition = "2021"
 rust-version = { workspace = true }
 description = "Allow/block list connection management for libp2p."
-version = "0.4.0"
+version = "0.4.1"
 license = "MIT"
 repository = "https://github.com/libp2p/rust-libp2p"
 keywords = ["peer-to-peer", "libp2p", "networking"]

misc/allow-block-list/src/lib.rs

@@ -94,44 +94,74 @@ pub struct BlockedPeers {
 }
 
 impl Behaviour<AllowedPeers> {
+    /// Peers that are currently allowed.
+    pub fn allowed_peers(&self) -> &HashSet<PeerId> {
+        &self.state.peers
+    }
+
     /// Allow connections to the given peer.
-    pub fn allow_peer(&mut self, peer: PeerId) {
-        self.state.peers.insert(peer);
-        if let Some(waker) = self.waker.take() {
-            waker.wake()
+    ///
+    /// Returns whether the peer was newly inserted. Does nothing if the peer was already present in the set.
+    pub fn allow_peer(&mut self, peer: PeerId) -> bool {
+        let inserted = self.state.peers.insert(peer);
+        if inserted {
+            if let Some(waker) = self.waker.take() {
+                waker.wake()
+            }
         }
+        inserted
     }
 
     /// Disallow connections to the given peer.
     ///
     /// All active connections to this peer will be closed immediately.
-    pub fn disallow_peer(&mut self, peer: PeerId) {
-        self.state.peers.remove(&peer);
-        self.close_connections.push_back(peer);
-        if let Some(waker) = self.waker.take() {
-            waker.wake()
+    ///
+    /// Returns whether the peer was present in the set. Does nothing if the peer was not present in the set.
+    pub fn disallow_peer(&mut self, peer: PeerId) -> bool {
+        let removed = self.state.peers.remove(&peer);
+        if removed {
+            self.close_connections.push_back(peer);
+            if let Some(waker) = self.waker.take() {
+                waker.wake()
+            }
         }
+        removed
     }
 }
 
 impl Behaviour<BlockedPeers> {
+    /// Peers that are currently blocked.
+    pub fn blocked_peers(&self) -> &HashSet<PeerId> {
+        &self.state.peers
+    }
+
     /// Block connections to a given peer.
     ///
     /// All active connections to this peer will be closed immediately.
-    pub fn block_peer(&mut self, peer: PeerId) {
-        self.state.peers.insert(peer);
-        self.close_connections.push_back(peer);
-        if let Some(waker) = self.waker.take() {
-            waker.wake()
+    ///
+    /// Returns whether the peer was newly inserted. Does nothing if the peer was already present in the set.
+    pub fn block_peer(&mut self, peer: PeerId) -> bool {
+        let inserted = self.state.peers.insert(peer);
+        if inserted {
+            self.close_connections.push_back(peer);
+            if let Some(waker) = self.waker.take() {
+                waker.wake()
+            }
         }
+        inserted
     }
 
     /// Unblock connections to a given peer.
-    pub fn unblock_peer(&mut self, peer: PeerId) {
-        self.state.peers.remove(&peer);
-        if let Some(waker) = self.waker.take() {
-            waker.wake()
+    ///
+    /// Returns whether the peer was present in the set. Does nothing if the peer was not present in the set.
+    pub fn unblock_peer(&mut self, peer: PeerId) -> bool {
+        let removed = self.state.peers.remove(&peer);
+        if removed {
+            if let Some(waker) = self.waker.take() {
+                waker.wake()
+            }
         }
+        removed
     }
 }