ci(main): links job이 잠깐 느린 외부 사이트를 4분쯤 다시 묻는다 #52

Merged
donghyeon.kang merged 2 commits from ci/links-retry-window into main 2026-11-19 09:35:24 +00:00
Owner

무엇을, 왜

main links job(lychee-action v2.9.0 = lychee v0.24.2)이 run 362(f415bdbb)에서 빨강이었다. 기록 문서 둘의 외부 링크 셋이 lychee 기본 재시도 동안 답하지 않았다.

  • https://man7.org/linux/man-pages/man2/openat2.2.html (docs/design fileserver 설계)
  • https://jdbc.postgresql.org/documentation/ssl/, .../use/ (docs/design jpa 설계)
  • 요약: Total 986, Timeouts 3, Errors 0. step 67초. 다음 run 367은 Timeouts 0, 노트북 curl 9회 모두 200 → 링크는 살아 있다(재현 안 됨 9/9, 분류: 외부).
  • main이 빨강이면 같은 repo의 병합이 멈춘다(design-docs ci/manual.md 9.3절). v0.24.2로 올린 뒤 main.yml run에서 links 실패는 이것 하나다.

이 PR은 lychee 재시도 창을 넓힌다: --max-retries 5 --retry-wait-time 5. 시간 초과·429를 받은 요청을 5·10·20·40·80초 뒤에 다시 묻는다. 시간 초과가 이어지면 마지막 시도는 첫 시도 4분쯤 뒤에 시작한다(바로 오는 429는 2분 반쯤). 그 안에 답하면 통과, 마지막 시도에도 답이 없으면 지금처럼 실패다.

고른 방법과 버린 대안

고름: (가) 재시도 창 넓히기. 시간 초과는 그대로 실패로 둔다.

버림:

  • --accept-timeouts(시간 초과만이면 exit 0): 처음 고른 안이었다. 리뷰에서 「패킷을 버리는 죽은 호스트와 바깥으로 나가지 못하는 runner를 초록으로 둔다」(거짓 통과)는 지적을 받아 버렸다.
  • (나) 기록 문서(docs/design·history·reviews)의 외부 링크를 main 실패에서 빼기: 외부 URL 고유 364개 중 345개가 기록이라 효과는 크다. 하지만 기록의 404까지 안 보게 되고, docs/README.md 「기록의 죽은 링크는 .lycheeignore에 더한다」 규칙을 바꾼다. 살아 있는 문서의 시간 초과는 그대로 빨강이다.
  • --timeout도 늘리기: 한 번에 하나만 바꾼다(ci/manual.md 11절 4). run 362 로그로는 느린 응답인지 응답 없음인지 가릴 수 없다.

인자가 v0.24.2에 있다는 근거(lychee-v0.24.2 태그 소스·README):

  • lychee-bin/src/config/mod.rs: max_retries 「Maximum number of retries per request [default: 3]」 #[arg(long)], retry_wait_time 「Minimum wait time in seconds between retries of failed requests [default: 1]」 #[arg(short, long)], timeout 기본 20.
  • lychee-lib/src/checker/website.rs retry_request: 첫 시도 뒤 max_retries번, 매번 tokio::time::sleep(wait_time) 후 wait_time.saturating_mul(2).
  • lychee-lib/src/retry.rs: 다시 묻는 것은 Status::Timeout, reqwest timeout, 429. 응답으로 받은 500·503과 connect 오류는 다시 묻지 않는다.
  • README 「Commandline Parameters」에도 같은 세 옵션이 있다. run 362 로그 114·169줄 lycheeVersion: v0.24.2.

위험과 영향

  • 4분 넘게 답하지 않는 사이트는 여전히 main을 빨갛게 한다. 그런 링크 하나는 4분 반쯤 걸린다(시도 6번 × 20초 + 대기 155초).
  • 호스트 하나가 통째로 답하지 않아도 lychee는 시도마다 호스트별 자리(기본 10)를 받고 대기 중에는 쥐지 않는다. 범위에서 URL이 가장 많은 docs.aws.amazon.com 53개가 53 × 6 × 20초 ÷ 10 ≈ 11분이다. timeout-minutes: 15 안이다.
  • 이 기계들(노트북·desktop)에는 lychee가 없고 내려받아 설치하지 않는다(docs/work/operate.md 4.1절). 재시도 동작은 위 소스로만 확인했다. 효과는 병합 뒤 main run의 links job으로 본다.
  • 운영 코드·HTTP 응답은 바뀌지 않는다. 파생 서비스는 main.yml을 받으면 같은 인자를 얻는다(따라 고칠 것 없음).

