From 3055002ffba901cd73fa1cf26ed82e10b413efb0 Mon Sep 17 00:00:00 2001
From: Max Inden <mail@max-inden.de>
Date: Fri, 30 Dec 2022 12:18:16 +0100
Subject: [PATCH 1/5] docs(coding-guidelines): Add request response correlation

Allow correlating asynchronous responses to their requests.
---
 docs/coding-guidelines.md | 53 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index 70a1ef53009..15a3cb18299 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -19,6 +19,7 @@
         - [Further Reading](#further-reading)
     - [Use iteration not recursion](#use-iteration-not-recursion)
         - [Further Reading](#further-reading-1)
+    - [Allow Correlating Asynchronous Responses to Their Requests](#allow-correlating-asynchronous-responses-to-their-requests)
 
 <!-- markdown-toc end -->
 
@@ -299,3 +300,55 @@ stack potentially unboundedly. Instead use iteration e.g. via `loop` or `for`.
 - https://en.wikipedia.org/wiki/Tail_call
 - https://stackoverflow.com/questions/65948553/why-is-recursion-not-suggested-in-rust
 - https://stackoverflow.com/questions/59257543/when-is-tail-recursion-guaranteed-in-rust
+
+## Allow Correlating Asynchronous Responses to Their Requests
+
+In an asynchronous context, it is important to enable users to determine the correlation between a
+response and a previous request. For example, if a user requests two new connections to the same
+peer, they should be able to match each new connection to the corresponding previous connection
+request without having to guess.
+
+When providing a **method** where the response to that method is delivered asynchronously through an
+event, either synchronously return a request ID which is later on contained in the asynchronous
+response event, or synchronously return a `Future` that eventually resolves into the response.
+
+``` rust
+fn my_method() -> Id {
+  // ...
+}
+```
+
+``` rust
+fn my_method() -> impl Future<Output = Response> {
+  // ...
+}
+```
+
+When accepting a **command** that eventually results in a response through an event, either require
+that command to contain a unique ID, which is later on contained in the asynchronous response event,
+or allow the user to provide an instance of a custom type which again is later on returned in the
+response event.
+
+``` rust
+struct Command {
+  id: Id,
+  // ...
+}
+
+struct Response {
+  command_id: Id,
+  // ...
+}
+```
+
+``` rust
+struct Command<UserData> {
+  user_data: UserData,
+  // ...
+}
+
+struct Response<UserData> {
+  command_user_data: UserData,
+  // ...
+}
+```

From a951fbdf78f24d49b236eed2c665ec7db64d1220 Mon Sep 17 00:00:00 2001
From: Max Inden <mail@max-inden.de>
Date: Mon, 23 Jan 2023 11:04:15 +0100
Subject: [PATCH 2/5] Remove user data command option

---
 docs/coding-guidelines.md | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index 15a3cb18299..26faa5f22d0 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -340,15 +340,3 @@ struct Response {
   // ...
 }
 ```
-
-``` rust
-struct Command<UserData> {
-  user_data: UserData,
-  // ...
-}
-
-struct Response<UserData> {
-  command_user_data: UserData,
-  // ...
-}
-```

From 694a09ce900f39d1fc0fb431916373eb6188c7e0 Mon Sep 17 00:00:00 2001
From: Max Inden <mail@max-inden.de>
Date: Mon, 23 Jan 2023 11:04:34 +0100
Subject: [PATCH 3/5] Add example for Command from NetworkBehaviour to Swarm

Note that this is only really valid once we have https://github.com/libp2p/rust-libp2p/pull/3327 and
the corresponding patch in `libp2p-swarm` `DialOpts`.
---
 docs/coding-guidelines.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index 26faa5f22d0..c48461b51f8 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -324,10 +324,9 @@ fn my_method() -> impl Future<Output = Response> {
 }
 ```
 
-When accepting a **command** that eventually results in a response through an event, either require
-that command to contain a unique ID, which is later on contained in the asynchronous response event,
-or allow the user to provide an instance of a custom type which again is later on returned in the
-response event.
+When accepting a **command** () that eventually results in a response through an event require that
+command to contain a unique ID, which is later on contained in the asynchronous response event. One
+such example is the `Swarm` accepting a `NetworkBehaviourAction::Dial` from the `NetworkBehaviour`.
 
 ``` rust
 struct Command {

From a7be5062f42636ab0fed4801ca9a4048d12ea8e7 Mon Sep 17 00:00:00 2001
From: Max Inden <mail@max-inden.de>
Date: Mon, 23 Jan 2023 11:14:33 +0100
Subject: [PATCH 4/5] Return leftover brackets

---
 docs/coding-guidelines.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index c48461b51f8..41b45647669 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -324,7 +324,7 @@ fn my_method() -> impl Future<Output = Response> {
 }
 ```
 
-When accepting a **command** () that eventually results in a response through an event require that
+When accepting a **command** that eventually results in a response through an event require that
 command to contain a unique ID, which is later on contained in the asynchronous response event. One
 such example is the `Swarm` accepting a `NetworkBehaviourAction::Dial` from the `NetworkBehaviour`.
 

From 12e61b638e53171f9e44338cac740f6550cfce24 Mon Sep 17 00:00:00 2001
From: Max Inden <mail@max-inden.de>
Date: Fri, 24 Feb 2023 16:19:39 +0100
Subject: [PATCH 5/5] Remove mention of function

---
 docs/coding-guidelines.md | 16 ----------------
 1 file changed, 16 deletions(-)

diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index 41b45647669..935e26f6854 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -308,22 +308,6 @@ response and a previous request. For example, if a user requests two new connect
 peer, they should be able to match each new connection to the corresponding previous connection
 request without having to guess.
 
-When providing a **method** where the response to that method is delivered asynchronously through an
-event, either synchronously return a request ID which is later on contained in the asynchronous
-response event, or synchronously return a `Future` that eventually resolves into the response.
-
-``` rust
-fn my_method() -> Id {
-  // ...
-}
-```
-
-``` rust
-fn my_method() -> impl Future<Output = Response> {
-  // ...
-}
-```
-
 When accepting a **command** that eventually results in a response through an event require that
 command to contain a unique ID, which is later on contained in the asynchronous response event. One
 such example is the `Swarm` accepting a `NetworkBehaviourAction::Dial` from the `NetworkBehaviour`.