PL Dev Guild Issue: refactor the swarm.listen() in rust-libp2p

[P1R]

Hello, since the first issue was a bit complex I decide to go on the second issue which I could not find in the Open issues section but it describes the following:

"2. refactor the swarm.listen() in rust-libp2p so that it returns a "listen_id" that gets passed back with SwarmEvent::NewListenAddress as well as a new SwarmEvent::ListenSetupDone event so that you get notified of the side effects and completion of each .listen() call. "

So if I understand correctly I made a quite large document mostly for myself to understand the project the structure the issue and what to do. There are few questions named after #### Question

Note: sorry for making it so explicit.

[P1R]

Issue Swarm Listen

Issue/feature not found, is it?
to ask.

Issue Description

refactor the swarm.listen() in rust-libp2p so that it returns a "listen_id" that
gets passed back with SwarmEvent::NewListenAddress as well as a new
SwarmEvent::ListenSetupDone event so that you get notified of the side effects
and completion of each .listen() call.

Understanding the repository

Issue research

Searching the swarm.listen() in the repo:

$ grep -nr "swarm.listen()"                                                               i

protocols/gossipsub/tests/smoke.rs:124:    swarm.listen().with_memory_addr_external().await;
protocols/autonat/tests/test_client.rs:426:    let (_, multiaddr) = swarm.listen().await;

Swarm struct signature:

location: /swarm/src/lib.rs:320

pub struct Swarm<TBehaviour>
where
    TBehaviour: NetworkBehaviour

trait SwarmExt:

location: /swarm-test/src/lib.rs:38

implementation signature:

location: /swarm-test/src/lib.rs:196

impl<B> SwarmExt for Swarm<B>
where
    B: NetworkBehaviour + Send,
    <B as NetworkBehaviour>::ToSwarm: Debug

method signature:

location: /swarm-test/src/lib.rs:303

fn listen(&mut self) -> ListenFuture<&mut Self>

Question: Is this the correct crate to test?

• swarm-test?
• swarm: the one where to implement the events?

Solution Proposal:

1. Define Listen ID:

• Create a unique identifier to track each listening address, referred to as ListenId.:

Definition is already in /core/src/transport: 250

/// The ID of a single listener.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct ListenerId(usize);

impl ListenerId {
    /// Creates a new `ListenerId`.
    pub fn next() -> Self {
        ListenerId(NEXT_LISTENER_ID.fetch_add(1, Ordering::SeqCst))
    }
}

2. Modify swarm.listen() Method:

location: /swarm-test/src/lib.rs:303

fn listen(&mut self) -> ListenFuture<&mut Self> {
    ListenFuture {
add_memory_external: false,
                         add_tcp_external: false,
                         swarm: self,
    }
}

• Adjust the swarm.listen() method to generate a ListenId and return it.
• Ensure this method sets up the listener and stores the generated ListenId.

QUESTION: is the same ListenID inside the swarm?

3. Emit SwarmEvent::NewListenAddress Event:

Note: ToDo in the Test

• Modify the swarm.listen() method to emit a SwarmEvent::NewListenAddress event, including the ListenId and the address.

4. Introduce SwarmEvent::ListenSetupDone Event:

location: /swarm/src/lib.rs:320

In the SwarmEvent...

QUESTION: Will these fields satisfy the requirement?

/// One of the listeners notifies of the side effects and completition
ListenerSetupDone {
    /// The listener that notifies the setup.
    listener_id: ListenerId,
    /// The setup address that was generated on the setup.
    address: Multiaddr,
},

• Create a new event type SwarmEvent::ListenSetupDone.
• This event will be emitted once the listening setup is confirmed to be complete.

5. Emit SwarmEvent::ListenSetupDone in a Poll Loop:

• Modify the poll loop within the Swarm implementation.
• Ensure that SwarmEvent::ListenSetupDone is emitted when the listening setup is completed.

6. Testing:

• Add tests to validate that listen_id is correctly generated and propagated through the events.
• Ensure that SwarmEvent::NewListenAddress and SwarmEvent::ListenSetupDone are emitted with the correct listen_id.

Change checklist

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

References/Sources

1. https://docs.rs/libp2p/latest/libp2p/struct.Swarm.html 2024-08-02