Merge pull request #92 from FabioPinheiro/return_route_should_be_used

The return_route extension is utilized by coordinate-mediation and messagepickup
decentralized-identity · Aug 28, 2023 · c2e3db3 · c2e3db3
2 parents 0aae3e0 + 83c5a44
commit c2e3db3
Show file tree

Hide file tree

Showing 3 changed files with 92 additions and 78 deletions.
diff --git a/site/content/protocols/mediator-coordination/2.0/readme.md b/site/content/protocols/mediator-coordination/2.0/readme.md
@@ -22,6 +22,12 @@ There are two roles in this protocol:
 - `mediator`: The agent that will be receiving `forward` messages on behalf of the _recipient_.
 - `recipient`: The agent for whom the `forward` message payload is intended.
 
+## Requirements
+
+The `return_route` extension must be supported by both agents (`recipient` and `mediator`).
+The common use of this protocol is for the reply messages from the `mediator` to be synchronous, utilizing the same connection channel for the reply. In order to have this synchronous behavior the `recipient` should specify `return_route` header to `all`.
+This header must be set each time the communication channel is established: once per established websocket, and every message for an HTTP POST.
+
 ## Connectivity
 
 This protocol consists of three different message requests from the `recipient` that should be replied by the `mediator`:
@@ -72,6 +78,7 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/2.0/mediate-request`
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/2.0/mediate-request",
+    "return_route": "all"
 }
 ```
 
@@ -96,10 +103,9 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/2.0/mediate-grant`
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/2.0/mediate-grant",
-    "body": 
-            {
-                "routing_did": "did:peer:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6"
-            }
+    "body": {
+        "routing_did": "did:peer:z6Mkfriq1MqLBoPWecGoDLjguo1sB9brj6wT3qZ5BxkKpuP6"
+    }
 }
 ```
 where:
@@ -117,15 +123,15 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/2.0/keylist-update`
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/2.0/keylist-update",
-    "body": 
+    "body": {
+        "updates":  [
             {
-                "updates":  [
-                                {
-                                    "recipient_did": `did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH`,
-                                    "action": "add"
-                                }
-                            ]
+                "recipient_did": `did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH`,
+                "action": "add"
             }
+        ]
+    },
+    "return_route": "all"
 }
 ```
 where:
@@ -142,16 +148,15 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/2.0/keylist-update-r
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/2.0/keylist-update-response",
-    "body": 
+    "body": {
+        "updated":  [
             {
-                "updated":  [
-                                {
-                                    "recipient_did": `did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH`,
-                                    "action": "" // "add" or "remove"
-                                    "result": "" // [client_error | server_error | no_change | success]
-                                }
-                            ]
+                "recipient_did": `did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH`,
+                "action": "" // "add" or "remove"
+                "result": "" // [client_error | server_error | no_change | success]
             }
+        ]
+    }
 }
 ```
 where:
@@ -169,13 +174,13 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/2.0/keylist-query`
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/2.0/keylist-query",
-    "body": 
-            {
-                "paginate": {
-                                "limit": 30,
-                                "offset": 0
-                            }
-            }
+    "body": {
+        "paginate": {
+            "limit": 30,
+            "offset": 0
+        }
+    },
+    "return_route": "all"
 }
 ```
 where:
@@ -191,19 +196,18 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/2.0/keylist`
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/2.0/keylist",
-    "body": 
+    "body": {
+        "keys": [
             {
-                "keys": [
-                            {
-                                "recipient_did": `did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH`
-                            }
-                        ]
-                "pagination":   {
-                                    "count": 30,
-                                    "offset": 30,
-                                    "remaining": 100
-                                }
+                "recipient_did": `did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH`
             }
+        ],
+        "pagination": {
+            "count": 30,
+            "offset": 30,
+            "remaining": 100
+        }
+    }
 }
 ```
 where:

diff --git a/site/content/protocols/mediator-coordination/3.0/readme.md b/site/content/protocols/mediator-coordination/3.0/readme.md
@@ -22,6 +22,12 @@ There are two roles in this protocol:
 - `mediator`: The agent that will be receiving `forward` messages on behalf of the _recipient_.
 - `recipient`: The agent for whom the `forward` message payload is intended.
 
+## Requirements
+
+The `return_route` extension must be supported by both agents (`recipient` and `mediator`).
+The common use of this protocol is for the reply messages from the `mediator` to be synchronous, utilizing the same connection channel for the reply. In order to have this synchronous behavior the `recipient` should specify `return_route` header to `all`.
+This header must be set each time the communication channel is established: once per established websocket, and every message for an HTTP POST.
+
 ## Connectivity
 
 This protocol consists of three different message requests from the `recipient` that should be replied by the `mediator`:
@@ -117,15 +123,15 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/3.0/recipient-update
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/3.0/recipient-update",
-    "body": 
+    "body": {
+        "updates": [
             {
-                "updates":  [
-                                {
-                                    "recipient_did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
-                                    "action": "add"
-                                }
-                            ]
+                "recipient_did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
+                "action": "add"
             }
+        ]
+    },
+    "return_route": "all"
 }
 ```
 where:
