Mercure-Hub: Iniziare

Come iniziare con Mercure-hub

👋 Benvenuti nella documentazione di Stackhero!

Stackhero offre una soluzione Mercure-Hub cloud pronta all'uso che fornisce numerosi vantaggi, tra cui:

  • Richieste e dimensioni dei messaggi illimitate.
  • Nome di dominio personalizzabile protetto con HTTPS (ad esempio, https://real-time.tua-azienda.com).
  • Aggiornamenti facili con un solo clic.
  • Prestazioni ottimali e sicurezza robusta grazie a una VM privata e dedicata.
  • Disponibile in 🇪🇺 Europa e 🇺🇸 USA.

Risparmia tempo e semplifica la tua vita: bastano solo 5 minuti per provare la soluzione di Mercure-Hub cloud hosting di Stackhero!

Cos'è Mercure-hub

Immaginate di avere un sito web che vende libri e volete mostrare lo stock disponibile in tempo reale.

Inviare dati dal back end al front end può essere complesso. Mercure-hub semplifica questo processo permettendovi di inviare dati direttamente ai browser dei clienti in pochi minuti. La parte migliore è che funziona con qualsiasi linguaggio di programmazione perché sfrutta il protocollo HTTP!

Come funziona Mercure-hub

Considerate uno scenario in cui un cliente sta visualizzando un libro con l'ID 1.

Sul front end, vi iscrivete al topic /books/1 su Mercure-hub utilizzando l'API Server-Sent Events (SSE), una funzionalità nativa di HTML5. Con circa 10 righe di codice JavaScript e senza bisogno di librerie esterne, questo approccio rimane sia semplice che efficiente.

Sul back end, quando un libro viene acquistato, inviate una richiesta HTTP a Mercure-hub per aggiornare lo stock. Ad esempio, se ci sono 7 libri con l'ID 1 e un utente ne acquista uno, lo stock aggiornato diventa 6.

Il vostro back end invia { stockCount: 6 } al topic /books/1 su Mercure-hub in modo che ogni utente che visualizza quel libro riceva immediatamente il conteggio dello stock aggiornato. Questo processo richiede solo una richiesta HTTP dal back end e poche righe di codice sul front end.

Questo principio può essere utilizzato per inviare dati dal server al client, tra client o anche tra server.

Iniziare con Mercure-hub

Sul lato client (il vostro front end), un semplice codice JavaScript che sfrutta l'API HTML5 SSE è tutto ciò di cui avete bisogno.

Nota: In questo esempio, l'abbonato non è autenticato. Per far funzionare questo esempio, dovete consentire abbonati anonimi sulla dashboard di Stackhero.

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

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

// Aggiungere i topic da ascoltare
url.searchParams.append('topic', `https://${endpoint}/users/1234`);
url.searchParams.append('topic', `https://${endpoint}/books/1`);

const eventSource = new EventSource(url);

// Il callback viene invocato ogni volta che viene pubblicato un aggiornamento
eventSource.onmessage = e => console.log(e);

Sul lato server (il vostro back end), quando volete inviare un aggiornamento, inviate semplicemente una richiesta POST all'API di Mercure-hub. Ecco un esempio utilizzando Node.js insieme alle librerie JsonWebToken e Request :

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

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

// Definire i dati da inviare
const data = {
  // Il topic dove i dati saranno inviati
  topic: `https://${endpoint}/books/1`,

  // I dati da inviare al topic
  data: JSON.stringify({
    available: false,
    date: new Date()
  })
};

// Generare il token bearer
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // Il token scade in un minuto
    noTimestamp: true // Non includere il timestamp 'emesso a' per evitare errori "Token usato prima di essere emesso"
  }
);

// Inviare i dati a Mercure-hub affinché distribuisca l'aggiornamento ai client
request.post(
  {
    url: `https://${endpoint}/.well-known/mercure`,
    auth: { bearer },
    form: data
  },
  (err, res) => err ? console.error(err) : console.log(res)
);

Ecco fatto! Ora avete un abbonato sul front end e un editore sul back end che lavorano insieme senza problemi.

Esempio di codice client Mercure-hub

Se volete testare Mercure-hub, potete consultare gli esempi di codice disponibili su https://github.com/stackhero-io/mercureHubGettingStarted.

Questi esempi funzionanti includono una semplice pagina front end e un server back end Node.js che dimostrano come Mercure funzioni in pratica.

Esempio semplice di comunicazione tra back end e front end con Mercure-hubEsempio semplice di comunicazione tra back end e front end con Mercure-hub

Autenticazione degli abbonati

Negli esempi precedenti, gli abbonati non erano autenticati e dovevate consentire "abbonati anonimi" sulla dashboard di Stackhero.

Per autenticare gli abbonati, generate un JWS (JSON Web Signature) utilizzando la 'Subscriber JWT key' definita nella dashboard di Stackhero. Il JWS viene poi inviato tramite cookie del browser o l'header authorization.

Poiché l'API Server-Sent Events non supporta le definizioni di header personalizzati, devono essere utilizzati i cookie. Tuttavia, l'uso dei cookie implica che il vostro server Mercure-hub e il client devono condividere lo stesso dominio (o sottodominio).

Se desiderate utilizzare SSE tra domini diversi, considerate un polyfill EventSource che consente le definizioni di header. Un'opzione è disponibile su https://github.com/Yaffle/EventSource.

Per prima cosa, generate un JWS per il vostro client sul vostro back end. Un esempio è disponibile in backend/subscriberJwsGenerator.js. Inserite semplicemente il vostro JWT di abbonato ed eseguite lo script con node subscriberJwsGenerator.js.

Poi, sul front end, nel file frontend/subscriberWithAuthorization.html, inserite il vostro endpoint e il JWS generato. Aprite il file nel vostro browser e Mercure-hub funzionerà ora con autenticazione!

Non dimenticate di deselezionare "Consenti abbonati anonimi" nella dashboard di Stackhero!