tyler-ag-tapper 0.1.0__py3-none-any.whl

tapper/registry/__init__.py

@@ -0,0 +1,18 @@
+"""Registry module for service discovery."""
+
+from tapper.registry.backends import InMemoryBackend, RegistryBackend
+from tapper.registry.client import RegistryClient
+from tapper.registry.server import create_registry_app
+
+__all__ = [
+    "RegistryBackend",
+    "InMemoryBackend",
+    "RegistryClient",
+    "create_registry_app",
+]
+
+try:
+    from tapper.registry.backends import RedisBackend
+    __all__.append("RedisBackend")
+except ImportError:
+    pass

tapper/registry/backends/__init__.py

@@ -0,0 +1,12 @@
+"""Registry backend implementations."""
+
+from tapper.registry.backends.base import RegistryBackend
+from tapper.registry.backends.memory import InMemoryBackend
+
+__all__ = ["RegistryBackend", "InMemoryBackend"]
+
+try:
+    from tapper.registry.backends.redis import RedisBackend
+    __all__.append("RedisBackend")
+except ImportError:
+    pass

tapper/registry/backends/base.py

@@ -0,0 +1,43 @@
+"""Abstract base class for registry backends."""
+
+from abc import ABC, abstractmethod
+
+from tapper.models import ServiceInfo, ServiceInstance
+
+
+class RegistryBackend(ABC):
+    """Abstract base class for service registry backends."""
+
+    @abstractmethod
+    async def register(self, service: ServiceInfo, instance: ServiceInstance) -> None:
+        """Register a service instance.
+
+        If the service already exists, adds the instance to it.
+        If the instance already exists, updates its information.
+        """
+        pass
+
+    @abstractmethod
+    async def unregister(self, name: str, instance_url: str) -> None:
+        """Remove a service instance from the registry."""
+        pass
+
+    @abstractmethod
+    async def get_service(self, name: str) -> ServiceInfo | None:
+        """Get a service by name, or None if not found."""
+        pass
+
+    @abstractmethod
+    async def get_all_services(self) -> list[ServiceInfo]:
+        """Get all registered services."""
+        pass
+
+    @abstractmethod
+    async def heartbeat(self, name: str, instance_url: str) -> None:
+        """Update the heartbeat timestamp for a service instance."""
+        pass
+
+    @abstractmethod
+    async def cleanup_stale(self, max_age_seconds: int = 60) -> None:
+        """Remove instances that haven't sent a heartbeat within max_age_seconds."""
+        pass

tapper/registry/backends/memory.py

