@smilintux/skcapstone 0.1.0 → 0.2.3

package/tests/test_pubsub.py

@@ -0,0 +1,377 @@
+"""Tests for sovereign pub/sub messaging."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+from skcapstone.pubsub import (
+    PubSub,
+    Subscription,
+    TopicMessage,
+    _sanitize_topic,
+    _unsanitize_topic,
+)
+
+
+@pytest.fixture
+def home(tmp_path: Path) -> Path:
+    """Create a minimal agent home."""
+    return tmp_path
+
+
+@pytest.fixture
+def bus(home: Path) -> PubSub:
+    """Create an initialized PubSub instance."""
+    ps = PubSub(home, agent_name="opus")
+    ps.initialize()
+    return ps
+
+
+# ---------------------------------------------------------------------------
+# Topic name sanitization
+# ---------------------------------------------------------------------------
+
+
+class TestSanitization:
+    """Tests for topic name conversion."""
+
+    def test_sanitize_dots(self) -> None:
+        """Dots are preserved (used as separators)."""
+        assert _sanitize_topic("system.health") == "system.health"
+
+    def test_sanitize_slashes(self) -> None:
+        """Slashes become double dashes."""
+        assert _sanitize_topic("team/dev") == "team--dev"
+
+    def test_unsanitize_roundtrip(self) -> None:
+        """Sanitize then unsanitize returns original."""
+        original = "team/dev"
+        assert _unsanitize_topic(_sanitize_topic(original)) == original
+
+
+# ---------------------------------------------------------------------------
+# Initialization
+# ---------------------------------------------------------------------------
+
+
+class TestInitialization:
+    """Tests for PubSub setup."""
+
+    def test_initialize_creates_dirs(self, home: Path) -> None:
+        """Initialize creates the directory structure."""
+        PubSub(home).initialize()
+        assert (home / "pubsub").is_dir()
+        assert (home / "pubsub" / "topics").is_dir()
+        assert (home / "pubsub" / "dead-letter").is_dir()
+
+    def test_initialize_idempotent(self, bus: PubSub, home: Path) -> None:
+        """Multiple initializations don't break anything."""
+        bus.initialize()
+        bus.initialize()
+        assert (home / "pubsub" / "topics").is_dir()
+
+
+# ---------------------------------------------------------------------------
+# Publishing
+# ---------------------------------------------------------------------------
+
+
+class TestPublish:
+    """Tests for message publishing."""
+
+    def test_publish_creates_topic_dir(self, bus: PubSub, home: Path) -> None:
+        """Publishing creates the topic directory."""
+        bus.publish("system.health", {"status": "alive"})
+        assert (home / "pubsub" / "topics" / "system.health").is_dir()
+
+    def test_publish_writes_message_file(self, bus: PubSub, home: Path) -> None:
+        """Publishing writes a JSON message file."""
+        msg = bus.publish("test.topic", {"key": "value"})
+        topic_dir = home / "pubsub" / "topics" / "test.topic"
+        files = list(topic_dir.glob("msg-*.json"))
+        assert len(files) == 1
+
+    def test_publish_returns_message(self, bus: PubSub) -> None:
+        """Publish returns a complete TopicMessage."""
+        msg = bus.publish("t", {"data": 42})
+        assert msg.topic == "t"
+        assert msg.sender == "opus"
+        assert msg.payload == {"data": 42}
+        assert msg.message_id
+
+    def test_publish_multiple_messages(self, bus: PubSub, home: Path) -> None:
+        """Multiple publishes to same topic create separate files."""
+        bus.publish("multi", {"n": 1})
+        bus.publish("multi", {"n": 2})
+        bus.publish("multi", {"n": 3})
+        files = list((home / "pubsub" / "topics" / "multi").glob("msg-*.json"))
+        assert len(files) == 3
+
+    def test_publish_with_tags(self, bus: PubSub) -> None:
+        """Messages can have tags."""
+        msg = bus.publish("tagged", {"x": 1}, tags=["critical", "health"])
+        assert msg.tags == ["critical", "health"]
+
+    def test_publish_with_custom_ttl(self, bus: PubSub) -> None:
+        """Custom TTL is set on the message."""
+        msg = bus.publish("short-lived", {}, ttl_seconds=60)
+        assert msg.ttl_seconds == 60
+
+    def test_prune_excess_messages(self, home: Path) -> None:
+        """Topic is pruned when exceeding max messages."""
+        bus = PubSub(home, agent_name="opus", max_topic_messages=3)
+        bus.initialize()
+        for i in range(5):
+            bus.publish("pruned", {"n": i})
+        files = list((home / "pubsub" / "topics" / "pruned").glob("msg-*.json"))
+        assert len(files) == 3
+
+
+# ---------------------------------------------------------------------------
+# Subscriptions
+# ---------------------------------------------------------------------------
+
+
+class TestSubscribe:
+    """Tests for subscription management."""
+
+    def test_subscribe_creates_entry(self, bus: PubSub) -> None:
+        """Subscribe creates a subscription record."""
+        sub = bus.subscribe("system.*")
+        assert sub.pattern == "system.*"
+
+    def test_subscribe_idempotent(self, bus: PubSub) -> None:
+        """Subscribing twice returns existing subscription."""
+        s1 = bus.subscribe("test.topic")
+        s2 = bus.subscribe("test.topic")
+        assert s1.subscribed_at == s2.subscribed_at
+
+    def test_subscribe_persists(self, bus: PubSub, home: Path) -> None:
+        """Subscriptions are persisted to disk."""
+        bus.subscribe("persistent")
+        subs_file = home / "pubsub" / "subscriptions.json"
+        assert subs_file.exists()
+        data = json.loads(subs_file.read_text(encoding="utf-8"))
+        assert "persistent" in data
+
+    def test_unsubscribe(self, bus: PubSub) -> None:
+        """Unsubscribe removes the subscription."""
+        bus.subscribe("temporary")
+        assert bus.unsubscribe("temporary") is True
+        subs = bus.list_subscriptions()
+        assert "temporary" not in subs
+
+    def test_unsubscribe_nonexistent(self, bus: PubSub) -> None:
+        """Unsubscribing from a nonexistent pattern returns False."""
+        assert bus.unsubscribe("ghost") is False
+
+    def test_list_subscriptions(self, bus: PubSub) -> None:
+        """List all active subscriptions."""
+        bus.subscribe("a.*")
+        bus.subscribe("b.topic")
+        subs = bus.list_subscriptions()
+        assert len(subs) == 2
+
+
+# ---------------------------------------------------------------------------
+# Polling
+# ---------------------------------------------------------------------------
+
+
+class TestPoll:
+    """Tests for message polling."""
+
+    def test_poll_specific_topic(self, bus: PubSub) -> None:
+        """Poll a specific topic returns its messages."""
+        bus.publish("poll.test", {"n": 1})
+        bus.publish("poll.test", {"n": 2})
+        msgs = bus.poll(topic="poll.test")
+        assert len(msgs) == 2
+
+    def test_poll_subscribed_topics(self, bus: PubSub) -> None:
+        """Poll with no topic returns all subscribed messages."""
+        bus.subscribe("sub.*")
+        bus.publish("sub.a", {"n": 1})
+        bus.publish("sub.b", {"n": 2})
+        bus.publish("other", {"n": 3})  # not subscribed
+        msgs = bus.poll()
+        assert len(msgs) == 2
+
+    def test_poll_with_since_filter(self, bus: PubSub) -> None:
+        """Since filter excludes older messages."""
+        bus.publish("time.test", {"n": 1})
+        cutoff = datetime.now(timezone.utc)
+        bus.publish("time.test", {"n": 2})
+        msgs = bus.poll(topic="time.test", since=cutoff)
+        assert len(msgs) == 1
+        assert msgs[0].payload["n"] == 2
+
+    def test_poll_limit(self, bus: PubSub) -> None:
+        """Limit caps the number of returned messages."""
+        for i in range(10):
+            bus.publish("many", {"n": i})
+        msgs = bus.poll(topic="many", limit=3)
+        assert len(msgs) == 3
+
+    def test_poll_skips_expired(self, bus: PubSub, home: Path) -> None:
+        """Expired messages are not returned."""
+        msg = bus.publish("expiry", {"data": "old"}, ttl_seconds=1)
+        # Manually backdate the message
+        topic_dir = home / "pubsub" / "topics" / "expiry"
+        msg_file = list(topic_dir.glob("msg-*.json"))[0]
+        data = json.loads(msg_file.read_text(encoding="utf-8"))
+        data["published_at"] = (datetime.now(timezone.utc) - timedelta(hours=1)).isoformat()
+        msg_file.write_text(json.dumps(data), encoding="utf-8")
+
+        msgs = bus.poll(topic="expiry")
+        assert len(msgs) == 0
+
+    def test_poll_wildcard_subscription(self, bus: PubSub) -> None:
+        """Wildcard subscriptions match multiple topics."""
+        bus.subscribe("team.*")
+        bus.publish("team.dev", {"n": 1})
+        bus.publish("team.ops", {"n": 2})
+        bus.publish("system.health", {"n": 3})
+        msgs = bus.poll()
+        assert len(msgs) == 2
+
+    def test_poll_empty_topic(self, bus: PubSub) -> None:
+        """Polling a topic with no messages returns empty list."""
+        msgs = bus.poll(topic="empty.topic")
+        assert msgs == []
+
+
+# ---------------------------------------------------------------------------
+# Callbacks
+# ---------------------------------------------------------------------------
+
+
+class TestCallbacks:
+    """Tests for callback-based message dispatch."""
+
+    def test_on_message_registers_callback(self, bus: PubSub) -> None:
+        """Registering a callback also subscribes."""
+        received: list[TopicMessage] = []
+        bus.on_message("cb.test", lambda msg: received.append(msg))
+        subs = bus.list_subscriptions()
+        assert "cb.test" in subs
+
+    def test_poll_and_dispatch(self, bus: PubSub) -> None:
+        """Dispatch triggers callbacks for matching messages."""
+        received: list[TopicMessage] = []
+        bus.on_message("dispatch.*", lambda msg: received.append(msg))
+        bus.publish("dispatch.a", {"n": 1})
+        bus.publish("dispatch.b", {"n": 2})
+        count = bus.poll_and_dispatch()
+        assert count == 2
+        assert len(received) == 2
+
+    def test_callback_error_doesnt_stop_dispatch(self, bus: PubSub) -> None:
+        """A failing callback doesn't prevent others from running."""
+        results: list[int] = []
+
+        def failing_cb(msg: TopicMessage) -> None:
+            raise RuntimeError("boom")
+
+        def good_cb(msg: TopicMessage) -> None:
+            results.append(1)
+
+        bus.on_message("error.test", failing_cb)
+        bus.on_message("error.test", good_cb)
+        bus.publish("error.test", {"x": 1})
+        bus.poll_and_dispatch()
+        assert len(results) == 1
+
+
+# ---------------------------------------------------------------------------
+# Topic listing and status
+# ---------------------------------------------------------------------------
+
+
+class TestListAndStatus:
+    """Tests for topic listing and status."""
+
+    def test_list_topics(self, bus: PubSub) -> None:
+        """List all topics with message counts."""
+        bus.publish("topic.a", {"n": 1})
+        bus.publish("topic.a", {"n": 2})
+        bus.publish("topic.b", {"n": 1})
+        topics = bus.list_topics()
+        assert len(topics) == 2
+        topic_a = next(t for t in topics if t["topic"] == "topic.a")
+        assert topic_a["messages"] == 2
+
+    def test_status_summary(self, bus: PubSub) -> None:
+        """Status returns structured summary."""
+        bus.subscribe("s.*")
+        bus.publish("s.a", {"n": 1})
+        status = bus.status()
+        assert status["agent"] == "opus"
+        assert status["subscriptions"] == 1
+        assert status["topics"] >= 1
+        assert status["total_messages"] >= 1
+
+
+# ---------------------------------------------------------------------------
+# Expiry purge
+# ---------------------------------------------------------------------------
+
+
+class TestPurge:
+    """Tests for expired message cleanup."""
+
+    def test_purge_removes_expired(self, bus: PubSub, home: Path) -> None:
+        """Purge removes expired messages."""
+        bus.publish("purge.test", {"data": "old"}, ttl_seconds=1)
+        # Backdate the message
+        topic_dir = home / "pubsub" / "topics" / "purge.test"
+        msg_file = list(topic_dir.glob("msg-*.json"))[0]
+        data = json.loads(msg_file.read_text(encoding="utf-8"))
+        data["published_at"] = (datetime.now(timezone.utc) - timedelta(hours=1)).isoformat()
+        msg_file.write_text(json.dumps(data), encoding="utf-8")
+
+        removed = bus.purge_expired()
+        assert removed == 1
+        assert len(list(topic_dir.glob("msg-*.json"))) == 0
+
+    def test_purge_keeps_valid(self, bus: PubSub) -> None:
+        """Purge doesn't remove valid messages."""
+        bus.publish("keep.test", {"data": "fresh"}, ttl_seconds=86400)
+        removed = bus.purge_expired()
+        assert removed == 0
+
+
+# ---------------------------------------------------------------------------
+# Model tests
+# ---------------------------------------------------------------------------
+
+
+class TestModels:
+    """Tests for Pydantic models."""
+
+    def test_topic_message_defaults(self) -> None:
+        """TopicMessage has sensible defaults."""
+        msg = TopicMessage(topic="t", sender="a")
+        assert msg.ttl_seconds == 86400
+        assert msg.tags == []
+        assert not msg.is_expired
+
+    def test_expired_message(self) -> None:
+        """Expired message is detected."""
+        msg = TopicMessage(
+            topic="t",
+            sender="a",
+            published_at=datetime.now(timezone.utc) - timedelta(hours=25),
+            ttl_seconds=86400,
+        )
+        assert msg.is_expired
+
+    def test_subscription_defaults(self) -> None:
+        """Subscription has sensible defaults."""
+        sub = Subscription(pattern="test.*")
+        assert sub.last_read is None
+        assert sub.message_count == 0

