CAKE20

AI Web PaaS

WebSocket

파일 기반 route에서 실시간 양방향 연결을 처리합니다.

WebSocket route

  • server/routes/chat.ws.ts는 /chat, room/index.ws.ts는 /room, admin/log.ws.ts는 /admin/log로 연결합니다.
  • 서브폴더와 [id], [[id]], [...path] 동적 경로를 지원합니다.
  • onOpen, onMessage, onClose와 onError는 선언한 경우 자동 호출됩니다.
  • active가 true인 파일만 연결을 받고 auth가 true이면 로그인 세션을 요구하며 peer.user에 사용자를 제공합니다.
// server/routes/chat.ws.ts
export const config = {
  active: false, // WebSocket 라우트를 활성화할지 설정합니다.
  auth: false, // 로그인한 사용자만 연결할 수 있는지 설정합니다.
  sample: { message: "Hello from client!" } // 테스트에서 2초마다 전송할 JSON
};

// 새로운 WebSocket 연결이 열리면 자동으로 호출됩니다.
export const onOpen = (peer: SocketPeer) => {
  console.log("Connected:", peer.id);
};

// 클라이언트에서 메시지를 받으면 자동으로 호출됩니다.
export const onMessage = (peer: SocketPeer, message: SocketMessage) => {
  console.log("Message:", message.text());
  peer.send("Hello from server!");
};

// WebSocket 연결이 종료되면 자동으로 호출됩니다.
export const onClose = (
  peer: SocketPeer,
  details: SocketCloseDetails
) => {
  console.log("Disconnected:", peer.id, details.code, details.reason);
};

// WebSocket 처리 중 오류가 발생하면 자동으로 호출됩니다.
export const onError = (peer: SocketPeer, error: Error) => {
  console.error("Error:", peer.id, error);
};

메시지와 연결 제한

  • 메시지 크기 64KB, 유휴 종료 60초, route별 동시 연결 100개와 연결당 초당 메시지 10개는 Runtime 내부 고정값입니다.
  • 64KB를 넘는 메시지는 handler에 전달하지 않고 close code 1009로 닫습니다.
  • 초당 메시지 제한을 넘으면 close code 1008로 닫습니다.
  • 웹사이트 전체 동시 연결은 최대 1,000개입니다.
  • 대용량 파일은 WebSocket 메시지가 아니라 HTTP 업로드로 전송합니다.

Peer와 message

  • peer는 id, params, request, user, remoteAddress, send, close, rooms, join, leave와 publish를 제공합니다.
  • message는 text(), json(), uint8Array()와 arrayBuffer()를 제공합니다.
  • peer.join(room)으로 연결당 최대 20개 room에 참여하고 await peer.publish(room, data)로 참여 연결 전체에 전송합니다.
  • room 이름은 공백 없이 1~100자입니다. 발신 연결도 참여 중인 room의 메시지를 받습니다.
  • server 데이터에서는 Redis event stream으로 여러 웹 프로세스의 room을 동기화하고 local 데이터에서는 현재 프로세스에 전송합니다.
  • 웹사이트 재시작이나 정상 종료 때 close code 1012로 연결을 닫습니다.
  • WebSocket 연결이 열려 있는 동안은 자동으로 잠들지 않습니다. 연결이 모두 닫힌 뒤 다른 HTTP, Task와 Queue job 활동도 5분간 없으면 잠듭니다.