streambus 0.2.0__tar.gz → 0.2.2__tar.gz

streambus-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --group dev
+      - run: uv run pytest -q

streambus-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+    branches:
+      - main
+    paths:
+      - ".github/workflows/release.yml"
+
+jobs:
+  build-and-publish:
+    if: >-
+      github.ref_type == 'tag' ||
+      github.event.head_commit.message == 'release: streambus v0.2.2'
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Verify package version
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          import tomllib
+
+          package = tomllib.loads(Path("pyproject.toml").read_text())
+          assert package["project"]["version"] == "0.2.2"
+          PY
+
+      - run: uv sync --group dev
+      - run: uv run pytest -q
+      - run: uv build
+
+      - name: Create GitHub release
+        if: github.ref == 'refs/heads/main'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create v0.2.2 dist/* \
+            --target "$GITHUB_SHA" \
+            --title "streambus v0.2.2" \
+            --notes "Recover idle pending Redis Streams messages via XAUTOCLAIM, with at-least-once delivery and tests."
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{streambus-0.2.0 → streambus-0.2.2}/AGENTS.md

@@ -103,6 +103,24 @@ class ClientEvent(StreamBusEvent):
 ```
 <!-- /rule:local-event-class -->
 
+<!-- post-merge-workflow -->
+## Post-merge
+
+Después de mergear un PR:
+
+1. Cambiar a `main` localmente y hacer pull.
+2. Ejecutar `uv run pytest` — si aparece algún fallo, abrir una rama nueva, corregirlo y hacer PR.
+3. Si todo verde: actualizar la versión en `pyproject.toml` y en `streambus/__init__.py` (`__version__`).
+4. Actualizar la documentación si el cambio afecta comportamiento visible para el caller.
+5. Publicar el tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+   El workflow `.github/workflows/release.yml` se dispara automáticamente y publica en PyPI vía OIDC.
+
+**Archivos con versión:**
+- `pyproject.toml` — campo `version`
+- `streambus/__init__.py` — `__version__`
+
+<!-- /post-merge-workflow -->
+
 <!-- rule:exceptions -->
 ## Jerarquía de excepciones
 

{streambus-0.2.0 → streambus-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: streambus
-Version: 0.2.0
+Version: 0.2.2
 Summary: Lightweight Redis Streams event listener with a clean callback API
 Project-URL: Homepage, https://github.com/jmeiracorbal/streambus
 Project-URL: Repository, https://github.com/jmeiracorbal/streambus
@@ -80,12 +80,10 @@ class OrderCreated(StreamBusEvent):
 Publish it:
 
 ```python
-from streambus import EventPublisher, RedisConfig
+from streambus import EventPublisher, RedisConfig, RedisStreamsTransport
 
-publisher = EventPublisher(
-    stream="orders:events",
-    config=RedisConfig(url="redis://localhost:6379"),
-)
+transport = RedisStreamsTransport(RedisConfig(url="redis://localhost:6379"))
+publisher = EventPublisher(stream="orders:events", transport=transport)
 
 publisher.publish(
     OrderCreated(
@@ -100,7 +98,7 @@ publisher.publish(
 Consume it:
 
 ```python
-from streambus import EventListener, RedisConfig
+from streambus import EventListener, RedisConfig, RedisStreamsTransport
 
 def handle_order(event: OrderCreated) -> None:
     print(f"New order {event.order_id}: total {event.total}")
@@ -110,7 +108,7 @@ EventListener(
     group="notifications",
     handler=handle_order,
     event_class=OrderCreated,
-    config=RedisConfig(url="redis://localhost:6379"),
+    transport=RedisStreamsTransport(RedisConfig(url="redis://localhost:6379")),
 ).run()
 ```
 
@@ -118,7 +116,7 @@ EventListener(
 
 streambus uses [Redis Streams](https://redis.io/docs/data-types/streams/) for transport: persistent storage, consumer groups, and at-least-once delivery. The library manages group creation, the blocking read loop, message acknowledgement, and automatic reconnection on connection loss.
 
-Each consumer group processes events independently. A message published to a stream reaches every group exactly once.
+Each consumer group processes events independently. Delivery is at least once: unacknowledged messages can be redelivered, so handlers must be idempotent. The listener reclaims idle pending entries using Redis XAUTOCLAIM before reading new entries (Redis 6.2+ required).
 
 ## Events
 
@@ -153,11 +151,12 @@ EventListener(
     group="consumer-group",   # required
     handler=my_handler,       # required — callable(event) -> None
     event_class=MyEvent,      # required — must subclass StreamBusEvent
-    config=RedisConfig(...),  # required
+    transport=RedisStreamsTransport(RedisConfig(...)),  # required
     consumer=None,            # defaults to "{group}-1"
     batch_size=10,
     block_ms=5000,
     retry_delay=3.0,
+    pending_idle_ms=60000,  # minimum idle time before retrying pending entries
 )
 ```
 
@@ -166,7 +165,7 @@ EventListener(
 ```python
 EventPublisher(
     stream="stream:name",    # required
-    config=RedisConfig(...), # required
+    transport=RedisStreamsTransport(RedisConfig(...)), # required
 )
 ```
 

{streambus-0.2.0 → streambus-0.2.2}/README.md

@@ -37,12 +37,10 @@ class OrderCreated(StreamBusEvent):
 Publish it:
 
 ```python
-from streambus import EventPublisher, RedisConfig
+from streambus import EventPublisher, RedisConfig, RedisStreamsTransport
 
-publisher = EventPublisher(
-    stream="orders:events",
-    config=RedisConfig(url="redis://localhost:6379"),
-)
+transport = RedisStreamsTransport(RedisConfig(url="redis://localhost:6379"))
+publisher = EventPublisher(stream="orders:events", transport=transport)
 
 publisher.publish(
     OrderCreated(
@@ -57,7 +55,7 @@ publisher.publish(
 Consume it:
 
 ```python
-from streambus import EventListener, RedisConfig
+from streambus import EventListener, RedisConfig, RedisStreamsTransport
 
 def handle_order(event: OrderCreated) -> None:
     print(f"New order {event.order_id}: total {event.total}")
@@ -67,7 +65,7 @@ EventListener(
     group="notifications",
     handler=handle_order,
     event_class=OrderCreated,
-    config=RedisConfig(url="redis://localhost:6379"),
+    transport=RedisStreamsTransport(RedisConfig(url="redis://localhost:6379")),
 ).run()
 ```
 
@@ -75,7 +73,7 @@ EventListener(
 
 streambus uses [Redis Streams](https://redis.io/docs/data-types/streams/) for transport: persistent storage, consumer groups, and at-least-once delivery. The library manages group creation, the blocking read loop, message acknowledgement, and automatic reconnection on connection loss.
 
-Each consumer group processes events independently. A message published to a stream reaches every group exactly once.
+Each consumer group processes events independently. Delivery is at least once: unacknowledged messages can be redelivered, so handlers must be idempotent. The listener reclaims idle pending entries using Redis XAUTOCLAIM before reading new entries (Redis 6.2+ required).
 
 ## Events
 
@@ -110,11 +108,12 @@ EventListener(
     group="consumer-group",   # required
     handler=my_handler,       # required — callable(event) -> None
     event_class=MyEvent,      # required — must subclass StreamBusEvent
-    config=RedisConfig(...),  # required
+    transport=RedisStreamsTransport(RedisConfig(...)),  # required
     consumer=None,            # defaults to "{group}-1"
     batch_size=10,
     block_ms=5000,
     retry_delay=3.0,
+    pending_idle_ms=60000,  # minimum idle time before retrying pending entries
 )
 ```
 
@@ -123,7 +122,7 @@ EventListener(
 ```python
 EventPublisher(
     stream="stream:name",    # required
-    config=RedisConfig(...), # required
+    transport=RedisStreamsTransport(RedisConfig(...)), # required
 )
 ```
 

{streambus-0.2.0 → streambus-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "streambus"
-version = "0.2.0"
+version = "0.2.2"
 description = "Lightweight Redis Streams event listener with a clean callback API"
 readme = "README.md"
 requires-python = ">=3.11"

{streambus-0.2.0 → streambus-0.2.2}/streambus/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "EventValidationError",
     "TransportConnectionError",
 ]
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{streambus-0.2.0 → streambus-0.2.2}/streambus/listener.py

@@ -21,6 +21,7 @@ class EventListener:
         batch_size: int = 10,
         block_ms: int = 5000,
         retry_delay: float = 3.0,
+        pending_idle_ms: int = 60000,
     ):
         if not stream:
             raise ConfigurationError("stream is required")
@@ -30,6 +31,8 @@ class EventListener:
             raise ConfigurationError("handler must be callable")
         if not (isinstance(event_class, type) and issubclass(event_class, StreamBusEvent)):
             raise ConfigurationError("event_class must be a subclass of StreamBusEvent")
+        if batch_size < 1 or block_ms < 0 or pending_idle_ms < 1:
+            raise ConfigurationError("batch_size must be positive, block_ms non-negative, and pending_idle_ms positive")
 
         self.stream = stream
         self.group = group
@@ -40,11 +43,17 @@ class EventListener:
         self.batch_size = batch_size
         self.block_ms = block_ms
         self.retry_delay = retry_delay
+        self.pending_idle_ms = pending_idle_ms
 
     def process_one_batch(self) -> int:
-        messages = self.transport.read(
-            self.stream, self.group, self.consumer, self.batch_size, self.block_ms,
+        # XAUTOCLAIM recovers unacknowledged messages from crashed/failed consumers.
+        messages = self.transport.claim_pending(
+            self.stream, self.group, self.consumer, self.batch_size, self.pending_idle_ms,
         )
+        if not messages:
+            messages = self.transport.read(
+                self.stream, self.group, self.consumer, self.batch_size, self.block_ms,
+            )
         count = 0
         for msg_id, data in messages:
             try:
@@ -53,6 +62,7 @@ class EventListener:
                 self.transport.ack(self.stream, self.group, msg_id)
                 count += 1
             except Exception:
+                # Leave the message in the pending entries list for retry after min idle.
                 logger.exception("error processing message %s", msg_id)
         return count
 

{streambus-0.2.0 → streambus-0.2.2}/streambus/transport.py

@@ -5,6 +5,7 @@ from typing import Protocol, runtime_checkable
 class EventTransport(Protocol):
     def publish(self, stream: str, data: dict) -> None: ...
     def read(self, stream: str, group: str, consumer: str, batch_size: int, block_ms: int) -> list[tuple[str, dict]]: ...
+    def claim_pending(self, stream: str, group: str, consumer: str, batch_size: int, min_idle_ms: int) -> list[tuple[str, dict]]: ...
     def ack(self, stream: str, group: str, msg_id: str) -> None: ...
     def ensure_group(self, stream: str, group: str) -> None: ...
     def reconnect(self) -> None: ...

{streambus-0.2.0 → streambus-0.2.2}/streambus/transports/redis_streams.py

@@ -42,6 +42,17 @@ class RedisStreamsTransport:
         except redis_lib.exceptions.ConnectionError as exc:
             raise TransportConnectionError(str(exc)) from exc
 
+    def claim_pending(self, stream: str, group: str, consumer: str, batch_size: int, min_idle_ms: int) -> list[tuple[str, dict]]:
+        """Recover idle pending entries, including entries owned by other consumers."""
+        try:
+            _cursor, messages, *_deleted = self._get_client().xautoclaim(
+                stream, group, consumer, min_idle_time=min_idle_ms, start_id="0-0",
+                count=batch_size,
+            )
+            return [(msg_id, data) for msg_id, data in messages]
+        except redis_lib.exceptions.ConnectionError as exc:
+            raise TransportConnectionError(str(exc)) from exc
+
     def ack(self, stream: str, group: str, msg_id: str) -> None:
         try:
             self._get_client().xack(stream, group, msg_id)

streambus-0.2.2/tests/test_pending.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+
+import fakeredis
+
+from streambus import EventListener, StreamBusEvent
+from streambus.config import RedisConfig
+from streambus.transports.redis_streams import RedisStreamsTransport
+
+
+@dataclass(kw_only=True)
+class SampleEvent(StreamBusEvent):
+    document: str
+
+
+def test_recovers_pending_message_after_handler_failure() -> None:
+    client = fakeredis.FakeRedis(decode_responses=True)
+    transport = RedisStreamsTransport(RedisConfig(url="redis://localhost:6379"))
+    transport._client = client
+    transport.ensure_group("documents", "conversion")
+
+    client.xadd("documents", SampleEvent(event_type="document.changed", document="one.pdf").to_dict())
+    failed = EventListener(
+        stream="documents", group="conversion", consumer="worker-a",
+        handler=lambda event: (_ for _ in ()).throw(RuntimeError("conversion failed")),
+        event_class=SampleEvent, transport=transport, pending_idle_ms=1,
+    )
+    assert failed.process_one_batch() == 0
+    assert client.xpending("documents", "conversion")["pending"] == 1
+
+    recovered = []
+    successful = EventListener(
+        stream="documents", group="conversion", consumer="worker-b",
+        handler=recovered.append, event_class=SampleEvent,
+        transport=transport, pending_idle_ms=1,
+    )
+    # Time-free deterministic claim: zero idle would bypass the delay, but the library
+    # deliberately requires a positive delay, so emulate a sufficiently idle record.
+    import time
+    time.sleep(0.01)
+    assert successful.process_one_batch() == 1
+    assert [event.document for event in recovered] == ["one.pdf"]
+    assert client.xpending("documents", "conversion")["pending"] == 0
+
+
+def test_processes_new_entries_when_no_pending_eligible() -> None:
+    client = fakeredis.FakeRedis(decode_responses=True)
+    transport = RedisStreamsTransport(RedisConfig(url="redis://localhost:6379"))
+    transport._client = client
+    transport.ensure_group("documents", "conversion")
+    client.xadd("documents", SampleEvent(event_type="document.changed", document="two.pdf").to_dict())
+    received = []
+    listener = EventListener(
+        stream="documents", group="conversion", handler=received.append,
+        event_class=SampleEvent, transport=transport, block_ms=0,
+    )
+    assert listener.process_one_batch() == 1
+    assert received[0].document == "two.pdf"

{streambus-0.2.0 → streambus-0.2.2}/uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 2
+revision = 5
 requires-python = ">=3.11"
 
 [[package]]
@@ -120,7 +120,7 @@ wheels = [
 
 [[package]]
 name = "streambus"
-version = "0.1.0"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "redis" },

streambus-0.2.0/.github/workflows/release.yml

@@ -1,23 +0,0 @@
-name: Release
-
-on:
-  push:
-    tags:
-      - "v*"
-
-jobs:
-  build-and-publish:
-    runs-on: ubuntu-latest
-    environment: release
-    permissions:
-      id-token: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: astral-sh/setup-uv@v4
-
-      - run: uv build
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1