WebSocket API

토스 프론트에서 WebSocket 서버를 생성하고 클라이언트와 양방향 통신을 하기 위한 API입니다.

Methods

start

WebSocket 서버를 시작하고 이벤트 리스너를 자동으로 설정합니다. 서버 열기, 연결 관리, 이벤트 수신을 한 번에 처리하는 고수준 API입니다.

Parameters

파라미터	타입	필수	기본값	설명
params	Object		-	서버 시작 파라미터
params.serverId	string		ULID	서버 식별자. 미지정 시 자동 생성
params.port	number		0	리스닝 포트
params.path	string		'/'	http-path 경로
params.onConnection	Function		-	새로운 연결 시 호출할 콜백 함수
params.onMessage	Function		-	메시지 수신 시 호출할 콜백 함수
params.onDisconnection	Function		-	연결 종료 시 호출할 콜백 함수
params.onError	Function		-	오류 발생 시 호출할 콜백 함수

반환값: Promise<WebSocketServerHandle> — 서버 정보(serverId, host, port, path, connectionIds)와 send, disconnect, stop 메서드를 포함한 객체

Example

/**
 * WebSocket 서버 시작 (고수준 API)
 * @param {Object} params 서버 시작 파라미터
 * @param {string} [params.serverId] 서버 식별자
 * @param {number} [params.port] 리스닝 포트
 * @param {string} [params.path] http-path 경로
 * @param {Function} [params.onConnection] 연결 콜백
 * @param {Function} [params.onMessage] 메시지 수신 콜백
 * @param {Function} [params.onDisconnection] 연결 종료 콜백
 * @param {Function} [params.onError] 오류 콜백
 * @returns {Promise<WebSocketServerHandle>} 서버 핸들 객체
 */
const server = await sdk.websocket.start({
  port: 8080,
  onConnection: (payload) => {
    console.log("연결됨:", payload.connectionId);
  },
  onMessage: (payload) => {
    console.log("메시지 수신:", payload.data);
  },
  onDisconnection: (payload) => {
    console.log("연결 종료:", payload.connectionId, payload.reason);
  },
  onError: (payload) => {
    console.error("오류:", payload.message);
  },
});

// 서버 핸들을 통한 메시지 송신
await server.send(connectionId, JSON.stringify({ type: "hello" }));

// 특정 연결 종료
await server.disconnect(connectionId);

// 서버 종료
await server.stop();

open

지정한 포트에 대해 WebSocket 서버 리스닝을 시작합니다.

Parameters

파라미터	타입	필수	기본값	설명
params	Object		-	서버 설정 파라미터
params.serverId	string		ULID	서버 식별자. 미지정 시 자동 생성
params.port	number		0	리스닝 포트
params.path	string		'/'	http-path 경로

반환값: { serverId, host, port, path, connectionIds } — 서버가 열린 결과

Example

/**
 * WebSocket 서버 리스닝 시작
 * @param {Object} params 서버 설정
 * @param {string} [params.serverId] 서버 식별자
 * @param {number} [params.port] 리스닝 포트
 * @param {string} [params.path] http-path 경로
 * @returns {{ serverId: string, host: string, port: number, path: string, connectionIds: string[] }}
 */
const result = await sdk.websocket.open({ port: 8080 });
console.log("서버 주소:", `ws://${result.host}:${result.port}${result.path}`);

list

현재 활성화된 WebSocket 서버 목록을 조회합니다.

Example

/**
 * 활성 WebSocket 서버 목록 조회
 * @returns {{ servers: Array<{ serverId, host, port, path, connectionIds }> }}
 */
const { servers } = await sdk.websocket.list();
servers.forEach((server) => {
  console.log(`서버 ${server.serverId}: ${server.host}:${server.port}`);
});

send

연결된 클라이언트로 메시지를 송신합니다.

Parameters

