Extract a transport-agnostic network discovery backend

kolibri/core/discovery/hooks.py

@@ -42,3 +42,43 @@ def on_renew(self, instance, network_locations):
         :type network_locations: kolibri.core.discovery.models.NetworkLocation[]
         """
         pass
+
+
+@define_hook(only_one_registered=True)
+class NetworkDiscoveryHook(KolibriHook):
+    """
+    A single-registration transport for network discovery. The default zeroconf
+    transport is registered with `as_default=True`; a platform may override it.
+    """
+
+    @abstractmethod
+    def register(self, instance):
+        """Start advertising `instance` on this transport."""
+
+    @abstractmethod
+    def update(self, instance, on_rebind):
+        """
+        Re-advertise `instance` (when not None) and apply any transport rebind.
+
+        Call `on_rebind()` before performing a rebind, not after: the backend
+        cycles its broadcast id there, and a peer rediscovered by the rebind
+        has to be enqueued under the incoming id.
+        """
+
+    @abstractmethod
+    def unregister(self):
+        """Stop advertising our instance."""
+
+    @abstractmethod
+    def start_listening(self, on_add, on_update, on_remove, is_known):
+        """
+        Begin discovering peers, dispatching KolibriInstances to the callbacks.
+
+        `is_known(name)` reports whether the backend already has a broadcasting
+        instance cached for a service name, so the transport can skip querying
+        it again.
+        """
+
+    @abstractmethod
+    def stop_listening(self):
+        """Stop discovering peers and release transport resources."""

kolibri/core/discovery/kolibri_plugin.py

@@ -0,0 +1,10 @@
+from kolibri.core.discovery.hooks import NetworkDiscoveryHook
+from kolibri.core.discovery.utils.network.zeroconf_transport import (
+    ZeroconfNetworkDiscovery,
+)
+from kolibri.plugins.hooks import register_hook
+
+
+@register_hook(as_default=True)
+class ZeroconfNetworkDiscoveryHook(ZeroconfNetworkDiscovery, NetworkDiscoveryHook):
+    """The built-in transport; a platform may override it with a non-default hook."""

kolibri/core/discovery/test/test_discovery_hooks.py

@@ -0,0 +1,63 @@
+import pytest
+
+from kolibri.core.discovery.hooks import NetworkDiscoveryHook
+from kolibri.core.discovery.utils.network.zeroconf_transport import (
+    ZeroconfNetworkDiscovery,
+)
+from kolibri.plugins.hooks import HookSingleInstanceError
+from kolibri.plugins.hooks import register_hook
+
+
+class ConcreteDiscoveryHook(NetworkDiscoveryHook):
+    """
+    Test-only concrete subclass supplying a stub body for all five abstract
+    methods so SingletonMeta can instantiate the singleton when the hook is
+    added to the registries.
+    """
+
+    def register(self, instance):
+        pass
+
+    def update(self, instance, on_rebind):
+        pass
+
+    def unregister(self):
+        pass
+
+    def start_listening(self, on_add, on_update, on_remove, is_known):
+        pass
+
+    def stop_listening(self):
+        pass
+
+
+@pytest.fixture
+def register_discovery_hook():
+    """Registers fresh hook subclasses against a clean registry."""
+    # swap in an empty registry, and restore the real one — which holds the
+    # default zeroconf transport — afterwards
+    registered_hooks = NetworkDiscoveryHook._registered_hooks
+    NetworkDiscoveryHook._registered_hooks = {}
+
+    def register(name):
+        Impl = type(
+            name, (ConcreteDiscoveryHook,), {"__module__": "test.kolibri_plugin"}
+        )
+        Hook = register_hook(Impl)
+        Hook.add_hook_to_registries()
+        return Hook
+
+    yield register
+
+    NetworkDiscoveryHook._registered_hooks = registered_hooks
+
+
+def test_only_one_transport_may_be_registered(register_discovery_hook):
+    register_discovery_hook("OverrideImpl")
+    with pytest.raises(HookSingleInstanceError):
+        register_discovery_hook("OtherOverrideImpl")
+
+
+def test_default_transport_is_zeroconf():
+    """`kolibri.core.discovery`'s plugin registers zeroconf as the default."""
+    assert isinstance(NetworkDiscoveryHook.registered_hook, ZeroconfNetworkDiscovery)