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 tailles de messages illimitées.
  • Nom de domaine personnalisable sécurisé avec HTTPS (par exemple, https://real-time.votre-entreprise.com).
  • Mises à jour faciles en un clic.
  • Performance optimale et sécurité robuste 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 cela en vous permettant d'envoyer des données directement aux navigateurs des clients en seulement quelques minutes. Le meilleur dans tout ça, c'est que cela fonctionne avec n'importe quel langage de programmation grâce à l'utilisation du protocole HTTP !

Comment fonctionne Mercure-hub

Prenons un scénario où un client consulte un livre avec l'ID 1.

Sur le front end, vous vous abonnez au topic /books/1 sur Mercure-hub en utilisant l'API Server-Sent Events (SSE), une fonctionnalité native de HTML5. Avec environ 10 lignes de code JavaScript et sans besoin de bibliothèques externes, cette approche reste à la fois simple et efficace.

Sur le back end, lorsqu'un livre est acheté, vous envoyez une requête HTTP à Mercure-hub pour mettre à jour le stock. Par exemple, s'il y a 7 livres avec l'ID 1 et qu'un utilisateur en achète un, le stock mis à jour devient 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 le stock mis à jour. Ce processus nécessite seulement une requête HTTP depuis le back end et quelques lignes de code sur le front end.

Ce principe peut être utilisé pour pousser des données du serveur au 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 HTML5 SSE est tout ce dont vous avez besoin.

Remarque : Dans cet exemple, le souscripteur n'est pas authentifié. Pour que cet exemple fonctionne, vous devez autoriser les souscripteurs anonymes sur le tableau de bord Stackhero.

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

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

// Ajouter des 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 invoqué à 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, envoyez simplement une requête POST à l'API Mercure-hub. Voici un exemple utilisant Node.js avec les bibliothèques JsonWebToken et Request :

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

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

// Définir les données à envoyer
const data = {
  // Le topic où 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érer le token bearer
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // Le token expire dans une minute
    noTimestamp: true // Ne pas inclure le timestamp 'émis à' pour éviter les erreurs "Token utilisé avant d'être émis"
  }
);

// Envoyer les données à Mercure-hub pour qu'il les distribue 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 souscripteur sur le front end et un éditeur sur le back end qui fonctionnent ensemble de manière 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 simple page front end et un serveur back end Node.js qui démontrent comment Mercure fonctionne en pratique.

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 souscripteurs

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

Pour authentifier les souscripteurs, 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 envoyé via des cookies du navigateur ou l'en-tête authorization.

Étant donné que l'API Server-Sent Events ne prend pas en charge les définitions d'en-têtes personnalisés, les cookies doivent être utilisés. Cependant, l'utilisation de cookies implique que votre serveur Mercure-hub et votre client doivent partager le même domaine (ou sous-domaine).

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

Tout d'abord, générez un JWS pour votre client sur votre back end. Un exemple est disponible dans backend/subscriberJwsGenerator.js. Entrez simplement votre JWT de souscripteur et exécutez le script avec node subscriberJwsGenerator.js.

Ensuite, sur le front end, dans le fichier frontend/subscriberWithAuthorization.html, remplissez 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 souscripteurs anonymes" dans le tableau de bord Stackhero !