실시간 3편 — SSE를 걷어내고 WebSocket으로 갈아탔다

1. 프론트 소비자 삭제   — SseProvider, useProjectSse, RefreshBar
2. 도메인 발행 삭제     — resolver의 publish 호출 7곳, 발행용 분기
3. 인프라 삭제         — libs/sse 통째, HttpSessionAuthGuard

/**
 * project 룸 기반 WebSocket 게이트웨이. 도메인 로직을 모르고 wire 타입(RealtimeEvent)만 안다.
 */
@NestWebSocketGateway({
  path: '/api/ws',
  cors: { origin: process.env.FRONTEND_URL, credentials: true },
  serveClient: false,
})
export class WebSocketGateway implements OnGatewayInit {
  /**
   * 인증을 핸드셰이크 미들웨어에 건다.
   */
  afterInit(server: Server): void {
    server.use((socket, next) => {
      void this.authenticate(socket).then(
        () => next(),
        (error: Error) => {
          this.logger.warn(`[ws.unauthorized] reason=${error.message}`);
          next(new Error('unauthorized'));
        }
      );
    });
  }

  /**
   * 세션 쿠키(APP_SID)만 검증하고 socket.data.userId 를 채운다.
   */
  private async authenticate(socket: Socket): Promise<void> {
    const sessionId = parseCookies(socket.handshake.headers.cookie)[SESSION_COOKIE_NAME];
    if (!sessionId) throw new Error('no_session_cookie');

    const session = await this.authHelper.validateSession(sessionId);
    socket.data.userId = session.userId;
  }
}

export const parseCookies = (header = ''): Record<string, string> => {
  const jar: Record<string, string> = {};

  for (const pair of header.split(';')) {
    // 값에 '=' 가 들어갈 수 있으므로 split 이 아니라 첫 '=' 기준으로 자른다.
    const separator = pair.indexOf('=');
    if (separator === -1) continue;
    jar[pair.slice(0, separator).trim()] = decodeURIComponent(pair.slice(separator + 1).trim());
  }

  return jar;
};

export const projectRoom = (projectId: string) => `project:${projectId}`;

@SubscribeMessage('project.join')
async handleJoin(
  @ConnectedSocket() client: Socket,
  @MessageBody() projectId: string
): Promise<{ ok: boolean }> {
  const userId = client.data.userId as string | undefined;
  if (!userId) {
    this.logger.error(`[ws.join_denied] reason=missing_user socket=${client.id}`);
    return { ok: false };
  }

  try {
    // project 멤버인지 확인
    await this.projectMemberService.getProjectMemberByProjectIdAndUserId({ projectId, userId });
  } catch {
    this.logger.warn(`[ws.join_denied] user=${userId} project=${projectId}`);
    return { ok: false };
  }

  // Set 순회 중 mutate 방지로 복사.
  [...client.rooms].filter((room) => room !== client.id).forEach((room) => client.leave(room));
  await client.join(projectRoom(projectId));

  return { ok: true };
}

/**
 * project 룸 전원에게 발행한다. 발행자 본인 소켓도 포함이므로 중복은 클라이언트가 거른다.
 * socket.io 이벤트 이름은 하나뿐이고, 종류 구분은 envelope 의 type/subtype 이 한다.
 */
emitToProject(projectId: string, event: RealtimeEvent): void {
  this.server.to(projectRoom(projectId)).emit(REALTIME_EVENT, event);
}

/**
 * 서버→클라이언트 단일 socket.io 이벤트 이름. 이벤트 종류 구분은
 * 페이로드(RealtimeEvent)의 type/subtype 이 한다.
 */
export const REALTIME_EVENT = 'event' as const;

/**
 * 서버→클라이언트 실시간 이벤트 전체 union. 슬랙 와이어 포맷처럼
 * 이벤트 이름 하나(REALTIME_EVENT)에 실리고 type/subtype 으로 판별한다.
 */
export type RealtimeEvent = NoteEvent | CommentEvent | ReactionEvent;

export type NoteCreatedPayload =
  | { versionId: string; refetch: true }
  | {
      versionId: string;
      refetch: false;
      scope: NoteScope;
      note: NoteNodePayload;
    };

// 와이어 포맷: 단일 socket.io 이벤트에 실리는 envelope. type/subtype 이중 리터럴로
// 판별한다. union payload 는 extends 가 불가능하므로 intersection 으로 결합한다 —
// TS 가 분배해 주므로 narrowing 후에도 refetch 판별이 그대로 동작한다.
export type NoteCreatedEvent = {
  type: 'note';
  subtype: 'created';
} & NoteCreatedPayload;