파라미터	타입	필수	기본값	설명
params	Object	✓	-	송신 파라미터
params.serverId	string	✓	-	서버 식별자
params.connectionId	string	✓	-	송신 대상 연결 ID
params.data	string	✓	-	송신할 JSON 문자열 (유효한 JSON 이어야 함)

Example

/**
 * WebSocket 메시지 송신
 * @param {Object} params 송신 파라미터
 * @param {string} params.serverId 서버 식별자
 * @param {string} params.connectionId 송신 대상 연결 ID
 * @param {string} params.data 송신할 JSON 문자열
 */
await sdk.websocket.send({
  serverId: "my-server",
  connectionId: "conn-123",
  data: JSON.stringify({ type: "greeting", message: "Hello!" }),
});

disconnect

특정 연결을 종료합니다.

Parameters

파라미터	타입	필수	기본값	설명
params	Object	✓	-	종료 파라미터
params.serverId	string	✓	-	서버 식별자
params.connectionId	string	✓	-	종료할 연결 ID

Example

/**
 * 특정 연결 종료
 * @param {Object} params 종료 파라미터
 * @param {string} params.serverId 서버 식별자
 * @param {string} params.connectionId 종료할 연결 ID
 */
await sdk.websocket.disconnect({
  serverId: "my-server",
  connectionId: "conn-123",
});

close

서버를 종료합니다. 서버에 속한 모든 연결을 정리하고 리스닝을 중단합니다.

Parameters

파라미터	타입	필수	기본값	설명
params	Object	✓	-	종료 파라미터
params.serverId	string	✓*	-	종료할 서버 식별자

Example

/**
 * 특정 서버 종료
 * @param {Object} params 종료 파라미터
 * @param {string} params.serverId 서버 식별자
 */
await sdk.websocket.close({ serverId: "my-server" });

closeAll

모든 서버를 종료합니다. 서버에 속한 모든 연결을 정리하고 리스닝을 중단합니다.

Example

/**
 * 모든 서버 종료
 * @returns {{ closedServerIds: string[] }} 종료된 서버 ID 목록
 */
const result = await sdk.websocket.closeAll();
console.log("종료된 서버:", result.closedServerIds);

listen.connection

새로운 연결이 맺어졌을 때 이벤트를 수신합니다.

Parameters

파라미터	타입	필수	기본값	설명
callback	Function	✓	-	연결 시 호출할 콜백 함수
options	Object		-	필터링 옵션
options.serverId	string		-	해당 serverId 이벤트만 수신 (미전달 시 전체 수신)

콜백 함수 파라미터:

• payload.serverId (string): 서버 식별자
• payload.connectionId (string): 연결 ID

Example

/**
 * 연결 이벤트 리스너 등록
 * @param {Function} callback 연결 시 호출할 콜백 함수
 * @param {Object} [options] 필터링 옵션
 * @returns {Function} 이벤트 리스너 해제 함수
 */
const unlisten = sdk.websocket.listen.connection(
  (payload) => {
    console.log("새 연결:", payload.serverId, payload.connectionId);
  },
  { serverId: "my-server" }
);

// 이벤트 리스너 해제
unlisten();

listen.message

메시지를 수신했을 때 이벤트를 수신합니다.

Parameters

파라미터	타입	필수	기본값	설명
callback	Function	✓	-	메시지 수신 시 호출할 콜백 함수
options	Object	✓	-	필터링 옵션
options.serverId	string		-	해당 serverId 이벤트만 수신 (미전달 시 전체 수신)
options.connectionId	string	✓	-	connection 이벤트에서 받은 connectionId

콜백 함수 파라미터:

• payload.serverId (string): 서버 식별자
• payload.connectionId (string): 연결 ID
• payload.data (string): 수신한 JSON 문자열 데이터

Example

/**
 * 메시지 수신 이벤트 리스너 등록
 * @param {Function} callback 메시지 수신 시 호출할 콜백 함수
 * @param {Object} options 필터링 옵션 (connectionId 필수)
 * @returns {Function} 이벤트 리스너 해제 함수
 */
