From 39bbc9d011e813cb028515c58361fa67e25664e7 Mon Sep 17 00:00:00 2001 From: James Ebert Date: Thu, 23 May 2024 15:02:32 -0700 Subject: [PATCH 01/13] feat: add pickup-v4 Signed-off-by: James Ebert --- .../protocols/messagepickup/4.0/readme.md | 260 ++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 site/content/protocols/messagepickup/4.0/readme.md diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md new file mode 100644 index 00000000..d75e0e7c --- /dev/null +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -0,0 +1,260 @@ +--- +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: telegramsam@gmail.com + - name: James Ebert + email: james@jamesebert.dev + +--- + +## 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 stems from ambiguity in the [messagepickup v3 protocol](https://didcomm.org/messagepickup/3.0/) as to whether `delivery` and `messages-received` messages must be used while using live mode. + +## 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`s **MUST** be [`did:key` references](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` + +```json +{ + "id": "123456780", + "type": "https://didcomm.org/message-pickup/4.0/status-request", + "body" : { + "recipient_did": "" + }, + "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. + +### Status +Status details about waiting messages. + +Message Type URI: `https://didcomm.org/message-pickup/4.0/status` + +```json +{ + "id": "123456780", + "type": "https://didcomm.org/message-pickup/4.0/status", + "body": { + "recipient_did": "", + "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 in seconds, and is the longest delay of any 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` + +```json +{ + "id": "123456780", + "type": "https://didcomm.org/message-pickup/4.0/delivery-request", + "body": { + "limit": 10, + "recipient_did": "" + }, + "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 `status` message **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` + +```json +{ + "id": "123456780", + "thid": "", + "type": "https://didcomm.org/message-pickup/4.0/delivery", + "body": { + "recipient_did": "" + }, + "attachments": [{ + "id": "", + "data": { + "base64": "" + } + }] +} +``` +Messages delivered from the queue must be delivered in a batch delivery message as attachments, with a batch size specified by the `limit` provided in the `delivery-request` message. +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`. + +The ONLY valid type of attachment for this message is a DIDComm v1 or v2 Message in encrypted form. + +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/pickup-message/4.0/messages-received` + +```json +{ + "id": "123456780", + "type": "https://didcomm.org/pickup-message/4.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. + +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 acknowledge 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/pickup-message/4.0/live-delivery-change` + +```json +{ + "id": "123456780", + "type": "https://didcomm.org/pickup-message/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: + +```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": { + "code": "e.m.live-mode-not-supported", + "comment": "Connection does not support Live Delivery" + } +} +``` + +## L10n + +No localization is required. + +## Implementations + +## 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. \ No newline at end of file From 68b022b0127b9f1c11833406cbbd8917d79a3d59 Mon Sep 17 00:00:00 2001 From: James Ebert Date: Tue, 4 Jun 2024 13:49:40 -0700 Subject: [PATCH 02/13] feat: add didcomm v1 & v2 examples Signed-off-by: James Ebert --- .../protocols/messagepickup/4.0/readme.md | 114 +++++++++++++++++- 1 file changed, 110 insertions(+), 4 deletions(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index d75e0e7c..895da260 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -36,7 +36,7 @@ The common use of this protocol is for the reply messages from the `mediator` to 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`s **MUST** be [`did:key` references](https://github.com/hyperledger/aries-rfcs/tree/main/features/0360-use-did-key). +When using this protocol with DIDComm V1, `recipient_did` **MUST** be [`did:key` references](https://github.com/hyperledger/aries-rfcs/tree/main/features/0360-use-did-key). ## Basic Walkthrough @@ -80,6 +80,19 @@ 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": "", + "~transport": { + "return_route": "all" + } +} +``` + +DIDComm v2 Example: ```json { "id": "123456780", @@ -90,13 +103,29 @@ Message Type URI: `https://didcomm.org/message-pickup/4.0/status-request` "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. +`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 [`did:key` references](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", + "recipient_did": "", + "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", @@ -112,6 +141,7 @@ Message Type URI: `https://didcomm.org/message-pickup/4.0/status` } } ``` + `message_count` is the only **REQUIRED** attribute. The others **MAY** be present if offered by the `mediator`. `longest_waited_seconds` is in seconds, and is the longest delay of any message in the queue. @@ -132,6 +162,20 @@ A request from the `recipient` to the `mediator` to have pending messages delive 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": "", + "~transport": { + "return_route": "all" + } +} +``` + +DIDComm v2 Example: ```json { "id": "123456780", @@ -143,6 +187,7 @@ Message Type URI: `https://didcomm.org/message-pickup/4.0/delivery-request` "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. @@ -156,6 +201,25 @@ 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": "" + }, + "recipient_did": "", + "~attach": [{ + "@id": "", + "data": { + "base64": "" + } + }] +} +``` + +DIDComm v2 Example: ```json { "id": "123456780", @@ -172,6 +236,7 @@ Message Type URI: `https://didcomm.org/message-pickup/4.0/delivery` }] } ``` + Messages delivered from the queue must be delivered in a batch delivery message as attachments, with a batch size specified by the `limit` provided in the `delivery-request` message. 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`. @@ -185,6 +250,19 @@ After receiving messages, the `recipient` **MUST** send an acknowledge message i Message Type URI: `https://didcomm.org/pickup-message/4.0/messages-received` +DIDComm v1 Example: +```json +{ + "@id": "123456780", + "@type": "https://didcomm.org/pickup-message/4.0/messages-received", + "message_id_list": ["123","456"], + "~transport": { + "return_route": "all" + } +} +``` + +DIDComm v2 Example: ```json { "id": "123456780", @@ -195,6 +273,7 @@ Message Type URI: `https://didcomm.org/pickup-message/4.0/messages-received` "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. 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. @@ -223,6 +302,16 @@ _Live Mode_ is changed with a `live-delivery-change` message. Message Type URI: `https://didcomm.org/pickup-message/4.0/live-delivery-change` +DIDComm v1 Example: +```json +{ + "@id": "123456780", + "@type": "https://didcomm.org/pickup-message/4.0/live-delivery-change", + "live_delivery": true +} +``` + +DIDComm v2 Example: ```json { "id": "123456780", @@ -232,15 +321,32 @@ Message Type URI: `https://didcomm.org/pickup-message/4.0/live-delivery-change` } } ``` + 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/pickup-message/4.0/problem-report", + "~thread": { + "pthid": "" + }, + "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/report-problem/2.0/problem-report", - "pthid": "< the value is the thid of the thread in which the problem occurred>", + "type": "https://didcomm.org/pickup-message/4.0/problem-report", + "pthid": "", "body": { "code": "e.m.live-mode-not-supported", "comment": "Connection does not support Live Delivery" From 3f8c7602fccde5eec75d8391451b761ed8ab57dc Mon Sep 17 00:00:00 2001 From: James Ebert Date: Tue, 4 Jun 2024 13:55:03 -0700 Subject: [PATCH 03/13] chore: adjust missed type fields appropriately Signed-off-by: James Ebert --- .../protocols/messagepickup/4.0/readme.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 895da260..75762f7c 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -248,13 +248,13 @@ The `recipient_did` attribute is only included when responding to a `delivery-re ### 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/pickup-message/4.0/messages-received` +Message Type URI: `https://didcomm.org/message-pickup/4.0/messages-received` DIDComm v1 Example: ```json { "@id": "123456780", - "@type": "https://didcomm.org/pickup-message/4.0/messages-received", + "@type": "https://didcomm.org/message-pickup/4.0/messages-received", "message_id_list": ["123","456"], "~transport": { "return_route": "all" @@ -266,7 +266,7 @@ DIDComm v2 Example: ```json { "id": "123456780", - "type": "https://didcomm.org/pickup-message/4.0/messages-received", + "type": "https://didcomm.org/message-pickup/4.0/messages-received", "body": { "message_id_list": ["123","456"] }, @@ -300,13 +300,13 @@ Recipients have three modes of possible operation for message delivery with vari ### Live Mode Change _Live Mode_ is changed with a `live-delivery-change` message. -Message Type URI: `https://didcomm.org/pickup-message/4.0/live-delivery-change` +Message Type URI: `https://didcomm.org/message-pickup/4.0/live-delivery-change` DIDComm v1 Example: ```json { "@id": "123456780", - "@type": "https://didcomm.org/pickup-message/4.0/live-delivery-change", + "@type": "https://didcomm.org/message-pickup/4.0/live-delivery-change", "live_delivery": true } ``` @@ -315,7 +315,7 @@ DIDComm v2 Example: ```json { "id": "123456780", - "type": "https://didcomm.org/pickup-message/4.0/live-delivery-change", + "type": "https://didcomm.org/message-pickup/4.0/live-delivery-change", "body": { "live_delivery": true } @@ -330,7 +330,7 @@ DIDComm v1 Example: ```json { "@id": "123456780", - "@type": "https://didcomm.org/pickup-message/4.0/problem-report", + "@type": "https://didcomm.org/message-pickup/4.0/problem-report", "~thread": { "pthid": "" }, @@ -345,7 +345,7 @@ DIDComm v2 Example: ```json { "id": "123456780", - "type": "https://didcomm.org/pickup-message/4.0/problem-report", + "type": "https://didcomm.org/message-pickup/4.0/problem-report", "pthid": "", "body": { "code": "e.m.live-mode-not-supported", From 37c948cbc7aa34ec9437fc344cbf603633462c53 Mon Sep 17 00:00:00 2001 From: James Ebert Date: Tue, 4 Jun 2024 14:04:46 -0700 Subject: [PATCH 04/13] chore: minor fixes/tweaks Signed-off-by: James Ebert --- .../protocols/messagepickup/4.0/readme.md | 40 ++++++++++--------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 75762f7c..6e2bf0be 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -36,7 +36,7 @@ The common use of this protocol is for the reply messages from the `mediator` to 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 [`did:key` references](https://github.com/hyperledger/aries-rfcs/tree/main/features/0360-use-did-key). +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 @@ -80,7 +80,7 @@ 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: +DIDComm v1 example: ```json { "@id": "123456780", @@ -92,7 +92,7 @@ DIDComm v1 Example: } ``` -DIDComm v2 Example: +DIDComm v2 example: ```json { "id": "123456780", @@ -103,14 +103,14 @@ DIDComm v2 Example: "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 [`did:key` references](https://github.com/hyperledger/aries-rfcs/tree/main/features/0360-use-did-key). +`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: +DIDComm v1 example: ```json { "@id": "123456780", @@ -125,7 +125,7 @@ DIDComm v1 Example: } ``` -DIDComm v2 Example: +DIDComm v2 example: ```json { "id": "123456780", @@ -162,7 +162,7 @@ A request from the `recipient` to the `mediator` to have pending messages delive Message Type URI: `https://didcomm.org/message-pickup/4.0/delivery-request` -DIDComm v1 Example: +DIDComm v1 example: ```json { "@id": "123456780", @@ -175,7 +175,7 @@ DIDComm v1 Example: } ``` -DIDComm v2 Example: +DIDComm v2 example: ```json { "id": "123456780", @@ -201,7 +201,7 @@ Batch of messages delivered to the `recipient` as attachments. Message Type URI: `https://didcomm.org/message-pickup/4.0/delivery` -DIDComm v1 Example: +DIDComm v1 example: ```json { "@id": "123456780", @@ -219,7 +219,7 @@ DIDComm v1 Example: } ``` -DIDComm v2 Example: +DIDComm v2 example: ```json { "id": "123456780", @@ -250,7 +250,7 @@ After receiving messages, the `recipient` **MUST** send an acknowledge message i Message Type URI: `https://didcomm.org/message-pickup/4.0/messages-received` -DIDComm v1 Example: +DIDComm v1 example: ```json { "@id": "123456780", @@ -262,7 +262,7 @@ DIDComm v1 Example: } ``` -DIDComm v2 Example: +DIDComm v2 example: ```json { "id": "123456780", @@ -286,11 +286,11 @@ If a message arrives at a `mediator` addressed to multiple `recipients`, the mes ### 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. +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 acknowledge message `messages-received`. If a message is not acknowledged, the message **MUST** be added to the queue for later pickup. +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: @@ -302,7 +302,7 @@ _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: +DIDComm v1 example: ```json { "@id": "123456780", @@ -311,7 +311,7 @@ DIDComm v1 Example: } ``` -DIDComm v2 Example: +DIDComm v2 example: ```json { "id": "123456780", @@ -326,7 +326,7 @@ Upon receiving the `live_delivery_change` message, the `mediator` **MUST** respo 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: +DIDComm v1 example: ```json { "@id": "123456780", @@ -341,7 +341,7 @@ DIDComm v1 Example: } ``` -DIDComm v2 Example: +DIDComm v2 example: ```json { "id": "123456780", @@ -363,4 +363,6 @@ No localization is required. ## 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. \ No newline at end of file +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? \ No newline at end of file From 661dac12d1ccb6912d6b00e89fdd0364f74b3b6b Mon Sep 17 00:00:00 2001 From: James Ebert Date: Tue, 4 Jun 2024 14:30:40 -0700 Subject: [PATCH 05/13] chore: thid adjustments Signed-off-by: James Ebert --- site/content/protocols/messagepickup/4.0/readme.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 6e2bf0be..95923384 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -150,7 +150,7 @@ DIDComm v2 example: `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. +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. @@ -243,6 +243,8 @@ The `id` is an opaque value, and the recipient should not deduce any information 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 @@ -255,10 +257,7 @@ DIDComm v1 example: { "@id": "123456780", "@type": "https://didcomm.org/message-pickup/4.0/messages-received", - "message_id_list": ["123","456"], - "~transport": { - "return_route": "all" - } + "message_id_list": ["123","456"] } ``` @@ -269,8 +268,7 @@ DIDComm v2 example: "type": "https://didcomm.org/message-pickup/4.0/messages-received", "body": { "message_id_list": ["123","456"] - }, - "return_route": "all" + } } ``` From 6a5257ee34670c5cab0b369891be429d33e14a07 Mon Sep 17 00:00:00 2001 From: James Ebert Date: Tue, 4 Jun 2024 14:38:53 -0700 Subject: [PATCH 06/13] chore: add thid to status message Signed-off-by: James Ebert --- site/content/protocols/messagepickup/4.0/readme.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 95923384..8883357b 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -115,6 +115,9 @@ DIDComm v1 example: { "@id": "123456780", "@type": "https://didcomm.org/message-pickup/4.0/status", + "~thread": { + "thid": "" + }, "recipient_did": "", "message_count": 7, "longest_waited_seconds": 3600, @@ -129,6 +132,7 @@ DIDComm v2 example: ```json { "id": "123456780", + "thid": "", "type": "https://didcomm.org/message-pickup/4.0/status", "body": { "recipient_did": "", @@ -358,6 +362,9 @@ No localization is required. ## Implementations +Name / Link | Implementation Notes +--- | --- + ## Endnotes ### Future Considerations From 7654eeae94eec5db0006fdf36ffda265653712bf Mon Sep 17 00:00:00 2001 From: James Ebert Date: Tue, 4 Jun 2024 14:42:55 -0700 Subject: [PATCH 07/13] chore: add pickup v2 reference Signed-off-by: James Ebert --- site/content/protocols/messagepickup/4.0/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 8883357b..1a45bbcc 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -20,7 +20,7 @@ A protocol to facilitate a _Recipient_ agent picking up messages held at a _Medi ## 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 stems from ambiguity in the [messagepickup v3 protocol](https://didcomm.org/messagepickup/3.0/) as to whether `delivery` and `messages-received` messages must be used while using live mode. +Motivation for v4 of this protocol 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. ## Roles There are two roles in this protocol: From a6aa306211557e57caea05ca6111e519f22f6836 Mon Sep 17 00:00:00 2001 From: James Ebert Date: Tue, 4 Jun 2024 14:45:21 -0700 Subject: [PATCH 08/13] fix: space Signed-off-by: James Ebert --- site/content/protocols/messagepickup/4.0/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 1a45bbcc..86233fce 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -45,7 +45,7 @@ This protocol consists of four different message requests from the `recipient` t 1. Status Request -> Status 2. Delivery Request -> Message Delivery 3. Message Received -> Status -4. Live Mode -> Status or Problem Report +4. Live Mode -> Status or Problem Report ## States From b355e51865724e9eee04c72cbca035be4859e9fa Mon Sep 17 00:00:00 2001 From: James Ebert Date: Tue, 16 Jul 2024 17:38:49 -0700 Subject: [PATCH 09/13] chore: add changelog Signed-off-by: James Ebert --- site/content/protocols/messagepickup/4.0/readme.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 86233fce..617e8339 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -20,7 +20,19 @@ A protocol to facilitate a _Recipient_ agent picking up messages held at a _Medi ## 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 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. +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_. + - 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`. ## Roles There are two roles in this protocol: From 2e0439d83797e8882f0ee8e3b1d8f6ba20f8d239 Mon Sep 17 00:00:00 2001 From: James Ebert Date: Tue, 16 Jul 2024 17:50:29 -0700 Subject: [PATCH 10/13] feat: adjust behavior of no pending messages on delivery request Signed-off-by: James Ebert --- site/content/protocols/messagepickup/4.0/readme.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 617e8339..6624c53f 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -25,7 +25,8 @@ Motivation for v4 of this protocol primarily stems from ambiguity in the [pickup ## Version Change Log ### 4.0 - - Clarifies that `delivery` and `messages-received` messages MUST be used while using _Live Mode_. + - 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 @@ -208,7 +209,7 @@ DIDComm v2 example: `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 `status` message **MUST** be sent immediately. +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. @@ -253,9 +254,11 @@ DIDComm v2 example: } ``` -Messages delivered from the queue must be delivered in a batch delivery message as attachments, with a batch size specified by the `limit` provided in the `delivery-request` message. +Messages delivered from the queue **MUST** be delivered in a batch delivery message as attachments, with a batch size specified by the `limit` provided in the `delivery-request` message. 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`. +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. From b8692186baff0cb966836ee88998549b86c8b543 Mon Sep 17 00:00:00 2001 From: James Ebert Date: Mon, 22 Jul 2024 11:03:20 -0700 Subject: [PATCH 11/13] chore: clarify language on batch limits in delivery messages Signed-off-by: James Ebert --- site/content/protocols/messagepickup/4.0/readme.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 6624c53f..f1e34b04 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -15,7 +15,7 @@ authors: --- ## 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/). +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. @@ -254,9 +254,9 @@ DIDComm v2 example: } ``` -Messages delivered from the queue **MUST** be delivered in a batch delivery message as attachments, with a batch size specified by the `limit` provided in the `delivery-request` 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`. +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. From d5d33b91950e06359dd0f80d5b854ad2a3e4f0c6 Mon Sep 17 00:00:00 2001 From: James Ebert Date: Mon, 9 Dec 2024 08:31:29 -0800 Subject: [PATCH 12/13] chore: clarify longest_waited_seconds Signed-off-by: James Ebert --- site/content/protocols/messagepickup/4.0/readme.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index f1e34b04..52f51aa3 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -34,6 +34,7 @@ Motivation for v4 of this protocol primarily stems from ambiguity in the [pickup - 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: @@ -161,7 +162,7 @@ DIDComm v2 example: `message_count` is the only **REQUIRED** attribute. The others **MAY** be present if offered by the `mediator`. -`longest_waited_seconds` is in seconds, and is the longest delay of any message in the queue. +`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. From 7e94035b1e2cfcc95f978a76dc09869d1f8015e7 Mon Sep 17 00:00:00 2001 From: James Ebert Date: Mon, 9 Dec 2024 13:20:22 -0800 Subject: [PATCH 13/13] chore: clarifies basic walkthrough, removes longest_waited_seconds, add specificity to limit Signed-off-by: James Ebert --- .../protocols/messagepickup/4.0/readme.md | 23 ++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/site/content/protocols/messagepickup/4.0/readme.md b/site/content/protocols/messagepickup/4.0/readme.md index 52f51aa3..47ce0e45 100644 --- a/site/content/protocols/messagepickup/4.0/readme.md +++ b/site/content/protocols/messagepickup/4.0/readme.md @@ -34,7 +34,8 @@ Motivation for v4 of this protocol primarily stems from ambiguity in the [pickup - 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. + - Removes the `longest_waited_seconds` field on the `status` message (as it is redundant in regards to `oldest_received_time`). + - Renames `limit` in the `delivery-request` to `message_count_limit` for increased specificity. ## Roles There are two roles in this protocol: @@ -54,12 +55,11 @@ When using this protocol with DIDComm V1, `recipient_did` **MUST** be a [`did:ke ## Basic Walkthrough -This protocol consists of four different message requests from the `recipient` that should be replied to by the `mediator`: +This protocol consists of three 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 +2. Delivery Request -> Message Delivery -> Message Received +3. Live Mode -> Status or Problem Report -> Message Delivery -> Message Received ## States @@ -151,7 +151,6 @@ DIDComm v2 example: "body": { "recipient_did": "", "message_count": 7, - "longest_waited_seconds": 3600, "newest_received_time": 1658085169, "oldest_received_time": 1658084293, "total_bytes": 8096, @@ -162,8 +161,6 @@ DIDComm v2 example: `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. @@ -185,7 +182,7 @@ DIDComm v1 example: { "@id": "123456780", "@type": "https://didcomm.org/message-pickup/4.0/delivery-request", - "limit": 10, + "message_count_limit": 10, "recipient_did": "", "~transport": { "return_route": "all" @@ -199,14 +196,14 @@ DIDComm v2 example: "id": "123456780", "type": "https://didcomm.org/message-pickup/4.0/delivery-request", "body": { - "limit": 10, + "message_count_limit": 10, "recipient_did": "" }, "return_route": "all" } ``` -`limit` is a **REQUIRED** attribute, and after receipt of this message, the `mediator` **SHOULD** deliver up to the limit indicated. +`message_count_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. @@ -255,7 +252,7 @@ DIDComm v2 example: } ``` -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`. +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 `message_count_limit`, the number of attached messages **MUST NOT** exceed the `message_count_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`. @@ -384,6 +381,6 @@ 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. +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 guaranteed 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? \ No newline at end of file