Skip to content

fix: Mercure env vars #1487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 16, 2021
Merged

fix: Mercure env vars #1487

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 4 additions & 21 deletions core/mercure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,26 +16,9 @@ Then, the Mercure hub dispatches the updates to all connected clients using [Ser
Mercure support is already installed, configured and enabled in [the API Platform distribution](../distribution/index.md).
If you use the distribution, you have nothing more to do, and you can skip to the next section.

If you have installed API Platform using another method (such as `composer require api`), you need to install a Mercure hub, and the [Symfony MercureBundle](https://symfony.com/doc/current/mercure.html):
If you have installed API Platform using another method (such as `composer require api`), you need to install [a Mercure hub](https://mercure.rocks/docs/getting-started) and the Symfony MercureBundle.

First, [download and run a Mercure hub](https://mercure.rocks/docs/hub/install).
Then, install the Symfony bundle:

```console
composer require symfony/mercure-bundle
```

Finally, 3 environment variables [must be set](https://symfony.com/doc/current/configuration.html#configuration-based-on-environment-variables):

* `MERCURE_URL`: the URL that must be used by API Platform to publish updates to your Mercure hub (can be an internal or a public URL)
* `MERCURE_PUBLIC_URL`: the **public** URL of the Mercure hub that clients will use to subscribe to updates
* `MERCURE_JWT_SECRET`: a valid Mercure [JSON Web Token (JWT)](https://jwt.io/) allowing API Platform to publish updates to the hub

The JWT **must** contain a `mercure.publish` property containing an array of topic selectors.
This array can be empty to allow publishing anonymous updates only. It can also be `["*"]` to allow publishing on every topics.
[Example publisher JWT](https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdfX0.obDjwCgqtPuIvwBlTxUEmibbBf0zypKCNzNKP7Op2UM) (demo key: `!ChangeMe!`).

[Learn more about Mercure authorization.](https://mercure.rocks/spec#authorization)
[Learn how to install and configure MercureBundle manually on the Symfony website](https://symfony.com/doc/current/mercure.html)

## Pushing the API Updates

Expand Down Expand Up @@ -72,7 +55,7 @@ Clients generated using [the API Platform Client Generator](../client-generator/

## Dispatching Private Updates (Authorized Mode)

Mercure allows to dispatch [private updates, that will be received only by authorized clients](https://mercure.rocks/spec#authorization).
Mercure allows dispatching [private updates, that will be received only by authorized clients](https://mercure.rocks/spec#authorization).
To receive this kind of updates, the client must hold a JWT containing at least one *target selector* matched by the update.

Then, use options to mark the published updates as privates:
Expand Down Expand Up @@ -117,7 +100,7 @@ In addition to `private`, the following options are available:

* `topics`: the list of topics of this update, if not the resource IRI is used
* `data`: the content of this update, if not set the content will be the serialization of the resource using the default format
* `id`: the SSE id of this event, if not set the ID will be generated by the mercure Hub
* `id`: the SSE id of this event, if not set the ID will be generated by the Mercure Hub
* `type`: the SSE type of this event, if not set this field is omitted
* `retry`: the `retry` field of the SSE, if not set this field is omitted
* `normalization_context`: the specific normalization context to use for the update.