style: Lombok 생성자·@Slf4j 도입 + 전 소스 주석 Javadoc 전환 - #18
Merged
Conversation
- renderer(구 PIKI-HeadlessBrowser)가 파싱을 걷어내고 HTML 렌더러로 재편되면서 /render 응답에서 title/price 가 빠지고 verdict 가 OK|BLOCK|EMPTY|ERROR 로 바뀜. 기존 번역 규칙(BLOCK→차단, 그 외는 html 유무)은 verdict 세부 값에 결합돼 있지 않아 그대로 유효 — 안 쓰게 된 source 필드만 제거하고 주석·테스트·api-contract 서술을 신계약으로 갱신 - compress=true 요청 시 응답이 zstd raw 바이트(X-Encoding: zstd)로 옴 → 해제 분기를 요청 플래그가 아닌 응답 헤더 기준으로 구현. 구버전 renderer 는 compress 필드를 무시(pydantic 기본)하고 plain JSON 을 주므로 renderer/extractor 어느 쪽이 먼저 배포돼도 안전 — 기본 on, product.extract.headless.compress 가 kill-switch - 사전 해제는 ZstdDictionaries 신설(파일명=사전ID, renderer compress.py 의 DICT_ID 와 대칭). X-Zstd-Dict 빈값=plain 해제, 미보유 사전ID 는 롤아웃 규약(사전은 extractor 먼저 배포) 위반 신호라 일시 실패(HEADLESS_UPSTREAM)로 번역. zstd-dict-dir 오설정은 부팅 fail-fast(baseUrl 검증과 같은 결) - zstd-jni(JNI) 로드가 Java 25 에서 native access 경고를 내(미래 JDK 는 차단, JEP 472) 테스트 jvmArgs 와 Dockerfile ENTRYPOINT 에 --enable-native-access=ALL-UNNAMED 명시
- 구 PIKI-HeadlessBrowser 가 TeamPiKi/renderer 로 재편되면서 CLAUDE.md 와 주석의 참조 명칭을 현행화 (주석만 바뀐 파일이라 신계약 대응 커밋과 분리)
충돌 27 hunk 를 '원격의 의미 + 이 브랜치의 스타일' 로 해결했다. 원격이 새로 들여온 사실은 전부 살리고(ExtractionMethod·withOrigin·finalUrl/method 근거·maxRedirects 상향 근거·verdict 설명), 주석 형식은 Javadoc 규약을 적용했다. 원격의 PIKI-Server → core 명칭 정리도 반영. 원격 산출물 무손실 확인: ExtractionMethod·ObservationConfig 파일 존재, withOrigin·finalUrl·method 필드, maxRedirects 기본값 5, testing-principles import 유지. 전체 테스트·javadoc 통과. 원격이 새로 들여온 ExtractionResponse 의 명시적 Logger 선언도 @slf4j 규약에 맞췄다.
|
Important Review skippedToo many files! This PR contains 103 files, which is 3 over the limit of 100. To get a review, narrow the scope: Upgrade to a paid plan to raise the limit. This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (103)
You can disable this status message by setting the 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. Comment |
m-a-king
added a commit
that referenced
this pull request
Aug 3, 2026
) * fix: 추출 경로의 안전 공백 3건 - 헤드리스 redirect SSRF·null 바이트 오분류·이미지 경로 검증 우회 주석 정리(#18) 중 코드를 정독하다 드러난 것들이다. 셋 다 회귀 테스트를 함께 넣었고, 수정 전에는 네 테스트가 모두 실패함을 확인했다. 1) 헤드리스 경로의 redirect SSRF — HttpHeadlessRenderer 는 원본 URL 만 InternalHostGuard 로 검증하고, 렌더 서비스가 따라간 최종 URL(final_url)은 검증 없이 그대로 썼다. '외부 URL → 내부 주소' redirect 를 렌더 서비스가 대신 따라가 주면 내부망 응답이 상품 HTML 로 흘러들고, #17 이후로는 그 주소가 응답 계약의 finalUrl 로 호출자의 정체성(canonical) 입력까지 나간다. 정적 fetch 가 매 hop 을 검증하는 것과 같은 기준을 세웠다 — BLOCKED_HOST 면 렌더 전체를 거부하고, DNS 미해결처럼 '검증 불가'인 경우만 원본 link 로 폴백해 렌더 결과를 살린다. 2) ProductImage.of(null, ...) 가 500 — null 검사 전에 bytes.length 를 읽어 NPE 가 됐다. 계약상 확정 실패(422)여야 할 입력이 일시 실패로 오분류돼 호출자가 무의미한 재시도를 한다. 3) 이미지 경로가 정규화를 우회 — GeminiImageResult 가 ProductSnapshot.fromExtracted 를 건너뛰고 직접 생성해, 같은 LLM 이 만든 값인데도 음수 가격·공백 이름이 link 경로에서는 막히고 이미지 경로에서만 호출자에게 새어 나갔다. 같은 팩토리를 태워 검증을 일치시켰다. * docs: 헤드리스 SSRF 검증의 사후 한계 명시 + 백로그 현행화 (CodeRabbit 리뷰 반영) CodeRabbit 이 지적한 대로 resolveFinalUrl 의 검증은 렌더 응답 이후에 도는 사후 검증이라, 내부 주소로의 요청 자체와 '외부 → 내부 → 외부' 체인은 막지 못한다. 코드가 그 한계를 스스로 말하도록 Javadoc 에 명시하고(다층 방어의 마지막 층이라는 위치까지), hop 단위 차단이 renderer 소관으로 남았음을 백로그에 남긴다. renderer 에 SSRF·egress 가드가 없음은 실측 확인했다. * docs: 백로그 2번 해소 표시 누락 보정
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
무엇을
세 갈래의 스타일 정리를 한 브랜치에 담았다. 전부 동작 등가이며, 산출물은 규약(
CLAUDE.md)과 결정 기록(docs/style-decisions.md)에 남겼다.1. Lombok — 보일러플레이트 표적 채택 (12개 클래스)
순수 필드-대입 생성자만
@RequiredArgsConstructor로 대체했다.@Qualifier는 필드로 옮기고lombok.config의copyableAnnotations로 생성자 파라미터에 복사되게 했다.조립 로직이 있는 생성자 4개는 손으로 유지했다 —
HttpPageFetcher·HttpHeadlessRenderer(주입받은 resolver 로InternalHostGuard를 직접 조립, IP-pin 계약),GeminiHttpClient(RestClient 빌드),RequestScopedDnsResolver(편의 생성자 2개).값 객체는 여전히
record이고@Builder·@Setter·@Data·@Getter는 미채택이다.2. 로거 —
@Slf4j(12개 클래스)명시적
private static final Logger log = LoggerFactory.getLogger(X.class)를 전부 애노테이션으로 바꿨다. 로그 출력은 바뀌지 않는다 — 바이트코드를 확인했다:수동 선언과 동일(필드 수정자·로거 이름 모두). 전 대상이 필드명
log, 인자가 자기 클래스여서 예외 케이스가 없었다.3. 주석 → Javadoc (97개 파일)
선언부 주석을 Javadoc 으로 옮기고, "숙련 Java 독자가 이 주석 없이 놓칠 정보가 있는가" 하나를 기준으로 정리했다.
| UNIQLO KR꼬리표와lastIndexOf인 이유, 29cmcontentUrl, 카카오 charset 누락), Java 함정(intValuewrap vsintValueExact, Jackson 3FAIL_ON_NULL_FOR_PRIMITIVES), 보안·계약 근거(IP pin 은 같은 resolver 로만 성립, 매 hop SSRF 재검증)@param, 클래스 Javadoc 과의 중복, 흐름 나레이션, SSOT 위반(호출자 repo 의 수치·코드 기본값·다른 클래스가 정본인 분류)./gradlew javadoc을 고쳤다. 이 브랜치 이전엔 error 1 로 실패하던 상태였다(GeminiPropertiesRetry Javadoc 본문 줄머리의@DefaultValue→ unknown block tag). 이제 error 0.origin/main 병합
작업 중 origin/main 이 11커밋 앞서갔고(#3~#17), 그중 #17 이 같은 파일들을 건드려 27 hunk 가 충돌했다.
원격의 의미 + 이 브랜치의 스타일로 해결했고, 원격 산출물 무손실을 실측 확인했다:ExtractionMethodenum ·ObservationConfigProductSnapshot.withOrigin· 편의 생성자ExtractionResponse의finalUrl·methodmaxRedirects기본값5(원격 상향값 유지)testing-principlesimport원격의
PIKI-Server→core명칭 정리도 반영했고, 원격이 새로 들여온ExtractionResponse의 명시적 Logger 도@Slf4j규약에 맞췄다.검증
./gradlew test·./gradlew javadoc통과 (javadoc error 0)후속 (이 PR 범위 밖)
주석을 쓰며 코드를 정독하다 드러난 이상 8건을
docs/style-decisions.md§4 에 기록만 해 뒀다. 심각한 셋은 헤드리스 경로의 redirect SSRF 비대칭,ProductImage.of(null)이 422 대신 500, 이미지 경로가ProductSnapshot.fromExtracted정규화를 우회하는 것이다.