@@ -0,0 +1,93 @@
+"""In-memory registry backend for development and testing."""
+
+import asyncio
+from datetime import UTC, datetime, timedelta
+
+from tapper.models import ServiceInfo, ServiceInstance
+from tapper.registry.backends.base import RegistryBackend
+
+
+class InMemoryBackend(RegistryBackend):
+    """In-memory implementation of the registry backend.
+
+    Suitable for development and single-instance deployments.
+    Data is lost when the process stops.
+    """
+
+    def __init__(self) -> None:
+        self._services: dict[str, ServiceInfo] = {}
+        self._lock = asyncio.Lock()
+
+    async def register(self, service: ServiceInfo, instance: ServiceInstance) -> None:
+        """Register a service instance."""
+        async with self._lock:
+            if service.name in self._services:
+                existing = self._services[service.name]
+                instance_urls = {inst.url for inst in existing.instances}
+                if instance.url in instance_urls:
+                    existing.instances = [
+                        instance if inst.url == instance.url else inst
+                        for inst in existing.instances
+                    ]
+                else:
+                    existing.instances.append(instance)
+                existing.routes = service.routes
+                existing.version = service.version
+                existing.description = service.description
+                existing.prefix = service.prefix
+                existing.tags = service.tags
+            else:
+                service_copy = service.model_copy(deep=True)
+                service_copy.instances = [instance]
+                self._services[service.name] = service_copy
+
+    async def unregister(self, name: str, instance_url: str) -> None:
+        """Remove a service instance from the registry."""
+        async with self._lock:
+            if name in self._services:
+                service = self._services[name]
+                service.instances = [
+                    inst for inst in service.instances if inst.url != instance_url
+                ]
+                if not service.instances:
+                    del self._services[name]
+
+    async def get_service(self, name: str) -> ServiceInfo | None:
+        """Get a service by name."""
+        async with self._lock:
+            service = self._services.get(name)
+            if service:
+                return service.model_copy(deep=True)
+            return None
+
+    async def get_all_services(self) -> list[ServiceInfo]:
+        """Get all registered services."""
+        async with self._lock:
+            return [svc.model_copy(deep=True) for svc in self._services.values()]
+
+    async def heartbeat(self, name: str, instance_url: str) -> None:
+        """Update the heartbeat timestamp for a service instance."""
+        async with self._lock:
+            if name in self._services:
+                for instance in self._services[name].instances:
+                    if instance.url == instance_url:
+                        instance.last_heartbeat = datetime.now(UTC)
+                        instance.healthy = True
+                        break
+
+    async def cleanup_stale(self, max_age_seconds: int = 60) -> None:
+        """Remove instances that haven't sent a heartbeat within max_age_seconds."""
+        async with self._lock:
+            cutoff = datetime.now(UTC) - timedelta(seconds=max_age_seconds)
+            services_to_remove = []
+
+            for name, service in self._services.items():
+                service.instances = [
+                    inst for inst in service.instances
+                    if inst.last_heartbeat > cutoff
+                ]
+                if not service.instances:
+                    services_to_remove.append(name)
+
+            for name in services_to_remove:
+                del self._services[name]

tapper/registry/backends/redis.py

