Merge pull request #305 from dunglas/docs

docs: Upgrade guide and some other improvements

docs/UPGRADE.md

@@ -1,5 +1,18 @@
 # Upgrade
 
+## 0.10
+
+This version is in sync with the latest version of the specification, which changed a lot. Upgrading to 0.10 **requires to change your code**. Carefully read this guide before upgrading the hub.
+
+* Private updates are now handled differently. *Targets* don't exist anymore. They have been superseded by the concept of *topic selectors*.
+  To send a private update, the publisher must now set the new `private` field to `on` when sending the `POST` request. The topics of the update must also match at least one selector (a URI Template, a raw string or `*` to match all topics) provided in the `mercure.publish` claim of the JWT.
+  To receive a private update, at least one topic of this update must match at least one selector provided in the `mercure.subscribe` claim of the JWT.
+* The structure of the JSON-LD document included in subscription events changed. Especially, `"@type": "https://mercure.rocks/Subscription"` is now `"type": "Subscription"` and `"@id": "/.well-known/mercure/subscriptions/foo/bar"` is now `"id": "/.well-known/mercure/subscriptions/foo/bar"`.
+* The `dispatch_subscriptions` config option has been renamed `subscriptions`.
+* The `subscriptions_include_ip` config option doesn't exist anymore. To include the subscriber IP (or any other value) in subscription events, use the new `mercure.payload` property of the JWT.
+* All IDs generated by the hub (updates ID, subscriptions IDs...) are now URN following the template `urn:uuid:{the-uuid}` (it was `{the-uuid}` before). You may need to update your code if you deal with these IDs.
+* The topic `*` is now reserved and allows to subscribe to all topics.
+
 ## 0.8
 
 * According to the new version of the spec, the URL of the Hub changed moved from `/hub` to `/.well-known/mercure`

docs/getting-started.md

