Mercure-Hub: Aan de slag

Hoe te beginnen met Mercure-hub

👋 Welkom bij de Stackhero-documentatie!

Stackhero biedt een kant-en-klare Mercure-Hub cloud oplossing die tal van voordelen biedt, waaronder:

  • Onbeperkte verzoeken en berichtgroottes.
  • Aanpasbare domeinnaam beveiligd met HTTPS (bijvoorbeeld, https://real-time.uw-bedrijf.com).
  • Moeiteloze updates met slechts één klik.
  • Optimale prestaties en robuuste beveiliging aangedreven door een privé en dedicated VM.
  • Beschikbaar in 🇪🇺 Europa en 🇺🇸 USA.

Bespaar tijd en vereenvoudig uw leven: het kost slechts 5 minuten om de Mercure-Hub cloud hosting oplossing van Stackhero te proberen!

Wat is Mercure-hub

Stel je voor dat je een website hebt die boeken verkoopt en je wilt de beschikbare voorraad in realtime weergeven.

Gegevens van de back-end naar de front-end pushen kan uitdagend zijn. Mercure-hub vereenvoudigt dit door je in staat te stellen gegevens direct naar de browsers van klanten te sturen in slechts enkele minuten. Het beste is dat het werkt met elke programmeertaal omdat het gebruikmaakt van het HTTP-protocol!

Hoe Mercure-hub werkt

Overweeg een scenario waarin een klant een boek met ID 1 bekijkt.

Aan de front-end abonneer je je op het onderwerp /books/1 op Mercure-hub met behulp van de Server-Sent Events (SSE) API, een native HTML5-functie. Met ongeveer 10 regels JavaScript-code en zonder externe bibliotheken blijft deze aanpak zowel eenvoudig als efficiënt.

Aan de back-end, wanneer een boek wordt gekocht, stuur je een HTTP-verzoek naar Mercure-hub om de voorraad bij te werken. Bijvoorbeeld, als er 7 boeken met ID 1 zijn en een gebruiker er een koopt, wordt de bijgewerkte voorraad 6.

Je back-end stuurt { stockCount: 6 } naar het onderwerp /books/1 op Mercure-hub zodat elke gebruiker die dat boek bekijkt onmiddellijk de bijgewerkte voorraad ontvangt. Dit proces vereist slechts een HTTP-verzoek van de back-end en slechts enkele regels code aan de front-end.

Dit principe kan worden gebruikt om gegevens van de server naar de client te pushen, tussen clients, of zelfs tussen servers.

Aan de slag met Mercure-hub

Aan de clientzijde (je front-end) is eenvoudige JavaScript-code die gebruikmaakt van de HTML5 SSE API alles wat je nodig hebt.

Opmerking: In dit voorbeeld is de abonnee niet geauthenticeerd. Om dit voorbeeld te laten werken, moet je anonieme abonnees toestaan op het Stackhero-dashboard.

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

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

// Voeg onderwerpen toe om naar te luisteren
url.searchParams.append('topic', `https://${endpoint}/users/1234`);
url.searchParams.append('topic', `https://${endpoint}/books/1`);

const eventSource = new EventSource(url);

// De callback wordt aangeroepen elke keer dat een update wordt gepubliceerd
eventSource.onmessage = e => console.log(e);

Aan de serverzijde (je back-end), wanneer je een update wilt verzenden, stuur je eenvoudig een POST-verzoek naar de Mercure-hub API. Hieronder is een voorbeeld met Node.js samen met de JsonWebToken en Request bibliotheken:

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

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

// Definieer de gegevens om te verzenden
const data = {
  // Het onderwerp waar de gegevens naar worden gepusht
  topic: `https://${endpoint}/books/1`,

  // De gegevens die naar het onderwerp worden verzonden
  data: JSON.stringify({
    available: false,
    date: new Date()
  })
};

// Genereer de bearer token
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // Token verloopt in één minuut
    noTimestamp: true // Geen 'uitgegeven op' tijdstempel opnemen om "Token gebruikt voordat uitgegeven" fouten te voorkomen
  }
);

// Stuur de gegevens naar Mercure-hub zodat het de update naar clients verzendt
request.post(
  {
    url: `https://${endpoint}/.well-known/mercure`,
    auth: { bearer },
    form: data
  },
  (err, res) => err ? console.error(err) : console.log(res)
);

Dat is alles! Je hebt nu een abonnee aan de front-end en een uitgever aan de back-end die naadloos samenwerken.

Mercure-hub client code voorbeeld

Als je Mercure-hub wilt testen, kun je de codevoorbeelden bekijken die beschikbaar zijn op https://github.com/stackhero-io/mercureHubGettingStarted.

Deze werkende voorbeelden omvatten een eenvoudige front-end pagina en een Node.js back-end server die laten zien hoe Mercure in de praktijk werkt.

Eenvoudig voorbeeld van communicatie tussen back-end en front-end met Mercure-hubEenvoudig voorbeeld van communicatie tussen back-end en front-end met Mercure-hub

Authenticatie van abonnees

In de eerdere voorbeelden waren abonnees niet geauthenticeerd en moest je "anonieme abonnees" toestaan op het Stackhero-dashboard.

Om abonnees te authenticeren, genereer je een JWS (JSON Web Signature) met behulp van de 'Subscriber JWT key' die is gedefinieerd in het Stackhero-dashboard. De JWS wordt vervolgens verzonden met behulp van browsercookies of de authorization header.

Aangezien de Server-Sent Events API geen aangepaste headerdefinities ondersteunt, moeten cookies worden gebruikt. Het gebruik van cookies impliceert echter dat je Mercure-hub server en client hetzelfde domein (of subdomein) moeten delen.

Als je SSE over verschillende domeinen wilt gebruiken, overweeg dan een EventSource polyfill die headerdefinities toestaat. Een optie is beschikbaar op https://github.com/Yaffle/EventSource.

Genereer eerst een JWS voor je client aan je serverzijde. Een voorbeeld is beschikbaar in backend/subscriberJwsGenerator.js. Voer eenvoudig je subscriber JWT in en voer het script uit met node subscriberJwsGenerator.js.

Vervolgens, aan de front-end, in het bestand frontend/subscriberWithAuthorization.html, vul je je endpoint en de gegenereerde JWS in. Open het bestand in je browser en Mercure-hub werkt nu met authenticatie!

Vergeet niet "Allow anonymous subscribers" uit te vinken in het Stackhero-dashboard!