xyberos-queues 0.1.0__tar.gz

xyberos_queues-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: xyberos-queues
+Version: 0.1.0
+Summary: Message queue plugin (RFC-0019, M9): Redis Streams, RabbitMQ, Kafka behind one MessageQueue contract
+License: Apache-2.0
+Keywords: xyberos,plugin,queue,redis,rabbitmq,kafka
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: redis
+Requires-Dist: redis; extra == "redis"
+Provides-Extra: rabbitmq
+Requires-Dist: pika; extra == "rabbitmq"
+Provides-Extra: kafka
+Requires-Dist: kafka-python; extra == "kafka"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: fakeredis; extra == "test"
+
+# xyberos-queues
+
+**Message queue plugin — RFC-0019, M9.** Redis Streams, RabbitMQ, and Kafka
+behind one `MessageQueue` contract (`publish` / `poll`).
+
+## Install
+
+```bash
+pip install -e ./queues
+pip install xyberos-queues[redis]      # optional drivers
+pip install xyberos-queues[rabbitmq]
+pip install xyberos-queues[kafka]
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_queues import QueuesPlugin
+
+app = create_app()
+app.load_plugin(QueuesPlugin(provider="redis"))     # or QUEUE_PROVIDER
+
+app.tools.execute("queue_publish", None, topic="jobs", message="do work")
+app.tools.execute("queue_poll", None, topic="jobs")     # -> "do work"
+```
+
+| Provider | Config |
+| -------- | ------ |
+| `redis` | Redis Streams (URL via `REDIS_URL`) |
+| `rabbitmq` | host/port (default `localhost:5672`) |
+| `kafka` | `bootstrap_servers` (default `localhost:9092`) |
+
+`poll` drains one message (oldest first) per call; returns `None` when empty.
+
+## Tests
+
+```bash
+pip install pytest fakeredis
+pytest tests/
+```
+
+fakeredis + fake clients — no live brokers.
+
+## Ship location
+
+Plugin (`xyberos.plugins` entry point) — infrastructure queues (M9).

xyberos_queues-0.1.0/README.md

@@ -0,0 +1,47 @@
+# xyberos-queues
+
+**Message queue plugin — RFC-0019, M9.** Redis Streams, RabbitMQ, and Kafka
+behind one `MessageQueue` contract (`publish` / `poll`).
+
+## Install
+
+```bash
+pip install -e ./queues
+pip install xyberos-queues[redis]      # optional drivers
+pip install xyberos-queues[rabbitmq]
+pip install xyberos-queues[kafka]
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_queues import QueuesPlugin
+
+app = create_app()
+app.load_plugin(QueuesPlugin(provider="redis"))     # or QUEUE_PROVIDER
+
+app.tools.execute("queue_publish", None, topic="jobs", message="do work")
+app.tools.execute("queue_poll", None, topic="jobs")     # -> "do work"
+```
+
+| Provider | Config |
+| -------- | ------ |
+| `redis` | Redis Streams (URL via `REDIS_URL`) |
+| `rabbitmq` | host/port (default `localhost:5672`) |
+| `kafka` | `bootstrap_servers` (default `localhost:9092`) |
+
+`poll` drains one message (oldest first) per call; returns `None` when empty.
+
+## Tests
+
+```bash
+pip install pytest fakeredis
+pytest tests/
+```
+
+fakeredis + fake clients — no live brokers.
+
+## Ship location
+
+Plugin (`xyberos.plugins` entry point) — infrastructure queues (M9).

