Network Working Group                                         K. Dunglas
Internet-Draft                                         Les-Tilleuls.coop
Intended status: Informational                          October 11, 2018
Expires: April 14, 2019


                          The Mercure Protocol
                        draft-dunglas-mercure-00

Abstract

   Mercure is a protocol allowing to push data updates to web browsers
   and other HTTP clients in a fast, reliable and battery-efficient way.
   It is especially useful to publish real-time updates of resources
   served through web APIs, to reactive web and mobile apps.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on April 14, 2019.

Copyright Notice

   Copyright (c) 2018 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.




Dunglas                  Expires April 14, 2019                 [Page 1]

 
Internet-Draft            The Mercure Protocol              October 2018


1.

   The keywords

   ,

   ,

   ,

   ,

   ,

   ,

   ,

   ,

   , and

   , when they appear in this document, are to be interpreted as
   described in [RFC2119].

2.

   The publisher

   advertises the URL of one or more hubs to the subscriber, allowing it
   to receive live updates when topics are updated.  If more than one
   hub URL is specified, it is expected that the publisher notifies each
   hub, so the subscriber

   subscribe to one or more of them.

   The publisher

   include at least one Link Header [RFC5988] with

   (a hub link header).  The target URL of these links

   be a hub implementing the Mercure protocol.

   Note: this relation type has not been registered yet [RFC5988].
   During the meantime, the relation type

   can be used instead.



Dunglas                  Expires April 14, 2019                 [Page 2]

 
Internet-Draft            The Mercure Protocol              October 2018


   The publisher

   provide the following target attributes in the Link headers:

   All these attributes are optional.

   The publisher

   also include one Link Header [RFC5988] with

   (the self link header).  It

   contain the canonical URL for the topic to which subscribers are
   expected to use for subscriptions.  If the Link with

   is ommitted, the current URL of the resource

   be used as fallback.

   Minimal example:

   Links embedded in HTML or XML documents (as defined in the WebSub
   recommendation)

   also be supported by subscribers.

   Note: the discovery mechanism described in this section is strongly
   inspired from the one specified in the WebSub recommendation [1].

3.

   The subscriber subscribes to an URL exposed by a hub to receive
   updates of one or many topics.  To subscribe to updates, the client
   opens an HTTPS connection following the Server-Sent Events
   specification [2] to the hub's subscription URL advertised by the
   Publisher.  The connection

   use HTTP/2 to leverage mutliplexing and other advanced features of
   this protocol.

   The subscriber specifies the list of topics to get updates for by
   using one or several query parameters named

   .  The value of these query parameters

   be URI templates [RFC6570].

   Note: an URL is also a valid URI template.



Dunglas                  Expires April 14, 2019                 [Page 3]

 
Internet-Draft            The Mercure Protocol              October 2018


   The protocol doesn't specify the maximum number of

   parameters that can be sent, but the hub

   apply an arbitrary limit.

   The EventSource JavaScript interface [3]

   be used to establish the connection.  Any other appropriate mechanism
   including but not limited to readable streams [4] and XMLHttpRequest
   [5] (used by popular polyfills)

   also be used.

   The hub sends updates concerning all subscribed resources matching
   the provided URI templates.  The hub

   send these updates as text/event-stream compliant events [6].

   The

   property

   contain the new version of the topic.  It can be the full resource,
   or a partial update by using formats such as JSON Patch

   or JSON Merge Patch

   .

   All other properties defined in the Server-Sent Events specification

   be used and

   be supported by hubs.

   The resource

   be represented in a format with hypermedia capabilities such as JSON-
   LD [W3C.REC-json-ld-20140116], Atom [RFC4287], XML
   [W3C.REC-xml-20081126] or HTML [W3C.REC-html52-20171214].

   Web Linking [RFC5988]

   be used to indicate the IRI of the resource sent in the event.  When
   using Atom, XML or HTML as serialization format for the resource, the
   document




Dunglas                  Expires April 14, 2019                 [Page 4]

 
Internet-Draft            The Mercure Protocol              October 2018


   contain a

   element with a

   relation containing the IRI of the resource.  When using JSON-LD, the
   document

   contain an

   property containing the IRI of the resource.

   Example:

4.

   The hub receives updates from the publisher on a dedicated HTTPS
   endpoint.  The connection

   use an encryption layer, such as TLS.  HTTPS certificate can be
   obtained for free using Let's Encrypt [7].

   When it receives an update, the hub dispatches it to subsribers using
   the established server-sent events connections.

   An application CAN send events directly to the subscribers, without
   using an external hub server, if it is able to do so.  In this case,
   it

   implement the endpoint to publish updates.

   The endpoint to publish updates is an HTTPS URL accessed using the

   method.  The request

   be encoded using the

   format and contains the following data:

   The request

   also contain an

   HTTP header containing the string

   followed by a valid JWS [RFC7515] in compact serialization that the
   hub will check to ensure that the publisher is authorized to publish
   the update.




Dunglas                  Expires April 14, 2019                 [Page 5]

 
Internet-Draft            The Mercure Protocol              October 2018


