Claude Code × リアルタイムアプリ開発実践ガイド｜WebSocket・SSE・Socket.IO・Hono・接続管理パターン

Socket.IO v4 + TypeScript + Redis Adapterでチャットサーバーを実装してください。

要件:
- 4つの型インターフェース（ServerToClient/ClientToServer/InterServer/SocketData）
- JWT認証middleware
- Redis Adapterで水平スケーリング対応
- 名前空間: /chat（チャット）, /notifications（通知）
- ルーム: チャットルームID単位のグループ配信
- 接続数上限: ユーザーあたり5接続まで

// サーバー→クライアントに送るイベント
interface ServerToClientEvents {
  message: (data: { id: string; text: string; userId: string; createdAt: string }) => void;
  userJoined: (data: { userId: string; roomId: string }) => void;
  userLeft: (data: { userId: string; roomId: string }) => void;
}

// クライアント→サーバーに送るイベント
interface ClientToServerEvents {
  sendMessage: (data: { text: string; roomId: string }) => void;
  joinRoom: (roomId: string, callback: (success: boolean) => void) => void;
  leaveRoom: (roomId: string) => void;
}

// サーバー間通信イベント（Redis Adapter経由）
interface InterServerEvents {
  ping: () => void;
}

// ソケットに紐づくデータ
interface SocketData {
  userId: string;
  role: "admin" | "user";
}

import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-adapter";
import { createClient } from "redis";
import jwt from "jsonwebtoken";
import type { ServerToClientEvents, ClientToServerEvents, InterServerEvents, SocketData } from "@/shared/types";

export async function createSocketServer(httpServer: any) {
  const io = new Server<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData>(httpServer, {
    cors: { origin: process.env.CLIENT_URL, credentials: true },
  });

  // Redis Adapter（水平スケーリング）
  const pub = createClient({ url: process.env.REDIS_URL });
  const sub = pub.duplicate();
  await Promise.all([pub.connect(), sub.connect()]);
  io.adapter(createAdapter(pub, sub));

  // JWT認証middleware
  io.use((socket, next) => {
    const token = socket.handshake.auth.token;
    if (!token) return next(new Error("認証が必要です"));
    try {
      const decoded = jwt.verify(token, process.env.JWT_SECRET!) as { sub: string; role: string };
      socket.data.userId = decoded.sub;
      socket.data.role = decoded.role as "admin" | "user";
      next();
    } catch {
      next(new Error("無効なトークンです"));
    }
  });

  // チャット名前空間
  const chat = io.of("/chat");
  chat.on("connection", (socket) => {
    socket.on("joinRoom", (roomId, callback) => {
      socket.join(roomId);
      socket.to(roomId).emit("userJoined", { userId: socket.data.userId, roomId });
      callback(true);
    });

    socket.on("sendMessage", async ({ text, roomId }) => {
      const message = {
        id: crypto.randomUUID(),
        text,
        userId: socket.data.userId,
        createdAt: new Date().toISOString(),
      };
      // DBに永続化（省略）
      chat.to(roomId).emit("message", message);
    });

    socket.on("disconnect", () => {
      // クリーンアップ処理
    });
  });

  return io;
}

import { Hono } from "hono";
import { streamSSE } from "hono/streaming";

const app = new Hono();

// SSEエンドポイント
app.get("/api/events", async (c) => {
  return streamSSE(c, async (stream) => {
    let id = 0;
    while (true) {
      const data = { time: new Date().toISOString(), count: id };
      await stream.writeSSE({
        data: JSON.stringify(data),
        event: "update",
        id: String(id++),
      });
      await stream.sleep(1000); // 1秒間隔
    }
  });
});

import { NextRequest } from "next/server";

export const dynamic = "force-dynamic"; // 静的化を防止

