hivescope 0.1.0__tar.gz

hivescope-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: hivescope
+Version: 0.1.0
+Summary: Hivescope: E2E testing library for HiveMind protocol
+Author-email: JarbasAi <jarbasai@mailfence.com>
+License: AGPL-3.0
+Keywords: hivemind,protocol,testing,e2e,pytest
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: hivemind-bus-client>=0.7.0a2
+Requires-Dist: hivemind-core>=4.0
+Requires-Dist: ovos-utils>=0.0.40
+Requires-Dist: pytest>=7.4
+Requires-Dist: websockets>=11
+Provides-Extra: ovos
+Requires-Dist: ovoscope>=0.13; extra == "ovos"
+Requires-Dist: ovos-core>=0.0.30; extra == "ovos"
+
+# Hivescope
+
+A self-contained pytest-based E2E testing library for HiveMind protocol implementations.
+
+## Install
+
+```bash
+pip install "hivescope @ git+https://github.com/JarbasHiveMind/hivescope@dev"
+```
+
+With OVOS skill-level testing support:
+
+```bash
+pip install "hivescope[ovos] @ git+https://github.com/JarbasHiveMind/hivescope@dev"
+```
+
+## Quick Start
+
+```python
+from hivescope.scenarios import single_satellite
+from hivescope.assertions import assert_handshake_complete, assert_encryption_match
+
+def test_handshake():
+    builder = single_satellite()
+    builder.start_all()
+    try:
+        master = builder.get_master("M0")
+        satellite = builder.get_satellite("S0")
+        assert_handshake_complete(master, satellite)
+        assert_encryption_match(master, satellite)
+    finally:
+        builder.stop_all()
+```
+
+Using pytest fixtures (add to `tests/conftest.py`):
+
+```python
+pytest_plugins = ['hivescope.pytest_fixtures']
+```
+
+```python
+def test_message_forwarded(master_node, satellite_node):
+    from ovos_bus_client.message import Message
+    satellite_node.send(Message("test:ping", {}))
+    master_node.recorder.assert_received("BUS", count=1)
+```
+
+## Templates
+
+Copy-paste test templates from `templates/` into your repo's `tests/e2e/`:
+
+| Template | Covers |
+|---|---|
+| `test_template_handshake.py` | Cipher/encoding agreement, handshake completion |
+| `test_template_routing.py` | Message routing through master |
+| `test_template_acl.py` | ACL enforcement for restricted satellites |
+| `test_template_binary.py` | Binary protocol message handling |
+
+## Configuration
+
+| Key | Default | Purpose |
+|---|---|---|
+| `use_loopback` | `False` | Pass `True` to `add_master()` to use loopback network protocol instead of in-process |
+| `[ovos]` extra | not installed | Enables `OvoscopeAgentProtocol` backed by a live MiniCroft |
+
+## API Reference
+
+See [docs/index.md](docs/index.md) for the full public API.
+
+## License
+
+AGPL-3.0

hivescope-0.1.0/README.md

@@ -0,0 +1,72 @@
+# Hivescope
+
+A self-contained pytest-based E2E testing library for HiveMind protocol implementations.
+
+## Install
+
+```bash
+pip install "hivescope @ git+https://github.com/JarbasHiveMind/hivescope@dev"
+```
+
+With OVOS skill-level testing support:
+
+```bash
+pip install "hivescope[ovos] @ git+https://github.com/JarbasHiveMind/hivescope@dev"
+```
+
+## Quick Start
+
+```python
+from hivescope.scenarios import single_satellite
+from hivescope.assertions import assert_handshake_complete, assert_encryption_match
+
+def test_handshake():
+    builder = single_satellite()
+    builder.start_all()
+    try:
+        master = builder.get_master("M0")
+        satellite = builder.get_satellite("S0")
+        assert_handshake_complete(master, satellite)
+        assert_encryption_match(master, satellite)
+    finally:
+        builder.stop_all()
+```
+
+Using pytest fixtures (add to `tests/conftest.py`):
+
+```python
+pytest_plugins = ['hivescope.pytest_fixtures']
+```
+
+```python
+def test_message_forwarded(master_node, satellite_node):
+    from ovos_bus_client.message import Message
+    satellite_node.send(Message("test:ping", {}))
+    master_node.recorder.assert_received("BUS", count=1)
+```
+
+## Templates
+
+Copy-paste test templates from `templates/` into your repo's `tests/e2e/`:
+
+| Template | Covers |
+|---|---|
+| `test_template_handshake.py` | Cipher/encoding agreement, handshake completion |
+| `test_template_routing.py` | Message routing through master |
+| `test_template_acl.py` | ACL enforcement for restricted satellites |
+| `test_template_binary.py` | Binary protocol message handling |
+
+## Configuration
+
+| Key | Default | Purpose |
+|---|---|---|
+| `use_loopback` | `False` | Pass `True` to `add_master()` to use loopback network protocol instead of in-process |
+| `[ovos]` extra | not installed | Enables `OvoscopeAgentProtocol` backed by a live MiniCroft |
+
+## API Reference
+
+See [docs/index.md](docs/index.md) for the full public API.
+
+## License
+
+AGPL-3.0

