Proposal for Message Pickup v4

site/content/protocols/messagepickup/4.0/readme.md

@@ -0,0 +1,389 @@
+---
+title: Message Pickup
+publisher: JamesKEbert
+license: MIT
+piuri: https://didcomm.org/message-pickup/4.0
+status: Production
+summary: A protocol to facilitate an agent picking up messages held at a mediator.
+tags: []
+authors:
+  - name: Sam Curren
+    email: [email protected]
+  - name: James Ebert
+    email: [email protected]
+
+---
+
+## Summary
+A protocol to facilitate a _Recipient_ agent picking up messages held at a _Mediator_. This protocol is likely to be used in tandem with the [Cooridinate Mediation protocol](https://didcomm.org/coordinate-mediation/3.0/).
+
+## Motivation
+This protocol is needed to facilitate retrieval of messages from a mediator in an explicit manner. Additionally, this protocol provides behavior for initiating live delivery of messages, which is crucial for good user experience for agents operating on mobile devices.
+
+Motivation for v4 of this protocol primarily stems from ambiguity in the [pickup v2 protocol](https://github.com/hyperledger/aries-rfcs/tree/main/features/0685-pickup-v2) and [messagepickup v3 protocol](https://didcomm.org/messagepickup/3.0/) as to whether `delivery` and `messages-received` messages must be used while using live mode. 
+
+## Version Change Log
+
+### 4.0
+ - Clarifies that `delivery` and `messages-received` messages MUST be used while using _Live Mode_ to ensure delivery of all messages.
+ - Adjusts handling of `delivery-request` messages when no messages are queued to be delivered. Rather than sending a status message indicating no messages are queued, an empty delivery message is sent. This was chosen to reduce complexity of the protocol.
+ - Adds DIDComm v1 message format (pickup v3 only contained DIDComm v2).
+    - In pickup v4 while using DIDComm v1, every `recipient_did` must be a [`did:key` reference](https://github.com/hyperledger/aries-rfcs/tree/main/features/0360-use-did-key).
+ - Adjustments to the protocol's use of thread ids
+    - Added thread id to `status` messages, as status messages are always in response to an original message from the `recipient`.
+    - Made the thread id (thid) on `delivery` messages optional, as messages received in _Live Mode_ do not have an associated `delivery-request` message.
+ - Removed return route all from `messages-received` messages, as it is not required.
+ - Updates protocol-name to `message-pickup`.
+ - Clarifies the `longest_waited_seconds` field on the `status` message.
+
+## 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
+
+### Return Route
+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.
+
+### DIDComm V1 Requirements
+When using this protocol with DIDComm V1, `recipient_did` **MUST** be a [`did:key` reference](https://github.com/hyperledger/aries-rfcs/tree/main/features/0360-use-did-key).
+
+## Basic Walkthrough
+
+This protocol consists of four different message requests from the `recipient` that should be replied to by the `mediator`:
+
+1. Status Request -> Status
+2. Delivery Request -> Message Delivery
+3. Message Received -> Status
+4. Live Mode -> Status or Problem Report
+
+## States
+
+This protocol follows the request-response message exchange pattern, and only requires the simple state of waiting for a response or to produce a response. 
+
+Additionally, the `return_route` header extension must be set to `all` in all request submitted by the `recipient`.
+
+## Basic Walkthrough
+
+The `status-request` message is sent by the `recipient` to the `mediator` to query how many messages are pending.
+
+The `status` message is the response to `status-request` to communicate the state of the message queue.
+
+The `delivery-request` message is sent by the `recipient` to request delivery of pending messages.
+
+The `delivery` message is the response to the `delivery-request` to send queued messages back to the `recipient`.
+
+The `messages-received` message is sent by the `recipient` to confirm receipt of delivered messages, prompting the `mediator` to clear messages from the queue.
+
+The `live-delivery-change` message is used to set the state of `live_delivery`.
+
+When _Live Mode_ is enabled, messages that arrive when an existing connection exists are delivered over the connection immediately, via a `delivery` message, rather than being pushed to the queue. See _Live Mode_ below for more details. 
+
+## Security
+
+This protocol expects messages to be encrypted during transmission, and repudiable. 
+
+## Message Reference
+
+### Status Request
+Sent by the `recipient` to the `mediator` to request a `status` message.
+
+Message Type URI: `https://didcomm.org/message-pickup/4.0/status-request`
+
+DIDComm v1 example:
+```json
+{
+    "@id": "123456780",
+    "@type": "https://didcomm.org/message-pickup/4.0/status-request",
+    "recipient_did": "<did:key for messages>",
+    "~transport": {
+        "return_route": "all"
+    }
+}
+```
+
+DIDComm v2 example:
+```json
+{
+    "id": "123456780",
+    "type": "https://didcomm.org/message-pickup/4.0/status-request",
+    "body" : {
+        "recipient_did": "<did for messages>"
+    },
+    "return_route": "all"
+}
+```
+`recipient_did` is optional. When specified, the `mediator` **MUST** only return status related to that recipient did. This allows the `recipient` to discover if any messages are in the queue that were sent to a specific DID. If using DIDComm v1, `recipient_did` **MUST** be a [`did:key` reference](https://github.com/hyperledger/aries-rfcs/tree/main/features/0360-use-did-key).
+
+### Status
+Status details about waiting messages.
+
+Message Type URI: `https://didcomm.org/message-pickup/4.0/status`
+
+DIDComm v1 example:
+```json
+{
+    "@id": "123456780",
+    "@type": "https://didcomm.org/message-pickup/4.0/status",
+    "~thread": {
+        "thid": "<message id of status-request message>"
+    },
+    "recipient_did": "<did:key for messages>",
+    "message_count": 7,
+    "longest_waited_seconds": 3600,
+    "newest_received_time": 1658085169,
+    "oldest_received_time": 1658084293,
+    "total_bytes": 8096,
+    "live_delivery": false
+}
+```
+
+DIDComm v2 example:
+```json
+{
+    "id": "123456780",
+    "thid": "<message id of status-request message>",
+    "type": "https://didcomm.org/message-pickup/4.0/status",
+    "body": {
+        "recipient_did": "<did for messages>",
+        "message_count": 7,
+        "longest_waited_seconds": 3600,
+        "newest_received_time": 1658085169,
+        "oldest_received_time": 1658084293,
+        "total_bytes": 8096,
+        "live_delivery": false
+    }
+}
+```
+
+`message_count` is the only **REQUIRED** attribute. The others **MAY** be present if offered by the `mediator`.
+
+`longest_waited_seconds` is the age, in seconds, of the oldest message in the queue.
+
+`newest_received_time` and `oldest_received_time` are expressed in UTC Epoch Seconds (seconds since 1970-01-01T00:00:00Z) as an integer.
+
+`total_bytes` represents the total size of all messages.
+
+If a `recipient_did` was specified in the `status-request` message, the matching value **MUST** be specified in the `recipient_did` attribute of the status message.
+
+`live_delivery` state is also indicated in the status message.
+
+**Note**: due to the potential for confusing what the actual state of the message queue is, a `status` message **MUST NOT** be put on the pending message queue and **MUST** only be sent when the `recipient` is actively connected (HTTP request awaiting response, WebSocket, etc.).
+
+
+### Delivery Request
+A request from the `recipient` to the `mediator` to have pending messages delivered.
+
+Message Type URI: `https://didcomm.org/message-pickup/4.0/delivery-request`
+
+DIDComm v1 example:
+```json
+{
+    "@id": "123456780",
+    "@type": "https://didcomm.org/message-pickup/4.0/delivery-request",
+    "limit": 10,
+    "recipient_did": "<did:key for messages>",
+    "~transport": {
+        "return_route": "all"
+    }
+}
+```
+
+DIDComm v2 example:
+```json
+{
+    "id": "123456780",
+    "type": "https://didcomm.org/message-pickup/4.0/delivery-request",
+    "body": {
+        "limit": 10,
+        "recipient_did": "<did for messages>"
+    },
+    "return_route": "all"
+}
+```
+
+`limit` is a **REQUIRED** attribute, and after receipt of this message, the `mediator` **SHOULD** deliver up to the limit indicated.
+
+`recipient_did` is optional. When specified, the `mediator` **MUST** only return messages sent to that recipient did.
+
+If no messages are available to be sent, a `delivery` message with an empty attachments array **MUST** be sent immediately.
+
+Delivered messages **MUST NOT** be deleted until delivery is acknowledged by a `messages-received` message.
+
+### Message Delivery
+Batch of messages delivered to the `recipient` as attachments.
+
+Message Type URI: `https://didcomm.org/message-pickup/4.0/delivery`
+
+DIDComm v1 example:
+```json
+{
+    "@id": "123456780",
+    "@type": "https://didcomm.org/message-pickup/4.0/delivery",
+    "~thread": {
+        "thid": "<message id of delivery-request message>"
+    },
+    "recipient_did": "<did:key for messages>",
+    "~attach": [{
+        "@id": "<id of message>",
+        "data": {
+            "base64": "<message>"
+        }
+    }]
+}
+```
+
+DIDComm v2 example:
+```json
+{
+    "id": "123456780",
+    "thid": "<message id of delivery-request message>",
+    "type": "https://didcomm.org/message-pickup/4.0/delivery",
+    "body": {
+        "recipient_did": "<did for messages>"
+    },
+    "attachments": [{
+        "id": "<id of message>",
+        "data": {
+            "base64": "<message>"
+        }
+    }]
+}
+```
+
+Messages delivered from the queue **MUST** be delivered in a delivery message as attachments. If the `delivery` message is in response to a `delivery-request` message that specifies a `limit`, the number of attached messages **MUST NOT** exceed the `limit` specified in the `delivery-request`. 
+The `id` of each attachment is used to confirm receipt.
+The `id` is an opaque value, and the recipient **SHOULD NOT** deduce any information from it, except that it is unique to the mediator. The recipient can use the `id`s in the `message_id_list` field of `messages-received`.
+
+If there are no messages in the queue for the `delivery-request`, the `delivery` message **MUST** contain an empty array of attachments.
+
+The ONLY valid type of attachment for this message is a DIDComm v1 or v2 Message in encrypted form.
+
+`thid` -- an optional field if the delivery message is in response to a singular `delivery-request` messsage.
+
+The `recipient_did` attribute is only included when responding to a `delivery-request` message that indicates a `recipient_did`.
+
+### Messages Received
+After receiving messages, the `recipient` **MUST** send an acknowledge message indiciating which messages are safe to clear from the queue.
+
+Message Type URI: `https://didcomm.org/message-pickup/4.0/messages-received`
+
+DIDComm v1 example:
+```json
+{
+    "@id": "123456780",
+    "@type": "https://didcomm.org/message-pickup/4.0/messages-received",
+    "message_id_list": ["123","456"]
+}
+```
+
+DIDComm v2 example:
+```json
+{
+    "id": "123456780",
+    "type": "https://didcomm.org/message-pickup/4.0/messages-received",
+    "body": {
+        "message_id_list": ["123","456"]
+    }
+}
+```
+
+`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.
+
+Upon receipt of this message, the `mediator` knows which messages have been received, and can remove them from the collection of queued messages with confidence.
+
+#### Multiple Recipients
+
+If a message arrives at a `mediator` addressed to multiple `recipients`, the message **MUST** be queued for each `recipient` independently. If one of the addressed `recipients` retrieves a message and indicates it has been received, that message **MUST** still be held and then removed by the other addressed `recipients`.
+
+
+### Live Mode
+_Live Mode_ is the practice of delivering newly arriving messages directly to a connected `recipient`. It is disabled by default and only activated by the `recipient`. Messages that arrive when _Live Mode_ is off **MUST** be stored in the queue for retrieval as described above. If _Live Mode_ is active, and the connection is broken, a new inbound connection starts with _Live Mode_ disabled.
+
+Messages already in the queue are not affected by _Live Mode_; they **MUST** still be requested with `delivery-request` messages.
+
+_Live Mode_ **MUST** only be enabled when a persistent transport is used, such as WebSockets.
+
+If _Live Mode_ is active, messages still **MUST** be delivered via a `delivery` message and the `recipient` **MUST** send an acknowledgement message `messages-received`. If a message is not acknowledged, the message **MUST** be added to the queue for later pickup.
+
+Recipients have three modes of possible operation for message delivery with various abilities and level of development complexity:
+
+1. Never activate _Live Mode_. Poll for new messages with a `status_request` message, and retrieve them when available.
+2. Retrieve all messages from queue, and then activate _Live Mode_. This simplifies message processing logic in the `recipient`.
+3. Activate _Live Mode_ immediately upon connecting to the `mediator`. Retrieve messages from the queue as possible. When receiving a message delivered live, the queue may be queried for any waiting messages delivered to the same did for processing.
+### Live Mode Change
+_Live Mode_ is changed with a `live-delivery-change` message.
+
+Message Type URI: `https://didcomm.org/message-pickup/4.0/live-delivery-change`
+
+DIDComm v1 example:
+```json
+{
+    "@id": "123456780",
+    "@type": "https://didcomm.org/message-pickup/4.0/live-delivery-change",
+    "live_delivery": true
+}
+```
+
+DIDComm v2 example:
+```json
+{
+    "id": "123456780",
+    "type": "https://didcomm.org/message-pickup/4.0/live-delivery-change",
+    "body": {
+        "live_delivery": true
+    }
+}
+```
+
+Upon receiving the `live_delivery_change` message, the `mediator` **MUST** respond with a `status` message.
+
+If sent with `live_delivery` set to true on a connection incapable of live delivery, a `problem_report` **SHOULD** be sent as follows:
+
+DIDComm v1 example:
+```json
+{
+    "@id": "123456780",
+    "@type": "https://didcomm.org/message-pickup/4.0/problem-report",
+    "~thread": {
+        "pthid": "<the value is the thid of the thread in which the problem occurred>"
+    },
+    "description": {
+        "code": "e.m.live-mode-not-supported",
+        "en": "Connection does not support Live Delivery"
+    }
+}
+```
+
+DIDComm v2 example:
+```json
+{
+    "id": "123456780",
+    "type": "https://didcomm.org/message-pickup/4.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"
+    }
+}
+```
+
+## L10n
+
+No localization is required.
+
+## Implementations
+
+Name / Link | Implementation Notes
+--- | --- 
+
+## Endnotes
+
+### Future Considerations
+The style of wrapping messages in a `delivery` message incurs an additional roughly 33% increased message size due to wrapping of the message. This size bloating is outweighed by the benefit of having explicit and gauranteed delivery of messages. This issue may be resolved in future versions of DIDComm.
+
+Should there be a strategy for a `mediator` to indicate support for _Live Mode_ via discover features?