[james-project] branch master updated: [ADR] JMAP PUSH over WebSockets

[bt...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git


The following commit(s) were added to refs/heads/master by this push:
     new d4e3782  [ADR] JMAP PUSH over WebSockets
d4e3782 is described below

commit d4e37822b0cbd8c590d67f38c1a52fd009b3803b
Author: Benoit Tellier <bt...@linagora.com>
AuthorDate: Tue Jan 26 12:35:44 2021 +0700

    [ADR] JMAP PUSH over WebSockets
---
 src/adr/0047-jmap-push-over-websockets.md | 77 +++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/src/adr/0047-jmap-push-over-websockets.md b/src/adr/0047-jmap-push-over-websockets.md
new file mode 100644
index 0000000..74d6509
--- /dev/null
+++ b/src/adr/0047-jmap-push-over-websockets.md
@@ -0,0 +1,77 @@
+# 47. JMAP PUSH over WebSockets
+
+Date: 2021-01-26
+
+## Status
+
+Accepted (lazy consensus).
+
+Relates to [45. Support JMAP Push with Mailbox/changes implementation](0045-support-jmap-push-with-mailbox-changes-implementation.md)
+
+Requires [46. Generalize EventBus](0046-generalize-event-bus.md)
+
+## Context
+
+JMAP Push notifications allow clients to efficiently update (almost) instantly to stay in sync with data changes on the server. 
+
+In order to support this, we need to have the server emit newest state changes to the client over a PUSH channel.
+
+## Decision
+
+We will implement [RFC-8887 - A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket](https://tools.ietf.org/html/rfc8887) 
+as a transport mechanism for PUSH notifications.
+
+We will [generalize EventBus](0046-generalize-event-bus.md) in order to achieve an out-of-the box Publish-Subscribe 
+system for JMAP related events, that does not fit in the mailbox API.
+
+We will implement listeners registered on the JMAP event bus for WebSocket clients in order to carry over state changes
+to the client.
+
+## Consequences
+
+We expect clients using the PUSH to lead to a drastic performance enhancement, as less data needs to be transmitted upon
+resynchronisation.
+
+As mentioned in RFC-8887 the usage of webSockets allows other performance optimizations:
+ - Requests can easily be compressed, which is not doable over HTTP for most available implementation (HTTP request 
+compression is not ubiquitous).
+ - WebSockets being connected, authentication can be performed once, when establishing the connection. This can allow to
+reduce the load, if needed, on authentication systems. It might ease the use for instance of custom OpenId connect 
+providers.
+
+People deploying JMAP need to be aware that load-balancing webSockets requires session stickiness.
+
+## Sequence
+
+ 1. Bob authenticates against the `ws://` endpoints. Upgrade to websockets is granted.
+ 2. Bob registers Email and Mailbox updates. A listener listens for state changes related to Bob account.
+ 3. Bob receives a mail. The MailboxManager adds it to Bob's mailbox. An `Added` event is fired on the mailbox event bus.
+ 4. The `MailboxChangeListener` processes the Added event, handles delegation, records the state change, and fires related
+ events for each account on the JMAP event bus, for both `Email` (as there is an addition) and `Mailbox` (as the counts 
+ were updated).
+ 5. Bob's webSocket listener receives a message from RabbitMQ and pushes it to Bob.
+ 6. Bob's MUA is aware it needs to re-synchronize. It will perform resynch requests combining `Email/changes`, `Email/get`,
+ `Mailbox/changes` and `Mailbox/get`.
+ 
+Event bus listener are created for each socket upon client requests, and removed upon disconnection or when PUSH is
+explicitly canceled by the client.
+
+In a multi-node setup, the event bus registration key mechanism described in [this ADR](0037-eventbus.md) and its 
+[distributed implementation](0038-distributed-eventbus.md) ensure events are routed to
+the James servers holding client PUSH registration. We will use the AccountId as a base for a registration key.
+ 
+## Alternatives
+
+The [JMAP RFC](https://tools.ietf.org/html/rfc8620) defines [event source](https://www.w3.org/TR/eventsource/) (Server 
+Sent Events) as a supported transport medium for PUSH notification. Yet:
+
+ - Active JMAP contributors lack production experience on Event source while they do already deploy webSockets
+ - Performance enhancements (authentication and request compression) unlocked by webSockets are not achievable via event 
+ source.
+ 
+ Note that nothing refrains about future implementation of event source mechanism, that, if need be can be ignored or
+ disabled via a reverse proxy.
+ 
+## References
+
+- [Support JMAP WebSocket PUSH](https://issues.apache.org/jira/browse/JAMES-3491)


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org