/**
 * 부속물(첨부·드로잉)이 없는 신규 노트만 노드를 실어 보낸다.
 * @param hasExtras 첨부나 드로잉이 붙었는지 — true 면 클라이언트가 refetch 한다
 */
async emitCreated(note: NoteEntity, hasExtras: boolean): Promise<void> {
  if (note.status !== NoteStatus.SUBMITTED) return;

  const { versionId, projectId } = await this.noteService.findEventTargetByNoteId(
    note.noteId
  );

  const event: NoteCreatedEvent = hasExtras
    ? { type: 'note', subtype: 'created', versionId, refetch: true }
    : {
        type: 'note',
        subtype: 'created',
        versionId,
        refetch: false,
        scope: note.scope,
        note: NoteEvents.toNodePayload(note),
      };

  this.webSocketGateway.emitToProject(projectId, event);
}

/**
 * 삭제는 행이 사라진 뒤라 좌표를 다시 못 찾는다. 호출부가 삭제 전에 잡아 둔
 * findEventTargetByNoteId 결과를 넘겨야 한다.
 */
emitDeleted(target: { versionId: string; projectId: string }, note: NoteEntity): void {

연결 (1개)          SocketProvider — 로그인 후 connect, 로그아웃 시 disconnect
  └ 룸 (라우트당 1개)  useProjectRoom — join/leave만, 연결은 안 건드림
      └ 수신 (1개)      useProjectDetailRealTime — 단일 dispatcher, 캐시 반영

export const socket: AppSocket = io(config.WS_ORIGIN, {
  path: '/api/ws',
  withCredentials: true,
  autoConnect: false,
});

// 인증 거부는 재시도해도 결과가 같다. 자동 재연결이 붙어야 하는 네트워크 끊김과 구분해서 멈춘다.
socket.on('connect_error', (error) => {
  if (error.message === 'unauthorized') socket.disconnect();
});

/**
 * project 룸 입·퇴장. 연결 자체는 건드리지 않는다.
 */
export const useProjectRoom = (projectId: string) => {
  const socket = useSocket();

  useEffect(() => {
    const join = () => socket.emit('project.join', projectId);

    if (socket.connected) join();
    socket.on('connect', join);

    return () => {
      socket.off('connect', join);
      socket.emit('project.leave', projectId);
    };
  }, [socket, projectId]);
};

export const useProjectDetailRealTime = () => {
  const queryClient = useQueryClient();
  const socket = useSocket();

  useEffect(() => {
    const handleEvent = (event: RealtimeEvent) => {
      switch (event.type) {
        case 'note':
          applyNoteRealtimeEvent(queryClient, event);
          return;

        case 'comment':
          if (event.subtype === 'indicator_updated') {
            // 발행은 comment 모듈이지만 소비자는 노트 목록의 배지 캐시다.
            applyNoteRealtimeEvent(queryClient, event);
            return;
          }
          applyCommentRealtimeEvent(queryClient, event);
          return;

        case 'reaction':
          syncReactionRealtimeCache(queryClient, event);
      }
    };

    socket.on(REALTIME_EVENT, handleEvent);
    return () => {
      socket.off(REALTIME_EVENT, handleEvent);
    };
  }, [queryClient, socket]);
};

case 'created': {
  const { payload } = event;
  if (payload.refetch) {
    void queryClient.invalidateQueries({ queryKey: notesQueryKey(payload.versionId) });
    return;
  }

  queryClient.setQueriesData<NotesByVersionQuery>(
    { queryKey: notesQueryKey(payload.versionId, payload.scope) },
    (cache) => upsertNote(cache, payload.note)
  );
  return;
}

/** scope가 없으면 해당 버전의 모든 scope 캐시를 부분 매칭한다. */
export const notesQueryKey = (versionId: string, scope?: NoteScope) =>
  useNotesByVersionQuery.getKey({ input: scope ? { versionId, scope } : { versionId } });

// 최초 connect 는 라우트 로더가 막 받아온 직후라 무효화할 갭이 없다. Manager 의 reconnect 만 잡는다.
const handleReconnect = () => {
  void queryClient.invalidateQueries();
  toast.success('실시간 연결이 복구되었어요.', { id: CONNECTION_TOAST_ID, duration: 3000 });
};

const handleDisconnect = (reason: Socket.DisconnectReason) => {
  if (reason === 'io client disconnect') return;

  toast.loading('실시간 연결이 끊겼습니다. 재연결 중…', {
    id: CONNECTION_TOAST_ID,
    duration: Infinity,
  });
};