Complete demo code available at: https://github.com/LastCallMedia/mercure-api-platform-demo
This video shows the demo user interface provided by Mercure. First we load up a base API Platform project and add Mercure into the docker compose file. After firing it up, we show how to generate JWT tokens and how to subscribe and publish through the Mercure demo UI.
Relevant URLs:
https://github.com/dunglas/mercure
https://github.com/api-platform/api-platform
https://jwt.io/
Transcript:
[bright electronic music]
Silas: Here I have the base project, this is starting with the API Platform GitHub project I was showing earlier, and this is just a base for getting started with API Platform. Now, I have, if you notice to the left here, VS Code is showing that I’ve made 41 changes, and this is primarily just deleting stuff that we don’t need, to try to make this demo project simpler, so I’m gonna commit that, and put the message as “Delete stuff we don’t need,” gonna commit that locally, and now we look at the project.
There is a directory, API, which is the PHP API. There’s Client, which is a React app that comes with this project, and we’ll be replacing that with our own React app that does only what we want it to do. Importantly for this video, there’s a docker-compose file. This docker-compose file has some services in it, has the PHP API, has the Postgres DB, for saving changes, and the React client, which is built from this client directory, and then we will just paste in here our Mercure service, and this will just be using an image which the creator made, to get us started quickly. We’re gonna set some environment variables below, these are of course very important, the JWT_KEY is what keeps this secure, and allows for us to decrypt and encrypt the JWT Tokens. So mine is just this super quick thing, probably you would want something longer and more secure, but this is gonna be easy for us. We’ll turn demo mode on, so we can play with the web UI that comes with Mercure. We’ll allow anonymous subscriptions, we’ll allow publishing from this URL, which will actually be our Mercure demo URL. We’ll turn debugging on and we’ll allow core’s request from this URL, localhost, which is the React client we’ll be building. And we will be exposing Mercure on my local machine at port 9090.
Okay. So, let’s do the demo, it’s gonna be fun. Let’s make sure we’re in the right directory. There’s our stuff, run docker-compose up to get this going. Here it goes, just takes a couple seconds. So, now Mercure should be running. Go to “localhost:9090,” and here we see the demo UI. The first thing we need to do is create a proper token to communicate with Mercure.
Click this button, “Create a token,” and it sends you over to JWT.io. Here you see the payload is pre-entered for you and this is showing you the format of the data that Mercure expects in the JWT tokens you send. Here we have subscribe, and below we have the targets, which this token bearer is allowed to subscribe to. That’s “foo” and “bar”. This token bearer will be allowed to publish to “foo”. This is great, on the left here, you see the token, which is encoded and encrypted. However, it’s encrypted with JWT.io’s default key. And since we’re using this other key, over here, in the docker-compose environment variable section, we need to make sure to use that here when we’re generating our JWT Tokens, so that they’re compatible with our Mercure server.
So, I copied that generated token and here I’m putting it into the demo above here you see that it’s using the Mercure authorization cookie and it says that, “This token will only be sent to the server after you discover a demo endpoint.” All that means is, we click “discover” and accept the cookie in our browser.
I’m just going to subscribe to this one and we’re subscribed to the “books/1” topic and over here this form is the publish form, and this is set to publish to the same topic, and this is the data that it will publish. If I click, “publish” here, it’s working.
Just to demo a little bit of how targets work, if I type in “bar” here and click “publish,” it says “unauthorized,” and this is because this token didn’t have “bar” in the publish section here, so it just has “foo”. If I change “bar” to “foo” and click “publish,” that worked. We saw another—we saw the data come in here for that. So that’s working.
The next thing to show is when things get more interesting, is when we have two browsers running with different tokens and different permissions. I’ve opened up incognito here on the right, and I’m going to see what happens when we create a new token. And we’ll make sure to put in our key. For this one, we will remove “bar,” so he’s able to subscribe to “foo” but not to “bar.” Then copy that, and put it in the demo, and click “discover,” so it’s using the cookie and we’re gonna be using the same topics as in the original browser. Now he’s subscribed and, if I type in “foo” here that’s a target. Uh, I’m sorry, don’t need to do that. So “foo” here is set as the target, and if I click “publish,” it works.
So, now I’m going to update this token and allow it to publish to “bar.” Bar is a target that the regular Chrome window’s allowed to subscribe to, but it is not allowed in the token used by the incognito window. So, let’s grab that token and update it here, we’ll click discover to get the new cookie, and then we’ll type “bar” in here and publish. And so here this one was updated, I’ll do it a few times so you can see they’re coming through. But on this one, nothing is coming through. If I change it back to “foo,” then we start getting them in both.
So that’s how targets and authorization works, and how you can limit with the JWT token that somebody has, you can limit them to what they’re allowed to see. In my team’s example from the introduction video, I only want team members to see updates from their own teams. So, basically I could create a target Team One and target Team Two, and then allow certain users to subscribe to those targets and not to others.
[bright electronic music]
