nodus-adapter-base 0.1.0__tar.gz

nodus_adapter_base-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: nodus-adapter-base
+Version: 0.1.0
+Summary: Abstract base for nodus channel adapters: reconnect loop, health recording, connection manager
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/nodus-adapters
+Project-URL: Repository, https://github.com/Masterplanner25/nodus-adapters
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: nodus-channels>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# nodus-adapter-base
+
+**Abstract base class for [nodus-channels](https://github.com/Masterplanner25/nodus-channels) adapters.**
+
+Provides the reconnect loop, health recording, and connection management
+so concrete adapters (Slack, Discord, webhook, etc.) only implement the
+three transport-specific methods.
+
+> **Status:** v0.1.0 — prepared, not yet published.
+
+---
+
+## Install
+
+```bash
+pip install nodus-adapter-base
+```
+
+Requires `nodus-channels>=0.1.0`.
+
+---
+
+## What it provides
+
+| Class | Purpose |
+|---|---|
+| `BaseChannelAdapter` | Abstract base with `connect()` retry backoff, health recording, `send()`, `subscribe()` |
+| `ConnectionManager` | `start_all()`, `stop_all()`, `health_check_all()` across a `ChannelRegistry` |
+
+---
+
+## Implementing an adapter
+
+```python
+from nodus_channels import ChannelInfo, Message
+from nodus_adapter_base import BaseChannelAdapter
+
+class SlackAdapter(BaseChannelAdapter):
+    @property
+    def channel_id(self) -> str:
+        return "slack"
+
+    @property
+    def info(self) -> ChannelInfo:
+        return ChannelInfo(id="slack", display_name="Slack")
+
+    async def _do_connect(self) -> None:
+        # establish websocket / API connection
+        ...
+
+    async def _do_send(self, content, peer_id, *, thread_id=None,
+                       reply_to_id=None, attachments=None) -> str:
+        # send message; return message ID
+        return "slack-msg-id"
+
+    def _do_subscribe(self):
+        # return an async generator yielding Message objects
+        async def _gen():
+            ...
+            yield message
+        return _gen()
+```
+
+### Reconnect backoff
+
+`connect()` retries up to `max_reconnect_attempts` times (default 5) using
+the backoff schedule `[1, 5, 30, 60, 300]` seconds. Each failure is recorded
+on the `HealthMonitor`. Raises the last exception if all attempts fail.
+
+### Health recording
+
+Every `connect()`, `send()`, and `health_check()` call records success or
+failure on the adapter's `HealthMonitor`. Access it via `adapter.health_monitor`.
+
+---
+
+## ConnectionManager
+
+```python
+from nodus_channels import ChannelRegistry
+from nodus_adapter_base import ConnectionManager
+
+registry = ChannelRegistry()
+registry.register(SlackAdapter())
+registry.register(DiscordAdapter())
+
+manager = ConnectionManager(registry)
+results = await manager.start_all()        # {"slack": True, "discord": True}
+health  = await manager.health_check_all() # {"slack": True, "discord": False}
+await manager.stop_all()
+```
+
+---
+
+## Development
+
+```bash
+cd base
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

nodus_adapter_base-0.1.0/README.md

@@ -0,0 +1,107 @@
+# nodus-adapter-base
+
+**Abstract base class for [nodus-channels](https://github.com/Masterplanner25/nodus-channels) adapters.**
+
+Provides the reconnect loop, health recording, and connection management
+so concrete adapters (Slack, Discord, webhook, etc.) only implement the
+three transport-specific methods.
+
+> **Status:** v0.1.0 — prepared, not yet published.
+
+---
+
+## Install
+
+```bash
+pip install nodus-adapter-base
+```
+
+Requires `nodus-channels>=0.1.0`.
+
+---
+
+## What it provides
+
+| Class | Purpose |
+|---|---|
+| `BaseChannelAdapter` | Abstract base with `connect()` retry backoff, health recording, `send()`, `subscribe()` |
+| `ConnectionManager` | `start_all()`, `stop_all()`, `health_check_all()` across a `ChannelRegistry` |
+
+---
+
+## Implementing an adapter
+
+```python
+from nodus_channels import ChannelInfo, Message
+from nodus_adapter_base import BaseChannelAdapter
+
+class SlackAdapter(BaseChannelAdapter):
+    @property
+    def channel_id(self) -> str:
+        return "slack"
+
+    @property
+    def info(self) -> ChannelInfo:
+        return ChannelInfo(id="slack", display_name="Slack")
+
+    async def _do_connect(self) -> None:
+        # establish websocket / API connection
+        ...
+
+    async def _do_send(self, content, peer_id, *, thread_id=None,
+                       reply_to_id=None, attachments=None) -> str:
+        # send message; return message ID
+        return "slack-msg-id"
+
+    def _do_subscribe(self):
+        # return an async generator yielding Message objects
+        async def _gen():
+            ...
+            yield message
+        return _gen()
+```
+
+### Reconnect backoff
+
+`connect()` retries up to `max_reconnect_attempts` times (default 5) using
+the backoff schedule `[1, 5, 30, 60, 300]` seconds. Each failure is recorded
+on the `HealthMonitor`. Raises the last exception if all attempts fail.
+
+### Health recording
+
+Every `connect()`, `send()`, and `health_check()` call records success or
+failure on the adapter's `HealthMonitor`. Access it via `adapter.health_monitor`.
+
+---
+
+## ConnectionManager
+
+```python
+from nodus_channels import ChannelRegistry
+from nodus_adapter_base import ConnectionManager
+
+registry = ChannelRegistry()
+registry.register(SlackAdapter())
+registry.register(DiscordAdapter())
+
+manager = ConnectionManager(registry)
+results = await manager.start_all()        # {"slack": True, "discord": True}
+health  = await manager.health_check_all() # {"slack": True, "discord": False}
+await manager.stop_all()
+```
+
+---
+
+## Development
+
+```bash
+cd base
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

nodus_adapter_base-0.1.0/nodus_adapter_base/__init__.py

@@ -0,0 +1,14 @@
+"""nodus-adapter-base — abstract base for channel adapters.
+
+BaseChannelAdapter:
+    - connect() with exponential backoff retry
+    - Health recording via HealthMonitor
+    - Abstract interface: _do_connect, _do_send, _do_subscribe
+
+ConnectionManager:
+    - start_all() / stop_all() / health_check_all()
+"""
+from .adapter import BaseChannelAdapter
+from .manager import ConnectionManager
+
+__all__ = ["BaseChannelAdapter", "ConnectionManager"]

nodus_adapter_base-0.1.0/nodus_adapter_base/adapter.py

@@ -0,0 +1,148 @@
+"""BaseChannelAdapter — abstract base with reconnect loop and health recording."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import AsyncIterator, Optional
+
+from nodus_channels import Attachment, ChannelInfo, ChannelRegistry, Message
+from nodus_channels.health import HealthMonitor
+
+logger = logging.getLogger(__name__)
+
+_RECONNECT_BACKOFF: list[float] = [1.0, 5.0, 30.0, 60.0, 300.0]
+
+
+class BaseChannelAdapter(ABC):
+    """Abstract base class for channel adapters.
+
+    Provides:
+    - ``connect()`` with exponential backoff retry
+    - Health recording via ``HealthMonitor``
+    - Default ``health_check()`` delegating to ``_do_health_check()``
+
+    Subclass this and implement ``_do_connect``, ``_do_send``,
+    ``_do_subscribe``, and optionally ``_do_health_check``.
+
+    Usage::
+
+        class MyAdapter(BaseChannelAdapter):
+            @property
+            def channel_id(self): return "my-channel"
+            @property
+            def info(self): return ChannelInfo("my-channel", "My Channel")
+            async def _do_connect(self): ...
+            async def _do_send(self, content, peer_id, **kwargs): return "msg-id"
+            def _do_subscribe(self): ...
+    """
+
+    def __init__(
+        self,
+        *,
+        health_monitor: Optional[HealthMonitor] = None,
+        max_reconnect_attempts: int = 5,
+    ) -> None:
+        self._health = health_monitor or HealthMonitor()
+        self._max_reconnect = max_reconnect_attempts
+        self._connected = False
+
+    # ── Abstract interface ────────────────────────────────────────────────────
+
+    @property
+    @abstractmethod
+    def channel_id(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def info(self) -> ChannelInfo: ...
+
+    @abstractmethod
+    async def _do_connect(self) -> None: ...
+
+    @abstractmethod
+    async def _do_send(
+        self,
+        content: str,
+        peer_id: str,
+        *,
+        thread_id: Optional[str] = None,
+        reply_to_id: Optional[str] = None,
+        attachments: Optional[list[Attachment]] = None,
+    ) -> str: ...
+
+    @abstractmethod
+    def _do_subscribe(self) -> AsyncIterator[Message]: ...
+
+    # ── Implemented methods ───────────────────────────────────────────────────
+
+    async def connect(self) -> None:
+        """Connect with exponential backoff retry on failure."""
+        for attempt, delay in enumerate(_RECONNECT_BACKOFF[: self._max_reconnect]):
+            try:
+                await self._do_connect()
+                self._connected = True
+                self._health.record_success(self.channel_id)
+                logger.info("[%s] connected", self.channel_id)
+                return
+            except Exception as exc:
+                self._health.record_failure(self.channel_id, str(exc))
+                if attempt < self._max_reconnect - 1:
+                    logger.warning(
+                        "[%s] connect failed (attempt %d): %s — retry in %.1fs",
+                        self.channel_id, attempt + 1, exc, delay,
+                    )
+                    await asyncio.sleep(delay)
+                else:
+                    logger.error("[%s] connect failed after %d attempts: %s",
+                                 self.channel_id, self._max_reconnect, exc)
+                    raise
+
+    async def disconnect(self) -> None:
+        self._connected = False
+        logger.info("[%s] disconnected", self.channel_id)
+
+    async def send(
+        self,
+        content: str,
+        peer_id: str,
+        *,
+        thread_id: Optional[str] = None,
+        reply_to_id: Optional[str] = None,
+        attachments: Optional[list[Attachment]] = None,
+    ) -> str:
+        try:
+            msg_id = await self._do_send(
+                content, peer_id,
+                thread_id=thread_id,
+                reply_to_id=reply_to_id,
+                attachments=attachments,
+            )
+            self._health.record_success(self.channel_id)
+            return msg_id
+        except Exception as exc:
+            self._health.record_failure(self.channel_id, str(exc))
+            raise
+
+    def subscribe(self) -> AsyncIterator[Message]:
+        return self._do_subscribe()
+
+    async def health_check(self) -> bool:
+        try:
+            result = await self._do_health_check()
+            if result:
+                self._health.record_success(self.channel_id)
+            else:
+                self._health.record_failure(self.channel_id, "health check returned False")
+            return result
+        except Exception as exc:
+            self._health.record_failure(self.channel_id, str(exc))
+            return False
+
+    async def _do_health_check(self) -> bool:
+        """Override to provide a real health check. Default: True if connected."""
+        return self._connected
+
+    @property
+    def health_monitor(self) -> HealthMonitor:
+        return self._health

nodus_adapter_base-0.1.0/nodus_adapter_base/manager.py

@@ -0,0 +1,65 @@
+"""ConnectionManager — start and stop all registered channel adapters."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Optional
+
+from nodus_channels import ChannelRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionManager:
+    """Start and gracefully stop all adapters in a ``ChannelRegistry``.
+
+    Usage::
+
+        registry = ChannelRegistry()
+        registry.register(MyAdapter())
+        manager = ConnectionManager(registry)
+        await manager.start_all()
+        # ... run forever ...
+        await manager.stop_all()
+    """
+
+    def __init__(self, registry: ChannelRegistry) -> None:
+        self._registry = registry
+
+    async def start_all(self) -> dict[str, bool]:
+        """Connect all registered adapters concurrently.
+
+        Returns a dict of ``{channel_id: success}`` for each adapter.
+        """
+        adapters = self._registry.list()
+        results: dict[str, bool] = {}
+        for adapter in adapters:
+            try:
+                await adapter.connect()
+                results[adapter.channel_id] = True
+            except Exception as exc:
+                logger.error("[ConnectionManager] failed to connect %s: %s",
+                             adapter.channel_id, exc)
+                results[adapter.channel_id] = False
+        return results
+
+    async def stop_all(self) -> None:
+        """Disconnect all registered adapters."""
+        adapters = self._registry.list()
+        for adapter in adapters:
+            try:
+                await adapter.disconnect()
+            except Exception as exc:
+                logger.warning("[ConnectionManager] error disconnecting %s: %s",
+                               adapter.channel_id, exc)
+
+    async def health_check_all(self) -> dict[str, bool]:
+        """Run health_check() on all adapters.  Returns {channel_id: healthy}."""
+        adapters = self._registry.list()
+        results: dict[str, bool] = {}
+        for adapter in adapters:
+            try:
+                results[adapter.channel_id] = await adapter.health_check()
+            except Exception:
+                results[adapter.channel_id] = False
+        return results

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

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: nodus-adapter-base
+Version: 0.1.0
+Summary: Abstract base for nodus channel adapters: reconnect loop, health recording, connection manager
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/nodus-adapters
+Project-URL: Repository, https://github.com/Masterplanner25/nodus-adapters
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: nodus-channels>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# nodus-adapter-base
+
+**Abstract base class for [nodus-channels](https://github.com/Masterplanner25/nodus-channels) adapters.**
+
+Provides the reconnect loop, health recording, and connection management
+so concrete adapters (Slack, Discord, webhook, etc.) only implement the
+three transport-specific methods.
+
+> **Status:** v0.1.0 — prepared, not yet published.
+
+---
+
+## Install
+
+```bash
+pip install nodus-adapter-base
+```
+
+Requires `nodus-channels>=0.1.0`.
+
+---
+
+## What it provides
+
+| Class | Purpose |
+|---|---|
+| `BaseChannelAdapter` | Abstract base with `connect()` retry backoff, health recording, `send()`, `subscribe()` |
+| `ConnectionManager` | `start_all()`, `stop_all()`, `health_check_all()` across a `ChannelRegistry` |
+
+---
+
+## Implementing an adapter
+
+```python
+from nodus_channels import ChannelInfo, Message
+from nodus_adapter_base import BaseChannelAdapter
+
+class SlackAdapter(BaseChannelAdapter):
+    @property
+    def channel_id(self) -> str:
+        return "slack"
+
+    @property
+    def info(self) -> ChannelInfo:
+        return ChannelInfo(id="slack", display_name="Slack")
+
+    async def _do_connect(self) -> None:
+        # establish websocket / API connection
+        ...
+
+    async def _do_send(self, content, peer_id, *, thread_id=None,
+                       reply_to_id=None, attachments=None) -> str:
+        # send message; return message ID
+        return "slack-msg-id"
+
+    def _do_subscribe(self):
+        # return an async generator yielding Message objects
+        async def _gen():
+            ...
+            yield message
+        return _gen()
+```
+
+### Reconnect backoff
+
+`connect()` retries up to `max_reconnect_attempts` times (default 5) using
+the backoff schedule `[1, 5, 30, 60, 300]` seconds. Each failure is recorded
+on the `HealthMonitor`. Raises the last exception if all attempts fail.
+
+### Health recording
+
+Every `connect()`, `send()`, and `health_check()` call records success or
+failure on the adapter's `HealthMonitor`. Access it via `adapter.health_monitor`.
+
+---
+
+## ConnectionManager
+
+```python
+from nodus_channels import ChannelRegistry
+from nodus_adapter_base import ConnectionManager
+
+registry = ChannelRegistry()
+registry.register(SlackAdapter())
+registry.register(DiscordAdapter())
+
+manager = ConnectionManager(registry)
+results = await manager.start_all()        # {"slack": True, "discord": True}
+health  = await manager.health_check_all() # {"slack": True, "discord": False}
+await manager.stop_all()
+```
+
+---
+
+## Development
+
+```bash
+cd base
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

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

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+nodus_adapter_base/__init__.py
+nodus_adapter_base/adapter.py
+nodus_adapter_base/manager.py
+nodus_adapter_base.egg-info/PKG-INFO
+nodus_adapter_base.egg-info/SOURCES.txt
+nodus_adapter_base.egg-info/dependency_links.txt
+nodus_adapter_base.egg-info/requires.txt
+nodus_adapter_base.egg-info/top_level.txt
+tests/test_adapter_base.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,5 @@
+nodus-channels>=0.1.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.21

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

@@ -0,0 +1 @@
+nodus_adapter_base

nodus_adapter_base-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nodus-adapter-base"
+version = "0.1.0"
+description = "Abstract base for nodus channel adapters: reconnect loop, health recording, connection manager"
+authors = [{ name = "Shawn Knight" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["nodus-channels>=0.1.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://github.com/Masterplanner25/nodus-adapters"
+Repository = "https://github.com/Masterplanner25/nodus-adapters"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["nodus_adapter_base*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

nodus_adapter_base-0.1.0/setup.cfg

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

nodus_adapter_base-0.1.0/tests/test_adapter_base.py

@@ -0,0 +1,148 @@
+"""nodus-adapter-base tests."""
+import asyncio
+import pytest
+
+from nodus_channels import ChannelInfo, ChannelRegistry, Message
+from nodus_adapter_base import BaseChannelAdapter, ConnectionManager
+
+
+class _StubAdapter(BaseChannelAdapter):
+    """Minimal concrete adapter for testing."""
+
+    def __init__(self, channel="test", fail_connect=False, **kw):
+        super().__init__(**kw)
+        self._channel = channel
+        self._fail_connect = fail_connect
+        self.connect_calls = 0
+        self.send_calls = []
+
+    @property
+    def channel_id(self): return self._channel
+
+    @property
+    def info(self): return ChannelInfo(id=self._channel, display_name=self._channel.title())
+
+    async def _do_connect(self):
+        self.connect_calls += 1
+        if self._fail_connect:
+            raise ConnectionError("deliberate failure")
+
+    async def _do_send(self, content, peer_id, **kwargs):
+        self.send_calls.append((content, peer_id))
+        return f"msg-{len(self.send_calls)}"
+
+    def _do_subscribe(self):
+        async def _gen():
+            if False: yield  # empty async generator
+        return _gen()
+
+    async def _do_health_check(self): return self._connected
+
+
+# ── connect / disconnect ──────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_connect_sets_connected():
+    adapter = _StubAdapter()
+    await adapter.connect()
+    assert adapter._connected is True
+
+
+@pytest.mark.asyncio
+async def test_connect_records_health_success():
+    adapter = _StubAdapter()
+    await adapter.connect()
+    snap = adapter.health_monitor.snapshot("test")
+    assert snap.failure_count == 0
+
+
+@pytest.mark.asyncio
+async def test_connect_failure_records_health():
+    adapter = _StubAdapter(fail_connect=True, max_reconnect_attempts=1)
+    with pytest.raises(ConnectionError):
+        await adapter.connect()
+    snap = adapter.health_monitor.snapshot("test")
+    assert snap.failure_count >= 1
+
+
+@pytest.mark.asyncio
+async def test_disconnect_clears_connected():
+    adapter = _StubAdapter()
+    await adapter.connect()
+    await adapter.disconnect()
+    assert adapter._connected is False
+
+
+# ── send ──────────────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_send_returns_msg_id():
+    adapter = _StubAdapter()
+    await adapter.connect()
+    msg_id = await adapter.send("hello", "peer-1")
+    assert msg_id == "msg-1"
+    assert adapter.send_calls[0] == ("hello", "peer-1")
+
+
+@pytest.mark.asyncio
+async def test_send_failure_records_health():
+    class _FailSend(_StubAdapter):
+        async def _do_send(self, *a, **kw):
+            raise RuntimeError("send failed")
+
+    adapter = _FailSend()
+    await adapter.connect()
+    with pytest.raises(RuntimeError):
+        await adapter.send("hello", "peer-1")
+    snap = adapter.health_monitor.snapshot("test")
+    assert snap.failure_count >= 1
+
+
+# ── health_check ──────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_health_check_true_when_connected():
+    adapter = _StubAdapter()
+    await adapter.connect()
+    assert await adapter.health_check() is True
+
+
+@pytest.mark.asyncio
+async def test_health_check_false_when_disconnected():
+    adapter = _StubAdapter()
+    # Not connected yet
+    assert await adapter.health_check() is False
+
+
+# ── ConnectionManager ─────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_manager_start_all():
+    registry = ChannelRegistry()
+    registry.register(_StubAdapter("a"))
+    registry.register(_StubAdapter("b"))
+    manager = ConnectionManager(registry)
+    results = await manager.start_all()
+    assert results == {"a": True, "b": True}
+
+
+@pytest.mark.asyncio
+async def test_manager_start_all_partial_failure():
+    registry = ChannelRegistry()
+    registry.register(_StubAdapter("ok"))
+    registry.register(_StubAdapter("fail", fail_connect=True, max_reconnect_attempts=1))
+    manager = ConnectionManager(registry)
+    results = await manager.start_all()
+    assert results["ok"] is True
+    assert results["fail"] is False
+
+
+@pytest.mark.asyncio
+async def test_manager_health_check_all():
+    registry = ChannelRegistry()
+    a = _StubAdapter("a")
+    await a.connect()
+    registry.register(a)
+    manager = ConnectionManager(registry)
+    results = await manager.health_check_all()
+    assert results["a"] is True