Mediation for Edge Agents in Aries Framework JavaScript

TimoGlastra commented 4 years ago

Current thoughts on implementing mediation for Edge Agents into Aries Framework JavaScript. I think in the beginning especially the Edge Agent role would be nice to implement, but eventually implementing the Mediator role would also be nice. This approach allows for interoperable mediaton with other agents that support the protocols mentioned in this document. Still some unresolved questions at the end. Would appreciate some other thoughts on this.

Creating A Connection with the Mediator

The Mediator creates a Connection Invitation and sends it to the Edge Agent. If the Edge Agent wishes to connect to the Mediator it should respond with a Connection Request. Because the Edge Agent has no endpoint to include in the Connection Request, an endpoint URI of didcomm:transport/queue will indicate to the Mediator that the Edge Agent does not have a direct endpoint and messages should be queued.

The Connection Request sent by the Edge Agent should include the Transport Return Route Decorator to allow the Mediator to directly respond with a Connection Response message.

The Edge Agent and Mediator now have a connection. The Mediator will queue all messages it wants to send to the Edge Agent due to the didcomm:transport/queue endpoint.

Requesting Mediation

The Mediator and Edge Agent now have a connection, but it is not clear yet whether the Mediator would like to mediate for the Edge Agent.

Using the Mediator Coordination Protocol the Edge Agent can send a Mediation Request to the Mediator. If the Mediator wishes to accept it will respond with a Mediation Grant message. The Mediation Grant will include the endpoint and routing_keys properties. The Edge Agent should store these values as they will be used when creating new connections with other agents.

Creating A Connection with Other Agents

Now that the Edge Agent made an agreement with the Mediator to act as an endpoint to receive messages, the Edge Agent can create connections with other agents using this endpoint.

It is not important whether the Edge Agent takes the role of Inviter or Invitee in the connection process. It is however important that before sending a message to the other agent the key used for this message is known by the Mediator. The Edge Agent should send a Keylist Update message to the Mediator containing the key that will be used. The Mediator now knows that whenever a Forward message is received for this key, it is intended for the Edge Agent.

After the key is registered the connection flow can continue like normal. The Edge Agent can use the endpoint and routing_keys from the Requesting Mediation step when exchanging DID Docs.

Receiving Messages

As the Edge Agent has no endpoint the Mediator can't directly forward the messages to the Edge Agent when it receives them. The Creating A Connection with the Mediator step allowed the Mediator to send a message to the Edge Agent using return routing. This is the implicit way for the Edge Agent to retrieve Messages. The explicit way is by using the Pickup Protocol

Implicit

Messages can be retrieved by the Edge Agent implicitly by connecting using the Return Routing Protocol. It is recommended that a WebSocket transport be used between the Edge Agent and the Mediator for efficient message passing, and responsive message delivery when the Edge Agent app is open.

Explicit

When WebSocket transport is not available and HTTP is used, return routing can only include one message in the HTTP response for each message the Edge Agent sends to the Mediator. This is where the Pickup Protocol can be used. Return routing will still be used, but by sending a Batch Pickup message as Edge Agent the Mediator can respond with a single Batch message containing multiple messages.

References

Questions

I'm not sure whether it is required for the Edge Agent to send a message to the Mediator when opening a WebSocket connection with the Transport Return Routing decorator. I think this is necessary, because you can't just send an object with the ~transport decorator without including a message @type. If this is the case we could maybe use Noop message from the Pickup Protocol
As mentioned in the notes below, Aries Framework .NET supports an add-device-info message especially useful for push notifications. This is not possible with this approach. Is this desired?
As also mentioned in the notes below, Aries Framework .NET uses a custom protocol, this means this approach won't be interoperable with Aries Framework .NET. Is this desired?

Notes

Aries Framework .NET created and implemented a custom basic-routing protocol that achieves approximately the same. Main differences are:
- The protocol allows to create an inbox. Messages will be stored inside the inbox. To delete messages from the inbox a separate delete message type is used. With the pickup protocol messages are only kept until delivered.
- The protocol has a message type to add device information. This is especially useful to send e.g. push notifications from the mediator to the edge agent when a message is received.
Aries Framework Go implemented the approach described in this document. I think the only thing missing is the didcomm:transport/queue endpoint. The Route Coordination Protocol got renamed to Mediator Coordination Protocol and got some small updates. With some adjustments Aries Framework Go could be used as a Mediator for Aries Framework JavaScript Edge Agents

jakubkoci commented 4 years ago

Hi @TimoGlastra, thanks for the write-up, I went through it briefly and it was really helpful. I'll look into it more over the weekend and we'll see how far I'll get :)

jakubkoci commented 4 years ago

I've prepared partial implementation here https://github.com/jakubkoci/aries-framework-javascript/tree/feature/connection-with-mediator.

It contains:

Creating A Connection with the Mediator
Receiving Messages - Explicit with pickup protocol

I'll create PR after merging #41 because I continued from that branch.

JS framework already has:

Creating A Connection with Other Agents

TimoGlastra commented 4 years ago

Great stuff!

I have some extra thoughts on this and other topics. Let's discuss during the call friday and keep this issue open to track progress.

troyronda commented 4 years ago

FYI: Updates were applied to aries-framework-go today.

@TimoGlastra

TimoGlastra commented 4 years ago

Awesome. I think everything is in place then to use framework-go as a mediator for framework-javascript.

@troyronda Some questions on the go implementation:

Is it correct the pickup protocol is not implemented?
What does the edge agent send to the mediator when opening a websocket connection? As it needs the ~transport decorator (see the first question in the original issue).
When I looked trough the code it seemed like forward messages are not stored at the moment if the mediator can't directly send them to the receiver edge agent. Is this correct?

rolsonquadras commented 4 years ago

@TimoGlastra

Awesome. I think everything is in place then to use framework-go as a mediator for framework-javascript.

@troyronda Some questions on the go implementation:

Is it correct the pickup protocol is not implemented?

Yes, the protocol is not implemented yet

What does the edge agent send to the mediator when opening a websocket connection? As it needs the ~transport decorator (see the first question in the original issue).

That's correct.Currently, only all return route option in ~transport is supported in aries-framework-go.

When I looked trough the code it seemed like forward messages are not stored at the moment if the mediator can't directly send them to the receiver edge agent. Is this correct?

Yes. At the moment, the edge agent needs to be online(active socket connection to the router) when router receives message for that particular agent.

jakubkoci commented 4 years ago

All mentioned protocol has been implemented except for Requesting Mediation part which will be solved in #63

openwallet-foundation / credo-ts