🛠️ API-Football 동기화 안정성 보완

[son0307]

변경 사항

API-Football 호출 실패 및 서킷 브레이커 보완

• 공통 실행기의 빠른 재시도가 모두 끝난 뒤 최종 결과만 API-Football 서킷 브레이커에 반영하도록 변경했습니다.
• timeout, network, upstream server, invalid response만 provider 장애로 집계하고 인증·요청 오류·quota·rate limit은 서킷 실패 횟수에서 제외했습니다.
• 최종 실패 예외의 retry 가능 여부와 Retry-After 정보를 자동 동기화의 느린 재시도 정책에 전달합니다.

자동 동기화 느린 재시도 개선

• 정기 scheduler와 startup 자동 동기화에만 느린 재시도를 유지하고 관리자 요청 실패에는 예약하지 않습니다.
• 기본 지연을 1분, 5분으로 증가시키며 일반 지연은 최대 30분으로 제한합니다.
• 유효한 Retry-After가 있으면 일반 지연보다 우선하고, 재시도 실패 시 가장 최근 응답 값을 다음 예약에 사용합니다.
• retryKey와 executionKey를 호출부에서 명시적으로 전달해 개별 팀·청크 재시도와 전체 동기화 범위를 구분합니다.
• 예약 상태에 ScheduledFuture와 취소 상태를 보관해 동일 범위의 자동 또는 관리자 동기화가 먼저 성공하면 대기 중인 재시도를 취소합니다.
• 취소와 timer 실행이 경합하더라도 이전 작업이 API를 호출하거나 스스로 다시 예약하지 못하도록 소유권을 확인합니다.
• 동일 작업이 이미 실행 중이면 재시도 횟수를 소모하지 않고 1분 후 다시 확인합니다.
• 부분 재시도 성공은 자신의 작업만 제거하고, 전체 동기화 성공은 같은 실행 범위의 팀·청크 재시도를 모두 제거합니다.

중복 동기화 방지

• 동기화 범위별 executionKey와 UUID 소유권 토큰을 사용하는 실행 잠금을 추가했습니다.
• scheduler, startup 재시도, 동기·비동기 관리자 요청이 같은 범위의 작업을 중복 수행하지 않도록 했습니다.
• 이전 작업이 늦게 종료되더라도 새 작업의 잠금을 해제할 수 없도록 소유권을 검증합니다.
• 비동기 관리자 작업은 큐 등록 시점이 아니라 worker의 실제 처리 완료 시점까지 잠금을 유지합니다.
• DB의 QUEUED/RUNNING/CANCEL_REQUESTED 상태도 함께 확인해 중복 큐 등록을 차단하고 409 오류를 반환합니다.

코드 리뷰 워크플로 모델 변경

• Codex PR 리뷰의 기본 모델을 gpt-5.4-mini에서 gpt-5.6-luna로 변경했습니다.
• 저장소 변수 CODEX_REVIEW_MODEL이 설정된 경우에는 기존처럼 해당 값을 우선합니다.

변경 이유

공통 실행기의 빠른 재시도와 자동 동기화의 느린 재시도는 목적이 다르므로 모두 유지하되, 이미 동일 범위의 동기화가 성공한 뒤에도 예약된 작업이 다시 실행되는 문제를 막을 필요가 있었습니다. 또한 scheduler와 관리자 요청이 동시에 같은 데이터를 갱신하면 중복 API 호출과 상태 경합이 발생할 수 있어 실행 범위와 소유권을 명확히 관리하도록 보완했습니다.

설정 변경

• API_FOOTBALL_SYNC_FAILURE_RETRY_INITIAL_DELAY_MINUTES: 느린 재시도 최초 지연
• API_FOOTBALL_SYNC_FAILURE_RETRY_DELAY_MULTIPLIER: 지연 배수
• API_FOOTBALL_SYNC_FAILURE_RETRY_MAX_DELAY_MINUTES: 일반 최대 지연
• 기존 API_FOOTBALL_SYNC_FAILURE_RETRY_DELAY_MINUTES는 최초 지연의 호환 설정으로 유지합니다.

외부 REST API, DB 스키마, 관리자 화면 응답 형식은 변경하지 않습니다.

검증