5.

   If a topic is not public, the update request sent by the publisher to
   the hub

   also contain a list of keys named

   .  Theirs values are

   . They can be, for instance a user ID, or a list of group IDs.

   To receive updates for private topics, the subscriber

   send a cookie called

   when connecting to the hub.

   The cookie

   be set by the publisher during the discovery.  The cookie

   have the

   ,

   .  It

   have the

   flag if appropriate.  Setting the cookie's

   to the path of the subscribe endpoint is also

   .  When skipping the discovery mechanism, the client

   set the cookie itself (for security reasons, this is not recommended
   in the context of a web browser).

   Consequently if the subscriber is a web browser, both the publisher
   and the hub have to share the same second level domain to use the
   autorization feature.  The

   flag

   be used to allow the publisher and the host to use different
   subdomains.

   By the



Dunglas                  Expires April 14, 2019                 [Page 6]

 
Internet-Draft            The Mercure Protocol              October 2018


   specification, connections can only be estabilished using the

   HTTP method, and it is not possible to set custom HTTP headers (such
   as the

   one).

   However, cookies are supported, and can be included even in
   crossdomain requests if the CORS credentials are set [8]:

   The value of this cookie

   be a JWS in compact serialization.  It

   have a claim named

   that contains an array of strings: the list of targets the user is
   authorized to receive updates for.  For instance, valid targets can
   be a username or a list of group identifiers.  The JWS

   be short lived, especially if the subscriber is a web browser.

   If one or more targets are specified, the update

   be sent to the subscriber by the hub, unless the

   claim of the subscriber contains at least one target specified for
   the topic by the publisher.

   When using the authorization mechanism, the connection between the
   subscriber and the hub

   use an encryption layer (HTTPS is required).

6.

   To allow re-establisment in case of connection lost, events
   dispatched by the hub

   include an

   property.  The value contained in this

   property

   be a globally unique identifier.  To do so, UUID [RFC4122]

   be used.



Dunglas                  Expires April 14, 2019                 [Page 7]

 
Internet-Draft            The Mercure Protocol              October 2018


   According to the server-sent events specification, in case of
   connection lost the subscriber will try to automatically reconnect.
   During the reconnection the subscriber

   send the last received event id in a Last-Event-ID [9] HTTP header.

   The server-sent events specification doesn't allow to set this HTTP
   header during the first connection (before a re-connection occurs).
   In order to fetch any update dispatched between the initial resource
   generation by the publisher and the connection to he hub, the
   subscriber

   send the event id provided during the discovery in the

   link's attribute in a query parameter named

   when connecting to the hub.

   If both the

   HTTP header and the query parameter are present, the HTTP header

   take precedence.

   If the

   header or query parameter exists, the hub

   send to the subscriber all events published since the one having this
   identifier.

   The hub

   discard some messages for operational reasons.  The subscriber

   assume that no update will be lost, and

   re-fetch the original topic to ensure this (for instance, after a
   long deconnection time).

   The hub

   also specify the reconnection time using the

   key, as specified in the server-sent events format.






Dunglas                  Expires April 14, 2019                 [Page 8]

 
Internet-Draft            The Mercure Protocol              October 2018


7.

   Using HTTPS doesn't prevent the hub to access to the update's
   content.  Depending of the intended privacy of informations contained
   in the updates, it

   be necessary to prevent eavesdropping by the hub.

   To make sure that the message content can not be read by the hub, the
   publisher

   encode the message before sending it to the hub.  The publisher

   use JSON Web Encryption [RFC7516] to encrypt the update content.  The
   publisher

   provide the relevant encryption key(s) in the

   attribute of the Link HTTP header during the discovery.  The

   attribute

   contain a key encoded using the JSON Web Key Set [RFC7517] format.
   Any other out-of-band mechanism

   be used instead to share the key between the publisher and the
   subscriber.

   Updates encyption is considered a best practice to prevent mass
   surveillance.  This is especially relevant if the hub is managed by
   an external provider.

.  References

8.1.  References

8.2.  References

8.3.  URIs

   [] https://www.w3.org/TR/websub/#discovery

   [] https://html.spec.whatwg.org/multipage/server-sent-events.html

   [] https://html.spec.whatwg.org/multipage/server-sent-
       events.html#the-eventsource-interface





Dunglas                  Expires April 14, 2019                 [Page 9]

 
Internet-Draft            The Mercure Protocol              October 2018


   [] https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/
       Using_readable_streams

   [] https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/
       Using_XMLHttpRequest

   [] https://html.spec.whatwg.org/multipage/server-sent-
       events.html#sse-processing-model

   [] https://letsencrypt.org/

   [] https://html.spec.whatwg.org/multipage/server-sent-
       events.html#dom-eventsourceinit-withcredentials

   [] https://html.spec.whatwg.org/multipage/iana.html#last-event-id

Author's Address

   Kevin Dunglas
   Les-Tilleuls.coop
   5 rue Hegel
   Lille  59000
   France

   Email: kevin@les-tilleuls.coop


























Dunglas                  Expires April 14, 2019                [Page 10]