package/tests/test_rate_limiter.py

@@ -0,0 +1,121 @@
+"""Tests for the token-bucket rate limiter."""
+
+from __future__ import annotations
+
+import threading
+import time
+
+import pytest
+
+from skcapstone.rate_limiter import RateLimiter, TokenBucket
+
+
+# ---------------------------------------------------------------------------
+# TokenBucket unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestTokenBucket:
+    def test_initial_full_bucket_allows_up_to_capacity(self):
+        bucket = TokenBucket(rate=10.0, capacity=5)
+        # Should allow exactly 5 consecutive requests from a full bucket
+        for _ in range(5):
+            assert bucket.consume() is True
+
+    def test_exhausted_bucket_rejects(self):
+        bucket = TokenBucket(rate=0.001, capacity=2)  # very slow refill
+        bucket.consume()
+        bucket.consume()
+        assert bucket.consume() is False
+
+    def test_tokens_refill_over_time(self):
+        # Start with an empty-ish bucket (capacity=1, drain it, wait for refill)
+        bucket = TokenBucket(rate=100.0, capacity=1)
+        assert bucket.consume() is True   # drain
+        assert bucket.consume() is False  # empty
+        time.sleep(0.02)                  # wait 20 ms → ~2 tokens at 100/s
+        assert bucket.consume() is True   # should be refilled
+
+    def test_invalid_rate_raises(self):
+        with pytest.raises(ValueError):
+            TokenBucket(rate=0, capacity=10)
+
+    def test_invalid_capacity_raises(self):
+        with pytest.raises(ValueError):
+            TokenBucket(rate=1.0, capacity=0)
+
+
+# ---------------------------------------------------------------------------
+# RateLimiter unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestRateLimiter:
+    def test_allows_requests_within_limit(self):
+        limiter = RateLimiter(requests_per_minute=60)
+        # First 60 requests from the same IP must all be allowed
+        for _ in range(60):
+            assert limiter.is_allowed("10.0.0.1") is True
+
+    def test_blocks_after_limit_exceeded(self):
+        limiter = RateLimiter(requests_per_minute=5)
+        ip = "192.168.1.1"
+        for _ in range(5):
+            limiter.is_allowed(ip)
+        assert limiter.is_allowed(ip) is False
+
+    def test_different_ips_have_independent_buckets(self):
+        limiter = RateLimiter(requests_per_minute=2)
+        ip_a, ip_b = "1.1.1.1", "2.2.2.2"
+        # Drain ip_a
+        limiter.is_allowed(ip_a)
+        limiter.is_allowed(ip_a)
+        assert limiter.is_allowed(ip_a) is False
+        # ip_b should still be untouched
+        assert limiter.is_allowed(ip_b) is True
+
+    def test_reset_restores_bucket(self):
+        limiter = RateLimiter(requests_per_minute=1)
+        ip = "10.0.0.5"
+        limiter.is_allowed(ip)           # drain the single token
+        assert limiter.is_allowed(ip) is False
+        limiter.reset(ip)                # discard bucket
+        assert limiter.is_allowed(ip) is True  # fresh bucket
+
+    def test_clear_removes_all_buckets(self):
+        limiter = RateLimiter(requests_per_minute=1)
+        for ip in ("10.0.0.1", "10.0.0.2", "10.0.0.3"):
+            limiter.is_allowed(ip)       # drain each
+        limiter.clear()
+        for ip in ("10.0.0.1", "10.0.0.2", "10.0.0.3"):
+            assert limiter.is_allowed(ip) is True
+
+    def test_invalid_rpm_raises(self):
+        with pytest.raises(ValueError):
+            RateLimiter(requests_per_minute=0)
+
+    def test_requests_per_minute_property(self):
+        limiter = RateLimiter(requests_per_minute=42)
+        assert limiter.requests_per_minute == 42
+
+    def test_concurrent_requests_thread_safe(self):
+        """Multiple threads hammering the same IP should not crash or over-allow."""
+        limiter = RateLimiter(requests_per_minute=50)
+        ip = "10.0.0.99"
+        allowed: list[bool] = []
+        lock = threading.Lock()
+
+        def hit():
+            result = limiter.is_allowed(ip)
+            with lock:
+                allowed.append(result)
+
+        threads = [threading.Thread(target=hit) for _ in range(100)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # Exactly 50 should be allowed, rest rejected
+        assert sum(allowed) == 50
+        assert len(allowed) == 100

package/tests/test_registry_client.py

@@ -0,0 +1,129 @@
+"""Tests for skcapstone.registry_client — bridge to skills-registry."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from skcapstone.registry_client import RegistryClient, get_registry_client
+
+
+class TestGetRegistryClient:
+    """Tests for the get_registry_client() factory function."""
+
+    def test_returns_none_when_skskills_missing(self):
+        """Should return None when skskills is not installed."""
+        with patch.dict("sys.modules", {"skskills.remote": None}):
+            # Force ImportError by removing the module
+            with patch(
+                "skcapstone.registry_client.RegistryClient.__init__",
+                side_effect=ImportError("no skskills"),
+            ):
+                result = get_registry_client()
+        assert result is None
+
+    def test_returns_client_when_skskills_available(self):
+        """Should return a RegistryClient when skskills is available."""
+        mock_remote = MagicMock()
+        mock_module = MagicMock()
+        mock_module.RemoteRegistry = mock_remote
+
+        with patch.dict("sys.modules", {"skskills.remote": mock_module}):
+            client = get_registry_client("https://test.example.com/api")
+
+        assert client is not None
+        assert isinstance(client, RegistryClient)
+
+    def test_custom_url_passed_to_client(self):
+        """Custom URL should be forwarded to the client."""
+        mock_remote = MagicMock()
+        mock_module = MagicMock()
+        mock_module.RemoteRegistry = mock_remote
+
+        with patch.dict("sys.modules", {"skskills.remote": mock_module}):
+            client = get_registry_client("https://custom.example.com/api")
+
+        assert client.registry_url == "https://custom.example.com/api"
+
+
+class TestRegistryClientIsAvailable:
+    """Tests for RegistryClient.is_available()."""
+
+    def test_available_when_fetch_succeeds(self):
+        """Should return True when remote responds."""
+        mock_remote_instance = MagicMock()
+        mock_remote_instance.fetch_index.return_value = MagicMock(skills=[])
+
+        mock_remote_cls = MagicMock(return_value=mock_remote_instance)
+        mock_module = MagicMock()
+        mock_module.RemoteRegistry = mock_remote_cls
+
+        with patch.dict("sys.modules", {"skskills.remote": mock_module}):
+            client = RegistryClient("https://test.example.com/api")
+            assert client.is_available() is True
+
+    def test_unavailable_when_fetch_fails(self):
+        """Should return False when remote is unreachable."""
+        mock_remote_instance = MagicMock()
+        mock_remote_instance.fetch_index.side_effect = ConnectionError("offline")
+
+        mock_remote_cls = MagicMock(return_value=mock_remote_instance)
+        mock_module = MagicMock()
+        mock_module.RemoteRegistry = mock_remote_cls
+
+        with patch.dict("sys.modules", {"skskills.remote": mock_module}):
+            client = RegistryClient("https://test.example.com/api")
+            assert client.is_available() is False
+
+
+class TestRegistryClientListAndSearch:
+    """Tests for list_skills() and search()."""
+
+    def _make_client(self):
+        """Create a client with mocked remote."""
+        mock_entry_1 = MagicMock()
+        mock_entry_1.model_dump.return_value = {
+            "name": "syncthing-setup",
+            "version": "1.0.0",
+            "description": "Syncthing sovereign sync",
+            "tags": ["sync"],
+        }
+        mock_entry_2 = MagicMock()
+        mock_entry_2.model_dump.return_value = {
+            "name": "pgp-identity",
+            "version": "0.2.0",
+            "description": "PGP key management",
+            "tags": ["identity"],
+        }
+
+        mock_index = MagicMock()
+        mock_index.skills = [mock_entry_1, mock_entry_2]
+
+        mock_remote_instance = MagicMock()
+        mock_remote_instance.fetch_index.return_value = mock_index
+        mock_remote_instance.search.return_value = [mock_entry_1]
+
+        mock_remote_cls = MagicMock(return_value=mock_remote_instance)
+        mock_module = MagicMock()
+        mock_module.RemoteRegistry = mock_remote_cls
+
+        with patch.dict("sys.modules", {"skskills.remote": mock_module}):
+            client = RegistryClient("https://test.example.com/api")
+
+        return client
+
+    def test_list_skills_returns_dicts(self):
+        """list_skills() should return list of dicts."""
+        client = self._make_client()
+        skills = client.list_skills()
+        assert len(skills) == 2
+        assert skills[0]["name"] == "syncthing-setup"
+        assert skills[1]["name"] == "pgp-identity"
+
+    def test_search_returns_matching_dicts(self):
+        """search() should return matching skill dicts."""
+        client = self._make_client()
+        results = client.search("syncthing")
+        assert len(results) == 1
+        assert results[0]["name"] == "syncthing-setup"