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

docs/Tasks.en.md

@@ -11,8 +11,8 @@ Task APIs, delivery policies, pools, and lifecycle hooks.
 | Function | Purpose | Connection ownership |
 | --- | --- | --- |
 | `declare(task=..., broker=...)` | Declare task queues and subscription resources | Caller connects and closes |
-| `emit(body, task=..., broker=...)` | Publish a one-way message to a task | Caller connects and closes |
-| `request(body, task=..., broker=..., timeout=5)` | Request a task result synchronously | Caller connects and closes; RabbitMQ only |
+| `emit(body, task=..., broker=..., retry=None, interval=1)` | Publish a one-way message to a task | Caller connects and closes |
+| `request(body, task=..., broker=..., timeout=5, retry=None, interval=1)` | Request a task result synchronously | Caller connects and closes; RabbitMQ only |
 
 Import these functions from `DefStream.Worker`. They do not connect or close
 the supplied connection. Neither `emit()` nor `request()` declares destinations.
@@ -118,14 +118,51 @@ result = request(
 - Priority affects delivery of waiting messages within the same queue. It does not
   preempt delivered or running tasks or guarantee execution and completion order.
 
+### Publication and request retries
+
+`emit()` and `request()` can optionally retry a broker call that raises an exception.
+The default `retry=None` preserves the existing single-call behavior. The value
+counts additional attempts after the first call, so `retry=3` allows up to four
+calls. The default `interval` is one second; it is applied only after a failure
+when another attempt remains. `retry` must be `None` or a non-negative integer
+other than `bool`, and `interval` must be a finite non-negative number other
+than `bool`. To stay within the platform's supported wait range, `interval` is capped
+at `threading.TIMEOUT_MAX` seconds. Out-of-range values raise `ValueError` before the broker call.
+
+```python
+emit(
+  {'a': 10, 'b': 20},
+  task=Add,
+  broker=broker,
+  retry=3,
+  interval=0.5,
+)
+
+# The request timeout applies to each call independently of the retry count.
+result = request(
+  {'a': 10, 'b': 20},
+  task=Add,
+  broker=broker,
+  timeout=5,
+  retry=2,
+)
+```
+
+A successful attempt returns immediately. If every attempt fails, the final exception
+is re-raised. Exceptions raised by broker `emit()` and `request()` calls are retried,
+including `RemoteError`; therefore a request may run again even if its remote task
+already executed before returning an error. Retries do not prevent duplicate
+publication or execution, so tasks using retries should be safe to run more than once.
+Invalid inputs and unsupported broker operations are not retried.
+
 ### Success, failures, and retries
 
 - ACK follows successful execution and completion hooks. RabbitMQ RPC also publishes the reply before ACK.
 - Failures use the task's `on_error` policy. If omitted, the broker's default behavior applies; choose a policy provided by that broker, such as `Reject()`, when needed.
 - `Policy` is the shared broker contract. Import `Requeue` and `Reject` from the selected broker package; behavior can differ by broker.
 - Rejection is broker-specific: RabbitMQ dead-letters to a configured DLQ or discards the message;
   Redis acknowledges it for the group while preserving stream history.
-- There is no automatic retry-count limit. Choose a policy that avoids endless redelivery of permanently invalid messages.
+- Consumer message redelivery has no automatic retry-count limit. Choose a policy that avoids endless redelivery of permanently invalid messages.
 - Publication and ACK are not one transaction. **Make tasks idempotent and safe to execute more than once.**
 
 The common resource operations below apply when accessing a broker directly.

docs/Tasks.md

@@ -11,8 +11,8 @@
 | 함수 | 역할 | 연결 관리 |
 | --- | --- | --- |
 | `declare(task=..., broker=...)` | 작업의 큐·구독 리소스 선언 | 호출자가 연결·종료 |
-| `emit(body, task=..., broker=...)` | 작업 목적지로 단방향 메시지 발행 | 호출자가 연결·종료 |
-| `request(body, task=..., broker=..., timeout=5)` | 작업 결과를 동기 RPC로 요청 | 호출자가 연결·종료; RabbitMQ만 지원 |
+| `emit(body, task=..., broker=..., retry=None, interval=1)` | 작업 목적지로 단방향 메시지 발행 | 호출자가 연결·종료 |
+| `request(body, task=..., broker=..., timeout=5, retry=None, interval=1)` | 작업 결과를 동기 RPC로 요청 | 호출자가 연결·종료; RabbitMQ만 지원 |
 
 세 함수는 `DefStream.Worker`에서 가져옵니다. 전달된 연결을 자동으로 열거나 닫지 않으며,
 `emit()`와 `request()`는 목적지를 자동 선언하지 않습니다.
@@ -116,6 +116,41 @@ result = request(
 - 우선순위는 같은 큐의 대기 메시지 전달에 적용됩니다. 이미 전달·실행 중인
   작업을 선점하거나 여러 작업의 실행·완료 순서를 보장하지 않습니다.
 
+### 발행·요청 재시도
+
+`emit()`과 `request()`는 브로커 호출이 예외로 실패하면 선택적으로 다시 시도할 수 있습니다.
+기본 `retry=None`은 기존처럼 한 번만 호출합니다. 횟수는 최초 시도 이후의
+추가 횟수이므로 `retry=3`은 최대 네 번 호출합니다. 실패 후 다음 시도가 남았을 때만
+`interval`초를 기다리며 기본 간격은 1초입니다.
+`retry`는 `None` 또는 bool이 아닌 0 이상의 정수이고, `interval`은 bool이 아닌
+유한한 0 이상의 숫자여야 합니다. 플랫폼의 대기 시간 범위를 넘지 않도록 `interval`의 상한은
+`threading.TIMEOUT_MAX`초로 제한합니다. 범위를 벗어난 값은 브로커 호출 전에 `ValueError`로 거부합니다.
+
+```python
+emit(
+  {'a': 10, 'b': 20},
+  task=Add,
+  broker=broker,
+  retry=3,
+  interval=0.5,
+)
+
+# 요청의 timeout은 재시도 횟수와 별도로 매 호출에 적용됩니다.
+result = request(
+  {'a': 10, 'b': 20},
+  task=Add,
+  broker=broker,
+  timeout=5,
+  retry=2,
+)
+```
+
+중간 호출이 성공하면 결과를 바로 반환하고, 모든 호출이 실패하면 마지막 예외를 그대로
+전파합니다. `RemoteError`를 포함해 브로커의 발행·요청 호출에서 발생한 예외를 재시도하므로,
+원격 작업이 이미 실행된 뒤 오류 응답을 받은 요청도 다시 실행될 수 있습니다. 중복 전송이나
+작업 실행을 방지하지 않으므로 재시도가 필요한 작업은 중복 실행에 안전하도록 설계하세요.
+잘못된 입력이나 브로커 기능 미지원 오류는 재시도하지 않습니다.
+
 ### 성공, 실패와 재시도
 
 - 작업 실행과 완료 훅이 성공한 뒤 ACK합니다. RabbitMQ RPC는 응답 발행도 ACK보다 먼저 수행합니다.
@@ -124,7 +159,7 @@ result = request(
   패키지에서 가져오며, 같은 이름의 정책도 동작은 브로커마다 다를 수 있습니다.
 - `Reject()`의 실제 효과는 브로커에 따라 다릅니다. RabbitMQ는 설정된 DLQ로 보내거나 폐기하며,
   Redis는 해당 그룹에서 ACK하고 스트림 이력은 유지합니다.
-- 재시도 횟수의 자동 제한은 없습니다. 영구적인 오류가 무한 재전달되지 않도록 정책을 선택하세요.
+- 소비자 측 메시지 재전달 횟수에는 자동 제한이 없습니다. 영구적인 오류가 무한 재전달되지 않도록 정책을 선택하세요.
 - 전송과 ACK는 하나의 트랜잭션이 아닙니다. **중복 실행에 안전한 멱등 작업**을 작성해야 합니다.
 
 브로커 리소스를 직접 사용할 때의 공통 메서드는 다음과 같습니다.

issues/feature/55/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Worker 메시지 발행·요청 재시도
+
+`emit()`과 `request()`에 `retry`와 `interval` 옵션을 추가했습니다. 기본 설정은 기존처럼 한 번만 호출하며, 재시도 횟수를 설정하면 실패한 브로커 호출을 지정 횟수까지 다시 시도합니다. `request()`의 `timeout`은 각 호출에 적용됩니다.
+
+브로커 호출에서 발생한 `RemoteError`를 포함한 예외도 재시도 대상입니다. 원격 작업이 이미 실행된 뒤 오류 응답을 받은 요청도 다시 실행될 수 있으므로, 중복 요청이나 부작용에 안전한 작업에만 재시도를 설정하세요.
+
+`interval`은 0 이상 `threading.TIMEOUT_MAX`초 이하로 제한합니다. 지나치게 큰 간격은 브로커 호출 전에 `ValueError`로 거부하여 대기 중 오버플로가 브로커 오류를 가리는 상황을 방지합니다.

issues/feature/55/IMPLEMENTS.md

@@ -0,0 +1,26 @@
+# Worker 메시지 발행·요청 재시도 구현
+
+## 결과
+
+[요구사항 명세](./REQUIREMENTS.md)에 따라 [Worker 메시지 함수](../../../src/Worker/Message.py)의 `emit()`과 `request()`에 `retry`와 `interval` 키워드 인자를 추가했습니다. 기본값은 각각 `None`과 1초입니다. `None` 또는 `0`은 한 번 호출하며, `N`은 최초 호출 후 최대 `N`번 추가 호출합니다.
+
+입력 설정은 브로커 호출 전에 검증합니다. 재시도는 브로커의 `emit()`·`request()` 호출에만 적용하고, 실패 후 시도가 남은 때만 대기하며, 최종 예외를 그대로 전파합니다. `request()`의 `timeout`과 두 API의 기존 우선순위 전달을 재시도마다 유지합니다. 모든 `Exception`을 대상으로 하므로 `RemoteError`도 재시도되며, 중복 요청·작업 실행 방지는 제공하지 않습니다.
+
+브로커 인터페이스나 구현체, 연결 생성·종료 동작은 변경하지 않았습니다.
+
+PR 리뷰 후 `interval`을 `threading.TIMEOUT_MAX` 이하로 제한하고 범위 비교를 실수 변환보다 먼저 수행하도록 보완했습니다. 지나치게 큰 간격은 브로커 호출 전에 `ValueError`로 거부합니다. 경계값 테스트 2개를 추가하여 현재 메시지 API 테스트 15개가 통과했습니다.
+
+초기 구현 후 공개 인자명을 `retry`와 `interval`로 변경했습니다. 현재 API와 문서에는 이전 이름을 남기지 않았습니다.
+
+## 검증
+
+- [메시지 API 회귀 테스트](../../../tests/test_task_messages.py): 15개 테스트 통과. 재시도 횟수·대기, 기본값·0회, 중간 성공, 최종 예외 객체 보존, `RemoteError`, priority·timeout, 입력 검증과 간격 경계값을 확인했습니다.
+- Pylance 함수 시그니처 호환성 검사에서 `emit()`·`request()`의 기존 호출부가 각각 호환됨을 확인했습니다.
+- Pylance 진단에서 오류가 없고, 변경한 Python 소스와 테스트의 syntax 검사도 통과했습니다.
+- 한국어·영어 작업 매뉴얼과 고객용 [변경 로그](./CHANGELOG.md)를 갱신했습니다.
+- 실제 RabbitMQ·Redis 연결 장애에 대한 통합 검증은 수행하지 않았습니다.
+
+## 단계별 기록
+
+- [Worker 재시도 구현](./implements/1793714914193.md)
+- [재시도 간격 오버플로 사전 차단](./implements/1793717149425.md)

issues/feature/55/PLAN.md

@@ -0,0 +1,77 @@
+# Worker 메시지 발행·요청 재시도 계획
+
+작업 범위와 진행 상태는 [이슈 기록](./README.md), 목표 동작과 미확정 사항은 [요구사항 명세](./REQUIREMENTS.md)를 따릅니다. 구현과 대상 단위 테스트, 한국어·영어 작업 매뉴얼 갱신을 완료했습니다. 최종 검증 결과와 남은 제한은 [작업 종합](./TASKS.md) 및 [구현 종합](./IMPLEMENTS.md)에 반영했습니다.
+
+## 수행 단계와 진행 상태
+
+### 1. 공개 인자와 입력 계약 확정
+
+상태: 완료
+
+- `emit()`·`request()`의 키워드 전용 인자는 `retry`와 `interval`로 확정했습니다.
+- 재시도 횟수는 `None` 또는 bool이 아닌 0 이상의 정수, 간격은 bool이 아닌 유한한 0 이상의 정수·실수로 제한하고, 브로커 호출 전에 검증합니다.
+- 재시도 범위가 모든 브로커 호출 예외, `RemoteError` 포함이라는 결정을 유지합니다.
+
+대응: R-01·R-04, AC-05·AC-07
+
+### 2. Worker 계층 재시도 구현
+
+상태: 완료 / 선행: 1단계
+
+대상: [Message.py](../../../src/Worker/Message.py)
+
+- 기존 입력·지원 기능 확인과 `priority_parameters()` 처리는 재시도 루프 바깥에 유지합니다.
+- `emit()`과 `request()`의 실제 브로커 호출에 동일한 횟수·간격 정책을 적용합니다.
+- 성공값을 그대로 반환하고, 실패 후 시도가 남아 있는 때만 대기하며, 최종 예외를 변환하지 않고 다시 발생시킵니다.
+- 기존 `request(timeout=...)` 및 우선순위 호출 경로의 전달값을 유지합니다.
+- 브로커 Protocol·구현체와 연결 소유권은 변경하지 않습니다.
+
+대응: R-02~R-08, AC-01~AC-07
+
+### 3. 단위 회귀 테스트
+
+상태: 완료 / 선행: 2단계
+
+대상: [test_task_messages.py](../../../tests/test_task_messages.py)
+
+- Mock 브로커의 성공·실패 순서를 제어해 최초 성공, 중간 성공, 최대 횟수 실패, 마지막 예외 객체 보존을 검증합니다.
+- `sleep` 등 실제 시간 대기는 Mock 처리하고, 기본·사용자 지정 간격 및 대기 횟수를 확인합니다.
+- `emit()`·`request()` 각각에서 `priority`와 `timeout`이 모든 호출에 유지되는지 확인합니다.
+- 기존 입력·기능 지원 검증이 브로커 호출 전에 실패하고 재시도하지 않는지 확인합니다.
+
+대응: AC-01~AC-08
+
+### 4. 매뉴얼과 고객용 변경 로그 갱신
+
+상태: 완료 / 선행: 2·3단계
+
+- [한국어 작업 매뉴얼](../../../docs/Tasks.md)과 [영어 작업 매뉴얼](../../../docs/Tasks.en.md)에 API 옵션·사용 예·기본값·시도 횟수 의미를 함께 반영합니다.
+- 호출 재시도와 소비자 메시지 재전달을 구분하고, `RemoteError` 포함 재시도가 중복 요청·작업 실행을 일으킬 수 있음을 설명합니다.
+- 구현 결과를 기준으로 이슈별 [변경 로그](./CHANGELOG.md)를 작성했습니다.
+
+대응: R-09, AC-09
+
+### 5. 검증 및 완료 확인
+
+상태: 완료 / 선행: 2~4단계
+
+- 저장소의 focused unittest 명령으로 메시지 API 회귀 테스트를 실행했습니다.
+- 변경된 문서와 인수 기준의 일치, 한국어·영어 매뉴얼 간 내용 일치, 새 예제의 실제 공개 API 적합성을 확인했습니다.
+- 실제 브로커 장애·전송 후 중복 처리 동작은 검증하지 않았으며, 테스트 결과로 주장하지 않고 제한사항으로 남겼습니다.
+- 실제 수행 결과를 작업 기록 및 `TASKS.md`에 반영하고, 구현 종합과 단계별 기록을 작성했습니다.
+
+## 검증 계획
+
+| 범위 | 방법 | 결과 |
+| --- | --- | --- |
+| Worker 메시지 API 회귀 | `tests.test_task_messages` 단위 테스트 | PR 리뷰 경계값 보완 후 15개 테스트 통과 |
+| 재시도 횟수·대기 | Mock 브로커와 Mock 대기 함수로 호출 수·대기 인자·횟수 확인 | 기본·0회, 최대 3회 추가 재시도, 중간 성공 및 대기 횟수 검증 통과 |
+| 기존 전달 계약 | Mock 호출 인자로 본문·작업 설정·priority·timeout 확인 | `emit()`·`request()` 재시도 호출에서 전달 유지 확인 |
+| 공개 시그니처·정적 검사 | Pylance 호출 호환성·진단·syntax 검사 | 기존 호출부 호환, 진단·syntax 오류 없음 |
+| 문서 계약 | `Tasks.md`·`Tasks.en.md`의 API 설명·예·중복 처리 주의사항 대조 | 한영 매뉴얼 및 이슈별 변경 로그 갱신 |
+
+## 계획의 한계
+
+- 모든 브로커 호출 예외를 재시도하므로 일시적인 전송 오류뿐 아니라 `RemoteError`와 같은 영구적 원격 작업 오류도 반복할 수 있습니다. 이 범위는 사용자 결정이며, 중복 방지는 별도 범위입니다.
+- 실제 브로커 통합 검증은 단위 테스트와 별개입니다. 구현 시 로컬 브로커 환경이 준비되지 않았다면 실행하지 않은 사실을 기록합니다.
+- 전체 검증 결과와 실행 환경 제약은 [작업 종합](./TASKS.md)을 기준으로 갱신합니다.