Mercure-Hub: はじめに

Mercure-hubの始め方

👋 Stackheroのドキュメントへようこそ！

Stackheroは、数多くの利点を提供するMercure-Hubクラウドソリューションを提供しています。

  • 無制限のリクエストとメッセージサイズ。
  • HTTPSで保護されたカスタマイズ可能なドメイン名（例: https://real-time.your-company.com）。
  • ワンクリックで簡単に更新。
  • プライベートで専用のVMによる最適なパフォーマンスと強力なセキュリティ。
  • 🇪🇺 ヨーロッパと🇺🇸 アメリカで利用可能。

時間を節約し、生活を簡素化：StackheroのMercure-Hubクラウドホスティングソリューションを試すのに5分しかかかりません！

Mercure-hubとは

本を販売するウェブサイトがあり、在庫をリアルタイムで表示したいとします。

バックエンドからフロントエンドにデータをプッシュするのは難しいことがあります。Mercure-hubは、データを数分で顧客のブラウザに直接送信できるようにすることで、これを簡素化します。最も良い点は、HTTPプロトコルを活用しているため、どのプログラミング言語でも動作することです！

Mercure-hubの仕組み

顧客がID 1の本を閲覧しているシナリオを考えてみましょう。

フロントエンドでは、HTML5のネイティブ機能であるServer-Sent Events (SSE) APIを使用して、Mercure-hubのトピック/books/1にサブスクライブします。約10行のJavaScriptコードで、外部ライブラリを必要とせず、このアプローチはシンプルで効率的です。

バックエンドでは、本が購入されたときに、在庫を更新するためにMercure-hubにHTTPリクエストを送信します。例えば、ID 1の本が7冊あり、ユーザーが1冊購入した場合、更新された在庫は6になります。

バックエンドは{ stockCount: 6 }をMercure-hubのトピック/books/1に送信し、その本を閲覧しているすべてのユーザーが即座に更新された在庫数を受け取ります。このプロセスは、バックエンドからのHTTPリクエストとフロントエンドの数行のコードだけで済みます。

この原則は、サーバーからクライアント、クライアント間、またはサーバー間でデータをプッシュするために使用できます。

Mercure-hubの始め方

クライアント側（フロントエンド）では、HTML5 SSE APIを活用したシンプルなJavaScriptコードが必要です。

注: この例では、サブスクライバーは認証されていません。この例を機能させるには、Stackheroダッシュボードで匿名サブスクライバーを許可する必要があります。

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

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

// リッスンするトピックを追加
url.searchParams.append('topic', `https://${endpoint}/users/1234`);
url.searchParams.append('topic', `https://${endpoint}/books/1`);

const eventSource = new EventSource(url);

// 更新が公開されるたびにコールバックが呼び出されます
eventSource.onmessage = e => console.log(e);

サーバー側（バックエンド）では、更新を送信したいときに、Mercure-hub APIにPOSTリクエストを送信するだけです。以下は、Node.jsとJsonWebTokenおよびRequestライブラリを使用した例です。

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

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

// 送信するデータを定義
const data = {
  // データがプッシュされるトピック
  topic: `https://${endpoint}/books/1`,

  // トピックに送信されるデータ
  data: JSON.stringify({
    available: false,
    date: new Date()
  })
};

// ベアラートークンを生成
const bearer = jwt.sign(
  { mercure: { publish: [ data.topic ] } },
  publisherJwtKey,
  {
    expiresIn: 60, // トークンは1分で期限切れ
    noTimestamp: true // "Token used before issued"エラーを避けるために'発行時'タイムスタンプを含めない
  }
);

// Mercure-hubにデータを送信して、クライアントに更新を配信
request.post(
  {
    url: `https://${endpoint}/.well-known/mercure`,
    auth: { bearer },
    form: data
  },
  (err, res) => err ? console.error(err) : console.log(res)
);

これで完了です！フロントエンドにサブスクライバーがあり、バックエンドにパブリッシャーがスムーズに連携しています。

Mercure-hubクライアントコードの例

Mercure-hubをテストしたい場合は、https://github.com/stackhero-io/mercureHubGettingStartedで利用可能なコード例を確認できます。

これらの動作する例には、シンプルなフロントエンドページと、Mercureの実際の動作を示すNode.jsバックエンドサーバーが含まれています。

Mercure-hubを使用したバックエンドとフロントエンドの通信の簡単な例Mercure-hubを使用したバックエンドとフロントエンドの通信の簡単な例

サブスクライバーの認証

前の例では、サブスクライバーは認証されておらず、Stackheroダッシュボードで「匿名サブスクライバー」を許可する必要がありました。

サブスクライバーを認証するには、Stackheroダッシュボードで定義された「Subscriber JWT key」を使用してJWS（JSON Web Signature）を生成します。JWSは、ブラウザのクッキーまたはauthorizationヘッダーを使用して送信されます。

Server-Sent Events APIはカスタムヘッダーの定義をサポートしていないため、クッキーを使用する必要があります。ただし、クッキーを使用するには、Mercure-hubサーバーとクライアントが同じドメイン（またはサブドメイン）を共有する必要があります。

異なるドメイン間でSSEを使用したい場合は、ヘッダー定義を可能にするEventSourceポリフィルを検討してください。https://github.com/Yaffle/EventSourceで利用可能なオプションがあります。

まず、バックエンドでクライアント用のJWSを生成します。例はbackend/subscriberJwsGenerator.jsにあります。サブスクライバーJWTを入力し、node subscriberJwsGenerator.jsを使用してスクリプトを実行します。

次に、フロントエンドのファイルfrontend/subscriberWithAuthorization.htmlで、エンドポイントと生成されたJWSを入力します。ブラウザでファイルを開くと、Mercure-hubが認証付きで動作します！

Stackheroダッシュボードで「匿名サブスクライバーを許可」をオフにするのを忘れないでください！

Mercure-Hub に関するその他の記事

  1. はじめに
    Mercure-hubの始め方