hivescope-0.1.0/hivescope/__init__.py

@@ -0,0 +1,67 @@
+"""
+Hivescope: E2E Testing Library for HiveMind
+
+A reusable pytest-based framework for writing end-to-end tests of HiveMind
+protocol implementations. Provides stable APIs for topology simulation,
+message routing verification, and protocol-level assertions.
+
+Public API — stable across versions:
+  - TopologyBuilder: Builder for test network topologies
+  - MasterNode, SatelliteNode, RelayNode: Network node types
+  - TestAgentProtocol: Agent protocol backed by FakeBus (fast, deterministic)
+  - OvoscopeAgentProtocol: Agent protocol backed by MiniCroft (realistic, slow)
+  - TestBinaryProtocol: Binary data handler stub for testing
+  - TestNetworkProtocol: Network protocol stub for in-process testing
+  - MessageRecorder, RecordedMessage: Message recording and inspection
+  - InMemoryClientDatabase: In-memory credential store for testing
+
+Fixtures & Helpers (use via conftest.py):
+  - pytest fixtures: topology, master_node, satellite_node, etc.
+  - Assertion helpers: assert_handshake_complete(), assert_message_routed(), etc.
+  - Preset topologies: single_satellite(), three_satellites(), with_relay(), etc.
+
+Example:
+  from hivescope import TopologyBuilder
+  from hivescope.scenarios import single_satellite
+
+  # Build and run a simple test topology
+  b = single_satellite()
+  b.start_all()
+  # ... test assertions ...
+  b.stop_all()
+"""
+
+from hivescope.topology import TopologyBuilder
+from hivescope.node import MasterNode, SatelliteNode
+from hivescope.topology import RelayNode
+from hivescope.recorder import MessageRecorder, RecordedMessage
+from hivescope.database import InMemoryClientDatabase
+from hivescope.plugins.agent import TestAgentProtocol
+from hivescope.plugins.binary import TestBinaryProtocol
+from hivescope.plugins.network import TestNetworkProtocol
+
+# Optional: OvoscopeAgentProtocol requires ovoscope+ovos-core
+try:
+    from hivescope.plugins.ovoscope_agent import OvoscopeAgentProtocol
+except ImportError:
+    OvoscopeAgentProtocol = None
+
+from hivescope.version import __version__
+
+__all__ = [
+    # Core topology classes (stable)
+    "TopologyBuilder",
+    "MasterNode",
+    "SatelliteNode",
+    "RelayNode",
+    # Protocol plugins (stable)
+    "TestAgentProtocol",
+    "TestBinaryProtocol",
+    "TestNetworkProtocol",
+    "OvoscopeAgentProtocol",
+    # Message recording (stable)
+    "MessageRecorder",
+    "RecordedMessage",
+    # Database (stable)
+    "InMemoryClientDatabase",
+]

hivescope-0.1.0/hivescope/assertions.py

