url 형식 검증을 Bean Validation 이 아니라 {@code ProductLink.parse} 에 맡긴다 — blank·형식·스킴 * 위반이 전부 계약 코드 INVALID_URL 하나로 떨어져야 하기 때문이다. * - *
headlessFirst 를 primitive boolean 이 아니라 Boolean 으로 받는 이유: Jackson 3 는 + *
headlessFirst·headlessAllowed 를 primitive boolean 이 아니라 Boolean 으로 받는 이유: Jackson 3 는 * FAIL_ON_NULL_FOR_PRIMITIVES 가 기본 on 이라, 이 선택 필드를 안 보내는 구버전 호출자의 요청이 400 으로 - * 깨진다(통합 테스트로 실측). 의미는 {@code ProductLinkExtractor.extract} 의 headlessFirst 와 같다. + * 깨진다(통합 테스트로 실측). 의미는 {@code ProductLinkExtractor.extract} 의 같은 이름 파라미터와 같다. + * + *
headlessAllowed 의 누락 정규화가 false 인 것은 fail-safe 다 — 이 필드를 모르는 구버전 호출자의 요청은 + * "허가 없음"으로 떨어져 헤드리스를 타지 않는다. 반대로 두면 허가 계약이 배포 순서에 따라 조용히 뚫린다. * *
model 은 호출자가 지정한 LLM 모델이며 선택 필드다. 안 보내면 null 이 되어 기본 모델을 쓴다(String 이라 * primitive 함정은 없다). 빈 문자열·공백 처리는 GeminiHttpClient 의 후보 계산이 흡수한다. */ -public record LinkExtractionRequest(String url, Boolean headlessFirst, String model) { +public record LinkExtractionRequest(String url, Boolean headlessFirst, Boolean headlessAllowed, String model) { public LinkExtractionRequest { headlessFirst = Boolean.TRUE.equals(headlessFirst); + headlessAllowed = Boolean.TRUE.equals(headlessAllowed); } } diff --git a/src/main/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractor.java b/src/main/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractor.java index ae3b87c..9d47dee 100644 --- a/src/main/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractor.java +++ b/src/main/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractor.java @@ -22,6 +22,10 @@ * 최적화로만 남긴다는 설계를 이 승격이 지킨다. * * + *
단 헤드리스 진입 3경로(직행·차단 승격·불완전 승격)는 전부 요청의 headlessAllowed 허가 뒤에 있다 — 허가가 + * 없으면 "비싸고 느려서" 가 아니라 "써서는 안 되므로" 열리지 않는다. 이 서비스는 허가 대상을 알지 못하고 판정도 + * 하지 않는다(무상태): 허가의 단일 진실은 호출자 쪽에 있고 여기서는 요청 단위 플래그로만 받는다. + * *
에스컬레이션 축(plain 확정 → headless)은 호출자 outbox 의 재시도 축(일시 오류 → 같은 plain 재시도)과 * 직교한다. 차단·불완전 결과는 재시도 축에서 이미 확정 실패(422)라 그 슬롯(attemptCount)에 얹을 수 없다. 그래서 * 여기서 별도로 판정한다. @@ -54,9 +58,12 @@ public class FallbackProductLinkExtractor implements ProductLinkExtractor { private final HeadlessExtractionProperties headlessProperties; @Override - public ProductSnapshot extract(ProductLink link, boolean headlessFirst, String model) { - // 호출자 정책이 이 서비스의 스위치를 앞설 수는 없다 — 스위치가 꺼져 있으면 headlessFirst 힌트도 무시한다. - if (!headlessProperties.enabled()) { + public ProductSnapshot extract(ProductLink link, boolean headlessFirst, boolean headlessAllowed, String model) { + // 두 조건이 모두 서 있어야 헤드리스가 열린다. enabled 는 이 서비스의 운영 비상 차단(호출자 정책이 앞설 수 + // 없다), headlessAllowed 는 이 대상에 브라우저를 써도 되는지에 대한 호출자의 허가다. 둘 중 하나라도 + // 없으면 plain 만 타고 헤드리스 진입 3경로(직행·차단 승격·불완전 승격)가 한꺼번에 닫힌다 — 아래 분기가 + // 전부 이 가드 뒤에 있는 것이 그 보장이다. headlessFirst 는 허가가 선 뒤에만 의미를 갖는 라우팅 힌트다. + if (!headlessProperties.enabled() || !headlessAllowed) { return plain.extract(link, model); } diff --git a/src/main/java/com/depromeet/piki/extractor/extraction/ProductLinkExtractor.java b/src/main/java/com/depromeet/piki/extractor/extraction/ProductLinkExtractor.java index 2a8d3a1..fa78e46 100644 --- a/src/main/java/com/depromeet/piki/extractor/extraction/ProductLinkExtractor.java +++ b/src/main/java/com/depromeet/piki/extractor/extraction/ProductLinkExtractor.java @@ -9,12 +9,15 @@ public interface ProductLinkExtractor { /** * @param headlessFirst 호출자(core)의 플랫폼 라우팅 정책 힌트. 정책의 단일 진실은 호출자 쪽 동적 설정(DB, * 백오피스)에 있고, 무상태인 이 서비스는 요청 단위 힌트로만 받는다. true 면 plain(정적 fetch)을 건너뛰고 - * 처음부터 헤드리스로 추출한다 — 단 이 서비스의 헤드리스 스위치가 꺼져 있으면 무시된다. - */ - /** + * 처음부터 헤드리스로 추출한다 — 단 이 서비스의 헤드리스 스위치가 꺼져 있으면 무시된다. 힌트일 뿐이라 + * headlessAllowed 가 false 면 함께 무시된다(허가가 라우팅보다 앞선다). + * @param headlessAllowed 이 대상에 헤드리스를 써도 되는지에 대한 호출자의 허가. false 면 어떤 경로로도 + * 헤드리스를 타지 않는다 — 직행(headlessFirst)·차단 승격·불완전 승격 셋 다 닫힌다. 허가 대상의 단일 + * 진실은 호출자(core) 쪽에 있고, 무상태인 이 서비스는 요청 단위로만 받는다. 누락은 false 로 정규화되는 + * fail-safe 다({@code LinkExtractionRequest}). * @param model 호출자가 지정한 LLM 모델 힌트. headlessFirst 와 같은 성질이다 — 정책의 단일 진실은 호출자 쪽 * 동적 설정(DB, 백오피스)이고 무상태인 이 서비스는 요청 단위로만 받는다. null 이면 기본 모델을 쓰며, * 지정 모델이 사라졌으면 기본 모델로 대체된다. */ - ProductSnapshot extract(ProductLink link, boolean headlessFirst, String model); + ProductSnapshot extract(ProductLink link, boolean headlessFirst, boolean headlessAllowed, String model); } diff --git a/src/test/java/com/depromeet/piki/extractor/api/ExtractionLinkIntegrationTest.java b/src/test/java/com/depromeet/piki/extractor/api/ExtractionLinkIntegrationTest.java index 81944af..4efe841 100644 --- a/src/test/java/com/depromeet/piki/extractor/api/ExtractionLinkIntegrationTest.java +++ b/src/test/java/com/depromeet/piki/extractor/api/ExtractionLinkIntegrationTest.java @@ -134,6 +134,21 @@ void headlessFirstHintIgnoredWhenHeadlessDisabled() throws Exception { .andExpect(jsonPath("$.name").value("직접파싱 상품")); } + @Test + @DisplayName("headlessAllowed 를 실어 보내도 요청이 깨지지 않고 plain 경로로 정상 추출한다") + void headlessAllowedFieldIsAcceptedOnTheWire() throws Exception { + // 이 필드는 primitive 로 받으면 안 보낸 요청이 400 으로 깨지는 함정이 있어(headlessFirst 와 같은 이유) + // wire 수용 자체가 계약이다. 필드를 안 보내는 구버전 호출자 쪽은 이 클래스의 나머지 케이스가 상시 검증한다. + stubGeminiClient.reset(); + stubPageFetcher.build = link -> PageContent.of(link, STRUCTURED_HTML); + + mockMvc().perform(post("/internal/extractions/link") + .contentType(MediaType.APPLICATION_JSON) + .content("{\"url\": \"https://shop.example.com/p/11\", \"headlessAllowed\": true}")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.name").value("직접파싱 상품")); + } + @Test @DisplayName("LLM 이 상품 페이지가 아니라고 판정하면 422 NOT_PRODUCT_PAGE 를 반환한다") void notProductPage() throws Exception { diff --git a/src/test/java/com/depromeet/piki/extractor/api/LinkExtractionRequestTest.java b/src/test/java/com/depromeet/piki/extractor/api/LinkExtractionRequestTest.java new file mode 100644 index 0000000..0835a4a --- /dev/null +++ b/src/test/java/com/depromeet/piki/extractor/api/LinkExtractionRequestTest.java @@ -0,0 +1,38 @@ +package com.depromeet.piki.extractor.api; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** + * 요청 계약의 선택 플래그 정규화. 특히 headlessAllowed 의 기본값은 안전 기본값(fail-safe)이라 계약의 일부다 — + * 이 필드를 모르는 구버전 호출자·필드를 빠뜨린 요청이 "허가받은 것"으로 흘러가면 허가 게이트가 배포 순서에 따라 + * 조용히 뚫린다. + */ +class LinkExtractionRequestTest { + + @Test + @DisplayName("headlessAllowed 를 안 보내면 허가 없음(false)으로 정규화된다") + void missingHeadlessAllowedDefaultsToDenied() { + LinkExtractionRequest request = new LinkExtractionRequest("https://shop.example.com/p", null, null, null); + + assertEquals(Boolean.FALSE, request.headlessAllowed()); + } + + @Test + @DisplayName("headlessAllowed=true 를 보내면 허가로 그대로 전달된다") + void explicitHeadlessAllowedIsPreserved() { + LinkExtractionRequest request = new LinkExtractionRequest("https://shop.example.com/p", null, true, null); + + assertEquals(Boolean.TRUE, request.headlessAllowed()); + } + + @Test + @DisplayName("headlessFirst 를 안 보내면 false 로 정규화된다") + void missingHeadlessFirstDefaultsToFalse() { + LinkExtractionRequest request = new LinkExtractionRequest("https://shop.example.com/p", null, null, null); + + assertEquals(Boolean.FALSE, request.headlessFirst()); + } +} diff --git a/src/test/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractorTest.java b/src/test/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractorTest.java index ab80eea..37af825 100644 --- a/src/test/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractorTest.java +++ b/src/test/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractorTest.java @@ -20,6 +20,9 @@ *
통합 테스트는 외부 경계(PageFetcher·GeminiClient)만 stub 하고 이 라우팅을 실제로 타므로, 분기 망라는 * 여기 단위에서 한다. 두 전략은 실제 빈이 네트워크/브라우저를 요구해 단위로 세울 수 없어, * LinkExtractionStrategy fake 로 "전략의 결과"만 주입한다. + * + *
헤드리스가 도는 케이스는 전부 headlessAllowed=true 를 넘긴다 — 허가가 헤드리스 진입의 전제 조건이기 + * 때문이다. 허가가 없을 때 3경로가 모두 닫히는지는 아래 headlessAllowed* 케이스가 따로 못박는다. */ class FallbackProductLinkExtractorTest { @@ -70,7 +73,7 @@ void headlessOffDelegatesToPlain() { throw new IllegalStateException("headless 는 호출되면 안 됨"); }); - ProductSnapshot result = fallback(false, plain, headless).extract(link, false, null); + ProductSnapshot result = fallback(false, plain, headless).extract(link, false, true, null); assertEquals(snapshot, result); assertEquals(1, plain.calls); @@ -85,7 +88,7 @@ void headlessOffPropagatesEscalatableFailure() { }); FakeStrategy headless = new FakeStrategy(l -> snapshot); - assertThrows(PageFetchException.class, () -> fallback(false, plain, headless).extract(link, false, null)); + assertThrows(PageFetchException.class, () -> fallback(false, plain, headless).extract(link, false, true, null)); assertEquals(0, headless.calls); } @@ -100,7 +103,7 @@ void escalatesToHeadlessOnEscalatableFailure() { FakeStrategy headless = new FakeStrategy(l -> headlessSnapshot); SimpleMeterRegistry registry = new SimpleMeterRegistry(); - ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, false, null); + ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, false, true, null); assertEquals(headlessSnapshot, result); assertEquals(1, plain.calls); @@ -120,7 +123,7 @@ void headlessOnButPlainSucceeds() { throw new IllegalStateException("headless 는 호출되면 안 됨"); }); - ProductSnapshot result = fallback(true, plain, headless).extract(link, false, null); + ProductSnapshot result = fallback(true, plain, headless).extract(link, false, true, null); assertEquals(snapshot, result); assertEquals(1, plain.calls); @@ -140,7 +143,7 @@ void headlessErrorIsCountedAndPropagated() { }); SimpleMeterRegistry registry = new SimpleMeterRegistry(); - assertThrows(Error.class, () -> fallback(true, plain, headless, registry).extract(link, false, null)); + assertThrows(Error.class, () -> fallback(true, plain, headless, registry).extract(link, false, true, null)); assertEquals( 1.0, registry.counter("product.extract.escalation", "outcome", "failed", "category", "FETCH_CLIENT_ERROR").count() @@ -160,7 +163,7 @@ void headlessFailureIsCountedAndPropagated() { }); SimpleMeterRegistry registry = new SimpleMeterRegistry(); - assertThrows(RuntimeException.class, () -> fallback(true, plain, headless, registry).extract(link, false, null)); + assertThrows(RuntimeException.class, () -> fallback(true, plain, headless, registry).extract(link, false, true, null)); assertEquals(1, plain.calls); assertEquals(1, headless.calls); assertEquals( @@ -180,7 +183,7 @@ void headlessFirstSkipsPlain() { FakeStrategy headless = new FakeStrategy(l -> headlessSnapshot); SimpleMeterRegistry registry = new SimpleMeterRegistry(); - ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, true, null); + ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, true, true, null); assertEquals(headlessSnapshot, result); assertEquals(0, plain.calls); @@ -199,7 +202,7 @@ void headlessFirstFailurePropagatesWithoutPlainFallback() { }); SimpleMeterRegistry registry = new SimpleMeterRegistry(); - assertThrows(RuntimeException.class, () -> fallback(true, plain, headless, registry).extract(link, true, null)); + assertThrows(RuntimeException.class, () -> fallback(true, plain, headless, registry).extract(link, true, true, null)); assertEquals(0, plain.calls); assertEquals(1, headless.calls); assertEquals(1.0, registry.counter("product.extract.headless_first", "outcome", "failed").count()); @@ -214,7 +217,7 @@ void headlessFirstIgnoredWhenDisabled() { throw new IllegalStateException("headless 는 호출되면 안 됨"); }); - ProductSnapshot result = fallback(false, plain, headless).extract(link, true, null); + ProductSnapshot result = fallback(false, plain, headless).extract(link, true, true, null); assertEquals(snapshot, result); assertEquals(1, plain.calls); @@ -230,7 +233,7 @@ void nonEscalatableFailureIsNeverEscalated() { }); FakeStrategy headless = new FakeStrategy(l -> snapshot); - assertThrows(PageFetchException.class, () -> fallback(true, plain, headless).extract(link, false, null)); + assertThrows(PageFetchException.class, () -> fallback(true, plain, headless).extract(link, false, true, null)); assertEquals(0, headless.calls); } @@ -246,7 +249,7 @@ void escalatesToHeadlessOnIncompleteSnapshot() { FakeStrategy headless = new FakeStrategy(l -> headlessSnapshot); SimpleMeterRegistry registry = new SimpleMeterRegistry(); - ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, false, null); + ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, false, true, null); assertEquals(headlessSnapshot, result); assertEquals(1, plain.calls); @@ -266,7 +269,7 @@ void incompleteEscalationReturnsHeadlessResultAsIs() { FakeStrategy headless = new FakeStrategy(l -> incomplete); SimpleMeterRegistry registry = new SimpleMeterRegistry(); - ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, false, null); + ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, false, true, null); assertEquals(incomplete, result); assertEquals(1, headless.calls); @@ -285,7 +288,7 @@ void headlessFirstIncompleteResultIsCountedFailed() { FakeStrategy headless = new FakeStrategy(l -> incomplete); SimpleMeterRegistry registry = new SimpleMeterRegistry(); - ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, true, null); + ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, true, true, null); assertEquals(incomplete, result); assertEquals(0, plain.calls); @@ -302,7 +305,7 @@ void incompleteEscalationFailurePropagatesWithoutReentry() { }); SimpleMeterRegistry registry = new SimpleMeterRegistry(); - assertThrows(PageFetchException.class, () -> fallback(true, plain, headless, registry).extract(link, false, null)); + assertThrows(PageFetchException.class, () -> fallback(true, plain, headless, registry).extract(link, false, true, null)); assertEquals(1, headless.calls); assertEquals( 1.0, @@ -318,7 +321,7 @@ void headlessOffReturnsIncompleteAsIs() { throw new IllegalStateException("headless 는 호출되면 안 됨"); }); - ProductSnapshot result = fallback(false, plain, headless).extract(link, false, null); + ProductSnapshot result = fallback(false, plain, headless).extract(link, false, true, null); assertEquals(incomplete, result); assertEquals(0, headless.calls); @@ -335,7 +338,79 @@ void productSnapshotFailureIsNotEscalated() { }); FakeStrategy headless = new FakeStrategy(l -> snapshot); - assertThrows(ProductSnapshotException.class, () -> fallback(true, plain, headless).extract(link, false, null)); + assertThrows(ProductSnapshotException.class, () -> fallback(true, plain, headless).extract(link, false, true, null)); + assertEquals(0, headless.calls); + } + + @Test + @DisplayName("허가가 없으면 plain 이 escalatable 차단으로 막혀도 headless 로 승격하지 않고 예외를 전파한다") + void headlessNotAllowedBlocksEscalation() { + // 허가는 "비싸니 아낀다"가 아니라 "써서는 안 된다"는 계약이라, 차단당했다는 사정이 허가를 대신하지 못한다. + FakeStrategy plain = new FakeStrategy(l -> { + throw PageFetchException.clientError(new RuntimeException("403")); + }); + FakeStrategy headless = new FakeStrategy(l -> { + throw new IllegalStateException("headless 는 호출되면 안 됨"); + }); + SimpleMeterRegistry registry = new SimpleMeterRegistry(); + + assertThrows( + PageFetchException.class, + () -> fallback(true, plain, headless, registry).extract(link, false, false, null)); + assertEquals(1, plain.calls); + assertEquals(0, headless.calls); + assertEquals( + 0.0, + registry.counter("product.extract.escalation", "outcome", "success", "category", "FETCH_CLIENT_ERROR").count() + ); + } + + @Test + @DisplayName("허가가 없으면 plain 결과가 불완전해도 headless 로 승격하지 않고 그대로 반환한다") + void headlessNotAllowedBlocksIncompleteEscalation() { + // 불완전 승격은 세 진입 경로 중 유일하게 plain 이 예외 없이 끝나는 경로다 — 여기로 허가가 새면 + // 게이트가 반쪽이 된다. 반환값은 응답 경계가 확정 실패(UNTRUSTWORTHY_VALUE)로 닫는 기존 계약 그대로다. + FakeStrategy plain = new FakeStrategy(l -> incomplete); + FakeStrategy headless = new FakeStrategy(l -> { + throw new IllegalStateException("headless 는 호출되면 안 됨"); + }); + + ProductSnapshot result = fallback(true, plain, headless).extract(link, false, false, null); + + assertEquals(incomplete, result); + assertEquals(1, plain.calls); + assertEquals(0, headless.calls); + } + + @Test + @DisplayName("허가가 없으면 headlessFirst 직행 힌트가 와도 무시하고 plain 만 탄다") + void headlessNotAllowedBeatsHeadlessFirstHint() { + // 라우팅 힌트(어디로 보낼까)와 허가(써도 되나)는 다른 질문이다 — 힌트가 허가를 만들어내지 못한다. + FakeStrategy plain = new FakeStrategy(l -> snapshot); + FakeStrategy headless = new FakeStrategy(l -> { + throw new IllegalStateException("headless 는 호출되면 안 됨"); + }); + SimpleMeterRegistry registry = new SimpleMeterRegistry(); + + ProductSnapshot result = fallback(true, plain, headless, registry).extract(link, true, false, null); + + assertEquals(snapshot, result); + assertEquals(1, plain.calls); + assertEquals(0, headless.calls); + assertEquals(0.0, registry.counter("product.extract.headless_first", "outcome", "success").count()); + } + + @Test + @DisplayName("허가가 없으면 escalatable 이 아닌 실패도 그대로 전파한다 (plain 단독 경로의 기존 계약)") + void headlessNotAllowedPropagatesNonEscalatableFailure() { + FakeStrategy plain = new FakeStrategy(l -> { + throw PageFetchException.blockedHost(); + }); + FakeStrategy headless = new FakeStrategy(l -> { + throw new IllegalStateException("headless 는 호출되면 안 됨"); + }); + + assertThrows(PageFetchException.class, () -> fallback(true, plain, headless).extract(link, false, false, null)); assertEquals(0, headless.calls); } }