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

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

Source: https://hibira.io/ja/blog/go-backend-realtime
Updated: 2026-11-20

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

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

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

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

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

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

```go
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 回です。注文の発送を例にします。

```go
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 サービスが提供するので、「誰がどのチャンネルを見られるか」はすべてあなたのコードで決まります。

```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 つのエンドポイントをつなぎます。

```go
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 サービスに向けます。

```js
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 がやってくれます。

```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 の導入ガイド](https://hibira.io/ja/guides/go)にもあり、アプリのページから開くとホストが自動で入ります。プッシュ通知が必要なら、[プッシュ通知ガイド](https://hibira.io/ja/guides/push-notifications)に Go の例があります。具体的なシナリオは[注文の追跡](https://hibira.io/ja/use-cases/order-tracking)と[共同編集とプレゼンス](https://hibira.io/ja/use-cases/collaboration-presence)を参考にしてください。Claude Code などの AI アシスタントでコードを書いているなら、[Hibira MCP サーバー](https://hibira.io/ja/mcp-server)経由で Go の導入ガイドを取得させ、プロジェクトをそのまま変更させることもできます。