• API-Football 서킷 브레이커 오류 category 집계 테스트 통과
• 실행 잠금의 중복 차단 및 UUID 소유권 검증 테스트 통과
• 관리자 동기화 중복 요청과 비동기 worker 성공 시점 테스트 통과
• 느린 재시도의 1분→5분 지연, Retry-After 우선 적용, 중복 예약 방지 테스트 통과
• 전체 성공·부분 성공에 따른 재시도 취소 범위와 timer 경합 테스트 통과
• 관련 단위 테스트 통과
• git diff --cached --check 통과
• 전체 백엔드 테스트 219개 중 218개 통과
  • contextLoads() 1개는 로컬 환경에서 Docker/Testcontainers를 사용할 수 없어 실패했습니다.

프런트엔드 변경은 없어 별도 빌드를 수행하지 않았습니다.

후속 검토

• 관리자 전체 동기화가 일부 실패했을 때 기존 자동 부분 재시도의 후속 성공과 전체 상태 우선순위를 어떻게 판단할지 별도로 검토합니다.
• 프로세스 재시작과 다중 인스턴스 환경에서도 잠금·재시도 상태를 유지해야 한다면 영속 저장소 기반으로 확장합니다.
• 부상 동기화의 페이지·부분 재시도 분리는 실제 호출 규모와 장애 빈도가 커질 때 검토합니다.

[github-actions]

Codex PR Review

PR 요약

요약

API-Football 동기화의 재시도, 중복 실행, 실패 판정 로직을 보완해 자동 동기화의 안정성을 높였습니다. 함께 Codex PR 리뷰 워크플로우의 기본 모델도 업데이트했습니다.

주요 변경사항

• API-Football 응답 검증을 강화해 빈 응답, 잘못된 envelope, 불일치한 결과 수를 INVALID_RESPONSE로 처리하도록 변경했습니다.
• 서킷 브레이커가 timeout, network, upstream server, invalid response만 장애로 집계하도록 조정했습니다.
• 자동 동기화의 느린 재시도를 개선해 Retry-After 우선 적용, 초기/최대 지연 조정, 중복 예약 취소를 지원했습니다.
• scheduler, startup, 관리자 동기화에 executionKey 기반 실행 잠금을 추가해 같은 범위의 중복 실행을 막았습니다.
• 관리자 동기화는 이미 실행/대기 중인 작업이 있으면 409로 차단하고, 성공 시 예약된 재시도를 취소하도록 변경했습니다.
• Codex 리뷰 기본 모델을 gpt-5.4-mini에서 gpt-5.6-luna로 변경했습니다.
• 관련 설정값을 application.yml에 추가/변경했습니다.

영향 범위

• API-Football 동기화
• 자동 재시도 및 스케줄러
• 관리자 동기화
• 오류 처리/서킷 브레이커
• 설정(application.yml)
• CI 워크플로우(codex-review.yml)

검증

• 관련 단위 테스트 통과
• git diff --cached --check 통과
• 전체 백엔드 테스트 일부 통과: 219개 중 218개 통과
• 프런트엔드 변경 없음으로 별도 빌드 없음

시니어 개발자 리뷰

• [P1] src/main/java/com/son/soccerStreaming/apifootball/scheduler/ApiFootballSyncFailureRetryScheduler.java:~70-120 - Retry-After를 무시한 1분 강제 재스케줄 가능성

  • 문제: runRetry()에서 동일 실행이 아직 active이면 scheduleNext(..., activeJobDeferred = true)로 다시 예약하는데, 이 분기에서는 retryAfter(failure)를 전혀 보지 않고 initialDelayMinutes(기본 1분)만 사용합니다. PR 설명상 “유효한 Retry-After가 있으면 일반 지연보다 우선”해야 하는데, 오히려 아직 실행 중일 때는 Retry-After가 무시됩니다.
  • 영향: API-Football이 Retry-After: 10분을 반환한 직후에도 1분마다 재시도가 발생할 수 있어 rate limit을 더 악화시키고, 불필요한 예약/로그가 반복됩니다.
  • 수정 방향: active job defer 경로에서도 마지막 실패 예외를 저장해 두고 retryDelay()를 그대로 적용하거나, 최소한 Retry-After가 있으면 max(initialDelay, retryAfter)가 아니라 retryAfter를 우선 사용하도록 수정하세요.

