[task-stream-automation]

변경 내용

원본 이슈: #55

README.md

Worker emit·request에 최대 재시도 횟수와 대기 간격 옵션 추가

이슈와 작업 상태

• 원본: GitHub Issues #55
• 제목: Worker emit·request에 최대 재시도 횟수와 대기 간격 옵션 추가
• 상태: Open
• 유형·레이블: 기능 (feature), 원본 이슈에 적용됨
• 작업 대상: yong5eon/DefStream, 작업 브랜치 feature/55
• 분기 기준: 깨끗한 로컬 master의 3ce6044
• 병합 대상: 미지정
• 로컬 진행 상태: 구현·focused 테스트·한영 매뉴얼 갱신 완료, 실제 브로커 통합 검증 미실행
• 댓글: 없음

작업 문서

• 요구사항 명세
• 작업 계획
• 구현 종합
• 작업 종합
• 변경 로그
• 최신 구현 기록
• 최신 작업 기록

이슈 원문

해결하려는 문제

Worker에서 제공하는 emit과 request는 현재 브로커 호출이 실패하면 즉시 예외를 전파한다. 일시적인 실패에 대응하려면 호출자가 각 호출부에서 재시도 로직을 직접 작성해야 한다.

제안하는 해결 방법

src/Worker/Message.py의 emit과 request에 재시도 횟수와 시도 간 대기 간격을 지정하는 선택 인자를 추가한다. 브로커 구현체가 아닌 Worker 함수 계층에서 처리한다.

옵션과 기본값

옵션	기본값	의미
최대 재시도 횟수	None	최초 호출을 제외하고 추가로 시도할 최대 횟수
재시도 간격	1초	실패 후 다음 시도 전 대기 시간

인자명은 구현 시 기존 API 명명 관례에 맞춰 확정한다.

동작

• 재시도 횟수가 None이면 기존과 동일하게 한 번만 호출하고, 실패 시 대기 없이 해당 예외를 즉시 전파한다.
• 재시도 횟수가 0이면 추가 시도 없이 최초 호출 결과만 반환하거나 예외를 전파한다.
• 재시도 횟수가 N이면 최초 호출 이후 최대 N번 추가로 시도한다. 예를 들어 3이면 최초 호출을 포함하여 최대 4번 호출한다.
• 최초 호출은 즉시 실행하며, 실패 후 다음 시도가 남아 있을 때만 지정한 간격만큼 대기한다.
• 도중에 성공하면 기존 반환값을 즉시 반환하고 추가로 시도하지 않는다.
• 모든 시도가 실패하면 마지막 시도에서 발생한 예외를 다른 예외로 감싸거나 대체하지 않고 그대로 raise한다. 마지막 실패 뒤에는 대기하지 않는다.
• emit과 request에 동일한 재시도 정책을 적용한다. 기존 인자와 브로커 호출의 반환값·예외 계약은 유지한다.
• request의 기존 timeout은 각 브로커 요청 호출에 그대로 전달한다. 전체 재시도 과정의 총 제한 시간으로 바꾸지 않는다.

구현 범위

• Worker의 emit·request에서 브로커 호출 실패에 대한 재시도를 제공한다.
• 브로커 구현체 및 브로커 인터페이스에 재시도 옵션이나 내부 재시도 기능을 추가하지 않는다.
• Worker의 기존 입력 검증과 지원 기능 확인은 유지하고, 이를 브로커 호출 재시도 대상으로 확대하지 않는다.
• 재시도 미설정 시 기존 동작을 유지한다.

고려한 대안

• 브로커별 구현체에 재시도를 구현하는 대신, 호출자가 사용하는 Worker 함수 계층에서 공통으로 제공한다.

인수 기준

