Mercure-Hub: Erste Schritte

Wie man mit Mercure-hub beginnt

👋 Willkommen bei der Stackhero-Dokumentation!

Stackhero bietet eine einsatzbereite Mercure-Hub Cloud Lösung, die zahlreiche Vorteile bietet, darunter:

• Unbegrenzte Anfragen und Nachrichtengrößen.
• Anpassbarer Domainname gesichert mit HTTPS (zum Beispiel, https://real-time.ihre-firma.com).
• Mühelose Updates mit nur einem Klick.
• Optimale Leistung und robuste Sicherheit durch eine private und dedizierte VM.
• Verfügbar in 🇪🇺 Europa und 🇺🇸 USA.

Sparen Sie Zeit und vereinfachen Sie Ihr Leben: Es dauert nur 5 Minuten, um die Mercure-Hub Cloud Hosting Lösung von Stackhero auszuprobieren!

Was ist Mercure-hub

Stellen Sie sich vor, Sie haben eine Website, die Bücher verkauft, und Sie möchten den verfügbaren Bestand in Echtzeit anzeigen.

Daten vom Backend zum Frontend zu übertragen kann herausfordernd sein. Mercure-hub vereinfacht dies, indem es Ihnen ermöglicht, Daten direkt an die Browser der Kunden zu senden – und das in nur wenigen Minuten. Das Beste daran ist, dass es mit jeder Programmiersprache funktioniert, da es das HTTP-Protokoll nutzt!

Wie Mercure-hub funktioniert

Betrachten Sie ein Szenario, in dem ein Kunde ein Buch mit der ID 1 ansieht.

Im Frontend abonnieren Sie das Thema /books/1 auf Mercure-hub mithilfe der Server-Sent Events (SSE) API, einer nativen HTML5-Funktion. Mit etwa 10 Zeilen JavaScript-Code und ohne externe Bibliotheken bleibt dieser Ansatz sowohl einfach als auch effizient.

Im Backend, wenn ein Buch gekauft wird, senden Sie eine HTTP-Anfrage an Mercure-hub, um den Bestand zu aktualisieren. Zum Beispiel, wenn es 7 Bücher mit der ID 1 gibt und ein Benutzer eines kauft, wird der aktualisierte Bestand 6.

Ihr Backend sendet { stockCount: 6 } an das Thema /books/1 auf Mercure-hub, sodass jeder Benutzer, der dieses Buch ansieht, sofort die aktualisierte Bestandszahl erhält. Dieser Prozess erfordert nur eine HTTP-Anfrage vom Backend und nur wenige Zeilen Code im Frontend.

Dieses Prinzip kann verwendet werden, um Daten vom Server zum Client, zwischen Clients oder sogar zwischen Servern zu übertragen.

Erste Schritte mit Mercure-hub

Auf der Clientseite (Ihr Frontend) benötigen Sie nur einfachen JavaScript-Code, der die HTML5 SSE API nutzt.

Hinweis: In diesem Beispiel ist der Abonnent nicht authentifiziert. Damit dieses Beispiel funktioniert, müssen Sie anonyme Abonnenten im Stackhero-Dashboard zulassen.

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

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

// Themen hinzufügen, die abgehört werden sollen
url.searchParams.append('topic', `https://${endpoint}/users/1234`);
url.searchParams.append('topic', `https://${endpoint}/books/1`);

const eventSource = new EventSource(url);

// Der Callback wird jedes Mal aufgerufen, wenn ein Update veröffentlicht wird
eventSource.onmessage = e => console.log(e);

Auf der Serverseite (Ihr Backend), wenn Sie ein Update versenden möchten, senden Sie einfach eine POST-Anfrage an die Mercure-hub API. Unten ist ein Beispiel mit Node.js und den Bibliotheken JsonWebToken und Request:

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

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

// Definieren Sie die Daten, die gesendet werden sollen
const data = {
  // Das Thema, an das die Daten gesendet werden
  topic: `https://${endpoint}/books/1`,

  // Die Daten, die an das Thema gesendet werden sollen
  data: JSON.stringify({
    available: false,
    date: new Date()
  })
};

// Erzeugen Sie das Bearer-Token
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // Token läuft in einer Minute ab
    noTimestamp: true // Kein 'issued at'-Zeitstempel, um "Token used before issued"-Fehler zu vermeiden
  }
);

// Senden Sie die Daten an Mercure-hub, damit es das Update an die Clients verteilt
request.post(
  {
    url: `https://${endpoint}/.well-known/mercure`,
    auth: { bearer },
    form: data
  },
  (err, res) => err ? console.error(err) : console.log(res)
);

Das war's! Sie haben jetzt einen Abonnenten im Frontend und einen Publisher im Backend, die nahtlos zusammenarbeiten.

Mercure-hub Client-Code-Beispiel

Wenn Sie Mercure-hub testen möchten, können Sie die verfügbaren Codebeispiele auf https://github.com/stackhero-io/mercureHubGettingStarted überprüfen.

Diese funktionierenden Beispiele beinhalten eine einfache Frontend-Seite und einen Node.js Backend-Server, die zeigen, wie Mercure in der Praxis funktioniert.

Einfaches Beispiel für die Kommunikation zwischen Backend und Frontend mit Mercure-hub

Authentifizierung von Abonnenten

In den vorherigen Beispielen waren die Abonnenten nicht authentifiziert und Sie mussten "anonyme Abonnenten" im Stackhero-Dashboard zulassen.

Um Abonnenten zu authentifizieren, generieren Sie ein JWS (JSON Web Signature) mit dem im Stackhero-Dashboard definierten 'Subscriber JWT key'. Das JWS wird dann entweder über Browser-Cookies oder den authorization-Header gesendet.

Da die Server-Sent Events API keine benutzerdefinierten Header-Definitionen unterstützt, müssen Cookies verwendet werden. Die Verwendung von Cookies bedeutet jedoch, dass Ihr Mercure-hub-Server und Ihr Client dieselbe Domain (oder Subdomain) teilen müssen.

Wenn Sie SSE über verschiedene Domains hinweg verwenden möchten, ziehen Sie ein EventSource-Polyfill in Betracht, das Header-Definitionen ermöglicht. Eine Option ist verfügbar unter https://github.com/Yaffle/EventSource.

Zuerst generieren Sie ein JWS für Ihren Client auf Ihrer Serverseite. Ein Beispiel ist in backend/subscriberJwsGenerator.js verfügbar. Geben Sie einfach Ihr Subscriber JWT ein und führen Sie das Skript mit node subscriberJwsGenerator.js aus.

Dann füllen Sie im Frontend in der Datei frontend/subscriberWithAuthorization.html Ihren Endpoint und das generierte JWS aus. Öffnen Sie die Datei in Ihrem Browser und Mercure-hub funktioniert nun mit Authentifizierung!

Vergessen Sie nicht, "Anonyme Abonnenten zulassen" im Stackhero-Dashboard zu deaktivieren!