docs: Write (/bring back) the page on writing a custom protocol

[matheus23]

Direct link to the deployment preview:
https://iroh-computer-git-matheus23-new-protocols-writing-number-0.vercel.app/docs/protocols/writing

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
iroh-computer	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 18, 2025 11:54am

[ValorZard]

The two main things I’d like to comment on is

1. What do you mean by “task leaking”? How exactly does that work and why is it a bad thing?
2. How would you access the connection outside of the connect or accept functions?

• For example, if I want to send something to the other peer in my “sync” world, how do I interface with the async protocol stuff?
• Do I store my connection struct or the sender and receiver somewhere for easy access?
• How do I “retrieve” it out of the accept loop or the connect side. (I guess by using channels)

for example something I’m dealing with right now is that I have two game clients, and I want to send messages between them. However, the game clients are full sync, and they only spawn async tasks to connect to each other.

something like (in pseudocode)

struct GameClient{
    isHost: bool,
    send: SendStream,
    // we should poll on receive in a game loop somewhere
    receive: RecvStream,
    conn: Connection
}

impl GameClient
{
    fn start_connection(&mut self)
    {
          // depending on whether we are the host or not, spawn task saying if we are accepting or connection to peers
          // then we set the “send”, “receive” and “connection” values for easy use 
    }

    fn send_message(&mut self, message: String)
    {
       // send message through sender
       let send = self.send.clone();
       spawn_task(async move{ send.send(message).await});
    }
    
    // run every frame in game loop
    fn process(&mut self, delta: f64) {
       while let Some(message) = self.reciever.get_data(){
            println!("Message from remote: {}", message);
       }
    }


    // get called when game ends
   fn close_connection(&mut self)
   {
      self.conn.close();
    }
}

[ValorZard]

Oh something I forgot to mention in my pseudocode is that this would get even more complicated on the accept side, since you’d need to be receieving all of these connections and would have to store them somewhere.

my idea is to do a hashmap, so something like

type ConnData = (SendStream, RecvStream, Connection);

struct GameClient{
    // blah blah blah
    
    // store connection data for each incoming connection
   net_map: HashMap<NodeId, ConnData>,
}

you'd then have to do something like this to send

fn send_message(&mut self, node_id: NodeId, message: String)
    {
       // send message through sender
       let send = self.net_map[node_id].sender.clone();
       spawn_task(async move{ send.send(message).await});
    }

 // run every frame in game loop
    fn process(&mut self, delta: f64) {
      for (node_id, (send, (_, receiver, _)) in self.connections.iter_mut() {
         while let Some(message) = receiver.get_data(){
              println!("Message from remote: {}", message);
         }
        }
    }

[b5]

Thanks so much for your feedback @ValorZard! I'm going to merge this just to get it onto the web site, but will open an issue to incorporate your feedback in additional docs!

Edit: issue opened here! #323