119 lines
8.3 KiB
Markdown
119 lines
8.3 KiB
Markdown
---
|
|
kind: CASE
|
|
slug: a-five-second-string-that-broke-every-prod-deploy
|
|
title: connection-timeout: 5s가 모든 prod 배포를 시작 실패시켰고 local만 통과했다
|
|
topic: transaction-deadline-and-pool
|
|
project: clean-architecture-backend-template
|
|
status: 게시 전
|
|
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
|
|
rootTreeNode: case:a-five-second-string-that-broke-every-prod-deploy
|
|
evidenceCapturedOn: 2026-09-02
|
|
body: case-a-five-second-string-that-broke-every-prod-deploy.body.md
|
|
assets:
|
|
- key: a-five-second-string-that-broke-every-prod-deploy-bind
|
|
file: ../../../final/evidence/rendered/a-five-second-string-that-broke-every-prod-deploy-bind.svg
|
|
- key: a-five-second-string-that-broke-every-prod-deploy
|
|
file: ../../../final/evidence/rendered/a-five-second-string-that-broke-every-prod-deploy.svg
|
|
evidence:
|
|
- ../../../final/evidence/raw/a-five-second-string-that-broke-every-prod-deploy-bind.txt
|
|
- ../../../final/evidence/raw/a-five-second-string-that-broke-every-prod-deploy.txt
|
|
source:
|
|
- 이 사건의 1차 기록은 `app-bootstrap/src/main/resources/application.yml` 의 해당 키 주석이다. 분석 문서 쪽에는 이 사건을 다루는 절이 없고, 후보 원장이 지정한 `final/document.md#a05` 의 절 번호는 그 파일에 존재하지 않는다. 원장 자신도 이 항목의 근거를 설정 파일 주석의 사후 기록으로 적고 있다.
|
|
---
|
|
|
|
# connection-timeout: 5s가 모든 prod 배포를 시작 실패시켰고 local만 통과했다
|
|
|
|
풀 연결 타임아웃 기본값이 `5s` 로 출하됐다. 이 키는 `long` 밀리초에 바인딩되므로 문자열은 변환 단계에서 거절된다. 로컬 프로파일이 값을 덮어쓰고 있어서 로컬로 띄우는 실행은 통과했다.
|
|
|
|
## 관계
|
|
|
|
- **로컬이 다른 DB면 로컬 테스트는 다른 시스템에 대한 진술이다**
|
|
통과한 레인이 다른 값을 보고 있었다.
|
|
- **validator가 요청을 서비스하지 않는 datasource를 검증하고 있었다**
|
|
같은 app-bootstrap 모듈에서 startup validator가 실제 바인딩 단계와 다른 파서를 사용해 형식 오류를 잡지 못했다.
|
|
|
|
## 문제
|
|
|
|
그 속성의 바인딩 대상은 HikariConfig 의 setConnectionTimeout(long) 세터다. 밀리초 정수만 받는다.
|
|
|
|
같은 출하 파일의 server.tomcat.connection-timeout 은 지속 시간에 바인딩되고 20s 로 적혀 있다. 마지막 단어가 같고 형식이 다르다.
|
|
|
|
## 결론
|
|
|
|
프로파일 오버라이드가 형식 결함을 가렸다. 로컬에는 오버라이드가 있었고 나머지에는 없었다.
|
|
|
|
풀 제약 검증기는 같은 키를 `DurationStyle`로 읽어서 `5s`를 5000밀리초로 해석한다. 하지만 이 검증기는 `SmartInitializingSingleton` 단계에서 실행되므로, `HikariDataSource` 빈 바인딩이 먼저 실패하면 검증기까지 도달하지 않는다.
|
|
|
|
지금은 출하 기본값이 정수로 고쳐져 있고, 밀리초 키 일곱 개의 출하 기본값이 정수인지 확인하는 정적 가드가 있다.
|
|
|
|
## 검증 환경
|
|
|
|
Spring Boot : 4.0.8
|
|
HikariCP : 7.0.2
|
|
OpenJDK : 21.0.12
|
|
확인 방식 : 출하 설정과 바인딩 대상 확인, 실제 바인더로 두 형식 주입
|
|
소스 수정 : x
|
|
|
|
## 재현 조건
|
|
|
|
1. 오버라이드가 없는 프로파일에 spring.datasource.hikari.connection-timeout=5s 를 두고 부팅하면 HikariDataSource 빈 생성에서 바인딩이 실패한다.
|
|
2. 같은 키를 저장소가 쓰는 Spring Boot·HikariCP 산출물의 바인더에 직접 넣으면 같은 예외 사슬이 나온다.
|
|
3. 같은 출하 파일에서 server.tomcat.connection-timeout 의 형식을 확인한다.
|
|
4. 시작 검증기가 같은 키를 어떤 파서로 읽는지, 어느 시점에 도는지 확인한다.
|
|
|
|
## 본문
|
|
|
|
<!-- body:start -->
|
|
|
|
`spring.datasource.hikari.connection-timeout`은 `HikariConfig#setConnectionTimeout(long)`에 바인딩되므로 Spring은 이 값을 `long` 밀리초 값으로 변환해야 한다.
|
|
|
|
기본값이 `5s` 로 출하됐다. 지금은 `${APP_DATASOURCE_CONNECTION_TIMEOUT:5000}` 로 고쳐져 있다.
|
|
|
|
## 통과한 레인은 그 값을 보고 있지 않았다
|
|
|
|
설정 파일의 주석이 사건을 기록한다. prod 와 dev 배포가 전부 시작에 실패했고, 로컬은 `application-local.yml` 이 값을 덮어쓰고 있어서 통과했다는 것이다. 그래서 결함을 만날 수 있는 곳이 prod 레인뿐이었다.
|
|
|
|
테스트 레인도 이 기본값을 보지 않는다. `application-test.yml` 이 자기 몫으로 `connection-timeout: 30000` 을 들고 있다.
|
|
|
|
## 바인더에 직접 넣으면 어디서 끊기는지 보인다
|
|
|
|
:::evidence key="a-five-second-string-that-broke-every-prod-deploy-bind" alt="저장소가 쓰는 Spring Boot 와 HikariCP 산출물로 같은 속성 키에 두 형식을 넣어 실제로 바인딩한 실행 결과. 지속 시간 문자열은 예외 사슬 세 단계로 거절되고 정수는 값이 그대로 들어간다." caption="Spring Boot 4.0.8 · HikariCP 7.0.2 — 같은 키, 두 형식, 실제 바인딩" zoom="true"
|
|
:::
|
|
|
|
예외는 바인딩 실패 → 문자열을 `long`으로 변환하는 실패 → `"5s"` 숫자 형식 예외 순으로 이어진다. 같은 프로퍼티에 `5000`을 넣으면 `long` 값으로 정상 바인딩된다.
|
|
|
|
## 같은 파일에 같은 이름이 두 형식으로 있다
|
|
|
|
:::evidence key="a-five-second-string-that-broke-every-prod-deploy" alt="코드베이스에서 출하 설정 파일의 두 네임스페이스에 같은 이름의 키가 다른 형식으로 있는 것과, 앞쪽이 바인딩되는 세터의 long 시그니처, 같은 키를 읽는 시작 검증기의 인터페이스와 파싱 함수, 그리고 그 형식을 막는 정적 가드의 키 목록과 그 가드가 한 번 잘못 탐지했던 설정을 뽑은 출력. 한 파일 안에서 같은 마지막 단어가 정수와 지속 시간 두 형식으로 쓰인다는 것이 그 출력에 그대로 보인다." caption="같은 파일의 두 네임스페이스 · long 세터 · 검증기의 다른 파서 · 정적 가드의 키 목록" zoom="true"
|
|
:::
|
|
|
|
`hikari` 아래의 키는 정수를 받고, `tomcat` 아래의 키는 `20s` 로 적혀 있다. 전체 경로는 다르고 마지막 단어만 같다.
|
|
|
|
## 검증기는 이 값을 다르게 읽고, 이 값에는 도달하지 못한다
|
|
|
|
풀 제약 검증기가 같은 키를 읽는다. 파서는 `DurationStyle.detectAndParse` 다. 그 규칙에서 `5s` 는 5000 밀리초이고 하한을 넘으므로 유효한 값이다.
|
|
|
|
이 검증기는 `SmartInitializingSingleton`이라 모든 singleton 생성 뒤에 실행된다. `5s`는 그보다 앞선 `HikariDataSource` 빈 생성의 바인딩 단계에서 실패하므로 검증기가 이 값을 판정할 기회가 없다.
|
|
|
|
## 두 문서가 같은 관용을 반대로 부른다
|
|
|
|
설정 파일의 주석은 그 관용을 결함으로 부른다. 잘못된 기본값이 지원되는 것처럼 보이게 만든 것이 그 관용이고, 여기서 조용히 고치는 대신 열린 항목으로 기록해 둔다고 적는다.
|
|
|
|
파서 쪽 javadoc 에는 Spring Boot 가 지속 시간 속성에 받아 주는 밀리초 정수와 단순 지속 시간과 ISO-8601 을 똑같이 받는다고 계약으로 적혀 있다. 그리고 테스트 하나가 `connection-timeout=5s` 와 `validation-timeout=PT3S` 로 컨텍스트가 실패하지 않음을 고정한다.
|
|
|
|
한쪽은 열린 결함이라 적고 다른 쪽은 고정된 계약이라 적는다. 두 기술은 서로를 참조하지 않는다.
|
|
|
|
## 같은 함정을 이름으로 막는다
|
|
|
|
정적 가드가 있다. 출하 설정 파일 넷을 Spring 의 yaml 로더로 직접 읽어 평탄화한 뒤, 밀리초 정수에 바인딩되는 키 일곱 개의 출하 기본값이 정수인지 확인한다.
|
|
|
|
부팅이 아니라 스캔이라 타입 목록을 손으로 들고 있다. 밀리초 키가 새로 생기면 그 목록에 줄을 더하는 것이 유일한 편입 경로다.
|
|
|
|
가드 주석에는 초기 구현이 키의 마지막 단어만 정규식으로 비교해 실제 duration 설정인 `server.tomcat.connection-timeout: 20s`까지 잘못 거부했다고 적혀 있다. 이후 실제 설정 로더로 값을 펼쳐 검사하도록 바꿨다.
|
|
|
|
## 확인하지 못한 것
|
|
|
|
실패 시점을 보려고 애플리케이션 전체를 부팅해 보지는 않았다. 바인딩 실패는 같은 산출물의 바인더에 값을 직접 넣어 확인했다.
|
|
|
|
<!-- body:end -->
|