Skip to content

ELOG 026 webpush library spike

wcorn edited this page Aug 8, 2026 · 1 revision

ELOG-026: 웹푸시 스파이크 — 라이브러리를 안 쓰기로 한 이유

항목 내용
분류 🔧 트러블슈팅
날짜 2026-08-08
영역 BE
관련 이슈/PR #1072
상태 해결 (실기기 배달 확인은 3단계 끝)

1. 상황 (Before)

3단계(알림)의 첫 관문. 에픽에 "여기서 막히면 전체가 밀림"으로 적어 둔 항목이다.

리포에 푸시 인프라가 전혀 없다 — Service Worker · VAPID · 구독 저장 · 발송 스케줄러가 전부 신규다. 먼저 답해야 할 것은 하나였다: Java 25 / Spring Boot 4에서 웹푸시를 실제로 보낼 수 있는가, 무엇으로 보내는가.

라이브러리 하나 붙이면 되는 일처럼 보이지만 두 가지가 걸렸다.

  • 자바 웹푸시 라이브러리는 대부분 오래됐다. 이 프로젝트는 Java 25 + Boot 4 + Jackson 3이다
  • 틀려도 조용히 실패한다. 페이로드 암호화(RFC 8291)나 VAPID 서명이 어긋나면 푸시 서비스가 200을 주고도 기기엔 아무것도 안 뜬다

2. 원인 분석 — 후보 조사

후보 두 개를 실제로 해석(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).

3. 조치

직접 구현했다. 새 의존성 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(npm web-push의 암호화 엔진)로 같은 입력에서 뽑았다. 우리 구현 · 규격 · 기존 구현 셋이 한 점에서 만나야 통과한다
  • 서명: JDK 검증기로 원문을 다시 세워 확인하고, 서명 길이가 항상 64바이트인지 50회 반복해 못박았다

4. 결과 (After)

막히지 않는다. 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과 같은 성격이다.

5. 교훈 / 후속

  • 라이브러리를 고르기 전에 의존성 트리를 찍는다. "웹푸시 라이브러리"라는 한 줄 뒤에 2019년 Netty가 있었고, 그게 이 프로젝트에서는 치명적이었다. README만 봤으면 못 봤다.
  • 이행 의존성은 우리가 못 올린다. Trivy가 CRITICAL을 물어도 우리 손이 닿지 않는 라이브러리 안쪽이면 방법이 없다. 얇은 라이브러리가 좋은 게 아니라, 올릴 수 있느냐가 기준이다.
  • 암호 코드는 "돌아간다"로 확인하지 않는다. 왕복(encrypt→decrypt)은 스스로 일관될 뿐 규격 준수를 증명하지 않는다. 바깥의 기준값(RFC 벡터 · 다른 구현)과 맞대야 한다.
  • 조용히 실패하는 코드일수록 일부러 깨 본다. 대문자 하나로 실패하는 걸 확인하고 나서야 이 테스트를 믿을 수 있다.
  • 후속: 구독 저장 · 예약 · 발송 스케줄러 · Service Worker가 남았다. 발송은 HolidayScheduler 선례를 따르고 replica 1 전제다(다중 replica가 되면 중복 발송 — 그때 DB 조건부 UPDATE로 락을 넣는다).

참고

Clone this wiki locally