export async function GET(req: NextRequest) {
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    start(controller) {
      // ハートビート（30秒間隔で接続維持）
      const heartbeat = setInterval(() => {
        controller.enqueue(encoder.encode(": heartbeat\n\n"));
      }, 30000);

      // 通知データの送信（例: 1秒間隔）
      const send = setInterval(() => {
        const data = { type: "notification", message: "新しいメッセージ", time: Date.now() };
        controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
      }, 1000);

      // クライアント切断時のクリーンアップ
      req.signal.addEventListener("abort", () => {
        clearInterval(heartbeat);
        clearInterval(send);
        controller.close();
      });
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      Connection: "keep-alive",
      "X-Accel-Buffering": "no", // Nginx/Vercelでのバッファリング防止
    },
  });
}

WebSocket接続を管理するReact Hookを作成してください。

要件:
- 型パラメータで受信メッセージの型を指定可能
- 接続状態（connecting / connected / disconnected）を管理
- 指数バックオフによる自動再接続（base 500ms, max 30s, jitter付き）
- コンポーネントアンマウント時に自動切断
- send関数で型安全にメッセージ送信

import { useEffect, useRef, useState, useCallback } from "react";

type Status = "connecting" | "connected" | "disconnected";

export function useWebSocket<T>(url: string) {
  const [status, setStatus] = useState<Status>("connecting");
  const [lastMessage, setLastMessage] = useState<T | null>(null);
  const wsRef = useRef<WebSocket | null>(null);
  const attemptRef = useRef(0);

  const connect = useCallback(() => {
    const ws = new WebSocket(url);
    wsRef.current = ws;
    setStatus("connecting");

    ws.onopen = () => {
      setStatus("connected");
      attemptRef.current = 0;
    };

    ws.onmessage = (e) => {
      setLastMessage(JSON.parse(e.data) as T);
    };

    ws.onclose = () => {
      setStatus("disconnected");
      // 指数バックオフ + jitter
      const delay = Math.min(500 * 2 ** attemptRef.current, 30000);
      const jitter = Math.random() * 1000;
      attemptRef.current++;
      setTimeout(connect, delay + jitter);
    };
  }, [url]);

  useEffect(() => {
    connect();
    return () => wsRef.current?.close();
  }, [connect]);

  const send = useCallback((data: unknown) => {
    if (wsRef.current?.readyState === WebSocket.OPEN) {
      wsRef.current.send(JSON.stringify(data));
    }
  }, []);

  return { status, lastMessage, send };
}

import { useEffect, useRef } from "react";

export function useSSE<T>(url: string, onMessage: (data: T) => void) {
  const callbackRef = useRef(onMessage);
  callbackRef.current = onMessage;

  useEffect(() => {
    const es = new EventSource(url);

    es.onmessage = (e) => {
      callbackRef.current(JSON.parse(e.data) as T);
    };

    es.onerror = () => {
      // EventSourceは自動再接続するため、ここではログのみ
      console.warn("SSE connection error, reconnecting...");
    };

    return () => es.close();
  }, [url]);
}

## リアルタイム通信

### プロトコル選定
- 双方向通信（チャット等）: Socket.IO v4
- サーバーpush（通知・ダッシュボード）: SSE（Hono streamSSE or Next.js Route Handlers）
- 素のWebSocket APIは禁止（Socket.IOを使用すること）

### Socket.IO規約
- 4つの型インターフェースを必ず定義（ServerToClient/ClientToServer/InterServer/SocketData）
- 認証: socket.handshake.auth.token でJWT検証（query stringは禁止）
- 名前空間: 機能単位（/chat, /notifications）
- ルーム: 動的グループ単位（ルームID、テナントID）
- @socket.io/redis-adapterで水平スケーリング対応

### SSE規約
- Next.js: export const dynamic = "force-dynamic" を必ず指定
- ハートビート: 30秒間隔で ": heartbeat\n\n" を送信
- ヘッダー: X-Accel-Buffering: no を必ず設定（Nginx/Vercel対策）
- クライアント切断時のクリーンアップ: req.signal.addEventListener("abort", ...)

### 接続管理
- 指数バックオフ再接続（base 500ms, max 30s, jitter付き）
- React Hook（useWebSocket / useSSE）で接続状態を管理
- コンポーネントアンマウント時にWebSocket/EventSourceをcloseする