Mercure-Hub: Introducción

Cómo empezar con Mercure-hub

👋 ¡Bienvenido a la documentación de Stackhero!

Stackhero ofrece una solución Mercure-Hub cloud lista para usar que proporciona una serie de beneficios, incluyendo:

  • Solicitudes y tamaños de mensajes ilimitados.
  • Nombre de dominio personalizable asegurado con HTTPS (por ejemplo, https://real-time.su-empresa.com).
  • Actualizaciones sin esfuerzo con solo un clic.
  • Rendimiento óptimo y seguridad robusta impulsados por una VM privada y dedicada.
  • Disponible en 🇪🇺 Europa y 🇺🇸 USA.

Ahorre tiempo y simplifique su vida: solo toma 5 minutos probar la solución de Mercure-Hub cloud hosting de Stackhero!

¿Qué es Mercure-hub?

Imagine que tiene un sitio web que vende libros y desea mostrar el stock disponible en tiempo real.

Enviar datos desde el back end al front end puede ser complicado. Mercure-hub simplifica esto permitiéndole enviar datos directamente a los navegadores de los clientes en solo unos minutos. Lo mejor de todo es que funciona con cualquier lenguaje de programación porque utiliza el protocolo HTTP.

Cómo funciona Mercure-hub

Considere un escenario donde un cliente está viendo un libro con el ID 1.

En el front end, se suscribe al tema /books/1 en Mercure-hub utilizando la API Server-Sent Events (SSE), una característica nativa de HTML5. Con alrededor de 10 líneas de código JavaScript y sin necesidad de bibliotecas externas, este enfoque sigue siendo sencillo y eficiente.

En el back end, cuando se compra un libro, envía una solicitud HTTP a Mercure-hub para actualizar el stock. Por ejemplo, si hay 7 libros con el ID 1 y un usuario compra uno, el stock actualizado se convierte en 6.

Su back end envía { stockCount: 6 } al tema /books/1 en Mercure-hub para que cada usuario que vea ese libro reciba instantáneamente el recuento de stock actualizado. Este proceso solo requiere una solicitud HTTP desde el back end y unas pocas líneas de código en el front end.

Este principio se puede utilizar para enviar datos desde el servidor al cliente, entre clientes o incluso entre servidores.

Empezando con Mercure-hub

En el lado del cliente (su front end), solo necesita un simple código JavaScript que utilice la API HTML5 SSE.

Nota: En este ejemplo, el suscriptor no está autenticado. Para que este ejemplo funcione, debe permitir suscriptores anónimos en el panel de Stackhero.

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

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

// Añadir temas para escuchar
url.searchParams.append('topic', `https://${endpoint}/users/1234`);
url.searchParams.append('topic', `https://${endpoint}/books/1`);

const eventSource = new EventSource(url);

// El callback se invoca cada vez que se publica una actualización
eventSource.onmessage = e => console.log(e);

En el lado del servidor (su back end), cuando desea enviar una actualización, simplemente envíe una solicitud POST a la API de Mercure-hub. A continuación se muestra un ejemplo utilizando Node.js junto con las bibliotecas JsonWebToken y Request:

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

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

// Definir los datos a enviar
const data = {
  // El tema donde se enviarán los datos
  topic: `https://${endpoint}/books/1`,

  // Los datos a enviar al tema
  data: JSON.stringify({
    available: false,
    date: new Date()
  })
};

// Generar el token bearer
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // El token expira en un minuto
    noTimestamp: true // No incluir el timestamp 'emitido en' para evitar errores "Token usado antes de ser emitido"
  }
);

// Enviar los datos a Mercure-hub para que distribuya la actualización a los clientes
request.post(
  {
    url: `https://${endpoint}/.well-known/mercure`,
    auth: { bearer },
    form: data
  },
  (err, res) => err ? console.error(err) : console.log(res)
);

¡Eso es todo! Ahora tiene un suscriptor en el front end y un publicador en el back end trabajando juntos sin problemas.

Ejemplo de código cliente de Mercure-hub

Si desea probar Mercure-hub, puede revisar los ejemplos de código disponibles en https://github.com/stackhero-io/mercureHubGettingStarted.

Estos ejemplos funcionales incluyen una simple página de front end y un servidor back end Node.js que demuestran cómo funciona Mercure en la práctica.

Ejemplo simple de comunicación entre back end y front end con Mercure-hubEjemplo simple de comunicación entre back end y front end con Mercure-hub

Autenticación de suscriptores

En los ejemplos anteriores, los suscriptores no estaban autenticados y necesitaba permitir "suscriptores anónimos" en el panel de Stackhero.

Para autenticar a los suscriptores, genera un JWS (JSON Web Signature) utilizando la 'Subscriber JWT key' definida en el panel de Stackhero. El JWS se envía luego usando cookies del navegador o el encabezado authorization.

Dado que la API Server-Sent Events no admite definiciones de encabezados personalizados, se deben usar cookies. Sin embargo, el uso de cookies implica que su servidor Mercure-hub y su cliente deben compartir el mismo dominio (o subdominio).

Si desea usar SSE entre diferentes dominios, considere un polyfill de EventSource que permita definiciones de encabezados. Una opción está disponible en https://github.com/Yaffle/EventSource.

Primero, genere un JWS para su cliente en su back end. Un ejemplo está disponible en backend/subscriberJwsGenerator.js. Simplemente ingrese su JWT de suscriptor y ejecute el script usando node subscriberJwsGenerator.js.

Luego, en el front end, en el archivo frontend/subscriberWithAuthorization.html, complete su endpoint y el JWS generado. Abra el archivo en su navegador y Mercure-hub ahora funcionará con autenticación.

¡No olvide desmarcar "Permitir suscriptores anónimos" en el panel de Stackhero!