@@ -0,0 +1,163 @@
+"""Redis-based registry backend for distributed deployments."""
+
+import hashlib
+import json
+from datetime import UTC, datetime, timedelta
+
+from tapper.models import ServiceInfo, ServiceInstance
+from tapper.registry.backends.base import RegistryBackend
+
+try:
+    import redis.asyncio as redis
+except ImportError:
+    redis = None  # type: ignore
+
+
+class RedisBackend(RegistryBackend):
+    """Redis-based implementation of the registry backend.
+
+    Suitable for distributed deployments where multiple registry instances
+    need to share state.
+
+    Requires the 'redis' optional dependency: pip install tapper[redis]
+    """
+
+    SERVICE_KEY_PREFIX = "tapper:service:"
+    INSTANCE_KEY_PREFIX = "tapper:instance:"
+    DEFAULT_INSTANCE_TTL = 90  # seconds
+
+    def __init__(
+        self,
+        redis_url: str = "redis://localhost:6379",
+        instance_ttl: int = DEFAULT_INSTANCE_TTL,
+    ) -> None:
+        if redis is None:
+            raise ImportError(
+                "Redis support requires the 'redis' package. "
+                "Install with: pip install tapper[redis]"
+            )
+        self._redis_url = redis_url
+        self._instance_ttl = instance_ttl
+        self._client: redis.Redis | None = None
+
+    async def _get_client(self) -> "redis.Redis":
+        """Get or create the Redis client."""
+        if self._client is None:
+            self._client = redis.from_url(self._redis_url)
+        return self._client
+
+    def _service_key(self, name: str) -> str:
+        """Generate Redis key for service info."""
+        return f"{self.SERVICE_KEY_PREFIX}{name}"
+
+    def _instance_key(self, name: str, url: str) -> str:
+        """Generate Redis key for service instance."""
+        url_hash = hashlib.md5(url.encode()).hexdigest()[:12]
+        return f"{self.INSTANCE_KEY_PREFIX}{name}:{url_hash}"
+
+    async def register(self, service: ServiceInfo, instance: ServiceInstance) -> None:
+        """Register a service instance."""
+        client = await self._get_client()
+
+        service_data = service.model_dump(mode="json")
+        service_data["instances"] = []
+        await client.set(
+            self._service_key(service.name),
+            json.dumps(service_data),
+        )
+
+        instance_data = instance.model_dump(mode="json")
+        await client.setex(
+            self._instance_key(service.name, instance.url),
+            self._instance_ttl,
+            json.dumps(instance_data),
+        )
+
+    async def unregister(self, name: str, instance_url: str) -> None:
+        """Remove a service instance from the registry."""
+        client = await self._get_client()
+        await client.delete(self._instance_key(name, instance_url))
+
+        instances = await self._get_instances(name)
+        if not instances:
+            await client.delete(self._service_key(name))
+
+    async def _get_instances(self, name: str) -> list[ServiceInstance]:
+        """Get all instances for a service."""
+        client = await self._get_client()
+        pattern = f"{self.INSTANCE_KEY_PREFIX}{name}:*"
+        instances = []
+
+        async for key in client.scan_iter(match=pattern):
+            data = await client.get(key)
+            if data:
+                instance_data = json.loads(data)
+                instance_data["last_heartbeat"] = datetime.fromisoformat(
+                    instance_data["last_heartbeat"]
+                )
+                instances.append(ServiceInstance(**instance_data))
+
+        return instances
+
+    async def get_service(self, name: str) -> ServiceInfo | None:
+        """Get a service by name."""
+        client = await self._get_client()
+        data = await client.get(self._service_key(name))
+
+        if not data:
+            return None
+
+        service_data = json.loads(data)
+        instances = await self._get_instances(name)
+        service_data["instances"] = [inst.model_dump() for inst in instances]
+
+        return ServiceInfo(**service_data)
+
+    async def get_all_services(self) -> list[ServiceInfo]:
+        """Get all registered services."""
+        client = await self._get_client()
+        pattern = f"{self.SERVICE_KEY_PREFIX}*"
+        services = []
+
+        async for key in client.scan_iter(match=pattern):
+            name = key.decode() if isinstance(key, bytes) else key
+            name = name.replace(self.SERVICE_KEY_PREFIX, "")
+            service = await self.get_service(name)
+            if service:
+                services.append(service)
+
+        return services
+
+    async def heartbeat(self, name: str, instance_url: str) -> None:
+        """Update the heartbeat timestamp for a service instance."""
+        client = await self._get_client()
+        key = self._instance_key(name, instance_url)
+        data = await client.get(key)
+
+        if data:
+            instance_data = json.loads(data)
+            instance_data["last_heartbeat"] = datetime.now(UTC).isoformat()
+            instance_data["healthy"] = True
+            await client.setex(key, self._instance_ttl, json.dumps(instance_data))
+
+    async def cleanup_stale(self, max_age_seconds: int = 60) -> None:
+        """Remove stale instances.
+
+        Note: With Redis, TTL handles automatic expiration.
+        This method is provided for manual cleanup if needed.
+        """
+        client = await self._get_client()
+        cutoff = datetime.now(UTC) - timedelta(seconds=max_age_seconds)
+
+        for service in await self.get_all_services():
+            for instance in service.instances:
+                if instance.last_heartbeat < cutoff:
+                    await client.delete(
+                        self._instance_key(service.name, instance.url)
+                    )
+
+    async def close(self) -> None:
+        """Close the Redis connection."""
+        if self._client:
+            await self._client.close()
+            self._client = None

tapper/registry/client.py