@@ -142,16 +148,15 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/3.0/recipient-update
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/3.0/recipient-update-response",
-    "body": 
+    "body": {
+        "updated": [
             {
-                "updated":  [
-                                {
-                                    "recipient_did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
-                                    "action": "" // "add" or "remove"
-                                    "result": "" // [client_error | server_error | no_change | success]
-                                }
-                            ]
+                "recipient_did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
+                "action": "" // "add" or "remove"
+                "result": "" // [client_error | server_error | no_change | success]
             }
+        ]
+    }
 }
 ```
 where:
@@ -169,13 +174,12 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/3.0/recipient-query`
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/3.0/recipient-query",
-    "body": 
-            {
-                "paginate": {
-                                "limit": 30,
-                                "offset": 0
-                            }
-            }
+    "body": {
+        "paginate": {
+            "limit": 30,
+            "offset": 0
+        }
+    }
 }
 ```
 where:
@@ -191,19 +195,18 @@ Message Type URI: `https://didcomm.org/coordinate-mediation/3.0/recipient`
 {
     "id": "123456780",
     "type": "https://didcomm.org/coordinate-mediation/3.0/recipient",
-    "body": 
+    "body": {
+        "dids": [
             {
-                "dids": [
-                            {
-                                "recipient_did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH"
-                            }
-                        ]
-                "pagination":   {
-                                    "count": 30,
-                                    "offset": 30,
-                                    "remaining": 100
-                                }
+                "recipient_did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH"
             }
+        ],
+        "pagination": {
+            "count": 30,
+            "offset": 30,
+            "remaining": 100
+        }
+    }
 }
 ```
 where:

diff --git a/site/content/protocols/pickup/3.0/readme.md b/site/content/protocols/pickup/3.0/readme.md
@@ -15,16 +15,22 @@ authors:
 ---
 
 # Motivation
-Messages can be picked up simply by sending a message to the _Mediator_ with a `return_route` header specified. This mechanism is implicit, and lacks some desired behavior made possible by more explicit messages.
 
-This protocol is the explicit companion to the implicit method of picking up messages.
+Messages can be picked up simply by sending a message to the _Mediator_.
 
 ## Roles
 There are two roles in this protocol: 
 
 - `mediator`: The agent that has messages waiting for pickup by the `recipient`.
 - `recipient`: The agent who is picking up messages from the `mediator`.
 
+## Requirements
+
+The `return_route` extension must be supported by both agents (`recipient` and `mediator`).
+The common use of this protocol is for the reply messages from the `mediator` to be synchronous, utilizing the same connection channel for the reply. In order to have this synchronous behavior the `recipient` should specify `return_route` header to `all`.
+This header must be set each time the communication channel is established: once per established websocket, and every message for an HTTP POST.
+
+
 ## Connectivity
 
 This protocol consists of three different message requests from the `recipient` that should be replied to by the `mediator`:
@@ -176,7 +182,8 @@ Message Type URI: `https://didcomm.org/messagepickup/3.0/messages-received`
     "type": "https://didcomm.org/messagepickup/3.0/messages-received",
     "body": {
         "message_id_list": ["123","456"]
-    }
+    },
+    "return_route": "all"
 }
 ```
 `message_id_list` is a list of `ids` of each message received. The `id` of each message is present in the attachment descriptor of each attached message of a delivery message.
@@ -220,13 +227,13 @@ If sent with `live_delivery` set to true on a connection incapable of live deliv
 
 ```json
 {
-  "id": "123456780",
-  "type": "https://didcomm.org/report-problem/2.0/problem-report",
-  "pthid": "< the value is the thid of the thread in which the problem occurred>",
-  "body": {
+    "id": "123456780",
+    "type": "https://didcomm.org/report-problem/2.0/problem-report",
+    "pthid": "< the value is the thid of the thread in which the problem occurred>",
+    "body": {
         "code": "e.m.live-mode-not-supported",
         "comment": "Connection does not support Live Delivery"
-  }
+    }
 }
 ```