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분간 없으면 잠듭니다.