헤드리스 홉 목록을 받아 상품 문서·차단 판정을 extractor 가 맡음

[m-a-king]

Situation

• 2026-09-07 prod 에서 에이블리 공유링크 2건이 NO_EXTRACTABLE_CONTENT 로 FAILED 됐다. renderer 가 3,188자 셸을 돌려줬고 셸 게이트가 그대로 확정 실패로 닫았다.
• 원인은 renderer 가 "어느 문서가 상품 페이지인가" 를 스스로 판단하다 오판한 것이다(renderer PR 참조). 에이블리는 서버 본문이 늘 3KB 셸이고 상품은 하이드레이션 뒤 DOM 에만 있다.

Task

• renderer 계약이 "최선의 HTML 한 장 + verdict" 에서 "거쳐 간 홉 목록(url·status·headers·body·dom)" 으로 바뀐다. 어느 홉의 어느 문서를 파이프라인에 태울지, 차단인지의 판단을 extractor 가 맡는다.
• renderer 배포는 수동이라 뒤처질 수 있으므로 구계약 응답도 읽어야 한다.

Action

홉 해석 (HeadlessProductLinkExtractor)

• 후보 순서: 마지막 홉부터 거슬러, 같은 홉 안에서는 dom 다음 body. 홈 피드·앱 유도로 튕긴 경우 상품은 앞 홉에 있고, 같은 홉에서는 하이드레이션된 dom 이 알차다.
• 차단 판정: status 401·403·405·429·490 또는 title 의 챌린지 마커(HeadlessBlockSignal). renderer 의 _block_reason 을 그대로 옮긴 것이고, 이제 홉 단위로 본다. 챌린지 홉을 지나 상품 홉에 도달했으면 차단이 아니다.
• 채택: 구조화 데이터가 잡히는 첫 후보. 없으면 마지막 홉의 dom 한 장을 기존 파이프라인(셸 게이트 → LLM)에 넘긴다. LLM 은 한 번만 부른다.

상황	결과
후보 중 구조화 데이터 있음	그 문서로 via=structured
후보는 있으나 구조화 없음	마지막 홉 dom 으로 셸 게이트 또는 LLM
모든 홉이 차단 신호	HEADLESS_BLOCKED(일시, 기존과 동일)
홉은 있으나 HTML 전부 빈값, 또는 홉 없음	HEADLESS_UPSTREAM(일시)

wire (HttpHeadlessRenderer)

• HeadlessRenderer 가 PageContent 대신 List<RenderedHop> 을 돌려준다. 가지치기는 후보를 만들 때 PageContent.of 가 한다.
• 매 홉 url 을 SSRF 가드에 통과시킨다. 어느 홉이든 내부망이면 렌더 전체를 거부한다. 형식 위반 url 은 원본 link 로 폴백한다(기존 final_url 규칙과 같다).
• 구계약(html·final_url·status) 응답은 홉 하나(dom=html)로 읽는다. renderer 가 먼저든 나중이든 배포 순서와 무관하게 동작한다.
• 요청에서 include_html 을 뺐다.

범위 밖

• 차단 status 세분화(접근 거부·챌린지·CAPTCHA·레이트리밋·상품 없음)는 infra 에러 코드 카탈로그가 additive 로 먼저 늘어야 해서 이번 PR 에 넣지 않았다. 404·410 은 지금처럼 셸 게이트로 흘러 NO_EXTRACTABLE_CONTENT 가 된다.

Result

• 홉 해석 8케이스·wire 12케이스를 단위로 고정했다. 에이블리 실패 케이스는 "body 셸 + dom 상품" 홉으로 재현해 LLM 없이 via=structured 로 닫히는 것을 확인했다.
• 로컬 전체 테스트에서 ExtractionErrorCodeCatalogTest 2건이 실패했는데 워크트리에 shared-infra/ 카탈로그가 설치되지 않은 환경 문제다(CI 는 infra 를 체크아웃한다). 이 변경과 무관.
• 배포 순서: 이 PR 먼저, renderer 나중.

---

연관 이슈

[github-actions]

Discord 스레드 연동용 메타데이터입니다. discord-pr-bot 워크플로가 자동 생성하며, 수정·삭제하면 PR 과 Discord 알림 연동이 끊깁니다.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: ab18c169-2639-4fb5-b8c7-f6e281c9e94a

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}