DefStream-RabbitMQ 0.1.25__tar.gz → 0.1.27__tar.gz

{defstream_rabbitmq-0.1.25 → defstream_rabbitmq-0.1.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DefStream-RabbitMQ
-Version: 0.1.25
+Version: 0.1.27
 Summary: Synchronous message processing with pluggable broker adapters
 Home-page: https://github.com/yong5eon/DefStream
 Author: Heo Yongseon
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: DefStream==0.1.25
+Requires-Dist: DefStream==0.1.27
 Requires-Dist: pika>=1.3.2
 Dynamic: author
 Dynamic: classifier

{defstream_rabbitmq-0.1.25 → defstream_rabbitmq-0.1.27}/build/RabbitMQ/DefStream_RabbitMQ.egg-info/SOURCES.txt

@@ -112,6 +112,22 @@ issues/feature/55/tasks/1793705387888.md
 issues/feature/55/tasks/1793714914194.md
 issues/feature/55/tasks/1793715537355.md
 issues/feature/55/tasks/1793717149426.md
+issues/feature/62/CHANGELOG.md
+issues/feature/62/IMPLEMENTS.md
+issues/feature/62/PLAN.md
+issues/feature/62/README.md
+issues/feature/62/REQUIREMENTS.md
+issues/feature/62/TASKS.md
+issues/feature/62/implements/1793777682327.md
+issues/feature/62/implements/1793778339166.md
+issues/feature/62/tasks/1793772101827.md
+issues/feature/62/tasks/1793774701691.md
+issues/feature/62/tasks/1793775544541.md
+issues/feature/62/tasks/1793775771772.md
+issues/feature/62/tasks/1793777337621.md
+issues/feature/62/tasks/1793777847993.md
+issues/feature/62/tasks/1793778003070.md
+issues/feature/62/tasks/1793778440735.md
 issues/feature/8/IMPLEMENTS.md
 issues/feature/8/README.md
 issues/feature/8/REQUIREMENTS.md
@@ -216,6 +232,18 @@ issues/fix/53/tasks/1793518878754.md
 issues/fix/6/IMPLEMENTS.md
 issues/fix/6/README.md
 issues/fix/6/REQUIREMENTS.md
+issues/fix/64/CHANGELOG.md
+issues/fix/64/IMPLEMENTS.md
+issues/fix/64/PLAN.md
+issues/fix/64/README.md
+issues/fix/64/REQUIREMENTS.md
+issues/fix/64/TASKS.md
+issues/fix/64/implements/1793807653096.md
+issues/fix/64/implements/1793807663436.md
+issues/fix/64/tasks/1793806949650.md
+issues/fix/64/tasks/1793807182094.md
+issues/fix/64/tasks/1793807663435.md
+issues/fix/64/tasks/1793807722809.md
 issues/task/18/IMPLEMENTS.md
 issues/task/18/README.md
 issues/task/18/REQUIREMENTS.md
@@ -292,6 +320,7 @@ res/docker/redis/redis-7.yml
 samples/Broker/Sample.py
 samples/Broker/RabbitMQ/Sample.RPC.py
 samples/Broker/RabbitMQ/Sample.Stream.py
+samples/Broker/RabbitMQ/Sample.Timer.py
 samples/Broker/RabbitMQ/Sample.py
 samples/Broker/Redis/Sample.Stream.py
 samples/Broker/Redis/Sample.py
@@ -402,6 +431,7 @@ tests/rabbitmq/test_rabbitmq_priorities.py
 tests/rabbitmq/test_rabbitmq_rpc.py
 tests/rabbitmq/test_rabbitmq_rpc_integration.py
 tests/rabbitmq/test_rabbitmq_timeouts.py
+tests/rabbitmq/test_rabbitmq_timers.py
 tests/rabbitmq/test_rabbitmq_worker.py
 tests/rabbitmq/test_specifications.py
 tests/rabbitmq/test_task_messages.py

{defstream_rabbitmq-0.1.25 → defstream_rabbitmq-0.1.27}/docs/README.en.md

@@ -35,5 +35,5 @@ Messages published by a producer pass through the broker to a Worker Consumer, a
 - [Lifecycle hooks](./LifecycleHooks.en.md): hook order and resource management across Workers, pools, and tasks
 - [Request/reply contracts and validation](./Contracts.en.md): schemas, validators, and task contracts
 - [Operations and monitoring](./Operations.en.md): Inspector, logging, and operational broker considerations
-- [RabbitMQ](./RabbitMQ.en.md): queues, exchanges, streams, RPC, and RabbitMQ workers
+- [RabbitMQ](./RabbitMQ.en.md): queues, exchanges, streams, RPC, connection timers, and RabbitMQ workers
 - [Redis Streams](./Redis.en.md): messages, consumer groups, acknowledgements, and Redis workers

{defstream_rabbitmq-0.1.25 → defstream_rabbitmq-0.1.27}/docs/README.md

@@ -35,5 +35,5 @@ Producer가 발행한 메시지는 브로커를 거쳐 Worker의 Consumer로 전
 - [생명주기 훅](./LifecycleHooks.md): Worker·풀·작업 훅의 실행 순서와 자원 관리
 - [요청·응답 계약과 검증](./Contracts.md): 스키마, validator와 작업 계약
 - [운영과 모니터링](./Operations.md): Inspector, 로깅, 브로커 선택과 운영 고려사항
-- [RabbitMQ](./RabbitMQ.md): 큐, Exchange, 스트림, RPC와 RabbitMQ Worker
+- [RabbitMQ](./RabbitMQ.md): 큐, Exchange, 스트림, RPC, 연결 타이머와 RabbitMQ Worker
 - [Redis Streams](./Redis.md): 메시지, consumer group, ACK와 Redis Worker

{defstream_rabbitmq-0.1.25 → defstream_rabbitmq-0.1.27}/docs/RabbitMQ.en.md

@@ -88,6 +88,116 @@ Call `ack()` on success, `nack()` for redelivery, or `reject()` to reject.
 Rejected messages go to the broker-configured dead-letter destination or are
 discarded when none is configured.
 
+### Connection timers
+
+RabbitMQ connections support the optional `SetTimer` protocol.
+`set_timer(cb, seconds)` schedules a one-shot callback using integer seconds
+from registration and returns a cancelable `Timer`. The callback takes no
+arguments and returns no value. Code using a connection can check support
+with `isinstance(connection, SetTimer)`. Timer support is not required by
+the base `Connection` contract or Redis connections.
+
+This example consumes an empty queue and stops consumption from a callback
+after five seconds. It requires local RabbitMQ and leaves
+`defstream.example.timer` in place. Messages sent to this queue by other
+producers are printed and acknowledged.
+
+```python
+from DefStream.Broker import Event, SetTimer
+from DefStream.Broker.Implements.RabbitMQ import Configuration, Connection
+
+
+def receive(event: Event) -> None:
+  print(event.body)
+  event.ack()
+
+
+connection = Connection(Configuration(
+  host='127.0.0.1',
+  port=5672,
+  username='guest',
+  password='guest',
+))
+try:
+  connection.connect()
+  if not isinstance(connection, SetTimer):
+    raise TypeError('Connection does not support timers')
+  connection.create_queue('defstream.example.timer')
+  consumer = connection.consumer()
+  consumer.subs('defstream.example.timer', receive)
+
+  def expired() -> None:
+    print('Timer fired')
+    consumer.stop()
+
+  timer = connection.set_timer(cb=expired, seconds=5)
+  try:
+    consumer.run()
+  finally:
+    timer.remove()
+    consumer.close()
+finally:
+  connection.close()
+```
+
+Call `timer.remove()` before execution to cancel the scheduled callback.
+The handle belongs to the connection that registered it; reopening a connection
+does not redirect cancellation to the new connection.
+Already-fired or canceled timers, closed connections, and negative or zero
+delays retain Pika's behavior and errors. `remove()` does not interrupt a
+callback that is already running.
+
+For repetition, register the next timer inside the callback.
+The following excerpt replaces the `expired` definition and the one-shot
+registration, execution, and consumer cleanup above, after preparing the
+subscription through `consumer.subs(...)`. Keep the outer `finally` that
+closes the connection. It fires three times at five-second intervals, then
+stops, retaining the latest handle for cancellation.
+
+```python
+from DefStream.Broker import Consumer, SetTimer, Timer
+
+
+def run_repeated(connection: SetTimer, consumer: Consumer) -> None:
+  remaining = 3
+  timer: Timer
+
+  def tick() -> None:
+    nonlocal remaining, timer
+    print('Timer fired')
+    remaining -= 1
+    if remaining:
+      timer = connection.set_timer(tick, 5)
+    else:
+      consumer.stop()
+
+  timer = connection.set_timer(tick, 5)
+  try:
+    consumer.run()
+  finally:
+    timer.remove()
+
+
+try:
+  run_repeated(connection, consumer)
+finally:
+  consumer.close()
+```
+
+The implementation delegates directly to Pika's `call_later` and
+`remove_timeout`. Callbacks run only while Pika processes events, such as
+during `consumer.run()`. Registering a timer and calling `sleep()` alone
+does not dispatch it. Long message handlers and other event-loop work can
+delay execution. Callbacks run on the connection owner thread, and their
+exceptions propagate through the existing event-processing path.
+
+Registration and cancellation follow Pika's owner-thread restrictions;
+no additional thread safety is provided. Consumer exit does not automatically
+cancel connection timers, so callers must cancel reservations when appropriate.
+The examples cancel before closing the connection; cancellation on a closed
+connection is not guaranteed to succeed. No separate timer thread,
+general-purpose scheduler, or automatic cleanup layer is provided.
+
 ### Logging
 
 `Connection`, `Consumer`, `Queue`, `Exchange`, `Stream`, and `Event` expose a class
@@ -383,3 +493,18 @@ publishing the reply but before ACK, the task may be redelivered and run again.
 - [Sample.py](../samples/Broker/RabbitMQ/Sample.py)
 - [Sample.Stream.py](../samples/Broker/RabbitMQ/Sample.Stream.py)
 - [Sample.RPC.py](../samples/Broker/RabbitMQ/Sample.RPC.py)
+- [Sample.Timer.py](../samples/Broker/RabbitMQ/Sample.Timer.py): one-shot cancellation and repetition by re-registering callbacks
+
+The timer sample uses local RabbitMQ at `127.0.0.1:5672` with the `guest` account.
+Enable the RabbitMQ implementation in your development environment and run it
+from the repository root.
+
+```shell
+python samples/Broker/RabbitMQ/Sample.Timer.py
+```
+
+Each run creates a uniquely named empty queue, cancels one callback before
+execution, then logs three timer callbacks at one-second intervals and stops
+consumption. It cleans up the latest timer, consumer channel, sample queue,
+and connection. The Stream sample also uses the connection's `set_timer`
+instead of a separate timer thread to stop consumption.

{defstream_rabbitmq-0.1.25 → defstream_rabbitmq-0.1.27}/docs/RabbitMQ.md

@@ -103,6 +103,109 @@ finally:
 일반 연결의 heartbeat는 애플리케이션 작업·유휴 시간에 맞게 설정하고 처리되도록 관리하세요.
 연결과 그 리소스는 **소유 스레드에서만 사용**해야 하며, 스레드·프로세스 사이에 공유하지 마세요.
 
+### 연결 타이머
+
+RabbitMQ 연결은 선택적 `SetTimer` 프로토콜을 지원합니다.
+`set_timer(cb, seconds)`는 등록 시점부터 정수 초 단위로 일회성 콜백을 예약하고,
+취소할 수 있는 `Timer`를 반환합니다. 콜백은 인자 없이 호출되며 반환값이 없습니다.
+연결을 사용하는 코드에서 `isinstance(connection, SetTimer)`로 지원 여부를 확인할 수 있습니다.
+기본 `Connection` 계약과 Redis 연결에는 타이머 지원이 강제되지 않습니다.
+
+다음 예제는 메시지가 없는 큐를 소비하면서 5초 뒤 콜백으로 소비를 중단합니다.
+로컬 RabbitMQ가 필요하며 `defstream.example.timer` 큐는 실행 후에도 유지합니다.
+다른 생산자가 이 큐에 보낸 메시지는 출력한 뒤 ACK합니다.
+
+```python
+from DefStream.Broker import Event, SetTimer
+from DefStream.Broker.Implements.RabbitMQ import Configuration, Connection
+
+
+def receive(event: Event) -> None:
+  print(event.body)
+  event.ack()
+
+
+connection = Connection(Configuration(
+  host='127.0.0.1',
+  port=5672,
+  username='guest',
+  password='guest',
+))
+try:
+  connection.connect()
+  if not isinstance(connection, SetTimer):
+    raise TypeError('Connection does not support timers')
+  connection.create_queue('defstream.example.timer')
+  consumer = connection.consumer()
+  consumer.subs('defstream.example.timer', receive)
+
+  def expired() -> None:
+    print('Timer fired')
+    consumer.stop()
+
+  timer = connection.set_timer(cb=expired, seconds=5)
+  try:
+    consumer.run()
+  finally:
+    timer.remove()
+    consumer.close()
+finally:
+  connection.close()
+```
+
+실행 전에 `timer.remove()`를 호출하면 해당 예약을 취소합니다.
+핸들은 등록 당시 연결에 연결되며, 연결을 다시 열어도 새 연결의 타이머를 취소하지 않습니다.
+이미 실행·취소된 예약, 닫힌 연결, 음수·0초 지연의 동작과 오류는 Pika API를 그대로 따릅니다.
+`remove()`는 실행 중인 콜백을 강제로 중단하지 않습니다.
+
+반복 실행은 콜백 안에서 다음 타이머를 등록하면 됩니다.
+아래는 반복 실행용 발췌입니다. 위 예제에서 `consumer.subs(...)`까지 준비한 뒤,
+`expired` 정의와 일회성 타이머 등록·실행·소비자 정리 부분을 아래 코드로 교체합니다.
+바깥쪽 `finally`의 연결 종료는 유지합니다.
+5초 간격으로 세 번 실행하고 중단하며, 취소할 때 사용할 최신 핸들을 보관합니다.
+
+```python
+from DefStream.Broker import Consumer, SetTimer, Timer
+
+
+def run_repeated(connection: SetTimer, consumer: Consumer) -> None:
+  remaining = 3
+  timer: Timer
+
+  def tick() -> None:
+    nonlocal remaining, timer
+    print('Timer fired')
+    remaining -= 1
+    if remaining:
+      timer = connection.set_timer(tick, 5)
+    else:
+      consumer.stop()
+
+  timer = connection.set_timer(tick, 5)
+  try:
+    consumer.run()
+  finally:
+    timer.remove()
+
+
+try:
+  run_repeated(connection, consumer)
+finally:
+  consumer.close()
+```
+
+RabbitMQ 구현은 Pika의 `call_later`·`remove_timeout`에 직접 위임합니다.
+`consumer.run()`과 같은 Pika 이벤트 처리가 진행되어야 콜백이 실행됩니다.
+단순히 등록 후 `sleep()`하는 것만으로는 실행되지 않으며,
+긴 메시지 처리나 이벤트 루프 작업 때문에 실행이 늦어질 수 있습니다.
+콜백은 연결 소유 스레드에서 실행되고, 예외는 기존 이벤트 처리 경로로 전파됩니다.
+
+등록·취소는 Pika의 소유 스레드 제약을 따르며 추가 스레드 안전성을 제공하지 않습니다.
+Consumer 종료 시 연결 타이머를 자동으로 취소하지 않으므로,
+필요한 예약은 호출자가 적절한 시점에 취소해야 합니다.
+위 예제는 연결을 닫기 전에 취소하며, 닫힌 연결에서 취소가 항상 성공한다고 보장하지 않습니다.
+별도 타이머 스레드·범용 스케줄러·자동 정리 계층은 제공하지 않습니다.
+
 ### 로깅
 
 여섯 클래스는 `Broker.RabbitMQ.ClassName` 이름의 클래스 멤버
@@ -370,3 +473,16 @@ sequenceDiagram
 - [Sample.py](../samples/Broker/RabbitMQ/Sample.py)
 - [Sample.Stream.py](../samples/Broker/RabbitMQ/Sample.Stream.py)
 - [Sample.RPC.py](../samples/Broker/RabbitMQ/Sample.RPC.py)
+- [Sample.Timer.py](../samples/Broker/RabbitMQ/Sample.Timer.py): 일회성 예약 취소와 콜백 재등록에 의한 반복 실행
+
+타이머 샘플은 로컬 RabbitMQ의 `127.0.0.1:5672`와 `guest` 계정을 사용합니다.
+개발 환경에서 RabbitMQ 구현체를 사용할 수 있어야 하며, 저장소 루트에서 실행하세요.
+
+```shell
+python samples/Broker/RabbitMQ/Sample.Timer.py
+```
+
+실행마다 고유한 빈 큐를 만들고, 취소한 콜백은 실행하지 않으며,
+1초 간격으로 세 번 출력한 뒤 소비를 중단합니다.
+종료 시 최신 타이머·소비 채널·샘플 큐·연결을 정리합니다.
+Stream 샘플의 소비 중단도 별도 스레드 타이머 대신 연결의 `set_timer`를 사용합니다.

defstream_rabbitmq-0.1.27/issues/feature/62/CHANGELOG.md

@@ -0,0 +1,26 @@
+# 연결 타이머 등록과 취소
+
+## 추가된 기능
+
+RabbitMQ 연결에서 `set_timer(cb, seconds)`로 일회성 콜백을 예약하고,
+반환된 `Timer`의 `remove()`로 취소할 수 있습니다.
+호출자는 Pika 연결이나 내부 타이머 ID를 직접 다루지 않아도 됩니다.
+
+`SetTimer`는 연결의 선택적 기능이며, `Timer`, `TimerCallback`과 함께
+`DefStream.Broker` 및 `DefStream.Broker.Connection`에서 import할 수 있습니다.
+반복 실행은 콜백에서 다음 타이머를 등록하는 방식으로 구성합니다.
+
+[실행 가능한 타이머 샘플](../../../samples/Broker/RabbitMQ/Sample.Timer.py)에서
+취소와 재등록을 확인할 수 있습니다. 기존 Stream 샘플의 소비 중단도
+외부 스레드 타이머 대신 연결 타이머를 사용합니다.
+
+## 사용 조건
+
+- 지연 시간은 등록 시점부터 정수 초 단위로 지정합니다.
+- RabbitMQ 소비 루프 등 Pika의 이벤트 처리가 진행되어야 콜백이 실행됩니다.
+- 등록·취소는 연결 소유 스레드에서 수행하며, 긴 이벤트 처리로 실행이 지연될 수 있습니다.
+- Consumer 종료 시 예약을 자동 취소하지 않습니다. 취소 시점과 연결의 사용 순서는 호출자가 관리합니다.
+- 중복 취소·종료된 연결·음수·0초 등의 동작과 오류는 기반 Pika API를 따릅니다.
+- Redis 타이머 지원이나 기존 Consumer·Worker API 변경은 포함하지 않습니다.
+
+자세한 사용법은 [RabbitMQ 연결 타이머 안내](../../../docs/RabbitMQ.md#연결-타이머)를 참고하세요.

defstream_rabbitmq-0.1.27/issues/feature/62/IMPLEMENTS.md

@@ -0,0 +1,26 @@
+# 연결 타이머 구현 결과
+
+## 구현 내용
+
+- [공통 연결 계약](../../../src/Broker/Connection.py)에 `Timer`, `TimerCallback`, `SetTimer`를 추가하고 [Broker 공개 진입점](../../../src/Broker/__init__.py)에서도 노출했다.
+- `Timer`, `SetTimer`의 런타임 검사·추상 메서드 선언과 `set_timer(cb: TimerCallback, seconds: int) -> Timer` 시그니처를 확정 명세대로 구현했다.
+- [RabbitMQ 연결](../../../src/Broker/Implements/RabbitMQ/Connection.py)은 `SetTimer`를 명시적으로 상속한다. 기존 연결 확인 후 즉시 `call_later(seconds, cb)`로 일회성 예약을 등록하므로 지연 시간은 등록 시점부터 계산된다.
+- 반환하는 구체 `Timer`는 등록 당시 실제 연결과 불투명 핸들만 보관한다. `remove()`는 해당 연결의 `remove_timeout`에 직접 위임하여 상위 연결 객체가 재연결되어도 취소 대상이 바뀌지 않는다.
+- 콜백 래퍼·스레드·추가 동기화·상태 검사·자동 정리 계층은 추가하지 않았다. 스레드 제약·취소·입력값·오류 동작은 Pika API를 따른다.
+- 한국어·영어 [RabbitMQ 사용 안내](../../../docs/RabbitMQ.md)에 일회성·취소·재등록 예제와 사용 제약을 반영했다.
+- 실행 가능한 [타이머 샘플](../../../samples/Broker/RabbitMQ/Sample.Timer.py)을 추가하고, [Stream 샘플](../../../samples/Broker/RabbitMQ/Sample.Stream.py)의 별도 스레드 타이머와 중계 함수를 연결의 `set_timer(consumer.stop, 1)`로 교체했다.
+
+## 유지한 범위
+
+Consumer·Worker·Ping·Pool·Executor·Event·Redis 구현과 연결·소비 종료 처리는 변경하지 않았다. 기본 Connection 계약에 타이머를 강제하지 않으며, 별도 이슈 #63·#64의 리팩터링을 포함하지 않았다.
+
+## 검증과 제한
+
+샘플 검증 추가 후 단위·회귀 45개가 통과했으며 실제 브로커 테스트 4개는 기본 실행에서 건너뛰었다. 별도 유휴 실행 테스트는 로컬 RabbitMQ 연결 실패로 동작 검증까지 진행하지 못했다. 타입·구문 진단과 사용 예제 검증 결과는 [작업 종합](./TASKS.md)에 구분하여 기록했다.
+
+구현은 반영했지만 유휴 실행·실제 소유 스레드·취소·재등록·콜백 예외의 실제 브로커 인수 확인은 남아 있다.
+
+## 구현 기록
+
+- [연결 타이머 계약과 RabbitMQ 등록·취소 구현](./implements/1793777682327.md)
+- [실행 가능한 연결 타이머 샘플 추가](./implements/1793778339166.md)

defstream_rabbitmq-0.1.27/issues/feature/62/PLAN.md

@@ -0,0 +1,175 @@
+# Connection 기반 타이머 작업 계획
+
+## 기준과 현재 상태
+
+- 범위와 공개 계약은 [요구사항](./REQUIREMENTS.md)을 따른다. 작업 브랜치·분기 기준·병합 대상은 [이슈 정보](./README.md)에 모은다.
+- 계약·RabbitMQ 구현·테스트·한국어와 영어 매뉴얼을 반영했다. 단위·회귀 검증은 통과했으며 실제 RabbitMQ 검증은 서버 연결 불가로 남아 있다. 세부 결과는 [구현 종합](./IMPLEMENTS.md)과 [작업 종합](./TASKS.md)을 따른다.
+- [워커 리팩토링 #63](https://github.com/yong5eon/DefStream/issues/63)과 [Recoverable 명시적 상속 #64](https://github.com/yong5eon/DefStream/issues/64)는 별도 작업이며 이번 선행 조건이 아니다.
+
+## 구현 방향
+
+추가할 동작은 다음 두 경로로 한정한다.
+
+```text
+connection.set_timer(cb, seconds)
+  → 현재 Pika 연결의 call_later(seconds, cb)
+  → 취소 핸들을 보관하는 Timer 반환
+
+timer.remove()
+  → 등록 당시 Pika 연결의 remove_timeout(등록 핸들)
+```
+
+- 등록 시 콜백과 초 단위 지연 시간을 그대로 전달한다. 콜백을 다른 함수로 감싸거나 소비 시작까지 등록을 미루지 않는다.
+- 반환 객체는 기반 연결과 등록 핸들만 보관하는 작은 구현체로 둔다. 호출자는 내부 Pika 객체나 타이머 ID를 다루지 않는다.
+- 핸들은 등록 당시의 실제 연결을 참조한다. 취소 시 상위 연결 객체의 현재 연결을 다시 조회하지 않아, 재연결 후 다른 연결에 이전 핸들을 전달하지 않는다.
+- `remove`는 기반 취소 API를 호출한다. 실행·취소 상태 플래그, 타이머 목록, 중복 취소 방지, 별도 입력 검증, 자동 정리 계층은 추가하지 않는다.
+- 기존 `connected()`와 오류 관찰 관례를 재사용한다. 새 폴백이나 오류를 정상 반환으로 바꾸는 처리는 추가하지 않는다.
+- 기존 Consumer의 확인용 타이머, `run`·`stop`·`close`, 연결 종료 처리에는 손대지 않는다.
+
+## 변경 대상
+
+| 대상 | 변경 내용 |
+| --- | --- |
+| [공통 연결 계약](../../../src/Broker/Connection.py) | `Timer`, `TimerCallback`, `SetTimer`와 `__all__` 등록 |
+| [Broker 공개 진입점](../../../src/Broker/__init__.py) | 세 계약의 import와 `__all__` 재노출 |
+| [RabbitMQ 연결](../../../src/Broker/Implements/RabbitMQ/Connection.py) | `SetTimer` 명시적 상속, `set_timer`, 취소 핸들 구현 |
+| [프로토콜 계약 테스트](../../../tests/test_protocol_contracts.py) | 공개 타입·시그니처·데코레이터·선택적 지원 검증 |
+| [타이머 테스트](../../../tests/rabbitmq/test_rabbitmq_timers.py) 신규 | 등록·취소 위임 단위 테스트와 opt-in 실제 타이머 테스트 |
+| [타이머 샘플](../../../samples/Broker/RabbitMQ/Sample.Timer.py) 신규·[Stream 샘플](../../../samples/Broker/RabbitMQ/Sample.Stream.py) | 실행 가능한 취소·재등록 예제와 기존 외부 타이머 교체 |
+| [RabbitMQ 한국어 안내](../../../docs/RabbitMQ.md)·[영어 안내](../../../docs/RabbitMQ.en.md) | 지원 범위와 등록·취소·재등록 사용법 |
+| [매뉴얼 한국어 진입점](../../../docs/README.md)·[영어 진입점](../../../docs/README.en.md) | 기존 RabbitMQ 안내 항목에 연결 타이머 주제 반영 |
+| 이 이슈의 기록 문서 | 진행 상태·검증 결과·최종 변경 로그 기록 |
+
+새 제품 소스 모듈은 만들지 않는 방향으로 진행한다. 구체 타이머는 RabbitMQ 연결 모듈 안에 `Timer` 클래스로 두고 공통 계약을 `BaseTimer`로 import하여 명시적으로 구현한다. 구체 핸들 클래스를 RabbitMQ 패키지의 새 공개 진입점으로 노출할 필요는 없다.
+
+## 수행 순서와 완료 조건
+
+### 1. 공통 계약과 공개 import 추가
+
+선행 조건: 확정 요구사항 확인.
+
+1. 공통 연결 계약 모듈에 다음 선언을 추가한다.
+   - `Timer`: `@runtime_checkable`, `remove(self) -> None`에 `@abstractmethod`
+   - `TimerCallback`: `__call__(self) -> None`, 추가 데코레이터 없음
+   - `SetTimer`: `@runtime_checkable`, `set_timer(self, cb: TimerCallback, seconds: int) -> Timer`에 `@abstractmethod`
+2. `cb`, `seconds`는 기본값 없는 위치 또는 키워드 인자로 유지한다. 위치 전용·키워드 전용 제한을 추가하지 않는다.
+3. 모듈과 Broker 패키지의 `__all__`·import를 함께 갱신한다. 사용자는 `DefStream.Broker` 및 `DefStream.Broker.Connection`에서 같은 계약을 import할 수 있어야 한다.
+4. 기본 `Connection`과 Consumer의 필수 메서드는 변경하지 않는다.
+5. 기존 계약 테스트에 공개 경로, 타입 힌트와 시그니처, 런타임 판별, 명시적 상속 시 필수 메서드 미구현 여부를 검증하는 항목을 추가한다.
+
+완료 조건: 요구사항 R1·R2의 선언과 공개 import가 일치하며 기존 계약은 유지된다.
+
+### 2. RabbitMQ 등록·취소 구현
+
+선행 조건: 1단계의 공통 계약 추가.
+
+1. 실제 개발 환경의 Pika `call_later`·`remove_timeout` 선언과 반환 핸들 타입을 확인하고 타입 힌트에 반영한다. 반환 핸들을 임의로 정수 ID로 가정하거나 근거 없는 캐스팅으로 숨기지 않는다.
+2. RabbitMQ `Connection`의 기존 상속 목록에 `SetTimer`를 추가한다.
+3. `set_timer`는 기존 `connected()`로 연결을 얻고 즉시 `call_later(seconds, cb)`를 호출한다. 설정값 변환·보정·추가 검증은 하지 않는다.
+4. 등록 당시 Pika 연결과 반환 핸들을 보관하는 구체 `Timer`를 반환한다.
+5. 구체 `Timer.remove()`는 보관한 연결의 `remove_timeout`에 보관한 핸들을 전달한다. 중복 호출과 종료된 연결의 결과도 기반 API에 맡긴다.
+6. 등록·취소의 기반 오류는 숨기지 않는다. 콜백은 그대로 전달하여 예외가 기존 Pika 이벤트 처리 경로에서 드러나게 한다.
+
+완료 조건: 요구사항 R1~R3을 만족하며 추가 스레드·이벤트 큐·상태 관리 계층이 없다.
+
+### 3. 직접 영향 범위 검증
+
+선행 조건: 1·2단계 구현.
+
+기존 `unittest`와 `unittest.mock` 관례를 사용한다. 새 검증 라이브러리는 추가하지 않는다.
+
+#### 단위 테스트
+
+| 항목 | 검증 방법과 기대 결과 | 요구사항 |
+| --- | --- | --- |
+| 공개 계약 | 두 공개 import 경로가 같은 타입을 가리키고 `__all__`에 포함되는지 확인 | R1·R2 |
+| 선택적 기능 | RabbitMQ 연결은 `SetTimer`로 판별되고 기본 Connection·Consumer·Redis에는 타이머 의무가 추가되지 않았는지 확인 | R1·R4 |
+| 정확한 등록 | 위치·키워드 호출 모두 `call_later(seconds, cb)`에 동일한 값과 같은 콜백 객체를 한 번 전달하는지 확인 | R2·R3 |
+| 콜백 계약 | 일반 함수와 `__call__` 객체를 `TimerCallback`으로 사용할 수 있고 등록 자체가 콜백을 호출하지 않는지 확인 | R2 |
+| 반환·취소 | 반환 핸들이 `Timer` 계약을 충족하고 `remove_timeout`에 기반 핸들을 그대로 전달하는지 확인 | R2·R3 |
+| 연결 대응 | 상위 연결 객체의 연결 참조가 바뀌어도 기존 핸들은 등록 당시 연결에 취소를 요청하는지 확인 | R3 |
+| 오류 전파 | 기반 등록·취소 API가 발생시킨 예외를 그대로 관찰할 수 있는지 확인 | R3 |
+| 얇은 위임 | 중복 취소를 자체 차단하지 않고 0·음수도 기반 API에 전달하는지 확인. 기반 동작을 새 정책으로 재정의하지 않음 | R3 |
+
+#### 실제 RabbitMQ 테스트
+
+- 신규 타이머 테스트 모듈의 `RabbitMQTimerIntegrationTests`에 기존 `RABBITMQ_TESTS=1` opt-in 방식을 적용한다. 포트는 기존 `rabbitmq_test_port()`를 사용한다.
+- 연결·소비·타이머 등록은 같은 소유 스레드에서 수행한다. 다른 스레드의 안전성을 검증한다는 명목으로 제품에 동기화 기능을 추가하지 않는다.
+- 테스트 전용 이름의 빈 큐를 구독하여 메시지 없는 소비 대기 중 콜백 실행과 소유 스레드 일치를 확인한다.
+- 개별 취소 후 미실행, 콜백 재등록에 의한 반복 실행, 콜백 예외가 `consumer.run()` 호출자에게 전달되는 동작을 확인한다.
+- 테스트에 유한 실행 제한을 두고, 테스트가 만든 큐·채널·연결은 테스트의 정리 코드에서 정리한다. 이를 제품의 자동 정리 요구로 옮기지 않는다.
+- 실제 서버를 사용할 수 없으면 단위 테스트로 유휴 실행까지 검증했다고 쓰지 않고 통합 검증 미실행으로 기록한다.
+
+완료 조건: 아래 명령과 진단 결과를 실제 수행 기록에 남긴다. 실패가 이번 변경에서 발생했으면 수정하고 관련 없는 기존 실패는 근거와 함께 구분한다.
+
+### 4. 한국어·영어 사용 안내
+
+선행 조건: 3단계에서 공개 동작 확인.
+
+1. 두 RabbitMQ 매뉴얼에 같은 범위의 연결 타이머 절을 추가한다.
+2. `isinstance(connection, SetTimer)`로 지원 여부를 확인하고 연결 후 `set_timer`로 등록하는 방법을 안내한다.
+3. 빈 큐 소비 중 실행되는 일회성 콜백과 콜백 안의 재등록, `Timer.remove()`를 설명한다. 기존 Consumer API를 그대로 사용하며 제품에 새로운 실행 API를 만들지 않는다.
+4. 초 단위·등록 시점 기준·Pika 이벤트 처리 필요·소유 스레드 제약·실행 지연 가능성·호출자의 취소 책임을 명시한다.
+5. 예제는 필요한 import·연결·구독·실행·테스트 자원 정리까지 확인 가능하게 작성한다. 종료된 연결의 핸들을 무조건 안전하게 취소할 수 있다고 보장하지 않는다.
+6. 두 매뉴얼 진입점의 기존 RabbitMQ 항목에 타이머 주제를 반영한다. 별도 타이머 매뉴얼이나 다이어그램은 단순 등록·취소 설명에 필요하지 않으면 만들지 않는다.
+7. 루트 README 요약에 타이머 안내가 필요한지만 확인한다. 필요할 때에만 한국어·영어 요약을 함께 갱신하며, 상세 사용법은 매뉴얼에 둔다.
+8. 사용자 요청으로 실행 가능한 타이머 샘플을 추가하고 기존 Stream 샘플도 연결 타이머를 이용하도록 갱신한다. 샘플의 등록·취소·재등록·자원 정리를 단위 검증하며, import 시 연결과 로깅 설정이 실행되지 않는지 기존 검증에 포함한다.
+
+완료 조건: 요구사항 R5와 실제 구현이 일치하며 미지원 브로커나 추가 스레드 안전성을 보장하는 표현이 없다.
+
+### 5. 결과 정리와 범위 확인
+
+선행 조건: 3·4단계 완료.
+
+1. 변경 파일 목록을 확인하여 Consumer·Worker·Ping·Pool·Executor·Event·Redis 구현이 섞이지 않았는지 확인한다. #63·#64의 작업은 하지 않는다.
+2. 구현 단계는 `implements/`, 검증 등 구현 외 작업은 `tasks/`에 실제 수행 시점의 기록을 남긴다.
+3. 구현 결과를 `IMPLEMENTS.md`, 작업 결과를 `TASKS.md`에 종합한다. 이 단계에서 아직 없는 구현 문서를 빈 파일로 미리 만들지 않는다.
+4. 실제 제공된 타이머 등록·취소 기능과 사용 제약만 이슈의 `CHANGELOG.md`에 작성한다. 내부 계획·문서 작성·테스트 통과를 고객 기능으로 나열하지 않는다.
+5. README와 이 계획의 진행 상태를 갱신한다. 필요한 검증이 남았다면 전체 구현 완료로 표시하지 않는다.
+
+## 검증 명령과 환경
+
+명령은 저장소 루트에서 개발 환경에 선택된 `python`으로 실행한다. 아래 타이머 테스트 모듈·클래스는 구현 단계에서 추가했다.
+
+### 먼저 실행할 단위·회귀 검증
+
+실제 RabbitMQ opt-in 환경변수가 꺼진 상태에서 다음 모듈을 한 번의 실행으로 검사한다.
+
+```shell
+python -m unittest tests.test_protocol_contracts tests.rabbitmq.test_rabbitmq_timers tests.rabbitmq.test_rabbitmq_broker_methods tests.rabbitmq.test_rabbitmq_logging tests.rabbitmq.test_rabbitmq_timeouts -v
+```
+
+- 등록·취소 단위 테스트와 공통 계약, 기존 연결 API·로깅·시간 설정 검증을 포함한다.
+- 변경 Python 파일의 구문·타입 진단을 확인한다. 새로운 타입 검사 도구를 설치하거나 저장소 전체의 기존 진단을 정리하지 않는다.
+- 이 범위의 결과에서 더 넓은 영향이 확인될 때만 관련 검증으로 확대한다. 전체 Worker·프로세스 테스트를 이번 선행 조건으로 삼지 않는다.
+- 설치된 코드가 현재 소스를 가리키는지 먼저 확인한다. 의존성·선택 구현체가 없어서 검증이 실패할 때에만 [기존 개발용 설치 절차](../../../docs/Packaging.md)를 따른다. 이 경우 공통 계약 테스트가 RabbitMQ·Redis를 모두 import한다는 점을 고려하고 기존 선택을 임의로 축소하지 않는다.
+
+### 실제 RabbitMQ 검증
+
+테스트 사용이 허용된 서버에만 접속한다. 기존 `RABBITMQ_PORT` 설정을 이용하며, 테스트를 위해 운영 서버에 큐를 생성하거나 별도 서버를 자동 설치하지 않는다.
+
+다음은 PowerShell에서 opt-in하는 실행 예시이다. 환경변수는 해당 검증 프로세스에서만 설정한다.
+
+```powershell
+$env:RABBITMQ_TESTS = '1'
+python -m unittest tests.rabbitmq.test_rabbitmq_timers.RabbitMQTimerIntegrationTests -v
+```
+
+### 문서·변경 범위 검증
+
+- 한국어·영어 예제와 공개 import·시그니처를 대조하고 상대 링크·코드 펜스를 검사한다.
+- 이슈 문서에는 로컬 절대 경로를 남기지 않는다.
+- `git diff --check`와 변경 파일 목록을 확인한다. 문서 검증과 단위·회귀·실제 브로커 검증 결과는 구분하여 기록한다.
+
+## 진행 상태
+
+- [x] 확정 요구사항과 현재 구현·공개 경로·기존 테스트·문서 위치 확인
+- [x] 범위에 맞는 구현·검증 계획 작성
+- [x] 공통 계약·공개 import와 계약 테스트 추가
+- [x] RabbitMQ 등록·취소와 단위 테스트 구현
+- [x] 단위·회귀 검증
+- [ ] 실제 RabbitMQ 검증: 로컬 서버 연결 단계에서 `AMQPConnectionError`
+- [x] 한국어·영어 매뉴얼 갱신
+- [x] 실행 가능한 타이머 샘플 추가와 Stream 샘플 전환·단위 검증
+- [x] 종합 결과·고객 변경 로그 작성
+- [ ] 최종 인수 확인: 실제 RabbitMQ 검증 완료 후 판단

defstream_rabbitmq-0.1.27/issues/feature/62/README.md

@@ -0,0 +1,69 @@
+# Consumer 소유 스레드 기반 타이머 등록·취소 지원
+
+## 이슈와 작업 상태
+
+- 원본: GitHub Issues [#62](https://github.com/yong5eon/DefStream/issues/62)
+- 제목: Consumer 소유 스레드 기반 타이머 등록·취소 지원
+- 상태: Open
+- 유형·레이블: 기능 (`feature`), 원본 이슈에 적용됨
+- 원본 레이블: `feature`, `rabbitmq`
+- 작업 대상: `yong5eon/DefStream`, 작업 브랜치 `feature/62`
+- 분기 기준: `origin/master`와 동일한 로컬 `master`의 `f1bf897`
+- 병합 대상: `master`
+- 로컬 진행 상태: 타이머 구현·실행 샘플·사용 문서 반영, 단위·회귀 45개 통과, 실제 RabbitMQ 검증은 서버 연결 불가
+- 댓글: 없음
+
+## 작업 문서
+
+- [요구사항 명세](./REQUIREMENTS.md)
+- [작업 계획](./PLAN.md)
+- [구현 종합](./IMPLEMENTS.md)
+- [작업 종합](./TASKS.md)
+- [변경 로그](./CHANGELOG.md)
+- [최신 구현 기록](./implements/1793778339166.md)
+- [최신 작업 기록](./tasks/1793778440735.md)
+
+## 이슈 원문
+
+## 해결하려는 문제
+
+RabbitMQ Consumer로 메시지를 소비하면서, 메시지가 없는 동안에도 연결 유지용 콜백 등을 일정 시간 뒤 실행할 필요가 있습니다.
+
+현재 `Consumer.call(callback)`은 연결 소유 스레드로 콜백을 전달하지만 지연 타이머의 등록·취소 API는 제공하지 않습니다. 따라서 호출자가 Pika의 `BlockingConnection.call_later()`·`remove_timeout()`에 직접 의존하거나 별도 스레드 타이머의 수명주기를 관리해야 합니다.
+
+`threading.Timer`에서 직접 출력·소비 중단을 처리하면 메시지 처리와 동시 실행될 수 있고, 타이머 스레드에서 발생한 예외도 소비 루프로 자동 전파되지 않습니다. `Consumer.call()`로 다시 전달할 수는 있지만 타이머 생성·재등록·취소·소비 종료 후 실행 방지는 호출자가 계속 관리해야 합니다.
+
+## 제안하는 해결 방법
+
+DefStream의 소비자 API를 통해 소비자 소유 스레드에서 실행되는 타이머를 등록·취소할 수 있게 지원해 주세요. 우선 현재 사용 사례인 RabbitMQ Consumer를 대상으로 합니다.
+
+- 지연 시간과 콜백을 지정해 일회성 타이머를 등록하고 취소 가능한 핸들을 반환합니다.
+- 메시지가 없는 소비 대기 중에도 콜백이 소비자 소유 스레드에서 실행되어야 합니다.
+- 반복 실행은 콜백에서 다음 타이머를 재등록하는 방식으로도 충분합니다. 별도 범용 스케줄러나 전용 타이머 스레드는 요구하지 않습니다.
+- 소비 종료·close 시 남은 타이머가 이후에 실행되지 않도록 수명주기를 정리합니다.
+- 콜백 오류는 기존 소비 루프의 오류 처리·전파 방식과 일관되게 드러내며 별도 스레드에서 조용히 유실하지 않습니다.
+- 호출자는 Pika 연결 객체·구현체 타이머 ID를 직접 다루지 않아도 되어야 합니다.
+
+구체적인 메서드 이름과 핸들 타입은 구현 시 기존 인터페이스와 대조해 결정하면 됩니다. 예를 들어 지연 콜백 등록과 해당 핸들 취소 형태를 고려할 수 있으며, 이 예시를 확정 API로 지정하는 것은 아닙니다.
+
+### 확인 기준
+
+- 메시지가 없는 동안에도 예약 콜백이 실행되고 메시지 처리와 같은 소유 스레드에서 실행되는지 확인합니다.
+- 취소한 타이머와 소비 종료 후의 타이머가 실행되지 않는지 확인합니다.
+- 재등록을 통한 주기 실행과 정상·오류 종료의 자원 정리를 검증합니다.
+- 콜백 예외가 기존 소비 오류 처리 경계로 전파되는지 확인합니다.
+- 기존 구독·ACK·소비 순서와 `Consumer.call()` 동작을 유지합니다.
+- 지원 범위·시간 단위·실행 지연 가능성·등록 및 취소 사용법을 관련 매뉴얼에 반영합니다.
+
+## 고려한 대안
+
+- Pika 연결의 타이머를 직접 사용: 같은 스레드에서 실행할 수 있지만 호출자가 브로커 구현체에 결합됩니다.
+- `threading.Timer`와 `Consumer.call()` 조합: 실행 스레드 전달은 가능하지만 별도 스레드·타이머 수명주기를 호출자가 관리해야 합니다.
+- 메시지를 받을 때만 경과 시간 검사: 유휴 중 실행이 필요한 요구를 충족하지 못합니다.
+
+## 추가 정보
+
+연결 유지용 출력은 사용 예시일 뿐이며 DefStream이 HTTP·SSE 프로토콜이나 해당 출력 내용을 구현해 달라는 요청은 아닙니다. 우선 타이머 등록·취소와 소비자 수명주기 통합만 지원하면 됩니다.
+
+- 현재 구현: https://github.com/yong5eon/DefStream/blob/master/src/Broker/Implements/RabbitMQ/Consumer.py
+- Pika BlockingConnection API: https://pika.readthedocs.io/en/stable/modules/adapters/blocking.html