Skip to content

서버 상태 오류 구분과 기존 ping 응답 계약 정리 - #1

Merged
AlphaBs merged 6 commits into
mainfrom
codex/server-status-latency-contract
Nov 1, 2026
Merged

AlphaBs merged 6 commits into
mainfrom
codex/server-status-latency-contract

Conversation

@AlphaBs

@AlphaBs AlphaBs commented Oct 17, 2026

Copy link
Copy Markdown
Member

Minecraft 서버 접속 실패와 API 내부 오류가 모두 HTTP 200 / result: false로 반환되어, 런처의 온라인 전환 감지가 API 장애를 오프라인으로 해석할 수 있었습니다. 정상 접속 불가는 기존 응답을 유지하고 주소 오류는 400, 프로토콜·조회 오류는 502, API 내부 오류는 500으로 구분하며 오류 응답은 캐싱하지 않습니다.

기존 status.latency가 이미 API 서버 → Minecraft status 응답 지연 시간(ms)을 제공하므로 중복 필드 없이 유지합니다. 측정값 누락·음수·비유한 값은 null로 직렬화하고 나머지 status 구조는 보존합니다. DNS와 status 요청 전체에 3초 제한을 적용하고, 기존 잘못된 오프라인 캐시를 재사용하지 않도록 cache namespace를 분리했습니다.

README와 OpenAPI에 운영 endpoint, 온라인·오프라인·오류 응답 예시, 측정 방식, timestamp 의미, 60초 캐시와 polling 권장 주기, 런처 연동 방법을 정리했습니다. 운영 응답에는 status.motd.clean이 없다는 기존 계약 차이도 명시했습니다.

검증:

  • Python 3.10 및 운영 requirements.txt의 고정 버전에서 python -m unittest discover -s tests -v: 16개 통과
  • 실제 로컬 TCP 서버를 통한 mcstatus status 응답 지연 측정과 연결 거부 검증
  • 기존 응답 필드 호환성, nullable latency, API 오류 비캐싱, 캐시 재사용·만료·304·오프라인 후 온라인 전환, Redis 장애 시 실제 조회 대체 검증
  • 같은 테스트를 실행하는 GitHub Actions 추가
  • 공개 운영 OpenAPI와 온라인 응답 확인: https://mcstatus.snowfrost.kr/java/{address}, 기존 status.latency 제공. 호스트·경로 전환 불필요

운영 배포와 운영 Redis 연결 검증은 수행하지 않았습니다. 런처 저장소는 수정하지 않았습니다.

@AlphaBs
AlphaBs merged commit a5d2762 into main Nov 1, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant