Files
clean-architecture-backend-…/docs/upgrade/2026-11-round9-outbound.md
T
DongHyeonka 931178760a
pr / done (pull_request) Canceled after 0s
fix(outbound)!: S3 조건부 쓰기·MongoDB 예산과 lease·HTTP 압축을 맞춘다
S3 control 저장소는 SDK가 응답을 잃고 다시 보낸 조건부 PUT의 412를
충돌로 본다. MongoDB 집계는 결과 바이트 예산을 보지 않고 전부 메모리에
올린다. tenant client registry는 쓰는 중인 client를 내보내고, 내보내다
닫기에 실패하면 다른 tenant의 acquire가 실패한다. migration lease를 잃은
runner가 그 뒤에도 checkpoint를 쓴다. HTTP client는 SOCKS proxy를 HTTP로
붙이고, 압축을 켜면 Apache는 스스로 풀어 max-wire-bytes가 푼 크기를
세며, JDK transport는 그 설정을 읽지 않는다.

고른 방법: S3는 412에서 다시 읽어 이 호출이 쓴 record 그대로면 성공으로
본다. 집계는 $limit(maxResults + 1)과 maxResultBytes를 집행한다. registry
acquire는 Lease를 돌려주고 쓰는 중에는 내보내지 않으며 idle은 마지막
close부터 잰다. 상한·lease 수·내보내기는 registry 밖에서 잡을 수 없는 전용
lock 하나로 묶는다. 닫기 실패는 evictionCloseFailures가 센다. migration
ledger는 lock 문서의 현재 fence로 쓴다. ProxyType은 HTTP만 남긴다.
압축은 RestClient 기본 헤더로 보내고 ContentDecoding이 버퍼·스트리밍
본문을 모두 푼다(겹친 coding과 그 밖의 coding은 거부, 빈 본문은 빈
본문). Jetty HTTP/3는 기동 뒤 decoder를 비운다. 버린 대안: SOCKS 지원
(transport 셋 중 하나만 된다), transport마다 자동 풀기(크기 상한이
transport마다 달라진다), 집계를 RawBsonDocument로 재기(converter를 거치지
않으면 반환 타입 mapping이 갈라진다).

위험·한계: MongoTenantClientRegistry.acquire 반환형과 ProxyType이 바뀐다.
S3에서 두 writer가 같은 버전에서 같은 record를 쓰면 둘 다 성공으로 본다
(Javadoc과 안내 3절). 집계 결과는 converter로만 바뀌어 entity callback이
돌지 않는다. evictionCloseFailures 지표는 지표 묶음에 넘긴다.

검증: desktop RED(pr2-red2). GREEN은 PR 본문의 verify.sh pr 결과.

Refs: RR9-01-08, RR9-01-11, RR9-01-19, RR9-01-20, RR9-01-27, RR9-01-28, RR9-01-30, RR9-01-31
BREAKING CHANGE: MongoTenantClientRegistry.acquire가 Lease를 돌려주고, migration lease를 잃은 refresh가 MongoOperationRejectedException을 던진다. HTTP client ProxyType.SOCKS가 없어져 그 설정은 바인딩이 실패한다. request.compression이 모든 transport에서 같은 coding만 받는다. docs/upgrade/2026-11-round9-outbound.md
2026-11-13 16:21:16 +09:00

8.5 KiB

업그레이드 안내 — 2026-11 outbound 발행·발송·캐시·S3·MongoDB·HTTP client

  • 범위: outbox 발행 대기, SMTP 발송 pool, Redis 캐시 시간·크기 상한, S3 조건부 쓰기, MongoDB 집계 예산·tenant client·migration lease, HTTP client 압축·proxy를 고친 변경. 기동 조건과 공개 타입이 바뀐 곳이 있다. 아래 표가 그 목록이다.
  • 근거: 2026-11-12 전체 리뷰(docs/reviews/2026-11-12-round9-review/)의 발행·발송·캐시(B10a)와 S3·Mongo·httpclient (B10b) 발견

1. 누가 읽나

이 템플릿을 upstream remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 SMTP 알림, Redis 캐시, MongoDB 집계·tenant별 database, HTTP client의 압축이나 proxy를 쓰는 서비스다.

2. 할 일