• emit과 request 모두 최대 재시도 횟수와 대기 간격을 지정할 수 있으며, 기본값은 각각 None과 1초이다.
• None 또는 0이면 한 번만 호출하고 실패 예외를 즉시 전파한다.
• 재시도 횟수 3에서 계속 실패하면 총 4회 호출하고 대기는 3회만 수행한다.
• 도중에 성공하면 반환값을 그대로 반환하며 남은 시도와 대기를 수행하지 않는다.
• 지정한 간격과 기본 간격이 실제 재시도 대기에 적용된다.
• 최종 실패 시 마지막 예외 객체와 타입을 그대로 전파하며, 별도 예외로 변환하지 않는다.
• 기존 priority 전달과 request의 timeout 전달을 유지한다.
• 브로커 구현체에 재시도 기능을 추가하지 않고 두 Worker 함수에서 검증한다.

추가 정보

기존 동작을 바꾸는 것이 아니라 선택적으로 사용할 수 있는 공개 기능을 추가하므로 feature로 분류한다.

재시도는 중복 전송이나 중복 실행 방지를 보장하지 않는다. 전송 이후 응답 대기 중 실패하는 등의 경우에는 이미 처리된 요청이 다시 전송될 수 있음을 사용 문서에 안내한다. 이 이슈에서 별도의 중복 방지 기능은 추가하지 않는다.

원문

REQUIREMENTS.md

Worker 메시지 발행·요청 재시도 요구사항

목적

Worker의 emit()과 request()에 선택적 재시도를 추가하여 브로커 호출 실패를 설정된 횟수까지 다시 시도합니다. 이슈 원문과 작업 브랜치 정보는 이슈 기록을 기준으로 합니다. 이 문서는 요청 내용과 현재 구현을 대조한 분석 및 목표 동작을 정의하며, 구현·검증 결과는 아직 포함하지 않습니다.

분석과 근거

이슈에서 요청한 결과

• emit()과 request()에서 최대 재시도 횟수와 시도 간 대기 시간을 선택적으로 지정합니다.
• 기본 최대 재시도 횟수는 None으로, 재시도하지 않고 기존처럼 한 번만 호출합니다. 기본 대기 간격은 1초입니다.
• 재시도 횟수는 최초 호출 이후의 추가 시도 횟수입니다. 실패 후 다음 시도가 있을 때만 대기하고, 성공하면 즉시 반환하며, 마지막 실패 뒤에는 대기하지 않습니다.
• 모든 시도가 실패하면 마지막 호출에서 난 예외를 그대로 전파합니다.
• 기존 request()의 timeout, priority 전달과 Worker 계층에서 재시도를 제공한다는 범위를 유지합니다.

현재 코드와 요구사항의 차이

• Worker 메시지 함수의 emit()은 작업·본문·브로커 기능·우선순위를 확인한 뒤 broker.emit()을 한 번 호출합니다. request()도 같은 순서로 입력을 확인한 뒤 broker.request()를 한 번 호출하고, 매번 기존 timeout을 전달합니다.
• 입력 검증과 지원 기능 확인은 브로커 호출보다 앞서 수행됩니다. 재시도는 브로커 메서드 호출에만 적용하고, 이 검증을 반복하거나 NotImplementedError를 재시도 대상으로 만들 필요는 없습니다.
• 공통 브로커 연결 계약은 발행·요청 지원 여부를 Protocol로 표현하지만, 재시도 가능한 예외를 공통 분류하는 계약은 없습니다. 이슈의 요청대로 재시도 동작은 Worker API 계층에 둡니다.
• request()를 지원하지 않는 연결은 Requestable 검사에서 브로커 I/O 전에 거부됩니다. Redis 연결은 현재 Requestable을 구현하지 않습니다.
• RabbitMQ의 RPC 응답 처리는 원격 작업 오류 응답을 RemoteError로 던집니다. 사용자는 재시도 범위에 브로커 호출에서 발생하는 모든 예외를 포함하도록 확정했습니다. 따라서 RemoteError도 재시도되며, 실패한 원격 작업이 다시 실행될 수 있습니다.
• 기존 작업 메시지 테스트는 Mock 브로커로 Worker 함수의 호출 횟수·인자·오류 전파를 검증할 수 있습니다. 실제 브로커에 의존하지 않고 재시도 횟수와 대기를 검증할 수 있습니다.
• 작업 매뉴얼과 영어판은 현재 소비 메시지의 오류 정책·재전달을 설명합니다. 새 API 재시도와 소비자 재전달이 서로 다른 동작임을 구분하여 두 문서를 함께 갱신해야 합니다.