검증

단계 명령 트리 결과 로그(desktop)
RED :app-bootstrap:repositoryContractTest --tests DeveloperExperienceContractTest --no-build-cache (기준 59349a2b + 시험만) 5eb884c1 rc=1, 16개 중 1 실패(--max-retries 없음) ~/be-ci-next-logs/a1-red3.log
GREEN 같은 시험 + :app-bootstrap:spotlessCheck, 그다음 :verifyStrictLaneStages --dry-run 1f3b1877 rc=0, 16개 통과, spotlessCheck·dry-run rc=0, FROM-CACHE 0 ~/be-ci-next-logs/a1-green4.log
문서 scripts/verify.sh docs(노트북) 같은 트리 rc=0 —
  • 리뷰 1회(렌즈 be-build-ci·be-docs): Medium 1(--accept-timeouts 거짓 통과), Low 1(실패 목록에 5xx 누락) → 고침. 확인 리뷰 1회: Low 1(429와 기본값의 시간 숫자) → 고침.
  • 흔들림 장부 docs/ledger/flaky-tests.jsonl에 run 362를 external로 한 줄 더했다. fixed_by는 병합 뒤 다음 PR에서 채운다.
  • 병합 뒤 볼 것: main push run의 links success.

리뷰어가 볼 곳

  • .gitea/workflows/main.yml links job 주석과 args 두 줄
  • DeveloperExperienceContractTest#linkCheckScansTheExactDocumentationScopeAndFails의 인자 목록
  • docs/work/reference/gates.md 「링크 검사」 문단

관련

  • brief be-ci-next (1), design-docs ci/manual.md 8·9·11절
  • 커밋 둘: 장부 착수 예측 한 줄, links 재시도