@@ -0,0 +1,225 @@
+"""
+Common assertion helpers for hivescope e2e tests.
+
+Simplify protocol-level assertions with helpers like:
+  - assert_handshake_complete(master, satellite)
+  - assert_message_routed(master, msg_type, count)
+  - assert_acl_enforced(master, satellite, msg_type)
+
+Each helper performs a specific protocol check and raises AssertionError
+with detailed failure messages if the check fails.
+
+Usage:
+
+  from hivescope.assertions import (
+      assert_handshake_complete,
+      assert_message_routed,
+  )
+
+  def test_handshake(master_node, satellite_node):
+      satellite_node.connect(master_node)
+      satellite_node.wait_for_handshake(timeout=5)
+
+      assert_handshake_complete(master_node, satellite_node)
+      assert_message_routed(master_node, "HELLO", count=1)
+"""
+
+from typing import Optional, Any
+from hivescope.node import MasterNode, SatelliteNode
+from hivemind_bus_client.message import HiveMessageType
+
+
+def assert_handshake_complete(
+    master: MasterNode,
+    satellite: SatelliteNode,
+    timeout: float = 5.0
+) -> None:
+    """
+    Assert that satellite has completed handshake with master.
+
+    Checks:
+    - satellite.crypto_key is not None
+    - satellite.handshake_event is set
+    - master has registered the satellite peer
+
+    Raises AssertionError with diagnostic details if any check fails.
+    """
+    errors = []
+
+    if satellite.shim.crypto_key is None:
+        errors.append("satellite.shim.crypto_key is None (no crypto negotiated)")
+
+    if not satellite.shim.handshake_event.is_set():
+        errors.append("satellite.shim.handshake_event not set (handshake not complete)")
+
+    connected_peers = master.connected_peers()
+    if satellite.peer not in connected_peers:
+        errors.append(
+            f"satellite peer '{satellite.peer}' not in master's connected_peers: {connected_peers}"
+        )
+
+    if errors:
+        raise AssertionError(
+            f"Handshake not complete:\n  " + "\n  ".join(errors)
+        )
+
+
+def assert_message_routed(
+    node,
+    msg_type: str,
+    count: int = 1,
+    direction: Optional[str] = None,
+    timeout: float = 2.0
+) -> None:
+    """
+    Assert that a specific message type was routed through a node.
+
+    Checks:
+    - message was recorded by node.recorder
+    - count matches expected number
+
+    Args:
+      node: MasterNode or SatelliteNode with MessageRecorder
+      msg_type: HiveMessageType name (e.g., "HELLO", "BUS", "BROADCAST")
+      count: Expected number of messages
+      direction: Optional "inbound" or "outbound" filter
+      timeout: Wait time for message to appear (not implemented yet)
+
+    Raises AssertionError if count doesn't match.
+    """
+    messages = node.recorder.messages
+
+    if direction:
+        messages = [m for m in messages if m.direction == direction]
+
+    matching = [m for m in messages if m.msg_type == msg_type]
+    actual_count = len(matching)
+
+    if actual_count != count:
+        raise AssertionError(
+            f"Expected {count} '{msg_type}' messages, got {actual_count}.\n"
+            f"All messages: {[m.msg_type for m in node.recorder.messages]}"
+        )
+
+
+def assert_acl_enforced(
+    master: MasterNode,
+    satellite: SatelliteNode,
+    msg_type: str,
+    allowed: bool = False
+) -> None:
+    """
+    Assert that ACL is enforced for a message type on a satellite.
+
+    If allowed=False, verify that sending msg_type to satellite is blocked.
+    If allowed=True, verify that msg_type is allowed through.
+
+    This is a placeholder for more complex ACL assertions.
+    """
+    # TODO: Implement after ACL enforcement logic is fully understood
+    pass
+
+
+def assert_encryption_match(
+    master: MasterNode,
+    satellite: SatelliteNode
+) -> None:
+    """
+    Assert that the master-side connection and satellite shim have matching
+    encryption settings after handshake.
+
+    Checks:
+    - cipher type matches
+    - json_encoding matches
+
+    Raises AssertionError if settings don't match.
+    """
+    errors = []
+
+    master_conn = next(
+        (c for c in master.hm_protocol.clients.values()
+         if c.peer == satellite.peer),
+        None,
+    )
+    if master_conn is None:
+        raise AssertionError(
+            f"satellite peer '{satellite.peer}' not registered at master; "
+            "cannot compare encryption settings"
+        )
+
+    if master_conn.cipher != satellite.shim.cipher:
+        errors.append(
+            f"cipher mismatch: master={master_conn.cipher}, "
+            f"satellite={satellite.shim.cipher}"
+        )
+
+    if master_conn.json_encoding != satellite.shim.json_encoding:
+        errors.append(
+            f"json_encoding mismatch: master={master_conn.json_encoding}, "
+            f"satellite={satellite.shim.json_encoding}"
+        )
+
+    if errors:
+        raise AssertionError(
+            f"Encryption settings don't match:\n  " + "\n  ".join(errors)
+        )
+
+
+def assert_client_registered(
+    master: MasterNode,
+    peer: str
+) -> None:
+    """
+    Assert that a client is registered in master's connected_peers.
+
+    Raises AssertionError if peer is not registered.
+    """
+    connected = master.connected_peers()
+    if peer not in connected:
+        raise AssertionError(
+            f"Peer '{peer}' not registered in master. "
+            f"Connected peers: {connected}"
+        )
+
+
+def assert_client_not_registered(
+    master: MasterNode,
+    peer: str
+) -> None:
+    """
+    Assert that a client is NOT registered in master's connected_peers.
+
+    Raises AssertionError if peer is registered.
+    """
+    connected = master.connected_peers()
+    if peer in connected:
+        raise AssertionError(
+            f"Peer '{peer}' is registered in master. "
+            f"Connected peers: {connected}"
+        )
+
+
+def assert_message_received_by(
+    node,
+    msg_type: str,
+    count: int = 1
+) -> None:
+    """
+    Assert that node's recorder has received a message type.
+
+    Convenience wrapper for assert_message_routed with direction='inbound'.
+    """
+    assert_message_routed(node, msg_type, count=count, direction="inbound")
+
+
+def assert_message_sent_by(
+    node,
+    msg_type: str,
+    count: int = 1
+) -> None:
+    """
+    Assert that node's recorder has sent a message type.
+
+    Convenience wrapper for assert_message_routed with direction='outbound'.
+    """
+    assert_message_routed(node, msg_type, count=count, direction="outbound")