확정 요구사항

ID	요구사항
R-01	emit()과 request()에 retry와 interval 키워드 인자를 제공해야 합니다. 기본값은 각각 None과 1초입니다.
R-02	None 또는 0회 재시도는 최초 호출만 수행합니다. N회 재시도는 최초 호출 후 최대 N회 추가 호출까지 허용합니다.
R-03	최초 호출은 대기 없이 수행합니다. 실패 후 재시도가 남은 경우에만 지정 간격을 기다립니다. 성공하면 즉시 반환하고, 마지막 실패 후에는 대기하지 않습니다.
R-04	브로커의 emit() 또는 request() 호출이 예외를 던지면 재시도 정책을 적용합니다. 사용자가 확정한 범위에는 RemoteError를 포함한 브로커 호출의 모든 일반 예외가 포함됩니다. 입력·작업 검증 및 기능 지원 확인 단계에서 발생하는 오류는 재시도하지 않습니다.
R-05	어느 시도에서든 성공하면 해당 호출의 기존 반환값을 그대로 반환합니다. 모든 시도가 실패하면 마지막 시도의 예외 객체와 타입을 바꾸지 않고 전파합니다.
R-06	request()의 기존 timeout은 각 재시도 호출에 동일하게 전달합니다. 재시도 전체 시간에 대한 별도 총 timeout은 추가하지 않습니다. 기존 priority, 본문과 작업 매개변수 전달도 유지합니다.
R-07	재시도는 DefStream.Worker의 emit()·request()에만 적용합니다. 브로커 Protocol·구현체에는 재시도 설정이나 중복 재시도를 추가하지 않습니다.
R-08	기존 동작을 유지하면서 재시도가 기본 비활성화된 선택 기능으로 동작해야 합니다. 입력 검증·브로커 소유권·연결 수명주기 계약은 바꾸지 않습니다.
R-09	문서에서 emit()/request() 호출 재시도와 소비 중 메시지 오류·재전달 정책을 구분하고, 이미 처리된 발행·요청이 다시 전송될 수 있음을 안내합니다.

구체화한 구현 계약

• retry는 None 또는 bool이 아닌 0 이상의 정수입니다. 다른 타입은 TypeError, 음수는 ValueError로 거부합니다.
• interval은 bool이 아닌 유한한 0 이상의 정수 또는 실수입니다. 타입이 맞지 않으면 TypeError, 음수나 비유한 값은 ValueError로 거부합니다. 두 인자의 유효성은 브로커 메서드 호출 전에 검사합니다.
• RemoteError까지 재시도하면 원격 작업 오류 응답을 받은 경우에도 해당 요청을 다시 실행할 수 있습니다. 이 동작은 사용자가 선택한 예외 범위에 따른 의도된 결과이며, 멱등성이나 중복 방지는 이 요구사항에 포함되지 않습니다.

인수 기준

아래 기준은 구현 완료 후 확인했으며, 검증 범위와 미실행 항목은 작업 종합에 기록합니다.

ID	검증 기준
AC-01	기본값에서는 emit()과 request()가 한 번만 호출되고 재시도 대기가 없습니다.
AC-02	재시도 횟수 0은 한 번, N은 최대 N + 1번 호출합니다.
AC-03	계속 실패하는 N회 재시도는 N회 대기만 수행하며, 마지막 실패 후에는 대기하지 않습니다.
AC-04	중간 시도에서 성공하면 반환값을 보존하고 후속 호출·대기를 하지 않습니다.
AC-05	계속 실패하면 마지막 예외 객체를 그대로 전파합니다. RemoteError도 지정 횟수까지 재시도합니다.
AC-06	두 함수의 재시도에서 priority·요청 timeout·본문·작업 매개변수 전달이 기존 계약과 일치합니다.
AC-07	작업·본문·브로커 기능 검증 실패는 브로커 메서드를 호출하지 않고 재시도도 하지 않습니다.
AC-08	단위 테스트에서 실제 대기 없이 기본·사용자 지정 간격과 정확한 대기 횟수를 검증합니다.
AC-09	한국어·영어 작업 매뉴얼에 공개 API, 사용 예, 기본 동작 및 중복 실행 주의사항을 일관되게 반영합니다.