@@ -0,0 +1,190 @@
+"""Async client for communicating with the service registry."""
+
+import asyncio
+import logging
+
+import httpx
+
+from tapper.exceptions import RegistryError
+from tapper.models import ServiceInfo, ServiceInstance
+
+logger = logging.getLogger(__name__)
+
+
+class RegistryClient:
+    """Async client for the Tapper service registry.
+
+    Handles registration, unregistration, heartbeats, and service discovery.
+    """
+
+    def __init__(
+        self,
+        registry_url: str,
+        timeout: float = 10.0,
+    ) -> None:
+        """Initialize the registry client.
+
+        Args:
+            registry_url: Base URL of the registry server.
+            timeout: Request timeout in seconds.
+        """
+        self._registry_url = registry_url.rstrip("/")
+        self._timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+        self._heartbeat_task: asyncio.Task | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create the HTTP client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self._timeout)
+        return self._client
+
+    async def register(
+        self,
+        service: ServiceInfo,
+        instance: ServiceInstance,
+    ) -> None:
+        """Register a service instance with the registry.
+
+        Args:
+            service: Service information including routes.
+            instance: Instance-specific information.
+
+        Raises:
+            RegistryError: If registration fails.
+        """
+        client = await self._get_client()
+        try:
+            response = await client.post(
+                f"{self._registry_url}/register",
+                json={
+                    "service": service.model_dump(mode="json"),
+                    "instance": instance.model_dump(mode="json"),
+                },
+            )
+            response.raise_for_status()
+        except httpx.HTTPError as e:
+            raise RegistryError(f"Failed to register service: {e}") from e
+
+    async def unregister(self, name: str, instance_url: str) -> None:
+        """Remove a service instance from the registry.
+
+        Args:
+            name: Service name.
+            instance_url: URL of the instance to unregister.
+
+        Raises:
+            RegistryError: If unregistration fails.
+        """
+        client = await self._get_client()
+        try:
+            response = await client.post(
+                f"{self._registry_url}/unregister",
+                json={"name": name, "instance_url": instance_url},
+            )
+            response.raise_for_status()
+        except httpx.HTTPError as e:
+            raise RegistryError(f"Failed to unregister service: {e}") from e
+
+    async def get_services(self) -> list[ServiceInfo]:
+        """Get all registered services from the registry.
+
+        Returns:
+            List of registered services.
+
+        Raises:
+            RegistryError: If the request fails.
+        """
+        client = await self._get_client()
+        try:
+            response = await client.get(f"{self._registry_url}/services")
+            response.raise_for_status()
+            return [ServiceInfo(**svc) for svc in response.json()]
+        except httpx.HTTPError as e:
+            raise RegistryError(f"Failed to get services: {e}") from e
+
+    async def get_service(self, name: str) -> ServiceInfo | None:
+        """Get a specific service by name.
+
+        Args:
+            name: Service name.
+
+        Returns:
+            Service information or None if not found.
+
+        Raises:
+            RegistryError: If the request fails (except 404).
+        """
+        client = await self._get_client()
+        try:
+            response = await client.get(f"{self._registry_url}/services/{name}")
+            if response.status_code == 404:
+                return None
+            response.raise_for_status()
+            return ServiceInfo(**response.json())
+        except httpx.HTTPError as e:
+            raise RegistryError(f"Failed to get service: {e}") from e
+
+    async def heartbeat(self, name: str, instance_url: str) -> None:
+        """Send a heartbeat for a service instance.
+
+        Args:
+            name: Service name.
+            instance_url: URL of the instance.
+
+        Raises:
+            RegistryError: If the heartbeat fails.
+        """
+        client = await self._get_client()
+        try:
+            response = await client.post(
+                f"{self._registry_url}/heartbeat/{name}",
+                json={"instance_url": instance_url},
+            )
+            response.raise_for_status()
+        except httpx.HTTPError as e:
+            logger.warning(f"Heartbeat failed for {name}: {e}")
+            raise RegistryError(f"Heartbeat failed: {e}") from e
+
+    def start_heartbeat(
+        self,
+        name: str,
+        instance_url: str,
+        interval: float = 30.0,
+    ) -> None:
+        """Start a background task to send periodic heartbeats.
+
+        Args:
+            name: Service name.
+            instance_url: URL of the instance.
+            interval: Seconds between heartbeats.
+        """
+        if self._heartbeat_task is not None:
+            self._heartbeat_task.cancel()
+
+        async def heartbeat_loop() -> None:
+            while True:
+                try:
+                    await self.heartbeat(name, instance_url)
+                except RegistryError:
+                    pass  # Already logged in heartbeat()
+                await asyncio.sleep(interval)
+
+        self._heartbeat_task = asyncio.create_task(heartbeat_loop())
+
+    async def stop_heartbeat(self) -> None:
+        """Stop the background heartbeat task."""
+        if self._heartbeat_task is not None:
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+            self._heartbeat_task = None
+
+    async def close(self) -> None:
+        """Close the client and stop any background tasks."""
+        await self.stop_heartbeat()
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None

