Mercure-Hub: Premiers pas

Comment débuter avec Mercure-hub

👋 Bienvenue sur la documentation de Stackhero !

Stackhero propose une solution Mercure-Hub cloud prête à l'emploi qui offre de nombreux avantages, notamment :

  • Requêtes et taille des messages illimitées.
  • Nom de domaine personnalisable sécurisé avec HTTPS (par exemple, https://real-time.votre-entreprise.com).
  • Mises à jour simplifiées en un clic.
  • Performance optimale et sécurité renforcée grâce à une VM privée et dédiée.
  • Disponible en 🇪🇺 Europe et 🇺🇸 USA.

Gagnez du temps et simplifiez-vous la vie : il suffit de 5 minutes pour essayer la solution Mercure-Hub cloud hosting de Stackhero !

Qu'est-ce que Mercure-hub

Imaginez que vous avez un site web qui vend des livres et que vous souhaitez afficher le stock disponible en temps réel.

Pousser des données du back end vers le front end peut être complexe. Mercure-hub simplifie ce processus en vous permettant d'envoyer des données directement dans le navigateur de vos clients en quelques minutes. Le plus intéressant, c'est que cela fonctionne avec n'importe quel langage de programmation car il s'appuie sur le protocole HTTP !

Comment fonctionne Mercure-hub

Prenons le cas d'un client qui consulte un livre avec l'ID 1.

Côté front end, vous vous abonnez au topic /books/1 sur Mercure-hub en utilisant l'API Server-Sent Events (SSE), une fonctionnalité native d'HTML5. Avec une dizaine de lignes de code JavaScript et sans aucune bibliothèque externe, cette approche reste simple et efficace.

Côté back end, lorsqu'un livre est acheté, vous envoyez une requête HTTP à Mercure-hub pour mettre à jour le stock. Par exemple, s'il reste 7 livres avec l'ID 1 et qu'un utilisateur en achète un, le stock passe à 6.

Votre back end envoie { stockCount: 6 } au topic /books/1 sur Mercure-hub afin que chaque utilisateur consultant ce livre reçoive instantanément la mise à jour du stock. Ce processus nécessite uniquement une requête HTTP côté back end et quelques lignes de code côté front end.

Ce principe peut être utilisé pour pousser des données du serveur vers le client, entre clients, ou même entre serveurs.

Premiers pas avec Mercure-hub

Côté client (votre front end), un simple code JavaScript utilisant l'API SSE d'HTML5 suffit.

Note: Dans cet exemple, l'abonné n'est pas authentifié. Pour que cet exemple fonctionne, vous devez autoriser les abonnés anonymes sur le tableau de bord Stackhero.

const endpoint = '<XXXXXX>.stackhero-network.com';

const url = new URL('https://' + endpoint + '/.well-known/mercure');

// Ajoutez les topics à écouter
url.searchParams.append('topic', `https://${endpoint}/users/1234`);
url.searchParams.append('topic', `https://${endpoint}/books/1`);

const eventSource = new EventSource(url);

// Le callback est appelé à chaque fois qu'une mise à jour est publiée
eventSource.onmessage = e => console.log(e);

Côté serveur (votre back end), lorsque vous souhaitez envoyer une mise à jour, il suffit d'envoyer une requête POST à l'API Mercure-hub. Voici un exemple utilisant Node.js avec les librairies JsonWebToken et Request :

const jwt = require('jsonwebtoken');
const request = require('request');

const endpoint = '<XXXXXX>.stackhero-network.com';
const publisherJwtKey = '<your publisher JWT key>';

// Définissez les données à envoyer
const data = {
  // Le topic sur lequel les données seront poussées
  topic: `https://${endpoint}/books/1`,

  // Les données à envoyer au topic
  data: JSON.stringify({
    available: false,
    date: new Date()
  })
};

// Générez le bearer token
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // Le token expire en une minute
    noTimestamp: true // N'incluez pas le timestamp 'issued at' pour éviter les erreurs "Token used before issued"
  }
);

// Envoyez les données à Mercure-hub pour qu'il diffuse la mise à jour aux clients
request.post(
  {
    url: `https://${endpoint}/.well-known/mercure`,
    auth: { bearer },
    form: data
  },
  (err, res) => err ? console.error(err) : console.log(res)
);

Et voilà ! Vous avez maintenant un abonné côté front end et un éditeur côté back end qui fonctionnent ensemble de façon fluide.

Exemple de code client Mercure-hub

Si vous souhaitez tester Mercure-hub, vous pouvez consulter les exemples de code disponibles sur https://github.com/stackhero-io/mercureHubGettingStarted.

Ces exemples fonctionnels incluent une page front end simple et un serveur back end Node.js qui illustrent concrètement le fonctionnement de Mercure.

Exemple simple de communication entre back end et front end avec Mercure-hubExemple simple de communication entre back end et front end avec Mercure-hub

Authentification des abonnés

Dans les exemples précédents, les abonnés n'étaient pas authentifiés et vous deviez autoriser les "abonnés anonymes" sur le tableau de bord Stackhero.

Pour authentifier les abonnés, vous générez un JWS (JSON Web Signature) en utilisant la 'Subscriber JWT key' définie dans le tableau de bord Stackhero. Le JWS est ensuite transmis via les cookies du navigateur ou l'en-tête authorization.

Comme l'API Server-Sent Events ne permet pas de définir des en-têtes personnalisés, il faut utiliser les cookies. Cependant, l'utilisation des cookies implique que votre serveur Mercure-hub et votre client partagent le même domaine (ou sous-domaine).

Si vous souhaitez utiliser SSE entre différents domaines, envisagez un polyfill EventSource qui permet de définir des en-têtes. Une option est disponible sur https://github.com/Yaffle/EventSource.

Commencez par générer un JWS pour votre client côté serveur. Un exemple est disponible dans backend/subscriberJwsGenerator.js. Il suffit de renseigner votre JWT abonné et d'exécuter le script avec node subscriberJwsGenerator.js.

Ensuite, côté front end, dans le fichier frontend/subscriberWithAuthorization.html, renseignez votre endpoint et le JWS généré. Ouvrez le fichier dans votre navigateur et Mercure-hub fonctionnera désormais avec authentification !

N'oubliez pas de décocher "Autoriser les abonnés anonymes" dans le tableau de bord Stackhero !