범위 제외

• 브로커별 재시도, 오류 종류별 backoff·jitter, 재시도 전체 deadline, 자동 연결 재생성은 추가하지 않습니다.
• 멱등 키, 중복 요청 제거, exactly-once 처리 또는 중복 실행 방지는 보장하지 않습니다.
• 소비자 측 ACK·NACK·메시지 재전달 정책은 변경하지 않습니다.

원문

CHANGELOG.md

Worker 메시지 발행·요청 재시도

emit()과 request()에 retry와 interval 옵션을 추가했습니다. 기본 설정은 기존처럼 한 번만 호출하며, 재시도 횟수를 설정하면 실패한 브로커 호출을 지정 횟수까지 다시 시도합니다. request()의 timeout은 각 호출에 적용됩니다.

브로커 호출에서 발생한 RemoteError를 포함한 예외도 재시도 대상입니다. 원격 작업이 이미 실행된 뒤 오류 응답을 받은 요청도 다시 실행될 수 있으므로, 중복 요청이나 부작용에 안전한 작업에만 재시도를 설정하세요.

원문

IMPLEMENTS.md

Worker 메시지 발행·요청 재시도 구현

결과

요구사항 명세에 따라 Worker 메시지 함수의 emit()과 request()에 retry와 interval 키워드 인자를 추가했습니다. 기본값은 각각 None과 1초입니다. None 또는 0은 한 번 호출하며, N은 최초 호출 후 최대 N번 추가 호출합니다.

입력 설정은 브로커 호출 전에 검증합니다. 재시도는 브로커의 emit()·request() 호출에만 적용하고, 실패 후 시도가 남은 때만 대기하며, 최종 예외를 그대로 전파합니다. request()의 timeout과 두 API의 기존 우선순위 전달을 재시도마다 유지합니다. 모든 Exception을 대상으로 하므로 RemoteError도 재시도되며, 중복 요청·작업 실행 방지는 제공하지 않습니다.

브로커 인터페이스나 구현체, 연결 생성·종료 동작은 변경하지 않았습니다.

초기 구현 후 공개 인자명을 retry와 interval로 변경했습니다. 현재 API와 문서에는 이전 이름을 남기지 않았습니다.

검증

• 메시지 API 회귀 테스트: 13개 테스트 통과. 재시도 횟수·대기, 기본값·0회, 중간 성공, 최종 예외 객체 보존, RemoteError, priority·timeout, 입력 검증을 확인했습니다.
• Pylance 함수 시그니처 호환성 검사에서 emit()·request()의 기존 호출부가 각각 호환됨을 확인했습니다.
• Pylance 진단에서 오류가 없고, 변경한 Python 소스와 테스트의 syntax 검사도 통과했습니다.
• 한국어·영어 작업 매뉴얼과 고객용 변경 로그를 갱신했습니다.
• 실제 RabbitMQ·Redis 연결 장애에 대한 통합 검증은 수행하지 않았습니다.

단계별 기록

• Worker 재시도 구현

원문

변경 유형

• 버그 수정 및 일반 변경, 핫픽스 처리
• 기능 추가
• 호환성에 영향을 주는 변경
• 문서 또는 예제 변경
• 기타

검증

TASKS.md

작업 종합

결과

이슈 #55의 요구를 현재 Worker API, Broker Protocol, 메시지 테스트와 작업 매뉴얼에 대조해 분석했다. emit()·request() 호출에만 재시도를 적용하고 입력 검증·지원 기능 확인은 재시도 바깥에 두었다. 구현 내용과 변경 파일은 구현 종합에 정리했다.

사용자 선택에 따라 브로커 호출에서 발생하는 모든 예외를 재시도하며 RemoteError도 포함한다. 따라서 재시도 도중 동일 작업이나 요청이 반복될 수 있다는 제한과 문서 반영 필요성을 명시했다.

단계별 기록

