Repository navigation
ELOG 026 webpush library spike
| 항목 | 내용 |
|---|---|
| 분류 | 🔧 트러블슈팅 |
| 날짜 | 2026-08-08 |
| 영역 | BE |
| 관련 이슈/PR | #1072 |
| 상태 | 해결 (실기기 배달 확인은 3단계 끝) |
3단계(알림)의 첫 관문. 에픽에 "여기서 막히면 전체가 밀림"으로 적어 둔 항목이다.
리포에 푸시 인프라가 전혀 없다 — Service Worker · VAPID · 구독 저장 · 발송 스케줄러가 전부 신규다. 먼저 답해야 할 것은 하나였다: Java 25 / Spring Boot 4에서 웹푸시를 실제로 보낼 수 있는가, 무엇으로 보내는가.
라이브러리 하나 붙이면 되는 일처럼 보이지만 두 가지가 걸렸다.
- 자바 웹푸시 라이브러리는 대부분 오래됐다. 이 프로젝트는 Java 25 + Boot 4 + Jackson 3이다
- 틀려도 조용히 실패한다. 페이로드 암호화(RFC 8291)나 VAPID 서명이 어긋나면 푸시 서비스가 200을 주고도 기기엔 아무것도 안 뜬다
후보 두 개를 실제로 해석(resolve)해 무엇을 끌고 오는지 봤다. 짐작이 아니라 의존성 트리를 찍었다.
nl.martijndwars:web-push:5.1.1 — 29개 아티팩트
| 끌고 오는 것 | 버전 | 비고 |
|---|---|---|
| io.netty:* | 4.1.42.Final | 2019 |
| org.asynchttpclient | 2.10.4 | 2019 |
| org.apache.httpcomponents:httpclient | 4.5.6 | 2018 |
| org.bitbucket.b_c:jose4j | 0.7.0 | 2019 |
| commons-codec | 1.10 | 2014 |
여기서 결정적인 문제가 나왔다. 이 프로젝트는 이미 Netty 4.2.16을 쓴다.
io.netty:netty-buffer:4.1.126.Final -> 4.2.16.Final
io.netty:netty-codec:4.1.126.Final -> 4.2.16.Final
Netty 4.1 → 4.2는 호환이 깨지는 메이저 변경이다(netty-codec이 netty-codec-base 등으로 쪼개졌다). Spring BOM이 버전을 4.2로 끌어올리면, 4.1 시절에 컴파일된 async-http-client 2.10.4가 런타임에 깨질 수 있다. 반대로 4.1로 내리면 앱 전체가 깨진다. 어느 쪽으로도 안전하지 않다.
여기에 2014~2019년 아티팩트 29개는 Trivy(CRITICAL/HIGH를 무시 목록으로 덮지 않고 버전을 올려 해결한다는 규칙) 관점에서도 부담이다 — 우리가 올릴 수 없는 라이브러리의 이행 의존성이다.
com.interaso:webpush:1.2.0 — 3개 아티팩트
com.interaso:webpush:1.2.0
org.jetbrains.kotlin:kotlin-stdlib:1.9.23
org.jetbrains:annotations:13.0
훨씬 깔끔하다. BouncyCastle도 안 쓴다. 다만 순수 Java 코드베이스에 kotlin-stdlib가 들어온다는 점과, 작은 프로젝트라 유지보수가 끊기면 결국 우리가 떠안는다는 점이 남는다.
세 번째 선택지 — 직접 구현. 웹푸시 발송은 본질적으로 "200바이트를 암호화해서 POST"다. 필요한 원시 연산이 전부 JDK에 있다: ECDH(P-256) · HMAC-SHA256 · AES-GCM · ECDSA. HKDF도 출력이 32바이트 이하라 HMAC 한 번이면 된다(RFC 5869).
직접 구현했다. 새 의존성 0개.
| 클래스 | 하는 일 |
|---|---|
P256 |
브라우저가 주는 원시 키(65바이트 점 · 32바이트 스칼라) ↔ JDK 키 객체 |
WebPushEncryption |
RFC 8291 + RFC 8188 aes128gcm 페이로드 암호화 |
VapidSigner |
RFC 8292 VAPID — ES256 JWT + Authorization 헤더 |
구현 중 걸린 두 함정을 코드 주석과 테스트로 못박았다.
① ECDSA 서명 형식. JDK는 DER(SEQUENCE { INTEGER r, INTEGER s })로 내는데 JWS는 **고정 길이 64바이트 R‖S**를 요구한다(RFC 7518 §3.4). DER INTEGER는 최상위 비트가 1이면 앞에 0x00을 붙이고 앞의 0은 생략하므로, 그대로 쓰면 길이가 63~65로 흔들린다. 자바로 VAPID를 붙일 때 가장 흔한 401 원인이다.
② aud는 엔드포인트 전체가 아니라 출처(origin)만. 전체를 넣으면 구독마다 aud가 달라진다.
스스로 만든 것을 스스로 확인하면 의미가 없다 — 형식이 틀려도 양쪽이 같이 틀린다. 그래서 바깥에 기준을 뒀다.
-
암호화: 입력은 RFC 8291 §5 테스트 벡터, 기대값은 널리 쓰이는 Node
http_ece(npmweb-push의 암호화 엔진)로 같은 입력에서 뽑았다. 우리 구현 · 규격 · 기존 구현 셋이 한 점에서 만나야 통과한다 - 서명: JDK 검증기로 원문을 다시 세워 확인하고, 서명 길이가 항상 64바이트인지 50회 반복해 못박았다
막히지 않는다. 3단계는 계획대로 진행할 수 있다.
WebPushEncryptionTest 5 tests, 0 failures
VapidSignerTest 6 tests, 0 failures
./gradlew check BUILD SUCCESSFUL
암호화가 RFC 8291 테스트 벡터와 바이트 단위로 일치한다.
회귀 테스트가 실제로 틀린 구현을 잡는지도 확인했다. "WebPush: info"를 "WebPush: Info"로 대문자 하나만 바꾸니 그 자리에서 실패한다.
WebPushEncryptionTest > RFC 8291 테스트 벡터와 바이트가 같다 FAILED
| martijndwars | interaso | 직접 구현 | |
|---|---|---|---|
| 새 아티팩트 | 29 | 3 | 0 |
| Netty 4.2 충돌 | 있음 | 없음 | 없음 |
| Kotlin 유입 | 없음 | 있음 | 없음 |
| 규격 검증 | 라이브러리 신뢰 | 라이브러리 신뢰 | 테스트 벡터로 직접 |
⚠️ 실기기 배달은 아직 확인 못 했다. 페이로드가 규격에 맞다는 것과 안드로이드 기기에 알림이 뜨는 것은 다른 문제다(FCM 등록·SW 수신). 3단계 끝의 실기기 검증에서 확인한다 — #1048과 같은 성격이다.
- 라이브러리를 고르기 전에 의존성 트리를 찍는다. "웹푸시 라이브러리"라는 한 줄 뒤에 2019년 Netty가 있었고, 그게 이 프로젝트에서는 치명적이었다. README만 봤으면 못 봤다.
- 이행 의존성은 우리가 못 올린다. Trivy가 CRITICAL을 물어도 우리 손이 닿지 않는 라이브러리 안쪽이면 방법이 없다. 얇은 라이브러리가 좋은 게 아니라, 올릴 수 있느냐가 기준이다.
- 암호 코드는 "돌아간다"로 확인하지 않는다. 왕복(encrypt→decrypt)은 스스로 일관될 뿐 규격 준수를 증명하지 않는다. 바깥의 기준값(RFC 벡터 · 다른 구현)과 맞대야 한다.
- 조용히 실패하는 코드일수록 일부러 깨 본다. 대문자 하나로 실패하는 걸 확인하고 나서야 이 테스트를 믿을 수 있다.
- 후속: 구독 저장 · 예약 · 발송 스케줄러 · Service Worker가 남았다. 발송은
HolidayScheduler선례를 따르고 replica 1 전제다(다중 replica가 되면 중복 발송 — 그때 DB 조건부 UPDATE로 락을 넣는다).
- 이슈 #1072
- Travel Architecture §6 (알림 흐름), Travel Spec v2 §4.2 (재계산 트리거)
- RFC 8291(Message Encryption) · RFC 8188(aes128gcm) · RFC 8292(VAPID) · RFC 7518 §3.4(ES256 서명 형식)