Mercure-Hub: Introdução

Como começar com Mercure-hub

👋 Bem-vindo à documentação da Stackhero!

A Stackhero oferece uma solução Mercure-Hub cloud pronta a usar que proporciona uma série de benefícios, incluindo:

  • Pedidos e tamanhos de mensagens ilimitados.
  • Nome de domínio personalizável seguro com HTTPS (por exemplo, https://real-time.sua-empresa.com).
  • Atualizações fáceis com apenas um clique.
  • Desempenho ótimo e segurança robusta alimentados por uma VM privada e dedicada.
  • Disponível na 🇪🇺 Europa e 🇺🇸 EUA.

Poupe tempo e simplifique a sua vida: são necessários apenas 5 minutos para experimentar a solução Mercure-Hub cloud hosting da Stackhero!

O que é o Mercure-hub

Imagine que tem um site que vende livros e quer mostrar o stock disponível em tempo real.

Enviar dados do back end para o front end pode ser desafiador. O Mercure-hub simplifica isso, permitindo que envie dados diretamente para os navegadores dos clientes em apenas alguns minutos. A melhor parte é que funciona com qualquer linguagem de programação porque utiliza o protocolo HTTP!

Como funciona o Mercure-hub

Considere um cenário onde um cliente está a visualizar um livro com o ID 1.

No front end, subscreve ao tópico /books/1 no Mercure-hub usando a API Server-Sent Events (SSE), uma funcionalidade nativa do HTML5. Com cerca de 10 linhas de código JavaScript e sem necessidade de bibliotecas externas, esta abordagem mantém-se simples e eficiente.

No back end, quando um livro é comprado, envia um pedido HTTP para o Mercure-hub para atualizar o stock. Por exemplo, se houver 7 livros com o ID 1 e um utilizador comprar um, o stock atualizado passa a ser 6.

O seu back end envia { stockCount: 6 } para o tópico /books/1 no Mercure-hub para que cada utilizador que visualize esse livro receba instantaneamente a contagem de stock atualizada. Este processo requer apenas um pedido HTTP do back end e apenas algumas linhas de código no front end.

Este princípio pode ser usado para enviar dados do servidor para o cliente, entre clientes, ou até entre servidores.

Começar com o Mercure-hub

No lado do cliente (o seu front end), um simples código JavaScript que utiliza a API HTML5 SSE é tudo o que precisa.

Nota: Neste exemplo, o subscritor não está autenticado. Para que este exemplo funcione, deve permitir subscritores anónimos no painel de controlo do Stackhero.

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

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

// Adicionar tópicos para ouvir
url.searchParams.append('topic', `https://${endpoint}/users/1234`);
url.searchParams.append('topic', `https://${endpoint}/books/1`);

const eventSource = new EventSource(url);

// O callback é invocado cada vez que uma atualização é publicada
eventSource.onmessage = e => console.log(e);

No lado do servidor (o seu back end), quando quiser enviar uma atualização, basta enviar um pedido POST para a API do Mercure-hub. Abaixo está um exemplo usando Node.js juntamente com as bibliotecas JsonWebToken e Request :

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

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

// Definir os dados a enviar
const data = {
  // O tópico onde os dados serão enviados
  topic: `https://${endpoint}/books/1`,

  // Os dados a serem enviados para o tópico
  data: JSON.stringify({
    available: false,
    date: new Date()
  })
};

// Gerar o token bearer
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // O token expira em um minuto
    noTimestamp: true // Não incluir o timestamp 'emitido em' para evitar erros "Token usado antes de ser emitido"
  }
);

// Enviar os dados para o Mercure-hub para que distribua a atualização aos clientes
request.post(
  {
    url: `https://${endpoint}/.well-known/mercure`,
    auth: { bearer },
    form: data
  },
  (err, res) => err ? console.error(err) : console.log(res)
);

E pronto! Agora tem um subscritor no front end e um publicador no back end a trabalhar juntos sem problemas.

Exemplo de código cliente Mercure-hub

Se quiser testar o Mercure-hub, pode rever os exemplos de código disponíveis em https://github.com/stackhero-io/mercureHubGettingStarted.

Estes exemplos funcionais incluem uma simples página front end e um servidor back end Node.js que demonstram como o Mercure funciona na prática.

Exemplo simples de comunicação entre back end e front end com Mercure-hubExemplo simples de comunicação entre back end e front end com Mercure-hub

Autenticação de subscritores

Nos exemplos anteriores, os subscritores não estavam autenticados e precisava de permitir "subscritores anónimos" no painel de controlo do Stackhero.

Para autenticar subscritores, gera um JWS (JSON Web Signature) usando a 'Subscriber JWT key' definida no painel de controlo do Stackhero. O JWS é então enviado usando cookies do navegador ou o cabeçalho authorization.

Dado que a API Server-Sent Events não suporta definições de cabeçalhos personalizados, os cookies devem ser usados. No entanto, usar cookies implica que o seu servidor Mercure-hub e o cliente precisam de partilhar o mesmo domínio (ou subdomínio).

Se desejar usar SSE entre diferentes domínios, considere um polyfill EventSource que permita definições de cabeçalhos. Uma opção está disponível em https://github.com/Yaffle/EventSource.

Primeiro, gere um JWS para o seu cliente no seu back end. Um exemplo está disponível em backend/subscriberJwsGenerator.js. Basta inserir o seu JWT de subscritor e executar o script usando node subscriberJwsGenerator.js.

Depois, no front end, no ficheiro frontend/subscriberWithAuthorization.html, preencha o seu endpoint e o JWS gerado. Abra o ficheiro no seu navegador e o Mercure-hub funcionará agora com autenticação!

Não se esqueça de desmarcar "Permitir subscritores anónimos" no painel de controlo do Stackhero!