## 무엇을, 왜 main `links` job(lychee-action v2.9.0 = lychee v0.24.2)이 run 362(f415bdbb)에서 빨강이었다. 기록 문서 둘의 외부 링크 셋이 lychee 기본 재시도 동안 답하지 않았다. - `https://man7.org/linux/man-pages/man2/openat2.2.html` (docs/design fileserver 설계) - `https://jdbc.postgresql.org/documentation/ssl/`, `.../use/` (docs/design jpa 설계) - 요약: Total 986, Timeouts 3, Errors 0. step 67초. 다음 run 367은 Timeouts 0, 노트북 curl 9회 모두 200 → 링크는 살아 있다(재현 안 됨 9/9, 분류: 외부). - main이 빨강이면 같은 repo의 병합이 멈춘다(design-docs `ci/manual.md` 9.3절). v0.24.2로 올린 뒤 main.yml run에서 links 실패는 이것 하나다. 이 PR은 lychee 재시도 창을 넓힌다: `--max-retries 5 --retry-wait-time 5`. 시간 초과·429를 받은 요청을 5·10·20·40·80초 뒤에 다시 묻는다. 시간 초과가 이어지면 마지막 시도는 첫 시도 4분쯤 뒤에 시작한다(바로 오는 429는 2분 반쯤). 그 안에 답하면 통과, 마지막 시도에도 답이 없으면 지금처럼 실패다. ## 고른 방법과 버린 대안 고름: (가) 재시도 창 넓히기. 시간 초과는 그대로 실패로 둔다. 버림: - `--accept-timeouts`(시간 초과만이면 exit 0): 처음 고른 안이었다. 리뷰에서 「패킷을 버리는 죽은 호스트와 바깥으로 나가지 못하는 runner를 초록으로 둔다」(거짓 통과)는 지적을 받아 버렸다. - (나) 기록 문서(docs/design·history·reviews)의 외부 링크를 main 실패에서 빼기: 외부 URL 고유 364개 중 345개가 기록이라 효과는 크다. 하지만 기록의 404까지 안 보게 되고, `docs/README.md` 「기록의 죽은 링크는 `.lycheeignore`에 더한다」 규칙을 바꾼다. 살아 있는 문서의 시간 초과는 그대로 빨강이다. - `--timeout`도 늘리기: 한 번에 하나만 바꾼다(`ci/manual.md` 11절 4). run 362 로그로는 느린 응답인지 응답 없음인지 가릴 수 없다. 인자가 v0.24.2에 있다는 근거(lychee-v0.24.2 태그 소스·README): - `lychee-bin/src/config/mod.rs`: `max_retries` 「Maximum number of retries per request [default: 3]」 `#[arg(long)]`, `retry_wait_time` 「Minimum wait time in seconds between retries of failed requests [default: 1]」 `#[arg(short, long)]`, `timeout` 기본 20. - `lychee-lib/src/checker/website.rs` `retry_request`: 첫 시도 뒤 `max_retries`번, 매번 `tokio::time::sleep(wait_time)` 후 `wait_time.saturating_mul(2)`. - `lychee-lib/src/retry.rs`: 다시 묻는 것은 `Status::Timeout`, reqwest timeout, 429. 응답으로 받은 500·503과 connect 오류는 다시 묻지 않는다. - README 「Commandline Parameters」에도 같은 세 옵션이 있다. run 362 로그 114·169줄 `lycheeVersion: v0.24.2`. ## 위험과 영향 - 4분 넘게 답하지 않는 사이트는 여전히 main을 빨갛게 한다. 그런 링크 하나는 4분 반쯤 걸린다(시도 6번 × 20초 + 대기 155초). - 호스트 하나가 통째로 답하지 않아도 lychee는 시도마다 호스트별 자리(기본 10)를 받고 대기 중에는 쥐지 않는다. 범위에서 URL이 가장 많은 docs.aws.amazon.com 53개가 53 × 6 × 20초 ÷ 10 ≈ 11분이다. `timeout-minutes: 15` 안이다. - 이 기계들(노트북·desktop)에는 lychee가 없고 내려받아 설치하지 않는다(`docs/work/operate.md` 4.1절). 재시도 동작은 위 소스로만 확인했다. 효과는 병합 뒤 main run의 `links` job으로 본다. - 운영 코드·HTTP 응답은 바뀌지 않는다. 파생 서비스는 main.yml을 받으면 같은 인자를 얻는다(따라 고칠 것 없음). ## 검증 | 단계 | 명령 | 트리 | 결과 | 로그(desktop) | | --- | --- | --- | --- | --- | | RED | `:app-bootstrap:repositoryContractTest --tests DeveloperExperienceContractTest --no-build-cache` (기준 59349a2b + 시험만) | 5eb884c1 | rc=1, 16개 중 1 실패(`--max-retries` 없음) | `~/be-ci-next-logs/a1-red3.log` | | GREEN | 같은 시험 + `:app-bootstrap:spotlessCheck`, 그다음 `:verifyStrictLaneStages --dry-run` | 1f3b1877 | rc=0, 16개 통과, spotlessCheck·dry-run rc=0, FROM-CACHE 0 | `~/be-ci-next-logs/a1-green4.log` | | 문서 | `scripts/verify.sh docs`(노트북) | 같은 트리 | rc=0 | — | - 리뷰 1회(렌즈 be-build-ci·be-docs): Medium 1(`--accept-timeouts` 거짓 통과), Low 1(실패 목록에 5xx 누락) → 고침. 확인 리뷰 1회: Low 1(429와 기본값의 시간 숫자) → 고침. - 흔들림 장부 `docs/ledger/flaky-tests.jsonl`에 run 362를 `external`로 한 줄 더했다. `fixed_by`는 병합 뒤 다음 PR에서 채운다. - 병합 뒤 볼 것: main push run의 `links` success. ## 리뷰어가 볼 곳 - `.gitea/workflows/main.yml` links job 주석과 `args` 두 줄 - `DeveloperExperienceContractTest#linkCheckScansTheExactDocumentationScopeAndFails`의 인자 목록 - `docs/work/reference/gates.md` 「링크 검사」 문단 ## 관련 - brief be-ci-next (1), design-docs `ci/manual.md` 8·9·11절 - 커밋 둘: 장부 착수 예측 한 줄, links 재시도
donghyeon.kang added 2 commits 2026-11-19 09:28:22 +00:00
백엔드 CI 후속 셋(links 외부 시간 초과, API surface 빈 root, BE-1·BE-4)을
시작하며 docs/work/README.md 6절대로 예측 한 줄을 더한다. 실측 줄은 일이
끝날 때 더한다.