• [P1] src/main/java/com/son/soccerStreaming/apifootball/scheduler/ApiFootballSyncFailureRetryScheduler.java:~220-290 - recordSuccessByKey가 너무 쉽게 눌려서 실패 상태가 영구적으로 남을 수 있음

  • 문제: recordSuccessWhenNoRelatedRetryRemains()는 completedRetryKey가 :team: 또는 :chunk:를 포함할 때만 success를 기록합니다. 그런데 terminalFailedRetries에는 같은 executionKey의 실패 키가 남아 있을 수 있고, cancelPendingByExecutionKey()가 호출되지 않은 경로(예: 성공 후 상태 갱신 타이밍 경합, 다른 성공 경로)에서는 성공으로 전환되지 않을 수 있습니다. 특히 전체 동기화 성공 후에도 이미 실패로 기록된 retryKey/상태가 남아 있으면 relatedRetryFailed가 true로 남아 성공 복구가 막힙니다.
  • 영향: 운영상 “이미 성공한 동기화”가 실패 상태로 지속 표시될 수 있고, 관리자 화면/상태 API가 실제와 다르게 보여 혼란을 줍니다.
  • 수정 방향: 성공 시에는 같은 executionKey에 매핑된 terminal 실패도 함께 정리하거나, terminalFailedRetries를 성공 이벤트에서 clear하는 경로를 명확히 두세요. 최소한 cancelPendingByExecutionKey()처럼 성공 처리 경로에서도 같은 executionKey의 terminal failure를 제거해야 합니다.

• [P2] src/main/java/com/son/soccerStreaming/admin/service/AdminService.java:704-720 - 큐 등록 전에 락을 잡아 비정상 종료 시 작업이 영구 차단될 수 있음

  • 문제: queueSync()에서 acquireManualSync(syncKey)를 먼저 호출한 뒤 adminSyncJobService.create(...)를 수행합니다. create()가 DB 예외 등으로 실패하면 releaseManualSync()는 호출되지만, apiFootballSyncExecutionGuard.acquire()가 성공한 뒤 manualSyncStates.compute(...) 내부에서 예외가 난 경우처럼 경로가 복잡해져, 향후 변경 시 락/상태 불일치가 생기기 쉽습니다. 또한 hasActiveJob(task, details)가 pre-check만 하고 DB 유니크 제약이 없어 경쟁 요청을 완전히 막지 못합니다.
  • 영향: 동시 요청이 몰릴 때 409 대신 중복 job 생성 시도나 불필요한 락 점유가 발생할 수 있고, 구현이 조금만 바뀌어도 남은 reservation 때문에 같은 syncKey가 막힐 수 있습니다.
  • 수정 방향: 지금 구조를 유지하더라도 job 생성 실패/예외 모든 경로에서 guard와 manual state가 반드시 해제되는지 더 명시적으로 보장하세요. 가능하면 DB 레벨에서 task+details+active status 충돌을 막는 최소한의 제약도 검토해야 합니다.

• [P2] src/main/java/com/son/soccerStreaming/apifootball/client/ApiFootballResponseValidator.java:17-35 - API-Football의 정상 응답을 오탐지로 실패 처리할 수 있음

  • 문제: 모든 응답에 대해 errors 필드가 비어 있어야 하고, results == response.size() 여야만 정상으로 인정합니다. 하지만 API-Football은 엔드포인트/버전에 따라 results와 response 개수가 정확히 일치하지 않거나, errors 필드가 없거나 형태가 다른 응답을 줄 수 있습니다. 현재 검증은 실제 정상 응답까지 INVALID_RESPONSE로 만들 위험이 있습니다.
  • 영향: 동기화가 불필요하게 실패로 전환되고, 서킷 브레이커와 느린 재시도가 연쇄적으로 동작해 운영 안정성이 나빠질 수 있습니다.
  • 수정 방향: 최소 검증만 하세요. 실제로 필요한 필드가 비었는지, response가 null인지 정도로 제한하고, results 일치 검증은 해당 엔드포인트에서 확실히 보장되는 경우에만 적용하는 게 안전합니다.

• [P3] src/main/resources/application.yml:100-104 - 새 설정 키는 추가됐지만 기존 delay-minutes를 읽는 코드 경로가 없음

  • 문제: application.yml은 initial-delay-minutes로 바뀌었지만, 코드가 다른 곳에서 여전히 API_FOOTBALL_SYNC_FAILURE_RETRY_DELAY_MINUTES를 기대하거나 문서/운영 설정이 혼재돼 있으면 실제 배포 환경에서 의도치 않게 기본값 1분으로 동작할 수 있습니다.
  • 영향: 운영자가 환경변수를 바꿨다고 생각했는데 반영되지 않아 재시도 정책이 예상과 달라질 수 있습니다.
  • 수정 방향: 호환 설정을 유지하는 의도는 좋아 보이지만, 배포 문서/환경 변수 안내에 새 키 우선순위를 명확히 남기고, 가능하면 로그에 실제 적용값을 초기에 한 번 노출하세요.

