Mercure-Hub: Pierwsze kroki

Jak zacząć z Mercure-hub

👋 Witamy w dokumentacji Stackhero!

Stackhero oferuje gotowe do użycia rozwiązanie Mercure-Hub cloud, które zapewnia wiele korzyści, w tym:

  • Nieograniczone żądania i rozmiary wiadomości.
  • Dostosowywalna nazwa domeny zabezpieczona za pomocą HTTPS (na przykład, https://real-time.twoja-firma.com).
  • Łatwe aktualizacje za pomocą jednego kliknięcia.
  • Optymalna wydajność i solidne zabezpieczenia dzięki prywatnej i dedykowanej VM.
  • Dostępne w 🇪🇺 Europie i 🇺🇸 USA.

Oszczędzaj czas i upraszczaj sobie życie: wystarczy 5 minut, aby wypróbować rozwiązanie Mercure-Hub cloud hosting Stackhero!

Czym jest Mercure-hub

Wyobraź sobie, że masz stronę internetową sprzedającą książki i chcesz wyświetlać dostępny stan magazynowy w czasie rzeczywistym.

Przesyłanie danych z back endu do front endu może być wyzwaniem. Mercure-hub upraszcza to, umożliwiając wysyłanie danych bezpośrednio do przeglądarek klientów w zaledwie kilka minut. Najlepsze jest to, że działa z każdym językiem programowania, ponieważ wykorzystuje protokół HTTP!

Jak działa Mercure-hub

Rozważmy scenariusz, w którym klient przegląda książkę o ID 1.

Na front endzie subskrybujesz temat /books/1 na Mercure-hub, używając API Server-Sent Events (SSE), natywnej funkcji HTML5. Dzięki około 10 liniom kodu JavaScript i bez potrzeby zewnętrznych bibliotek, to podejście pozostaje zarówno proste, jak i efektywne.

Na back endzie, gdy książka zostaje zakupiona, wysyłasz żądanie HTTP do Mercure-hub, aby zaktualizować stan magazynowy. Na przykład, jeśli jest 7 książek o ID 1 i użytkownik kupuje jedną, zaktualizowany stan wynosi 6.

Twój back end wysyła { stockCount: 6 } do tematu /books/1 na Mercure-hub, aby każdy użytkownik przeglądający tę książkę natychmiast otrzymał zaktualizowany stan magazynowy. Proces ten wymaga tylko żądania HTTP z back endu i kilku linii kodu na front endzie.

Ta zasada może być używana do przesyłania danych z serwera do klienta, między klientami, a nawet między serwerami.

Pierwsze kroki z Mercure-hub

Po stronie klienta (twój front end), prosty kod JavaScript wykorzystujący API HTML5 SSE to wszystko, czego potrzebujesz.

Uwaga: W tym przykładzie subskrybent nie jest uwierzytelniony. Aby ten przykład działał, musisz zezwolić na anonimowych subskrybentów w panelu Stackhero.

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

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

// Dodaj tematy do nasłuchiwania
url.searchParams.append('topic', `https://${endpoint}/users/1234`);
url.searchParams.append('topic', `https://${endpoint}/books/1`);

const eventSource = new EventSource(url);

// Callback jest wywoływany za każdym razem, gdy publikowana jest aktualizacja
eventSource.onmessage = e => console.log(e);

Po stronie serwera (twój back end), gdy chcesz wysłać aktualizację, po prostu wyślij żądanie POST do API Mercure-hub. Poniżej znajduje się przykład użycia Node.js wraz z bibliotekami JsonWebToken i Request:

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

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

// Zdefiniuj dane do wysłania
const data = {
  // Temat, do którego dane będą przesyłane
  topic: `https://${endpoint}/books/1`,

  // Dane do wysłania do tematu
  data: JSON.stringify({
    available: false,
    date: new Date()
  })
};

// Generuj token bearer
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // Token wygasa po jednej minucie
    noTimestamp: true // Nie dołączaj znacznika czasu 'wydany o', aby uniknąć błędów "Token użyty przed wydaniem"
  }
);

// Wyślij dane do Mercure-hub, aby rozesłał aktualizację do klientów
request.post(
  {
    url: `https://${endpoint}/.well-known/mercure`,
    auth: { bearer },
    form: data
  },
  (err, res) => err ? console.error(err) : console.log(res)
);

I to wszystko! Masz teraz subskrybenta na front endzie i wydawcę na back endzie, którzy współpracują bezproblemowo.

Przykład kodu klienta Mercure-hub

Jeśli chcesz przetestować Mercure-hub, możesz przejrzeć przykłady kodu dostępne na https://github.com/stackhero-io/mercureHubGettingStarted.

Te działające przykłady obejmują prostą stronę front end i serwer back end Node.js, które demonstrują, jak Mercure działa w praktyce.

Prosty przykład komunikacji między back endem a front endem z Mercure-hubProsty przykład komunikacji między back endem a front endem z Mercure-hub

Uwierzytelnianie subskrybentów

W wcześniejszych przykładach subskrybenci nie byli uwierzytelnieni i musiałeś zezwolić na "anonimowych subskrybentów" w panelu Stackhero.

Aby uwierzytelnić subskrybentów, generujesz JWS (JSON Web Signature) używając 'Subscriber JWT key' zdefiniowanego w panelu Stackhero. JWS jest następnie wysyłany za pomocą ciasteczek przeglądarki lub nagłówka authorization.

Ponieważ API Server-Sent Events nie obsługuje definicji niestandardowych nagłówków, muszą być używane ciasteczka. Jednak użycie ciasteczek oznacza, że twój serwer Mercure-hub i klient muszą dzielić tę samą domenę (lub subdomenę).

Jeśli chcesz używać SSE między różnymi domenami, rozważ użycie polyfill EventSource, który pozwala na definicje nagłówków. Jedna z opcji jest dostępna na https://github.com/Yaffle/EventSource.

Najpierw wygeneruj JWS dla swojego klienta na swoim back endzie. Przykład jest dostępny w backend/subscriberJwsGenerator.js. Wprowadź po prostu swój JWT subskrybenta i uruchom skrypt za pomocą node subscriberJwsGenerator.js.

Następnie, na front endzie, w pliku frontend/subscriberWithAuthorization.html, wypełnij swój endpoint i wygenerowany JWS. Otwórz plik w przeglądarce i Mercure-hub będzie teraz działać z uwierzytelnianiem!

Nie zapomnij odznaczyć "Zezwól na anonimowych subskrybentów" w panelu Stackhero!