const unlisten = sdk.websocket.listen.message(
  (payload) => {
    console.log("메시지:", payload.data);
  },
  { serverId: "my-server", connectionId: "conn-123" }
);

// 이벤트 리스너 해제
unlisten();

listen.disconnection

연결이 종료되었을 때 이벤트를 수신합니다.

Parameters

파라미터	타입	필수	기본값	설명
callback	Function	✓	-	연결 종료 시 호출할 콜백 함수
options	Object	✓	-	필터링 옵션
options.serverId	string		-	해당 serverId 이벤트만 수신 (미전달 시 전체 수신)
options.connectionId	string	✓	-	connection 이벤트에서 받은 connectionId

콜백 함수 파라미터:

• payload.serverId (string): 서버 식별자
• payload.connectionId (string): 연결 ID
• payload.reason (string | undefined): 종료 사유

Example

/**
 * 연결 종료 이벤트 리스너 등록
 * @param {Function} callback 연결 종료 시 호출할 콜백 함수
 * @param {Object} options 필터링 옵션 (connectionId 필수)
 * @returns {Function} 이벤트 리스너 해제 함수
 */
const unlisten = sdk.websocket.listen.disconnection(
  (payload) => {
    console.log("연결 종료:", payload.connectionId, payload.reason);
  },
  { serverId: "my-server", connectionId: "conn-123" }
);

// 이벤트 리스너 해제
unlisten();

listen.error

서버/연결 처리 중 오류가 발생했을 때 이벤트를 수신합니다.

Parameters

파라미터	타입	필수	기본값	설명
callback	Function	✓	-	오류 발생 시 호출할 콜백 함수
options	Object	✓	-	필터링 옵션
options.serverId	string		-	해당 serverId 이벤트만 수신 (미전달 시 전체 수신)
options.connectionId	string	✓	-	connection 이벤트에서 받은 connectionId

콜백 함수 파라미터:

• payload.serverId (string): 서버 식별자
• payload.connectionId (string | undefined): 연결 ID
• payload.message (string): 오류 메시지

Example

/**
 * 오류 이벤트 리스너 등록
 * @param {Function} callback 오류 발생 시 호출할 콜백 함수
 * @param {Object} options 필터링 옵션 (connectionId 필수)
 * @returns {Function} 이벤트 리스너 해제 함수
 */
const unlisten = sdk.websocket.listen.error(
  (payload) => {
    console.error("오류:", payload.message);
  },
  { serverId: "my-server", connectionId: "conn-123" }
);

// 이벤트 리스너 해제
unlisten();

사용 예시

start를 활용한 WebSocket 서버 운영

// 1. 서버 시작 — start 하나로 서버 열기 + 이벤트 리스너 설정을 한 번에 처리
const server = await sdk.websocket.start({
  port: 8080,
  onConnection: (payload) => {
    console.log("새 연결:", payload.connectionId);

    // 연결된 클라이언트에 환영 메시지 송신
    server.send(payload.connectionId, JSON.stringify({ type: "welcome" }));
  },
  onMessage: (payload) => {
    const message = JSON.parse(payload.data);
    console.log(`메시지 수신 (${payload.connectionId}):`, message);
  },
  onDisconnection: (payload) => {
    console.log("연결 종료:", payload.connectionId, payload.reason);
  },
  onError: (payload) => {
    console.error("오류:", payload.message);
  },
});

console.log(`서버 시작: ws://${server.host}:${server.port}${server.path}`);

// 2. 특정 클라이언트에 메시지 송신
await server.send(connectionId, JSON.stringify({ type: "ping" }));

// 3. 특정 연결 종료
await server.disconnect(connectionId);

// 4. 서버 종료 (모든 연결 정리 + 리스너 해제)
await server.stop();