사후 분석: 빈 diff 요약으로 인증된 HTML 인터스티셜

결론부터 말하자면, 릴리스 게이트는 HTTP 상태 코드와 본문(body)의 진실성(truthiness)만을 확인했습니다. HTML 로그인 페이지가 200 OK로 반환되었기 때문에 유효한 모델 요약으로 간주되어 통과했습니다. 실제 "요약" 내용은 캡티브 포털 화면이었음에도 게이트는 녹색 상태를 유지했습니다.

이 사후 분석(postmortem)은 타임라인, 기여 요인, 그리고 영구적인 해결책을 다룹니다. 이는 단순한 재정리가 아닌 실패 분석입니다.

범위 참고 사항: 아래 타임라인은 고객사 사고가 아닌 로컬 재현 장치(reproduction harness)에서 재구성된 것입니다. 모든 명령어와 코드 조각은 작성된 그대로 실행 가능합니다.

게이트가 실제로 확인했던 것

게이트는 세 가지 조건을 가지고 있었고, 이 세 조건 모두 잘못된 페이로드(payload)에 의해 충족되었습니다.

response.status_code == 200
len(response.text) > 0
요청 중 예외가 발생하지 않음

HTML 오류 페이지는 이 세 가지 조건을 모두 만족시킵니다. 래퍼(wrapper)의 JSON 파싱은 경고를 기록하고 계속 진행하는 try/except 블록 안에 있었습니다.

설계 의도는 합리적이었습니다. 하지만 구현은 전송 메타데이터(transport metadata)를 페이로드 의미론(payload semantics)의 대리 지표(proxy)로 신뢰했습니다. 이 둘은 서로 다른 계약(contract)입니다.

재구성된 타임라인

모든 타임스탬프는 UTC이며 장치 로그에서 가져온 것입니다.

09:12:04 — 야간 작업이 무료 서버 인스턴스의 모델 엔드포인트에 diff를 게시합니다.
09:12:39 — 엔드포인트 앞의 게이트웨이가 200과 Content-Type: text/html로 응답하며 로그인 인터스티셜(interstitial)을 반환합니다.
09:12:39 — 클라이언트가 status=200 bytes=412를 기록하고 넘어갑니다. 바이트 수가 0이 아니므로 아무것도 잘못된 것처럼 보이지 않습니다.
09:12:41 — JSON 디코딩에 실패합니다. 래퍼가 ValueError를 포착하여 warn: non-JSON response 경고를 발생시키고 빈 문자열("")을 반환합니다.
09:12:42 — 게이트는 빈 요약을 읽습니다. 빈 문자열의 경우, 발견 사항 목록은 비어 있습니다. 발견 사항이 없다는 것은 차단 요소(blocker)가 없다는 의미입니다.
09:12:43 — 패치가 verified로 레이블링되고 병합 대기열에 추가됩니다.
09:52:10 — 사람이 요약 창이 비어 있다는 것을 알아차리고 실행을 중단합니다.

전체 교환에서 Content-Type의 20바이트가 유일하게 정직한 신호였습니다. 아무도 그것을 읽지 않았습니다.

재현 장치 (The reproduction harness)

네 개의 파일이 이 실패를 엔드투엔드로 재현합니다. 어떤 요약 파이프라인을 신뢰하기 전에 이것들을 실행하세요.

1. HTML과 200 코드를 반환하는 스텁(stub) 엔드포인트

# stub_endpoint.py
from http.server import BaseHTTPRequestHandler, HTTPServer

...

python stub_endpoint.py로 시작하세요. 이 서버는 모든 POST 요청에 인터스티셜을 응답합니다.

2. 이를 거부하는 계약(contract) 검증기

검증기는 전송 경계(transport boundary)에서 실행됩니다. 다운스트림 코드가 페이로드(payload)를 보기 전에 모양(shape) 단계에서 거부합니다.

# contract.py
REQUIRED = {"summary": str, "findings": list}

...

.split(";")[0]에 주목하세요. 실제 엔드포인트는 application/json; charset=utf-8을 전송합니다. 원시 헤더(raw header)에 대한 순진한 동등성 검사(naive equality check)는 유효한 응답을 망가뜨립니다.

3. 실패를 고정하는 테스트

# test_contract.py
import requests, pytest
from contract import validate_summary, ContractError
...

pytest -q test_contract.py를 실행하세요. 이 테스트는 이전 래퍼(wrapper)에서는 실패하고 검증기에서는 통과합니다. 그 차이가 전체 수정 사항입니다.

4. 일일 작업용 드리프트 카나리(drift canary)

계약은 예고 없이 변경됩니다. 카나리는 병합 창(merge window)이 열리기 전에 드리프트를 포착합니다.