xyberos_queues-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xyberos-queues"
+version = "0.1.0"
+description = "Message queue plugin (RFC-0019, M9): Redis Streams, RabbitMQ, Kafka behind one MessageQueue contract"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+dependencies = ["xyberos>=1.0"]
+keywords = ["xyberos", "plugin", "queue", "redis", "rabbitmq", "kafka"]
+
+[project.optional-dependencies]
+redis = ["redis"]
+rabbitmq = ["pika"]
+kafka = ["kafka-python"]
+test = ["pytest", "fakeredis"]
+
+[project.entry-points."xyberos.plugins"]
+queues = "xyberos_queues.plugin:plugin"
+
+[tool.setuptools]
+packages = ["xyberos_queues"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

xyberos_queues-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xyberos_queues-0.1.0/tests/test_adapters.py

@@ -0,0 +1,83 @@
+"""Tests for the queue adapters (fakeredis / fake clients, no servers)."""
+
+from __future__ import annotations
+
+import pytest
+
+from xyberos_queues import KafkaQueue, RabbitMqQueue, RedisStreamsQueue
+
+
+@pytest.fixture()
+def redis_client():
+    return pytest.importorskip("fakeredis").FakeStrictRedis()
+
+
+def test_redis_streams_roundtrip(redis_client):
+    queue = RedisStreamsQueue(client=redis_client)
+    queue.publish("events", "hello")
+    assert queue.poll("events") == "hello"
+    assert queue.poll("events", timeout=0.01) is None  # drained
+
+
+class _FakePikaChannel:
+    def __init__(self):
+        self.messages: list[str] = []
+
+    def queue_declare(self, **kwargs):
+        return None
+
+    def basic_publish(self, **kwargs):
+        self.messages.append(kwargs["body"])
+
+    def basic_get(self, queue, auto_ack):
+        if self.messages:
+            return ("method", None, self.messages.pop(0))
+        return (None, None, None)
+
+
+def test_rabbitmq_roundtrip():
+    channel = _FakePikaChannel()
+    queue = RabbitMqQueue(channel=channel)
+    queue.publish("q", "hello")
+    assert queue.poll("q") == "hello"
+    assert queue.poll("q") is None
+
+
+class _FakeKafkaProducer:
+    def __init__(self):
+        self.sent: list[bytes] = []
+
+    def send(self, topic, value):
+        self.sent.append(value)
+        return None
+
+    def flush(self):
+        pass
+
+    def close(self):
+        pass
+
+
+class _FakeKafkaConsumer:
+    def __init__(self, messages: list[bytes]):
+        self._messages = messages
+        self.closed = False
+
+    def poll(self, **kwargs):
+        if self._messages:
+            return {"tp": [type("M", (), {"value": self._messages.pop(0)})()]}
+        return {}
+
+    def close(self):
+        self.closed = True
+
+
+def test_kafka_roundtrip():
+    producer = _FakeKafkaProducer()
+    consumer = _FakeKafkaConsumer([b"hello"])
+    queue = KafkaQueue(producer=producer, consumer=consumer)
+    queue.publish("topic", "world")
+    assert producer.sent == [b"world"]
+    assert queue.poll("topic") == "hello"
+    queue.close()
+    assert consumer.closed

xyberos_queues-0.1.0/tests/test_plugin.py

@@ -0,0 +1,33 @@
+"""Tests for loading the queues plugin into a Xyberos app."""
+
+from __future__ import annotations
+
+import pytest
+from xyberos import create_app
+
+from xyberos_queues import QueuesPlugin
+
+
+@pytest.fixture()
+def redis_client():
+    return pytest.importorskip("fakeredis").FakeStrictRedis()
+
+
+def test_plugin_registers_and_executes(redis_client):
+    app = create_app()
+    app.load_plugin(QueuesPlugin(provider="redis", client=redis_client))
+    assert "queue_publish" in app.tools.names
+    assert "queue_poll" in app.tools.names
+
+    app.tools.execute("queue_publish", None, topic="jobs", message="do work")
+    assert app.tools.execute("queue_poll", None, topic="jobs") == "do work"
+
+    app.unload_plugin("queues")
+    assert "queue_publish" not in app.tools.names
+
+
+def test_unknown_provider_raises():
+    import pytest as _pytest
+
+    with _pytest.raises(ValueError, match="unknown queue provider"):
+        QueuesPlugin(provider="bogus").message_queue()

xyberos_queues-0.1.0/xyberos_queues/__init__.py

@@ -0,0 +1,7 @@
+"""Message queue plugin (RFC-0019, M9)."""
+
+from .adapters import KafkaQueue, RabbitMqQueue, RedisStreamsQueue
+from .contract import MessageQueue
+from .plugin import QueuesPlugin
+
+__all__ = ["KafkaQueue", "MessageQueue", "QueuesPlugin", "RabbitMqQueue", "RedisStreamsQueue"]

xyberos_queues-0.1.0/xyberos_queues/adapters.py

@@ -0,0 +1,172 @@
+"""Queue adapters: Redis Streams, RabbitMQ, Kafka (lazy drivers, injectable)."""
+
+from __future__ import annotations
+
+import importlib
+import os
+from typing import Any
+
+from xyberos.exceptions.provider import ProviderError
+
+
+def _require(package: str, extra: str) -> Any:
+    try:
+        return importlib.import_module(package)
+    except ImportError as exc:
+        raise ProviderError(
+            f"the '{package}' package is required for {extra}; install with "
+            f"'pip install xyberos-queues[{extra}]'"
+        ) from exc
+
+
+class RedisStreamsQueue:
+    """Redis Streams (lazy ``redis``; injectable client for tests)."""
+
+    name = "redis"
+
+    def __init__(
+        self,
+        *,
+        url: str | None = None,
+        client: Any | None = None,
+        stream_prefix: str = "xyberos:queue",
+    ) -> None:
+        self._url = url
+        self._client = client
+        self._prefix = stream_prefix
+
+    def publish(self, topic: str, message: str) -> None:
+        self._get_client().xadd(self._stream(topic), {"message": message})
+
+    def poll(self, topic: str, timeout: float = 0.1) -> str | None:
+        # XRANGE (oldest first) + XDEL drains the stream like a queue and works
+        # on both real Redis and fakeredis (no XREAD-">" quirks).
+        client = self._get_client()
+        stream = self._stream(topic)
+        entries = client.xrange(stream, count=1)
+        if not entries:
+            return None
+        entry_id, fields = entries[0]
+        client.xdel(stream, entry_id)
+        value = fields.get(b"message", fields.get("message"))
+        if isinstance(value, bytes):
+            return value.decode("utf-8")
+        return str(value)
+
+    def close(self) -> None:
+        pass
+
+    def _stream(self, topic: str) -> str:
+        return f"{self._prefix}:{topic}"
+
+    def _get_client(self) -> Any:
+        if self._client is not None:
+            return self._client
+        redis = _require("redis", "redis")
+        self._client = redis.from_url(self._url) if self._url else redis.Redis()
+        return self._client
+
+
+class RabbitMqQueue:
+    """RabbitMQ via lazy ``pika`` (injectable channel for tests)."""
+
+    name = "rabbitmq"
+
+    def __init__(
+        self,
+        queue: str = "xyberos",
+        *,
+        host: str = "localhost",
+        port: int = 5672,
+        channel: Any | None = None,
+    ) -> None:
+        self._queue = queue
+        self._host = host
+        self._port = port
+        self._channel = channel
+
+    def _get_channel(self) -> Any:
+        if self._channel is not None:
+            return self._channel
+        pika = _require("pika", "rabbitmq")
+        connection = pika.BlockingConnection(
+            pika.ConnectionParameters(host=self._host, port=self._port)
+        )
+        channel = connection.channel()
+        channel.queue_declare(queue=self._queue)
+        self._channel = channel
+        return channel
+
+    def publish(self, topic: str, message: str) -> None:
+        self._get_channel().basic_publish(exchange="", routing_key=self._queue, body=message)
+
+    def poll(self, topic: str, timeout: float = 0.1) -> str | None:
+        method, _properties, body = self._get_channel().basic_get(self._queue, auto_ack=True)
+        if method is None or body is None:
+            return None
+        return body.decode("utf-8") if isinstance(body, bytes) else str(body)
+
+    def close(self) -> None:
+        pass
+
+
+class KafkaQueue:
+    """Apache Kafka via lazy ``kafka-python`` (injectable producer/consumer)."""
+
+    name = "kafka"
+
+    def __init__(
+        self,
+        bootstrap_servers: str = "localhost:9092",
+        *,
+        producer: Any | None = None,
+        consumer: Any | None = None,
+        group_id: str = "xyberos",
+    ) -> None:
+        self._bootstrap_servers = bootstrap_servers
+        self._producer = producer
+        self._consumer = consumer
+        self._group_id = group_id
+
+    def publish(self, topic: str, message: str) -> None:
+        producer = self._get_producer()
+        producer.send(topic, value=message.encode("utf-8"))
+        producer.flush()
+
+    def poll(self, topic: str, timeout: float = 0.1) -> str | None:
+        consumer = self._get_consumer(topic)
+        records = consumer.poll(timeout_ms=int(timeout * 1000), max_records=1)
+        for _tp, messages in records.items():
+            for message in messages:
+                return message.value.decode("utf-8")
+        return None
+
+    def close(self) -> None:
+        if self._consumer is not None:
+            try:
+                self._consumer.close()
+            except Exception:
+                pass
+            self._consumer = None
+        if self._producer is not None:
+            try:
+                self._producer.close()
+            except Exception:
+                pass
+            self._producer = None
+
+    def _get_producer(self) -> Any:
+        if self._producer is not None:
+            return self._producer
+        kafka = _require("kafka", "kafka")
+        self._producer = kafka.KafkaProducer(bootstrap_servers=self._bootstrap_servers)
+        return self._producer
+
+    def _get_consumer(self, topic: str) -> Any:
+        if self._consumer is not None:
+            return self._consumer
+        kafka = _require("kafka", "kafka")
+        self._consumer = kafka.KafkaConsumer(
+            topic, bootstrap_servers=self._bootstrap_servers, group_id=self._group_id
+        )
+        return self._consumer

xyberos_queues-0.1.0/xyberos_queues/contract.py

@@ -0,0 +1,21 @@
+"""The MessageQueue contract (RFC-0019, M9)."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class MessageQueue(Protocol):
+    """Anything that publishes and polls messages on named topics."""
+
+    name: str
+
+    def publish(self, topic: str, message: str) -> None:
+        """Publish ``message`` to ``topic``."""
+
+    def poll(self, topic: str, timeout: float = 0.1) -> str | None:
+        """Return one message from ``topic`` (or ``None`` if empty)."""
+
+    def close(self) -> None:
+        """Release the connection."""

xyberos_queues-0.1.0/xyberos_queues/plugin.py

@@ -0,0 +1,85 @@
+"""Queues plugin entry point (RFC-0019, M9)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, cast
+
+from xyberos.contracts import Plugin, Tool
+from xyberos.tools import FunctionTool
+
+from .adapters import KafkaQueue, RabbitMqQueue, RedisStreamsQueue
+from .contract import MessageQueue
+
+
+def _pop_tool(registry: Any, name: str) -> None:
+    unregister = getattr(registry, "unregister", None)
+    if callable(unregister):
+        unregister(name)
+        return
+    store = getattr(registry, "_tools", None)
+    if isinstance(store, dict):
+        cast(dict[str, Any], store).pop(name, None)
+
+
+class QueuesPlugin(Plugin):
+    """Registers ``queue_publish`` / ``queue_poll`` for a configured provider."""
+
+    def __init__(
+        self,
+        provider: str | None = None,
+        *,
+        env_prefix: str = "QUEUE",
+        client: Any | None = None,
+        channel: Any | None = None,
+        producer: Any | None = None,
+        consumer: Any | None = None,
+    ) -> None:
+        self._provider = (provider or os.getenv(f"{env_prefix}_PROVIDER") or "redis").lower()
+        self._client = client
+        self._channel = channel
+        self._producer = producer
+        self._consumer = consumer
+
+    @property
+    def name(self) -> str:
+        return "queues"
+
+    def message_queue(self) -> MessageQueue:
+        name = self._provider
+        if name == "redis":
+            return RedisStreamsQueue(client=self._client)
+        if name == "rabbitmq":
+            return RabbitMqQueue(channel=self._channel)
+        if name == "kafka":
+            return KafkaQueue(producer=self._producer, consumer=self._consumer)
+        raise ValueError(f"unknown queue provider '{name}' (redis | rabbitmq | kafka)")
+
+    def tools(self) -> list[Tool]:
+        queue = self.message_queue()
+
+        def _publish(topic: str, message: str) -> dict[str, Any]:
+            queue.publish(topic, message)
+            return {"topic": topic, "published": True}
+
+        def _poll(topic: str, timeout: float = 0.1) -> str | None:
+            return queue.poll(topic, timeout)
+
+        return [
+            FunctionTool("queue_publish", _publish, description=f"Publish a message via {self._provider}."),
+            FunctionTool("queue_poll", _poll, description=f"Poll one message from a {self._provider} topic."),
+        ]
+
+    def register(self, kernel: object) -> None:
+        registry = kernel.resolve("tools")
+        for tool in self.tools():
+            registry.register(tool)
+
+    def unregister(self, kernel: object) -> None:
+        registry = kernel.resolve("tools")
+        for tool in self.tools():
+            _pop_tool(registry, tool.name)
+
+
+#: Auto-discovered by ``app.load_entry_points()``.
+plugin = QueuesPlugin()

xyberos_queues-0.1.0/xyberos_queues.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: xyberos-queues
+Version: 0.1.0
+Summary: Message queue plugin (RFC-0019, M9): Redis Streams, RabbitMQ, Kafka behind one MessageQueue contract
+License: Apache-2.0
+Keywords: xyberos,plugin,queue,redis,rabbitmq,kafka
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: redis
+Requires-Dist: redis; extra == "redis"
+Provides-Extra: rabbitmq
+Requires-Dist: pika; extra == "rabbitmq"
+Provides-Extra: kafka
+Requires-Dist: kafka-python; extra == "kafka"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: fakeredis; extra == "test"
+
+# xyberos-queues
+
+**Message queue plugin — RFC-0019, M9.** Redis Streams, RabbitMQ, and Kafka
+behind one `MessageQueue` contract (`publish` / `poll`).
+
+## Install
+
+```bash
+pip install -e ./queues
+pip install xyberos-queues[redis]      # optional drivers
+pip install xyberos-queues[rabbitmq]
+pip install xyberos-queues[kafka]
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_queues import QueuesPlugin
+
+app = create_app()
+app.load_plugin(QueuesPlugin(provider="redis"))     # or QUEUE_PROVIDER
+
+app.tools.execute("queue_publish", None, topic="jobs", message="do work")
+app.tools.execute("queue_poll", None, topic="jobs")     # -> "do work"
+```
+
+| Provider | Config |
+| -------- | ------ |
+| `redis` | Redis Streams (URL via `REDIS_URL`) |
+| `rabbitmq` | host/port (default `localhost:5672`) |
+| `kafka` | `bootstrap_servers` (default `localhost:9092`) |
+
+`poll` drains one message (oldest first) per call; returns `None` when empty.
+
+## Tests
+
+```bash
+pip install pytest fakeredis
+pytest tests/
+```
+
+fakeredis + fake clients — no live brokers.
+
+## Ship location
+
+Plugin (`xyberos.plugins` entry point) — infrastructure queues (M9).

xyberos_queues-0.1.0/xyberos_queues.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+tests/test_adapters.py
+tests/test_plugin.py
+xyberos_queues/__init__.py
+xyberos_queues/adapters.py
+xyberos_queues/contract.py
+xyberos_queues/plugin.py
+xyberos_queues.egg-info/PKG-INFO
+xyberos_queues.egg-info/SOURCES.txt
+xyberos_queues.egg-info/dependency_links.txt
+xyberos_queues.egg-info/entry_points.txt
+xyberos_queues.egg-info/requires.txt
+xyberos_queues.egg-info/top_level.txt

xyberos_queues-0.1.0/xyberos_queues.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xyberos_queues-0.1.0/xyberos_queues.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xyberos.plugins]
+queues = xyberos_queues.plugin:plugin

xyberos_queues-0.1.0/xyberos_queues.egg-info/requires.txt

@@ -0,0 +1,14 @@
+xyberos>=1.0
+
+[kafka]
+kafka-python
+
+[rabbitmq]
+pika
+
+[redis]
+redis
+
+[test]
+pytest
+fakeredis

xyberos_queues-0.1.0/xyberos_queues.egg-info/top_level.txt

@@ -0,0 +1 @@
+xyberos_queues