원격 프로토콜 · 05

WSS는 기력이 아닙니다: KataGo JSON 원격 통로

Read19 암호화 WebSocket 세션을 설명합니다. 각 텍스트 프레임은 표준 KataGo Analysis Engine JSON이며 탐색 중에도 갱신됩니다.

  1. 암호화된 양방향 통로에 연결합니다

    클라이언트는 wss://read19.com/v1/katago/<API_KEY> 에 연결합니다. WSS는 TLS 위의 WebSocket입니다. 경로의 API Key는 자격 증명이므로 로그, 스크린샷과 공개 예시에 남기지 마세요. 연결 뒤 같은 세션에서 양쪽이 메시지를 보낼 수 있습니다.

    TLS 핸드셰이크 뒤 양방향 세션이 유지됩니다. 전체 URL을 비밀번호처럼 보호하세요.

  2. 프레임마다 KataGo JSON 하나를 보냅니다

    질의에는 고유 id와 moves, initialStones, rules, komi, boardXSize, boardYSize, analyzeTurns가 들어갑니다. 탐색 중 갱신은 reportDuringSearchEvery로 요청하며 Read19는 0.1~5초 간격을 받습니다.

    WSS는 전송층이고 본문은 Analysis Engine JSON입니다. 별도의 사설 기보 형식이 아닙니다.

  3. isDuringSearch로 완료를 판단합니다

    탐색 중 응답은 isDuringSearch: true이며 후보 수와 그래프를 갱신할 수 있습니다. false가 해당 id의 최종 응답입니다. 국면이 바뀌면 action: terminate와 terminateId를 보내 세션은 유지하고 그 질의만 취소합니다.

    한 id는 여러 중간 스냅샷과 하나의 최종 스냅샷을 받습니다. terminate는 전체 소켓이 아닌 질의를 가리킵니다.

프로토콜 근거

  1. Read19 API 문서
  2. KataGo Analysis Engine 문서

구현 점검

  • API Key를 로그에 남기지 않기
  • 질의 id를 고유하게 만들기
  • isDuringSearch로 상태 갱신
  • 국면 전환 시 이전 id 종료
stdout 글 읽기