← ブログ

Go バックエンドでリアルタイム機能を:WebSocket サーバーを自前で運用せずに

· Hibira

公式の pusher-http-go で Go からリアルタイムイベントを配信し、プライベート/presence チャンネルを認可し、Webhook を検証する。ブラウザは Hibira に接続します。

Go は WebSocket サーバーを書くのに向いた言語なので、多くのチームはまず自分で作ろうと考えます。hub を用意し、接続ごとに goroutine を立て、イベントが来たらブロードキャストする。サーバー 1 台ならこれで快適に動きます。ところが 2 台以上で動かし、presence(誰がオンラインか)を実装し、再接続やデプロイ中の接続の移動まで扱うようになると、WebSocket は機能のひとつではなく、運用するシステムになります。

もうひとつの方法は、Go バックエンドには「何を送るか」を決めることだけを任せ、数万本の接続を維持する部分はホスティング型サービスに任せることです。Hibira は Pusher Channels プロトコルを話すので、Pusher 公式の Go ライブラリ pusher-http-go をそのまま使い、ブラウザ側は pusher-js を使えます。この記事では、クライアントの作成、イベントの配信、プライベート/presence チャンネルの認可、フロントエンドの接続、Webhook の受信の 5 つを順に見ていきます。

あなたの Go サービス
HTTP API
Hibiraws.hibira.io
WebSocket
ブラウザとアプリ
ブラウザとアプリ
プライベートチャンネル購読時
/pusher/authあなたの Go サービス
Hibira
Webhook
/pusher/webhookあなたの Go サービス
Go バックエンドは HTTP で配信し、ブラウザは WebSocket で受け取る

ステップ 1:インストールしてクライアントを作る

go get github.com/pusher/pusher-http-go/v5

起動時にクライアントをひとつ作り、App ID、key、secret は環境変数から読み込みます(アプリを作成すると表示されます)。あとはイベントを配信するハンドラーやサービスに渡します。

import pusher "github.com/pusher/pusher-http-go/v5"

func newRealtime() *pusher.Client {
	return &pusher.Client{
		AppID:  os.Getenv("HIBIRA_APP_ID"),
		Key:    os.Getenv("HIBIRA_APP_KEY"),
		Secret: os.Getenv("HIBIRA_APP_SECRET"),
		Host:   "ws.hibira.io",
		Secure: true,
		// ライブラリが最初のリクエストで作るのに任せず、起動時に設定しておく
		HTTPClient: &http.Client{Timeout: 3 * time.Second},
	}
}

HTTPClient の行には理由があります。これを設定しないと、pusher-http-go は最初のリクエストのときにタイムアウト 5 秒の http.Client を作り、クライアントに書き戻します。複数の goroutine が同時に初めて配信すると、これはデータ競合になり、go test -race で検出されます。起動時に自分で設定し、ついでにサービスに合ったタイムアウトにしておきましょう。

ステップ 2:イベントを配信する

配信は HTTP 呼び出し 1 回です。注文の発送を例にします。

func shipOrder(rt *pusher.Client, w http.ResponseWriter, r *http.Request) {
	order := Order{ID: 1024, Status: "shipped"}
	// … 先に注文の状態をデータベースに書き込む …

	socketID := r.Header.Get("X-Socket-ID") // フロントエンドから送られる。空でもよい
	if err := rt.TriggerExclusive("private-user-42", "order-updated", order, socketID); err != nil {
		log.Printf("realtime: %v", err) // 配信に失敗しても注文自体は取り消さない
	}
	json.NewEncoder(w).Encode(order)
}

実践的なポイント:

  • 先にデータベースに書き、それから配信する。 リアルタイムイベントは通知であって、データの正本ではありません。再接続したクライアントは、届かなかったかもしれないイベントに頼らず、API から読み直すべきです。
  • 操作した本人を除外する。 フロントエンドの socket ID を TriggerExclusive に渡すと、変更を行ったタブには自分の更新が戻ってきません。全員に送るなら普通の Trigger で十分です。
  • まとめて送る。 1 回のリクエストで複数のチャンネルを更新するときは、TriggerMulti(同じイベントを複数チャンネルへ)や TriggerBatch(別々のイベント)で往復を減らせます。
  • リクエストを待たせない。 配信が遅延に敏感な経路にあるなら、バックグラウンドの goroutine やジョブキューに任せます。ただしエラー処理と、停止時に残りを送り切る処理は忘れずに。

セキュリティ上の注意: X-Socket-ID は送信元タブへのエコーを抑えるための任意の値であり、利用者の本人確認には使えません。チャンネル認可は検証済みのセッションまたは JWT に基づいて行い、フォームの構文とリクエストサイズも検証してください。

ステップ 3:プライベート/presence チャンネルの認可

private- や presence- で始まるチャンネルは、購読の前にクライアントがあなたのサーバーに署名を求めます。このエンドポイントは Go サービスが提供するので、「誰がどのチャンネルを見られるか」はすべてあなたのコードで決まります。