@@ -16,10 +16,10 @@ Subscribing to updates from a web browser or any other platform supporting [Serv
 ```javascript
 // The subscriber subscribes to updates for the https://example.com/users/dunglas topic
 // and to any topic matching https://example.com/books/{id}
-const url = new URL('https://example.com/.well-known/mercure');
+const url = new URL('http://localhost:3000/.well-known/mercure');
 url.searchParams.append('topic', 'https://example.com/books/{id}');
 url.searchParams.append('topic', 'https://example.com/users/dunglas');
-// The URL class is a convenient way to generate URLs such as https://example.com/.well-known/mercure?topic=https://example.com/books/{id}&topic=https://example.com/users/dunglas
+// The URL class is a convenient way to generate URLs such as http://localhost:3000/.well-known/mercure?topic=https://example.com/books/{id}&topic=https://example.com/users/dunglas
 
 const eventSource = new EventSource(url);
 
@@ -35,12 +35,7 @@ It is important to close this connection between the client and the hub if it is
 Opened connections have a continuous buffer that will drain your application resources. 
 This is especially true when using Single Page Applications (based on e.g. ReactJS): the connection is maintained even if the component that created it is unmounted.
 
-```javascript
-if(eventSource !== null) {
-    eventSource.close();
-    eventSource = null;
-}
-```
+To close the connection, call `eventSource.close()`.
 
 ## Sending Private Updates
 
@@ -57,7 +52,7 @@ Also optionally, the hub URL can be automatically discovered:
 Here is a snippet to extract the URL of the hub from the `Link` HTTP header.
 
 ```javascript
-fetch('https://example.com/books/1') // Has this header `Link: <https://example.com/.well-known/mercure>; rel="mercure"`
+fetch('https://example.com/books/1') // Has this header `Link: <http://localhost:3000/.well-known/mercure>; rel="mercure"`
     .then(response => {
         // Extract the hub URL from the Link header
         const hubUrl = response.headers.get('Link').match(/<([^>]+)>;\s+rel=(?:mercure|"[^"]*mercure[^"]*")/)[1];
@@ -76,22 +71,26 @@ Bearer eyJhbGciOiJIUzI1NiJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdLCJzdWJzY3JpYmUi
 topic=https://example.com/books/1&data={"foo": "updated value"}
 ```
 
+Example using [curl](https://curl.haxx.se/):
+
+    curl -d 'topic=https://example.com/books/1' -d 'data={"foo": "updated value"}' -H 'Bearer eyJhbGciOiJIUzI1NiJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdLCJzdWJzY3JpYmUiOlsiaHR0cHM6Ly9leGFtcGxlLmNvbS9teS1wcml2YXRlLXRvcGljIiwie3NjaGVtZX06Ly97K2hvc3R9L2RlbW8vYm9va3Mve2lkfS5qc29ubGQiLCIvLndlbGwta25vd24vbWVyY3VyZS9zdWJzY3JpcHRpb25zey90b3BpY317L3N1YnNjcmliZXJ9Il0sInBheWxvYWQiOnsidXNlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXNlcnMvZHVuZ2xhcyIsInJlbW90ZUFkZHIiOiIxMjcuMC4wLjEifX19.z5YrkHwtkz3O_nOnhC_FP7_bmeISe3eykAkGbAl5K7c' -X POST http://localhost:3000/.well-known/mercure
+
 Example using [Node.js](https://nodejs.org/) / [Serverless](https://serverless.com/):
 
 ```javascript
 // Handle a POST, PUT, PATCH or DELETE request or finish an async job...
 // and notify the hub
-const https = require('https');
+const http = require('http');
 const querystring = require('querystring');
 
 const postData = querystring.stringify({
     'topic': 'https://example.com/books/1',
     'data': JSON.stringify({ foo: 'updated value' }),
 });
 
-const req = https.request({
-    hostname: 'example.com',
-    port: '443',
+const req = http.request({
+    hostname: 'localhost',
+    port: '3000',
     path: '/.well-known/mercure',
     method: 'POST',
     headers: {
@@ -111,6 +110,14 @@ req.end();
 
 The JWT must contain a `publish` property containing an array of topic selectors. This array can be empty to allow publishing anonymous updates only. The topic selector `*` can be used to allow publishing private updates for all topics. To create and read JWTs try [jwt.io](https://jwt.io) ([demo token](https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdLCJzdWJzY3JpYmUiOlsiaHR0cHM6Ly9leGFtcGxlLmNvbS9teS1wcml2YXRlLXRvcGljIiwie3NjaGVtZX06Ly97K2hvc3R9L2RlbW8vYm9va3Mve2lkfS5qc29ubGQiLCIvLndlbGwta25vd24vbWVyY3VyZS9zdWJzY3JpcHRpb25zey90b3BpY317L3N1YnNjcmliZXJ9Il0sInBheWxvYWQiOnsidXNlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXNlcnMvZHVuZ2xhcyIsInJlbW90ZUFkZHIiOiIxMjcuMC4wLjEifX19.z5YrkHwtkz3O_nOnhC_FP7_bmeISe3eykAkGbAl5K7c), key: `!ChangeMe!`).
 
+## Active Subscriptions
+
+Mercure dispatches events every time a new subscription is created or terminated. It also exposes a web API to retrieve the list of active subscriptions.
+
+[Learn more about subscriptions](../spec/mercure.md#active-subscriptions).
+
 ## Going Further
 
-[Read the full specification](../spec/mercure.md)
+* [Read the full specification](../spec/mercure.md)
+* [Install the hub](hub/install.md)
+* [Checkout the examples](ecosystem/awesome.md#examples)

docs/hub/troubleshooting.md

@@ -2,19 +2,21 @@
 
 ## 401 Unauthorized
 
+* Double-check that the request to the hub includes a `mercureAuthorization` cookie or an `Authorization` HTTP header
+* If the cookie isn't set, you may have to explicitly include [the request credentials](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) (`new EventSource(url, {withCredentials: true})` and `fetch(url, {credentials: 'include'})`)
 * Check the logs written by the hub on `stderr`, they contain the exact reason why the token has been rejected
 * Be sure to set a **secret key** (and not a JWT) in `JWT_KEY` (or in `SUBSCRIBER_JWT_KEY` and `PUBLISHER_JWT_KEY`)
 * If the secret key contains special characters, be sure to escape them properly, especially if you set the environment variable in a shell, or in a YAML file (Kubernetes...)
 * The publisher always needs a valid JWT, even if `ALLOW_ANONYMOUS` is set to `1`, this JWT **must** have a property named `publish`. To dispatch private updates, the `publish` property must contain the list of topic selectors this publisher can use ([example](https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdLCJzdWJzY3JpYmUiOlsiaHR0cHM6Ly9leGFtcGxlLmNvbS9teS1wcml2YXRlLXRvcGljIiwie3NjaGVtZX06Ly97K2hvc3R9L2RlbW8vYm9va3Mve2lkfS5qc29ubGQiLCIvLndlbGwta25vd24vbWVyY3VyZS9zdWJzY3JpcHRpb25zey90b3BpY317L3N1YnNjcmliZXJ9Il0sInBheWxvYWQiOnsidXNlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXNlcnMvZHVuZ2xhcyIsInJlbW90ZUFkZHIiOiIxMjcuMC4wLjEifX19.z5YrkHwtkz3O_nOnhC_FP7_bmeISe3eykAkGbAl5K7c))
 * The subscriber needs a valid JWT only if `ALLOW_ANONYMOUS` is set to `0` (default), or to subscribe to private updates, in this case the JWT **must** have a property named `subscribe` and containing an array of topic selectors ([example](https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdLCJzdWJzY3JpYmUiOlsiaHR0cHM6Ly9leGFtcGxlLmNvbS9teS1wcml2YXRlLXRvcGljIiwie3NjaGVtZX06Ly97K2hvc3R9L2RlbW8vYm9va3Mve2lkfS5qc29ubGQiLCIvLndlbGwta25vd24vbWVyY3VyZS9zdWJzY3JpcHRpb25zey90b3BpY317L3N1YnNjcmliZXJ9Il0sInBheWxvYWQiOnsidXNlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXNlcnMvZHVuZ2xhcyIsInJlbW90ZUFkZHIiOiIxMjcuMC4wLjEifX19.z5YrkHwtkz3O_nOnhC_FP7_bmeISe3eykAkGbAl5K7c))
 
-For both the `publish` and `subscribe` properties, the array can be empty to publish only public updates, or set it to `["*"]` to allow publishing updates for all topics.
+For both the `publish` property, the array can be empty to publish only public updates. For both `publish` and `subscribe`, you can use `["*"]` to match all topics.
 
 ## Browser Issues
 
 If subscribing to the `EventSource` in the browser doesn't work (the browser instantly disconnects from the stream or complains about CORS policy on receiving an event), check that you've set a proper value for `CORS_ALLOWED_ORIGINS` on running Mercure. It's fine to use `CORS_ALLOWED_ORIGINS=*` for your local development.
 
-## URI Template and Topics
+## URI Templates and Topics
 
 Try [our URI template tester](https://uri-template-tester.mercure.rocks/) to ensure that the template matches the topic.
 

docs/spec/faq.md

@@ -1,23 +1,11 @@
 # Frequently Asked Questions
 
-## How to Use Mercure with GraphQL?
-
-Because they are delivery agnostic, Mercure plays particularly well with [GraphQL's subscriptions](https://facebook.github.io/graphql/draft/#sec-Subscription).
-
-In response to the subscription query, the GraphQL server may return a corresponding topic URL.
-The client can then subscribe to the Mercure's event stream corresponding to this subscription by creating a new `EventSource` with an URL like `https://example.com/.well-known/mercure?topic=https://example.com/subscriptions/<subscription-id>` as parameter.
-
-Updates for the given subscription can then be sent from the GraphQL server to the clients through the Mercure hub (in the `data` property of the server-sent event).
-
-To unsubscribe, the client just calls `EventSource.close()`.
-
-Mercure can easily be integrated with Apollo GraphQL by creating [a dedicated transport](https://github.com/apollographql/graphql-subscriptions).
+## What's the Difference Between Mercure and WebSockets?
 
-## What's the Difference Between Mercure and WebSocket?
+In a nutshell [the WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) is low level, Mercure is a high level.
+Mercure provides convenient built-in features such as authorization, re-connection, state reconciliation and a presence API ; while with WebSockets, you need to implement them yourself.
 
-[WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) is a low level protocol, Mercure is a high level one.
-Mercure provides convenient built-in features such as authorization, re-connection and state reconciliation ; while with WebSocket, you need to implement them yourself.
-Also, unlike Mercure (which is built on top of HTTP and Server-Sent Events), WebSocket [is not designed to leverage HTTP/2](https://www.infoq.com/articles/websocket-and-http2-coexist).
+Also WebSockets [are not designed to leverage HTTP/2+](https://www.infoq.com/articles/websocket-and-http2-coexist) and are known to be [hard to secure](https://gravitational.com/blog/kubernetes-websocket-upgrade-security-vulnerability/). On the other hand Mercure relies on plain HTTP connections and benefits from the performance an security improvement built in the latest versions of this protocol.
 
 HTTP/2 connections are multiplexed and bidirectional by default (it was not the case of HTTP/1).
 When using Mercure over a h2 connection (recommended), your app can receive data through Server-Sent Events, and send data to the server with regular `POST` (or `PUT`/`PATCH`/`DELETE`) requests, with no overhead.
@@ -40,3 +28,25 @@ In most implementations, the size of the payload to dispatch is very limited, an
 On the other hand, Mercure is a duplex protocol designed to send live updates to devices currently connected to the web or mobile app. The payload is not limited, and the message goes directly from your servers to the clients.
 
 In summary, use the Push API to send notifications to offline users (that will be available in Chrome, Android and iOS's notification centers), and use Mercure to receive and publish live updates when the user is using the app.
+
+## What's the Maximum Number of Open Connections Per Browser?
+
+When using HTTP/2+ ([the default for almost all users](https://caniuse.com/#feat=http2)), the maximum number of simultaneous HTTP **streams** is negotiated between the server and the client (it defaults to 100).
+When using HTTP 1.1, this limit is of 6.
+
+By using template selectors and by passing several `topic` parameters, it's possible to subscribe to an unlimited of topics using a single HTTP connection.
+
+## How to Use Mercure with GraphQL?
+
+Because they are delivery agnostic, Mercure plays particularly well with [GraphQL's subscriptions](https://facebook.github.io/graphql/draft/#sec-Subscription).
+
+For instance, [the API Platform framework has native support for GraphQL subscriptions thanks to Mercure](https://api-platform.com/docs/master/core/graphql/#subscriptions).
+
+In response to the subscription query, the GraphQL server may return a corresponding topic URL.
+The client can then subscribe to the Mercure's event stream corresponding to this subscription by creating a new `EventSource` with an URL like `https://example.com/.well-known/mercure?topic=https://example.com/subscriptions/<subscription-id>` as parameter.
+
+Updates for the given subscription can then be sent from the GraphQL server to the clients through the Mercure hub (in the `data` property of the server-sent event).
+
+To unsubscribe, the client just calls `EventSource.close()`.
+
+Also, Mercure can easily be integrated with Apollo GraphQL by creating [a dedicated transport](https://github.com/apollographql/graphql-subscriptions).

docs/spec/use-cases.md

@@ -1,10 +1,14 @@
 
 # Use Cases
 
+From building a chat room to expose a fully-featured event store, Mercure covers a broad spectrum of use cases related to realtime and async APIs.
+
 Example of usage: the Mercure integration in [API Platform](https://api-platform.com/docs/client-generator):
 
 ![API Platform screencast](https://api-platform.com/d20c0f7f49b5655a3788d9c570c1c80a/client-generator-demo.gif)
 
+Here are some popular use cases:
+
 ## Live Availability
 
 * a webapp retrieves the availability status of a product from a REST API and displays it: only one is still available
@@ -23,3 +27,5 @@ Example of usage: the Mercure integration in [API Platform](https://api-platform
 * changes made are immediately broadcasted to all connected users
 
 **Mercure gets you covered!**
+
+See also, [the examples](../ecosystem/awesome.md#examples).