# 할 일 안 하면 해당 서비스
1 SMTP provider profile들의 max-concurrency 합이 발송 pool이 담는 수(app.notification.platform.smtp.dispatch-concurrency개 thread와 그 네 배의 대기열) 이하인지 확인한다. 모든 SMTP profile이 pool 하나를 같이 쓴다. 기본값(profile 하나, 4와 4)은 맞는다 넘으면 넘게 만든 profile의 조립이 기동 때 실패한다. 전에는 넘친 발송이 대기열에서 거절되어 결과 불명으로 남았다 SMTP 알림을 켠 서비스
2 Redis 캐시의 command-timeout이 이제 한 캐시 연산 전체(연결 대기와 응답 전부)의 상한이다. 연결 대기가 길던 배포는 값을 다시 본다 상한 안에 못 끝난 연산이 캐시 없음(DEGRADED_UNAVAILABLE·Unavailable)으로 끝나는 일이 늘 수 있다. 전에는 lane 대기 2초가 더해졌다 Redis 캐시를 켠 서비스
3 encode한 값이 1 MiB(RedisCacheRegionAdapter.DEFAULT_MAXIMUM_VALUE_BYTES)를 넘는 캐시는 그 값을 기록하지 않는다(NOT_RECORDED_PROVIDER_POLICY). 더 큰 값이 필요하면 app.capabilities.cache.maximum-value-bytes(APP_CACHE_REDIS_MAXIMUM_VALUE_BYTES, 1..16777216)로 상한을 올린다. 2026-08-10에 폐기했던 그 env 키가 다시 묶였다 그 값은 매번 source에서 읽힌다 큰 값을 캐시하던 서비스
4 MongoDB PolicyAwareMongoAggregationExecutor는 등록 예산의 maxResultBytes를 집행하고, pipeline 끝에 $limit(maxResults + 1)을 붙인다. 결과가 큰 집계의 예산을 다시 본다. 집계 결과는 template의 converter로만 바뀌어 AfterLoadEvent·AfterConvertEvent와 entity callback이 돌지 않는다. 그것에 기대던 listener는 돌려받은 타입에서 직접 한다 바이트 예산을 넘는 집계가 MongoOperationRejectedException(aggregation.result)으로 실패한다. 전에는 결과를 전부 메모리에 올렸다 MongoDB 집계를 쓰는 서비스
5 experimental MongoTenantClientRegistry.acquire가 Lease(interface)를 돌려준다. client를 다 쓴 뒤 lease.close()(또는 try-with-resources)를 부른다. 쓰는 중인 tenant의 release는 거부된다. idle 시간은 마지막 lease를 닫은 때부터 잰다. 열린 lease 수는 openLeases()다. 시각을 인자로 받던 acquire(tenant, Instant)는 없어졌다. 시계는 생성자의 Clock 하나다 반환값을 버리는 호출은 컴파일되지만, 닫지 않은 lease의 client는 쓰는 중으로 남아 내보내지지 않고 cap 한 칸을 계속 차지한다. acquire(tenant, Instant)를 부른 코드는 컴파일이 실패한다 tenant별 database를 쓰는 서비스
6 MongoDB migration lease를 잃은 뒤의 refresh는 MongoOperationRejectedException(migration.lock)을 던진다. IllegalStateException을 잡던 코드를 바꾼다. collection을 직접 넘겨 MongoCollectionMigrationLedger를 만들던 코드는 셋째 인자로 lock collection(MongoCollectionMigrationLock.DEFAULT_COLLECTION)을 넘긴다. 옛 runner의 recordApplied는 새 runner가 lease를 잡은 뒤면(checkpoint를 쓰기 전이어도) 거부된다 그 예외를 잡지 못한다. 두 인자 생성자는 컴파일이 실패한다 MongoDB migration runner를 직접 쓰는 서비스
7 HTTP client profile의 proxy.type: SOCKS를 지우거나 HTTP proxy로 바꾼다. ProxyType에는 이제 HTTP만 있다 설정 바인딩이 실패해 기동하지 않는다. 전에는 SOCKS port에 HTTP proxy로 붙어 첫 요청에서 실패했다 SOCKS proxy를 설정한 서비스
8 request.compression: true인 HTTP client는 transport와 상관없이 Accept-Encoding: gzip, deflate를 보내고, 버퍼 본문과 스트리밍 다운로드 모두 이 플랫폼이 푼다(JDK transport는 전에 이 설정을 읽지 않았다). 압축을 켰든 껐든, 그 밖의 Content-Encoding(br 등)이나 겹친 coding으로 온 응답은 HttpTargetRejectedException(TARGET_REJECTED, 증거 RESPONSE_RECEIVED)으로 거부된다. 본문이 빈 gzip 응답(HEAD·204·304)은 빈 본문이다 — 동작 변경. response.max-wire-bytes가 이제 압축된 크기로 센다. 스트리밍 다운로드도 identity 본문까지 max-decoded-bytes로 센다. 실험 transport인 Jetty HTTP/3도 이제 스스로 풀지 않는다 HTTP client를 쓰는 서비스
9 SMTP provider profile의 timeout(기본이 10s에서 30s로 바뀌었다)이 발송 한 번을 두 번 묶는다. 발송이 send pool에서 그 시간이 지나도록 시작하지 못하면 relay에 보내지 않고 시작 전 실패(PROVIDER_UNAVAILABLE, 재시도)로 기록한다. 시작한 뒤 그 시간이 지나면 결과 불명(PROVIDER_RESPONSE_LOST)으로 기록하고 자동으로 다시 보내지 않는다. 값은 mail.smtp.connectiontimeout에 mail.smtp.timeout·mail.smtp.writetimeout 중 긴 것을 더한 값보다 길어야 하고, dispatch.lease-duration은 그 두 배보다 길어야 한다. dispatch.shutdown-grace가 그 두 배보다 짧으면 종료 중에 끝나지 않은 발송이 결과 불명으로 남는다(docs/notification/configuration-reference.md 「SMTP relay」). SmtpNotificationProviderAdapter를 직접 만들던 코드는 마지막 인자로 이 timeout을 넘긴다. 직접 만든 ProviderRuntimeAssembler는 새 default 메서드 requireTogether(profiles, deliveryLease)로 한 family의 켜진 profile 전체에 걸린 검사를 할 수 있다(NotificationProviderAssembly가 SERVING일 때 family마다 한 번 부른다). assemble을 직접 부르는 코드는 그 전에 requireTogether를 부른다 timeout이 socket timeout 합 이하이거나 lease가 timeout 두 배 이하면 SMTP 조립이 기동 때 실패한다. 상한 안에 끝나지 않는 발송이 결과 불명으로 남는다. 전에는 socket timeout이 명령마다만 묶어, 느린 relay에서 발송이 lease를 넘으면 lease 복구가 아직 도는 발송을 운영자 확인으로 넘겼다. SMTP 알림을 켠 서비스