tapper/registry/server.py

@@ -0,0 +1,106 @@
+"""FastAPI-based service registry server."""
+
+import asyncio
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from fastapi import FastAPI, HTTPException, status
+
+from tapper.models import (
+    HeartbeatRequest,
+    RegisterRequest,
+    ServiceInfo,
+    UnregisterRequest,
+)
+from tapper.registry.backends.base import RegistryBackend
+from tapper.registry.backends.memory import InMemoryBackend
+
+
+def create_registry_app(
+    backend: RegistryBackend | None = None,
+    cleanup_interval: int = 30,
+    stale_threshold: int = 60,
+) -> FastAPI:
+    """Create a FastAPI application for the service registry.
+
+    Args:
+        backend: Registry backend to use. Defaults to InMemoryBackend.
+        cleanup_interval: Seconds between stale instance cleanup runs.
+        stale_threshold: Seconds after which an instance is considered stale.
+    """
+    if backend is None:
+        backend = InMemoryBackend()
+
+    cleanup_task: asyncio.Task | None = None
+
+    async def cleanup_loop() -> None:
+        """Periodically clean up stale service instances."""
+        while True:
+            await asyncio.sleep(cleanup_interval)
+            await backend.cleanup_stale(stale_threshold)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        nonlocal cleanup_task
+        cleanup_task = asyncio.create_task(cleanup_loop())
+        yield
+        if cleanup_task:
+            cleanup_task.cancel()
+            try:
+                await cleanup_task
+            except asyncio.CancelledError:
+                pass
+
+    app = FastAPI(
+        title="Tapper Service Registry",
+        description="Central registry for service discovery",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    @app.post("/register", status_code=status.HTTP_201_CREATED)
+    async def register(request: RegisterRequest) -> dict:
+        """Register a service instance with the registry."""
+        await backend.register(request.service, request.instance)
+        return {"status": "registered", "service": request.service.name}
+
+    @app.post("/unregister", status_code=status.HTTP_200_OK)
+    async def unregister(request: UnregisterRequest) -> dict:
+        """Remove a service instance from the registry."""
+        await backend.unregister(request.name, request.instance_url)
+        return {"status": "unregistered", "service": request.name}
+
+    @app.get("/services", response_model=list[ServiceInfo])
+    async def list_services() -> list[ServiceInfo]:
+        """List all registered services."""
+        return await backend.get_all_services()
+
+    @app.get("/services/{name}", response_model=ServiceInfo)
+    async def get_service(name: str) -> ServiceInfo:
+        """Get a specific service by name."""
+        service = await backend.get_service(name)
+        if service is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Service not found: {name}",
+            )
+        return service
+
+    @app.post("/heartbeat/{name}", status_code=status.HTTP_200_OK)
+    async def heartbeat(name: str, request: HeartbeatRequest) -> dict:
+        """Update heartbeat for a service instance."""
+        service = await backend.get_service(name)
+        if service is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Service not found: {name}",
+            )
+        await backend.heartbeat(name, request.instance_url)
+        return {"status": "ok"}
+
+    @app.get("/health")
+    async def health() -> dict:
+        """Health check endpoint for the registry itself."""
+        return {"status": "healthy"}
+
+    return app