hivescope-0.1.0/hivescope/database.py

@@ -0,0 +1,113 @@
+"""
+In-memory ClientDatabase that avoids any plugin loading or disk I/O.
+Implements the same public interface as hivemind_core.database.ClientDatabase
+so it can be passed directly to HiveMindListenerProtocol.
+"""
+from typing import List, Optional, Iterable
+
+from hivemind_plugin_manager.database import Client
+
+
+class InMemoryClientDatabase:
+    """Drop-in replacement for ClientDatabase backed by a plain dict."""
+
+    def __init__(self):
+        self._clients: dict[str, Client] = {}  # keyed by api_key
+
+    # --- write API ---
+
+    def add_client(self,
+                   name: str,
+                   key: str = "",
+                   admin: bool = False,
+                   intent_blacklist: Optional[List[str]] = None,
+                   skill_blacklist: Optional[List[str]] = None,
+                   message_blacklist: Optional[List[str]] = None,
+                   allowed_types: Optional[List[str]] = None,
+                   crypto_key: Optional[str] = None,
+                   password: Optional[str] = None,
+                   can_escalate: bool = True,
+                   can_propagate: bool = True,
+                   can_broadcast: bool = True) -> bool:
+        if crypto_key is not None:
+            crypto_key = crypto_key[:16]
+        existing = self.get_client_by_api_key(key)
+        if existing:
+            if name:
+                existing.name = name
+            if intent_blacklist is not None:
+                existing.intent_blacklist = intent_blacklist
+            if skill_blacklist is not None:
+                existing.skill_blacklist = skill_blacklist
+            if message_blacklist is not None:
+                existing.message_blacklist = message_blacklist
+            if allowed_types is not None:
+                existing.allowed_types = allowed_types
+            existing.is_admin = admin
+            if crypto_key:
+                existing.crypto_key = crypto_key
+            if password:
+                existing.password = password
+            existing.can_escalate = can_escalate
+            existing.can_propagate = can_propagate
+            existing.can_broadcast = can_broadcast
+            self._clients[key] = existing
+            return True
+
+        client = Client(
+            api_key=key,
+            name=name,
+            client_id=self.total_clients() + 1,
+            is_admin=admin,
+            intent_blacklist=intent_blacklist,
+            skill_blacklist=skill_blacklist,
+            message_blacklist=message_blacklist,
+            allowed_types=allowed_types,
+            crypto_key=crypto_key,
+            password=password,
+            can_escalate=can_escalate,
+            can_propagate=can_propagate,
+            can_broadcast=can_broadcast,
+        )
+        self._clients[key] = client
+        return True
+
+    def update_item(self, client: Client) -> bool:
+        self._clients[client.api_key] = client
+        return True
+
+    def delete_client(self, key: str) -> bool:
+        if key in self._clients:
+            # mark revoked (don't reuse client_id)
+            c = self._clients[key]
+            self._clients[key] = Client(client_id=c.client_id, api_key="revoked")
+            return True
+        return False
+
+    # --- read API ---
+
+    def get_client_by_api_key(self, api_key: str) -> Optional[Client]:
+        return self._clients.get(api_key)
+
+    def get_clients_by_name(self, name: str) -> List[Client]:
+        return [c for c in self._clients.values() if c.name == name]
+
+    def total_clients(self) -> int:
+        return len(self._clients)
+
+    # --- lifecycle ---
+
+    def sync(self):
+        pass  # nothing to reload from disk
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, _type, value, traceback):
+        pass  # nothing to commit
+
+    def __iter__(self) -> Iterable[Client]:
+        return iter(list(self._clients.values()))
+
+    def __len__(self) -> int:
+        return len(self._clients)