3. 바뀐 동작 (따라 할 일 없음)

  • outbox relay의 발행 대기는 publish()를 부른 때부터 publisher의 longestAttempt()까지다. 넘으면 결과 불명(PUBLISH_WAIT_EXCEEDED)으로 기록하고 다음 claim에서 다시 본다. 직접 만든 IntegrationEventPublishPort는 longestAttempt()를 실제 최장 시간으로 답한다. 0이나 음수를 답하면 그 행은 보내지 않고 REJECTED_RETRYABLE(PUBLISH_BOUND_NOT_POSITIVE)로 backoff 뒤에 다시 본다.
  • 이미 interrupt된 relay thread는 그 행을 발행하지 않고 REJECTED_RETRYABLE(PUBLISH_INTERRUPTED_BEFORE_SEND)로 돌려준다. relay가 그 행을 backoff 뒤로 미뤘다가 발행한다. 기다리는 중의 interrupt는 전처럼 결과 불명(PUBLISH_WAIT_INTERRUPTED)이다.
  • SMTP 발송 pool은 첫 발송부터 dispatch-concurrency개 thread로 돈다(전에는 대기열이 찰 때까지 thread 하나였다). pool이 거절한 발송은 relay에 닿지 않은 것(PROVIDER_UNAVAILABLE, CAPACITY_REJECTED)으로 기록되어 재시도된다.
  • S3 control 저장소의 조건부 PUT이 412를 받으면 key를 다시 읽는다. 이 호출이 쓴 record 그대로면 성공이다(SDK가 응답을 잃은 첫 쓰기를 다시 보낸 경우). 다른 내용이나 없음이면 전처럼 충돌이다. 「그대로」는 같은 값이라는 뜻이라, 두 writer가 같은 버전에서 같은 record를 쓰면 둘 다 성공으로 본다. 그럴 수 있는 호출자는 record에 자기 토큰을 싣는다.
  • MongoDB tenant client를 내보내다 닫기에 실패하면 그 tenant 대신 evictionCloseFailures()가 센다. 닫기를 부른 다른 tenant의 acquire는 실패하지 않는다.