• 이슈 #55 분석 및 검증 계획 작성
• Worker 재시도 구현 검증 및 문서 갱신
• 재시도 API 인자 이름 변경

검증 결과와 제한사항

• tests.test_task_messages focused suite의 13개 테스트가 통과했다. 기본 Python 명령은 editable .pth의 Windows symlink 권한 문제로 import에 실패했으나, workspace Python과 임시 unittest runner로 동일한 suite를 통과시켰다.
• Pylance 함수 시그니처 호환성 검사를 통과했고, Message.py에 진단이 없으며 변경 Python 파일의 syntax 오류가 없다.
• 한국어·영어 작업 매뉴얼과 고객용 변경 로그를 갱신했다.
• 실제 RabbitMQ·Redis 브로커 장애·전송 결과의 통합 검증은 수행하지 않았다. RemoteError도 재시도하므로 원격 작업이 이미 처리된 경우 중복 실행 가능성이 남는다.

원문

• 관련 테스트를 실행했습니다.
• 문서와 예제를 확인했습니다.

확인 사항

• 변경 범위가 요청 사항에 한정되어 있습니다.
• 공개 API나 기존 동작에 영향을 주는 경우 변경 내용과 마이그레이션 방법을 설명했습니다.
• 민감 정보나 불필요한 디버깅 코드를 포함하지 않았습니다.

Closes #55

[Copilot]

🟡 Changes recommended

The interval validation and retry delay handling still allow extremely large finite values to raise OverflowError, bypassing the documented contract and preventing the intended retry or broker-error behavior.

2 open issues

• Handle overflow when validating very large integer intervals · New
• Reject or handle intervals too large for time.sleep · New

What changed in this PR

Adds configurable retry behavior to the Worker-level emit() and request() APIs while preserving existing broker contracts, payloads, priorities, timeouts, and exception propagation.

Changes:

• Added retry and interval options with validation and broker-call retry handling.
• Added focused tests for retry counts, delays, successful recovery, exception propagation, and argument forwarding.
• Updated Korean and English manuals, changelog, and issue implementation records.
• Documented the possibility of duplicate execution when retries are used.

File	Summary
tests/​test_task_messages.py	Adds focused coverage for retry behavior, delays, validation, exception propagation, priority, and timeout forwarding.
src/​Worker/​Message.py	Implements retry validation and broker-call retry loops for emit() and request(). Two moderate findings remain regarding oversized interval validation and time.sleep() overflow handling.
issues/​feature/​55/​tasks/​1793715537355.md	Records the public argument-name change; contains one nit regarding the accuracy of a repository search result.
issues/​feature/​55/​tasks/​1793714914194.md	Records focused testing and documentation verification.
issues/​feature/​55/​tasks/​1793705387888.md	Records the initial requirements analysis and verification plan.
issues/​feature/​55/​TASKS.md	Summarizes completed work, testing, and integration-test limitations.
issues/​feature/​55/​REQUIREMENTS.md	Defines the retry API contract, validation rules, and acceptance criteria.
issues/​feature/​55/​README.md	Records the feature scope and acceptance criteria; contains one nit because the documented argument names are not yet stated as finalized.
issues/​feature/​55/​PLAN.md	Describes the implementation, testing, and documentation plan.
issues/​feature/​55/​implements/​1793714914193.md	Records implementation details and focused verification results.
issues/​feature/​55/​IMPLEMENTS.md	Summarizes the implementation, tests, and known integration-validation limitations.
issues/​feature/​55/​CHANGELOG.md	Documents the retry options and duplicate-execution warning.
docs/​Tasks.md	Documents the retry API and operational behavior in Korean.
docs/​Tasks.en.md	Documents the retry API and operational behavior in English.

_{Review effort: Lite}

[Copilot]

🟡 Changes recommended

현재 검증 요약이 테스트 수와 일치하지 않는 문서상의 불일치가 남아 있어 수정이 필요합니다.

1 open issue

• 검증 요약의 테스트 수가 현재 테스트 수와 불일치 · New

2 resolved since last review

• Reject or handle intervals too large for time.sleep
• Handle overflow when validating very large integer intervals

_{Review effort: Lite}