검증: ledger.py append가 칸을 검사했다. scripts/verify.sh docs rc=0(노트북).
문제: main links job(lychee-action v2.9.0 = lychee v0.24.2)이 run 362
(f415bdbb)에서 빨강이었다. 기록 문서 둘의 외부 링크 셋(man7.org의
openat2.2, jdbc.postgresql.org의 documentation/ssl·use)이 lychee 기본
재시도(첫 시도 뒤 3회, 대기 1·2·4초, 시한 20초) 동안 답하지 않았다. 요약은
Timeouts 3, Errors 0이었고 step은 67초 걸렸다. 링크는 살아 있었다. 다음 run
367은 Timeouts 0이고, 노트북 curl 9회가 모두 200이었다. main이 빨강이면 같은
repo의 병합이 멈춘다(design-docs ci/manual.md 9.3절).

고른 방법: --max-retries 5 --retry-wait-time 5. 시간 초과나 429를 받은
요청을 5·10·20·40·80초 뒤에 다시 묻는다. 시도마다 20초 시한이라 시간 초과가
이어지면 마지막 시도는 첫 시도 4분쯤 뒤에 시작한다(바로 오는 429는 2분
반쯤). 그 안에 다시 답하면 통과하고, 마지막 시도에도 답이 없으면 지금처럼
실패한다. 근거는
lychee-v0.24.2 태그 소스다: lychee-bin/src/config/mod.rs의 max_retries
("Maximum number of retries per request", 기본 3)와 retry_wait_time
("Minimum wait time in seconds between retries of failed requests", 기본 1),
lychee-lib/src/checker/website.rs의 retry_request(첫 시도 뒤 max_retries번,
대기는 매번 두 배), lychee-lib/src/retry.rs(시간 초과와 429만 다시 묻는다).

버린 대안:
- --accept-timeouts(시간 초과만이면 exit 0): 처음 고른 안이었다. 리뷰에서
  패킷을 버리는 죽은 호스트와 바깥으로 나가지 못하는 runner를 초록으로 둔다는
  지적을 받아 버렸다. 게이트가 막겠다던 것을 조용히 못 막는다.
- 기록 문서(docs/design·history·reviews)의 외부 링크를 main 실패에서 빼기:
  외부 URL 고유 364개 중 345개가 기록이라 효과는 크다. 하지만 기록의 404까지
  안 보게 되고, 「기록의 죽은 링크는 .lycheeignore에 더한다」는
  docs/README.md 규칙을 바꾼다. 살아 있는 문서의 시간 초과는 그대로 빨강이다.
- 시한(--timeout)도 늘리기: 한 번에 하나만 바꾼다(ci/manual.md 11절 4).
  run 362 로그로는 느린 응답인지 응답 없음인지 가릴 수 없다.

위험·한계: 4분 넘게 답하지 않는 사이트는 여전히 main을 빨갛게 한다. 그런
링크 하나는 4분 반쯤 걸린다(시도 6번 × 20초 + 대기 155초). 호스트 하나가
통째로 답하지 않아도 lychee는 시도마다 호스트별 자리(기본 10)를 받고 대기
중에는 쥐지 않으므로, 범위에서 URL이 가장 많은 docs.aws.amazon.com 53개가
53 × 6 × 20초 ÷ 10 ≈ 11분이다. timeout-minutes 15 안이다. 이 기계들에는
lychee가 없고 내려받아 설치하지 않으므로, 재시도 동작은 위 소스로만
확인했다. 효과는 병합 뒤 main run의 links job으로 본다. 흔들림 장부에 run
362를 external로 한 줄 더했다.

검증:
- 계약 시험 RED: 기준 59349a2b에 시험만 얹은 트리 5eb884c1에서
  DeveloperExperienceContractTest 16개 중 1개 실패(--max-retries 없음).
  desktop ~/be-ci-next-logs/a1-red3.log.
- GREEN: 트리 1f3b1877에서 같은 클래스 16개 통과,
  :app-bootstrap:spotlessCheck, :verifyStrictLaneStages --dry-run rc=0,
  --no-build-cache, FROM-CACHE 0. ~/be-ci-next-logs/a1-green4.log.
- scripts/verify.sh docs rc=0(노트북).
- 리뷰 1회(be-build-ci·be-docs): Medium 1(위 --accept-timeouts), Low 1(실패
  목록에서 5xx 누락) → 둘 다 고침. 확인 리뷰: Low 1(429와 기본값의 시간
  숫자) → 고침.
donghyeon.kang merged commit 9709404df9 into main 2026-11-19 09:35:24 +00:00
donghyeon.kang deleted branch ci/links-retry-window 2026-11-19 09:35:24 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#52