보안 리뷰

• [Medium] src/main/java/com/son/soccerStreaming/apifootball/service/ApiFootballSyncExecutionGuard.java:1-49 - 단일 인스턴스 메모리 잠금으로 중복 동기화만 막고, 다중 인스턴스/재시작 환경에서는 우회 가능

  • 문제:
    • ConcurrentHashMap 기반의 실행 가드는 JVM 내부에서만 유효합니다. PR 본문에도 다중 인스턴스와 프로세스 재시작 시 영속 저장소로 확장해야 한다고 언급되어 있습니다.
    • 따라서 여러 애플리케이션 인스턴스가 같은 API-Football 동기화를 동시에 수행할 수 있어, 중복 호출·상태 경합·쿼터 소진이 발생할 수 있습니다.
  • 공격/노출 시나리오:
    • 운영이 수평 확장된 상태에서 스케줄러가 각 인스턴스마다 실행되면 같은 동기화 작업이 중복 실행될 수 있습니다.
    • 재시작 직후 예약된 재시도와 새 인스턴스의 정기 작업이 동시에 API를 호출해 장애 재현이나 레이트리밋 유발이 가능해집니다.
  • 수정 방향:
    • DB/분산락(Redis, DB row lock 등) 기반의 전역 실행 잠금으로 변경하세요.
    • 최소한 executionKey를 영속 저장소에 기록하고 TTL/heartbeat를 둬서 장애 복구와 중복 방지를 함께 보장하세요.

• [Medium] src/main/java/com/son/soccerStreaming/apifootball/scheduler/ApiFootballSyncFailureRetryScheduler.java:전체 hunk(라인 번호 제공 불가, diff가 잘려 정확한 라인 확인 불가) - 재시도 스케줄 상태가 메모리에만 저장되어 재시작 시 소실

  • 문제:
    • retryStates, terminalFailedRetries가 모두 인메모리 자료구조라서 프로세스 재시작 시 예약/취소/실패 상태가 사라집니다.
    • 그 결과 이미 실패한 작업이 다시 예약되거나, 반대로 반드시 수행되어야 할 재시도가 영구적으로 누락될 수 있습니다.
  • 공격/노출 시나리오:
    • 운영 중 재배포나 크래시가 발생하면 예약된 후속 재시도가 날아가 데이터 동기화가 누락될 수 있습니다.
    • 반대로 재시작 후 이전 실패 상태를 잃어버려 같은 작업이 반복 실행될 수 있습니다.
  • 수정 방향:
    • 재시도 큐와 상태를 DB/Redis 등에 저장하고, 재시작 시 복구 가능한 구조로 바꾸세요.
    • 최소한 재시작 시 중복 예약을 막는 idempotency key와 TTL 기반 상태 정리를 추가하세요.

• [Low] src/main/java/com/son/soccerStreaming/apifootball/client/ApiFootballClient.java:268-287, src/main/java/com/son/soccerStreaming/apifootball/client/ApiFootballResponseValidator.java:1-59 - 외부 응답 검증 강화로 인한 서비스 거부 가능성

  • 문제:
    • results와 response.size()를 엄격 비교하고, errors 메타데이터 형식이 기대와 다르면 모두 INVALID_RESPONSE로 처리합니다.
    • 외부 공급자가 스키마를 약간 변경하거나, 응답의 일부 필드를 비워 반환하면 정상 응답도 장애로 분류될 수 있습니다.
  • 공격/노출 시나리오:
    • API-Football이 일시적으로 포맷을 변경하거나 부분 응답을 반환하면 동기화가 반복 실패하고 재시도 스케줄이 쌓여 장애가 길어질 수 있습니다.
  • 수정 방향:
    • 실제로 필수인 필드만 엄격하게 검증하고, 공급자 변동에 대비해 허용 가능한 변형 범위를 정의하세요.
    • errors/results 검증 실패 시 즉시 장애로 분류하기보다, 일부 엔드포인트별로 완화된 검증 규칙을 두는 것을 검토하세요.

중대한 보안 문제 없음
Model: gpt-5.4-mini
Diff was truncated to 90000 characters; review may be incomplete.