Skip to content

[feat] 인증 이메일 작업 영속화 및 재시작·다중 서버 재시도 복구 #270

Closed

Description

@PHJ2000

목적 (Why)

무엇을 추가/변경하나?

  • 인증 이메일을 DB 기반 작업으로 저장하고 재시작·다중 서버 환경에서 복구한다.

왜 필요한가? (User value / Problem)

  • 현재 AFTER_COMMIT 이벤트와 메모리 기반 @retryable은 프로세스 종료 시 미발송 작업과 재시도 횟수를 잃는다.

Out of scope / Non-goals

  • SMTP exactly-once 보장, 자동 병합·운영 배포, 기존 FCM Outbox 변경.

비즈니스/기술적 배경

  • 최초 시도 포함 최대 4회와 5→10→20초 지수 백오프를 유지한다. 사용자 요청의 3분 재전송 제한은 토큰 생성 시각을 기준으로 유지한다.

전체 설계 (How)

핵심 아이디어/접근법

  • 인증 토큰과 email_jobs를 같은 트랜잭션에서 저장한다.
  • PostgreSQL 행 잠금(SKIP LOCKED)으로 작업을 선점하고 시도 횟수·이력을 함께 커밋한다. SMTP 호출은 DB 트랜잭션 밖에서 수행한다.
  • 현재 선점의 시도 번호로 완료 UPDATE를 제한해 오래된 워커의 상태 덮어쓰기를 막는다.

주요 컴포넌트/모듈

  • 작업 저장소, 주기/시작 시 복구 워커, SMTP 오류 분류기, Flyway 마이그레이션.

데이터 흐름/상태 변화

  • PENDING → SENDING → SUCCEEDED / RETRY_WAIT / FAILED. 만료된 SENDING은 횟수를 유지하며 복구한다.

PR 분할 전략 (리뷰어가 부담을 느끼질 않도록)

  • 하나의 원자적인 기능 PR: 저장·선점·실행·기존 경로 교체·장애 검증이 함께 적용되어야 누락/이중 발송 경로를 피할 수 있다. 테스트 포함 300라인 초과 예상.

부분 머지 안전성

  • 기능 전체를 함께 적용한다. 스키마 확장은 기존 버전과 호환되지만 구버전 메모리 작업은 복구할 수 없다.

전체 Acceptance Criteria (AC)

  • AC1: 상태 5종, 시도 횟수, 마지막 시도/다음 재시도 시각을 DB에 저장한다.
  • AC2: 시작 및 주기 실행에서 PENDING·기한 도래 RETRY_WAIT·오래된 SENDING을 복구한다.
  • AC3: 다중 서버의 동일 작업 선점을 방지하고 오래된 선점자의 상태 변경을 차단한다.
  • AC4: DB 기준 최대 4회/지수 백오프 및 SMTP 일시 오류와 영구 오류 분류를 적용한다.
  • AC5: 작업 ID와 시도 이력을 남기고 SMTP 수락 후 DB 기록 전 장애의 중복 가능성을 문서화한다.
  • AC6: 최종 실패를 보존하며 자동 재시도는 토큰 생성/3분 재전송 제한을 갱신하지 않는다.
  • AC7: 재시작·동시 실행·SMTP 성공 후 DB 기록 실패·횟수 소진·트랜잭션 롤백을 검증한다.

영향 범위

  • API 스펙 변경
  • DB 스키마 변경: email_jobs 및 시도 이력 테이블 추가
  • 설정/환경변수 변경: polling/lease, SMTP timeout
  • 라이브러리 추가/업그레이드
  • 외부 연동 영향: SMTP 재시도 분류 및 실행 시점

롤아웃/관측 (배포 전략)

  • DB 작업 상태와 시도 이력, 비식별 로그/Trace로 관측한다. 실제 SMTP 운영 발송은 로컬 검증 범위에 포함하지 않는다.

리스크 & 롤백

리스크

  • SMTP와 DB를 원자적으로 커밋할 수 없어 수락 후 장애 시 중복 발송 가능. exactly-once는 보장하지 않는다.
  • 작업 payload에 인증 링크가 포함되므로 로그 노출 금지와 저장/보존 정책을 명시한다.

롤백 전략

  • 워커를 중지하고 진행 중 SMTP 처리를 종료한 뒤 대기 작업을 확인한다. 이전 버전은 DB 작업을 처리하지 않으므로 단순 코드 롤백만으로 미완료 작업을 폐기하지 않는다.

의존성

  • 선행 이슈/PR: 없음. 기존 FCM Outbox 선점 이슈 #262와는 별도 범위.

증빙/참고 자료

  • 구현 PR에 실제 검증 명령·결과 및 장애 한계를 첨부한다.

구현·검증: PR #271에서 전체 338개 테스트와 빌드/정적 검사 통과를 확인했습니다. 사람 리뷰·병합·운영 배포는 별도이며 이슈는 열린 상태로 유지합니다.

최신 커밋 ef294334은 로컬 전체 검사 및 GitHub CI를 통과했습니다. 최초 CI의 기존 해변 스케줄러 Trace 테스트 1회 실패는 로컬 분리 실행과 동일 커밋 재실행에서 재현되지 않았으며, 원인 미확정 사항으로 PR에 기록했습니다.

리뷰 보완: 기존 메일 실행기에서 최대 3개 소비 작업 실행, 메일 비활성화 시 작업 생성·처리·키 검증 제외, 20건 배치 내 무효 후보 뒤 조회 지속, 복호화 실패의 암호문 보존. 새 의존성·추가 스키마 변경은 없습니다.

추가 정리: 주기 실행은 소비 작업 하나로 시작하고 실제 작업 발견 시에만 최대 3개까지 늘립니다. 미사용 Trace fixture/RetryConfig와 중복 설정 검증을 제거하고 기존 DB 보존 검증은 유지했습니다.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions