wait-on + localhost repro

wait-on http://localhost:41230가 GitHub Actions에서 간헐적으로 실패하는지, 그리고 127.0.0.1로 바꾸면 안정성이 달라지는지 빠르게 확인하기 위한 실용적인 최소 레포입니다.

이 버전은 복잡한 런처 코드를 없애고 아래 핵심만 남겼습니다.

• Fastify 서버 부트스트랩
• localhost vs 127.0.0.1 비교
• 각 시도를 별도 GitHub-hosted runner에서 실행
• parent -> detached child -> immediate wait-on 경로 재현
• wait-on --verbose 로그 수집
• 실패 시 tcp wait-on, curl, ss, ps, 서버 로그 출력

caching-for-turbo가 localhost:41230에 Fastify 기반 서버를 띄우고 listen({ port })처럼 host를 생략할 수 있다는 점을 반영해 서버는 Fastify + 기본 host 생략 방식으로 구성했습니다. 참고: rharkor/caching-for-turbo, Fastify Server docs

파일

• package.json: fastify, wait-on
• parent.mjs: detached child spawn 후 즉시 wait-on 수행
• server.mjs: 매우 단순한 Fastify 서버
• .github/workflows/repro-wait-on.yml: 반복 실험 워크플로우

서버

• PORT: 기본 41230
• BIND_HOST: 기본 미설정
• STARTUP_DELAY_MS: 기본 0
• RANDOM_STARTUP_DELAY_MAX_MS: 기본 0
• /에 200 JSON 응답

서버 코드는 의도적으로 짧지만, Fastify의 기본 부트스트랩 흐름은 유지합니다.

• Fastify() 생성
• 라우트 등록
• onReady 훅 실행
• listen({ port }) 또는 listen({ host, port })
• fastify.addresses() 로그 출력
• 선택적으로 랜덤 시작 지연 추가

parent 경로

parent.mjs는 실제 액션과 비슷하게 아래 순서로 동작합니다.

• detached child process로 server.mjs spawn
• stdout/stderr를 logs/server.log로 리다이렉트
• spawn 직후 바로 wait-on --verbose 실행
• 실패 시 추가 진단 수집
  • wait-on tcp:localhost:PORT
  • wait-on tcp:127.0.0.1:PORT
  • curl -v localhost
  • curl -v 127.0.0.1
  • ss -ltnp
  • ps -fp <pid>

시나리오

• A: host 생략, wait http-get://localhost:41230
• B: host 생략, wait http-get://127.0.0.1:41230

각 시나리오는 attempt 1..20으로 실행되며, 각 attempt는 별도 job이므로 매번 새 GitHub-hosted runner에서 실행됩니다.

로컬 확인

npm ci
WAIT_TARGET=http-get://localhost:41230 PORT=41230 node parent.mjs
ls logs

npm ci
WAIT_TARGET=http-get://127.0.0.1:41230 RANDOM_STARTUP_DELAY_MAX_MS=1500 PORT=41230 node parent.mjs
ls logs

GitHub Actions 실행

1. 새 GitHub 레포에 push
2. Actions에서 repro-wait-on 선택
3. Run workflow 실행
4. 필요하면 timeout_ms, startup_delay_ms, random_startup_delay_max_ms 조정
5. job 로그와 artifact 확인

해석

• ECONNREFUSED ::1:41230 localhost가 IPv6 ::1로 해석됐는데, 서버가 IPv6에 안정적으로 bind 되지 않았거나 실제로는 IPv4 쪽만 열렸을 가능성이 큽니다.

• 127.0.0.1은 성공하고 localhost만 실패 이름 해석 또는 주소 선택 순서 차이로 보는 게 가장 자연스럽습니다. 특히 host 생략 시 Fastify가 어떤 주소들에 실제 bind 되었는지 fastify.addresses() 로그를 같이 봐야 합니다.

• 둘 다 실패 단순한 localhost 문제가 아니라 부팅 지연, bind 실패, 포트 충돌, 프로세스 시작 방식 문제를 더 의심해야 합니다.

• 새 러너 기준으로 localhost 쪽만 간헐 실패 같은 머신 내부 상태가 아니라 GitHub runner 초기 상태, localhost 해석, IPv6/IPv4 선택 순서와 더 관련 있을 가능성이 커집니다.

• HTTP wait는 실패하지만 TCP wait는 성공 포트는 열렸지만 HTTP readiness 또는 wait-on http-get 경로가 문제일 수 있습니다.