func pusherAuth(rt *pusher.Client) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		user, ok := currentUser(r) // 自前のセッションまたは JWT の確認
		if !ok {
			http.Error(w, "unauthorized", http.StatusUnauthorized)
			return
		}
		body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 4096))
		if err != nil {
			http.Error(w, "bad request", http.StatusBadRequest)
			return
		}
		form, err := url.ParseQuery(string(body))
		if err != nil {
			http.Error(w, "bad request", http.StatusBadRequest)
			return
		}
		channel := form.Get("channel_name")
		if (!strings.HasPrefix(channel, "private-") && !strings.HasPrefix(channel, "presence-")) || !user.CanJoin(channel) {
			http.Error(w, "forbidden", http.StatusForbidden)
			return
		}

		var resp []byte
		if strings.HasPrefix(channel, "presence-") {
			resp, err = rt.AuthorizePresenceChannel(body, pusher.MemberData{
				UserID:   user.ID,
				UserInfo: map[string]string{"name": user.Name},
			})
		} else {
			resp, err = rt.AuthorizePrivateChannel(body)
		}
		if err != nil {
			http.Error(w, "forbidden", http.StatusForbidden)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		w.Write(resp)
	}
}

ライブラリは署名するだけで、権限は確認しません。CanJoin の部分は必ず自分で書いてください。よくある間違いは「ログインしているか」だけを確認することで、そうするとログインしたユーザーなら誰でも private-user-42 を購読できてしまいます。presence チャンネルの UserInfo はチャンネル内の全メンバーに送られるので、公開してよい情報だけを入れます。

Go 1.22 以降の http.ServeMux のパターンで 3 つのエンドポイントをつなぎます。

rt := newRealtime()
mux := http.NewServeMux()
mux.HandleFunc("POST /orders/{id}/ship", func(w http.ResponseWriter, r *http.Request) { shipOrder(rt, w, r) })
mux.HandleFunc("POST /pusher/auth", pusherAuth(rt))
mux.HandleFunc("POST /pusher/webhook", pusherWebhook(rt))
log.Fatal(http.ListenAndServe(":8080", mux))

ステップ 4:フロントエンドをつなぐ

ブラウザでは pusher-js のホストを Hibira に、認可エンドポイントを Go サービスに向けます。

import Pusher from 'pusher-js';

const pusher = new Pusher('your-app-key', {
  cluster: 'hkg',
  wsHost: 'ws.hibira.io',
  wsPort: 443,
  wssPort: 443,
  forceTLS: true,
  enabledTransports: ['ws', 'wss'],
  channelAuthorization: { endpoint: '/pusher/auth', transport: 'ajax' },
});

pusher.subscribe('private-user-42').bind('order-updated', (order) => {
  renderOrder(order);
});

// 自分の API を呼ぶときに socket ID を付け、サーバーがこのタブを除外できるようにする
await fetch('/orders/1024/ship', {
  method: 'POST',
  headers: { 'X-Socket-ID': pusher.connection.socket_id },
});

認可リクエストにはブラウザの cookie が付くので、フロントエンドと Go サービスが同じドメインなら、既存のセッションがそのまま使えます。JWT を使う場合は channelAuthorization.headers に Authorization ヘッダーを追加します。モバイルアプリも同じで、PusherSwift と pusher-java-client はどちらもホストと認可エンドポイントを設定できます。

ステップ 5:Webhook を受け取る

チャンネルに最初の購読者が来たとき、presence チャンネルに誰かが入った・出たときを知りたいなら、アプリのページで Webhook の URL を設定します。X-Pusher-Key ヘッダーと HMAC 署名の検証は pusher-http-go がやってくれます。

func pusherWebhook(rt *pusher.Client) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
		if err != nil {
			http.Error(w, "bad request", http.StatusBadRequest)
			return
		}
		hook, err := rt.Webhook(r.Header, body) // X-Pusher-Key と署名を検証する
		if err != nil {
			http.Error(w, "invalid signature", http.StatusUnauthorized)
			return
		}
		for _, e := range hook.Events {
			switch e.Name {
			case "member_added":
				markOnline(e.UserID)
			case "member_removed":
				markOffline(e.UserID)
			}
		}
		w.WriteHeader(http.StatusOK)
	}
}

Webhook は短い時間内のイベントをまとめて 1 回のリクエストで送ります。エンドポイントが 2xx を返さなければ Hibira は最大 5 分間再送するので、処理は冪等にしてください。同じ member_added を 2 回受け取っても結果が変わらないようにします。処理に時間がかかるなら、先に 200 を返し、バックグラウンドジョブに渡します。

本番前のチェック

  • 配信するコードを go test -race で実行した。
  • プライベートチャンネルの認可で「ログインしているか」だけでなく「このユーザーがこのチャンネルを見てよいか」を確認している。
  • App secret は環境変数かシークレット管理サービスにだけ置き、バージョン管理やフロントエンドのコードには入れていない。
  • アプリのページのデバッグコンソールで、配信したイベント、購読、Webhook が表示されることを確認した。

Go の基本設定は Go の導入ガイドにもあり、アプリのページから開くとホストが自動で入ります。プッシュ通知が必要なら、プッシュ通知ガイドに Go の例があります。具体的なシナリオは注文の追跡と共同編集とプレゼンスを参考にしてください。Claude Code などの AI アシスタントでコードを書いているなら、Hibira MCP サーバー経由で Go の導入ガイドを取得させ、プロジェクトをそのまま変更させることもできます。