#!/usr/bin/env bash
# shape-canary.sh
set -euo pipefail
...

시간당 스케줄링하세요. 카나리 실패는 경고가 아닌 페이지(page)를 발생시켜야 합니다.

기여 요인 (Contributing factors)

다섯 가지 요소가 결합되었습니다. 그중 어느 것도 단일한 근본 원인은 아니며, 이것이 수정 사항이 계층적(layered)인 이유입니다.

유효성으로 사용된 진리값(Truthiness). 비어있지 않은 본문이 유효한 본문을 의미하지 않습니다.
예외 포용(Exception swallowing). except ValueError가 오류를 전파하는 대신 빈 문자열을 반환했습니다.
메타데이터 신뢰. 상태 코드와 바이트 수가 의미적 보장으로 취급되었습니다.
부정적 피처(Negative fixtures) 부재. 테스트 스위트에는 HTML-200 케이스가 없어 구멍이 테스트되지 않았습니다.
관측 가능성 격차(Observability gap). 로그는 상태와 크기만 포착하고 콘텐츠 유형이나 본문 해시(body hash)는 포착하지 못했습니다.

무료 모델 접근과 무료 서버 옵션 덕분에 운영 비용이 저렴했고, 그것이 핵심입니다. 비용이 저렴하다는 것은 더 많은 실행을 의미하고, 더 많은 재시도를 가능하게 하며, 공유 게이트웨이 뒤에 숨어 있을 기회를 늘린다는 뜻입니다.

공유 게이트웨이는 인터스티셜(interstitials)을 방출합니다. 세션 만료, 속도 제한 화면, 프록시 알림 등 모든 것이 200 코드를 가진 HTML을 반환합니다. 이는 제품의 결함이 아니라 배포상의 특성입니다.

유료 전용 파이프라인 역시 같은 벽에 부딪힙니다. 다만 그 빈도가 덜하여 찾기 어려울 뿐입니다.

공개 정보: 이 기사는 MonkeyCode의 제품 아웃리치(product outreach)의 일환으로 작성되었습니다. 운영자는 무료 등급에 초기 할당량 1,000만 토큰과 함께 무료 서버 옵션이 포함되어 있다고 명시합니다. 할당량과 약관은 변경될 수 있으므로 프로젝트 페이지에서 현재 약관을 확인하십시오.

지속 가능한 해결책 (The durable fix)

우선순위에 따라 네 가지 변경 사항입니다.

경계(boundary)에서 유효성 검사. 하나의 함수가 응답 형태를 소유해야 합니다. 하위 단계에서는 원시 전송 출력을 파싱해서는 안 됩니다.
닫힌 실패 (Fail closed). ContractError는 실행을 중단시켜야 하며, 절대 빈 기본값을 반환해서는 안 됩니다.
빈 값과 무효 값을 분리. findings: []는 유효한 결과입니다. findings 키가 누락된 것은 그렇지 않습니다. 이 둘을 다른 종료 코드로 추적해야 합니다.
계약(contract)에 캐나리아 테스트 적용. 스케줄링으로 shape-canary.sh를 실행하고 드리프트(drift) 발생 시 경고해야 합니다.

종료 코드들은 이러한 구분을 운영적으로 만듭니다:

# 0 = 유효한 요약, 2 = 계약 위반, 3 = 전송 실패
python run_summary.py || case $? in
  2) echo

응답 스키마의 소유자가 없는 Teams는 이를 채택해서는 안 됩니다. 한 개발자에 의해 관리되는 단일 엔드포인트 프로토타입 역시 마찬가지입니다. 그 규모에서는 오버헤드가 위험보다 큽니다.

## 배포 전 검증 체크리스트

-   diff를 게시하고 요약 창이 비어있지 않고 사람이 읽을 수 있는지 확인합니다.
-   stub을 `text/html`로 변경하고 종료 코드 2가 나오는 실행 블록을 확인합니다.
-   실제 엔드포인트에 대해 canary를 실행하고 종료 코드 0이 나오는지 확인합니다.
-   모든 호출에서 로그가 콘텐츠 유형과 바디 해시를 기록하는지 확인합니다.

녹색 게이트는 페이로드가 이해되었다는 것을 의미해야 합니다. 상태 코드와 바이트 카운트만으로는 이를 인증할 수 없습니다. 유효성이 검증된 계약(validated contract)만이 할 수 있습니다.

Harness를 재현하고 싶다면, 무료 모델 접근 및 무료 서버 옵션만으로 두 프로세스를 구축하고 게이트가 올바르게 실패하는지 확인할 수 있습니다.