Skip to content

0212: Pickup Protocol

Summary

A protocol to coordinate routing configuration between a routing agent and the recipient.

Motivation

Messages can be picked up simply by sending a message to the message holder with a return_route decorator 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.

Tutorial

Roles

message_holder - The agent that has messages waiting for pickup by the recipient. recipient - The agent who is picking up messages. batch_sender - A message_holder that is capable of returning messages in a batch. batch_recipient - A recipient that is capable of receiving and processing a batch message.

Flow

status can be used to see how many messages are pending. batch retrieval can be executed when many messages ...

Reference

StatusRequest

Sent by the recipient to the message_holder to request a status message.

{
  "@id": "123456781",
  "@type": "https://didcomm.org/messagepickup/1.0/status-request"
}

Status

Status details about pending messages

{
  "@id": "123456781",
  "@type": "https://didcomm.org/messagepickup/1.0/status",
  "message_count": 7,
  "duration_waited": 3600,
  "last_added_time": "2019-05-01 12:00:00Z",
  "last_delivered_time": "2019-05-01 12:00:01Z",
  "last_removed_time": "2019-05-01 12:00:01Z",
  "total_size": 8096
}

message_count is the only required attribute. The others may be present if offered by the message_holder.

Batch Pickup

A request to have multiple waiting messages sent inside a batch message.

{
  "@id": "123456781",
  "@type": "https://didcomm.org/messagepickup/1.0/batch-pickup",
  "batch_size": 10
}

Batch

A message that contains multiple waiting messages.

{
    "@id": "123456781",
    "@type": "https://didcomm.org/messagepickup/1.0/batch",
    "messages~attach": [
        {
            "@id" : "06ca25f6-d3c5-48ac-8eee-1a9e29120c31",
            "message" : "{
                ...
            }"
        },

        {
            "@id" : "344a51cf-379f-40ab-ab2c-711dab3f53a9a",
            "message" : "{
                ...
            }"
        }
    ]
}

Message Query With Message Id List

A request to read single or multiple messages with a message message id array.

{
  "@id": "123456781",
  "@type": "https://didcomm.org/messagepickup/1.0/list-pickup",
  "message_ids": [
    "06ca25f6-d3c5-48ac-8eee-1a9e29120c31",
    "344a51cf-379f-40ab-ab2c-711dab3f53a9a"
  ]
}

message_ids message id array for picking up messages. Any message id in message_ids could be delivered via several ways to the recipient (Push notification or with an envoloped message).

Message List Query Response

A response to query with message id list.

{
    "@type": "https://didcomm.org/messagepickup/1.0/list-response",
    "messages~attach": [
        {
            "@id" : "06ca25f6-d3c5-48ac-8eee-1a9e29120c31",
            "message" : "{
                ...
            }"
        },
        {
            "@id" : "344a51cf-379f-40ab-ab2c-711dab3f53a9a",
            "message" : "{
                ...
            }"
        }
    ]
}

Noop

Used to receive another message implicitly. This message has no expected behavior when received.

{
  "@id": "123456781",
  "@type": "https://didcomm.org/messagepickup/1.0/noop"
}

Prior art

Concepts here borrow heavily from a document written by Andrew Whitehead of BCGov.

Unresolved questions

  • We are using multiple roles to indicate which portions of the protocol are supported by each party. This is a new thing we have not done before. Is this ok?

Implementations

The following lists the implementations (if any) of this RFC. Please do a pull request to add your implementation. If the implementation is open source, include a link to the repo or to the implementation within the repo. Please be consistent in the "Name" field so that a mechanical processing of the RFCs can generate a list of all RFCs supported by an Aries implementation.

Name / Link Implementation Notes