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

tapper/__init__.py

@@ -0,0 +1,66 @@
+"""Tapper - A microservices framework for FastAPI.
+
+Tapper provides service discovery and API gateway routing for FastAPI applications.
+
+Quick Start:
+    # Register a service
+    from fastapi import FastAPI
+    from tapper import Service
+
+    @Service(name="user-service", version="1.0.0")
+    app = FastAPI()
+
+    # Create a gateway
+    from tapper import TapperGateway
+
+    gateway = TapperGateway(registry_url="http://localhost:8001")
+
+    # Run with uvicorn
+    # uvicorn gateway:gateway --port 8000
+
+Example:
+    See the README for full usage examples.
+"""
+
+from tapper.exceptions import (
+    LoadBalancerError,
+    NoHealthyInstanceError,
+    RegistryError,
+    ServiceNotFoundError,
+    TapperException,
+)
+from tapper.gateway import TapperGateway
+from tapper.load_balancer import (
+    LeastConnectionsBalancer,
+    LoadBalancer,
+    RandomBalancer,
+    RoundRobinBalancer,
+)
+from tapper.models import Route, ServiceInfo, ServiceInstance
+from tapper.registry import RegistryBackend
+from tapper.service import Service
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "Service",
+    "TapperGateway",
+    # Load Balancing
+    "LoadBalancer",
+    "RoundRobinBalancer",
+    "RandomBalancer",
+    "LeastConnectionsBalancer",
+    # Models
+    "ServiceInfo",
+    "ServiceInstance",
+    "Route",
+    # Registry
+    "RegistryBackend",
+    # Exceptions
+    "TapperException",
+    "RegistryError",
+    "ServiceNotFoundError",
+    "NoHealthyInstanceError",
+    "LoadBalancerError",
+]

tapper/cli.py

@@ -0,0 +1,109 @@
+"""Command-line interface for Tapper."""
+
+import click
+import uvicorn
+
+from tapper.registry.backends import InMemoryBackend, RegistryBackend
+
+
+def get_backend(backend_type: str, redis_url: str | None) -> RegistryBackend:
+    """Create a registry backend based on the specified type."""
+    if backend_type == "memory":
+        return InMemoryBackend()
+    elif backend_type == "redis":
+        try:
+            from tapper.registry.backends.redis import RedisBackend
+        except ImportError:
+            raise click.ClickException(
+                "Redis backend requires the 'redis' package. "
+                "Install with: pip install tapper[redis]"
+            )
+        url = redis_url or "redis://localhost:6379"
+        return RedisBackend(redis_url=url)
+    else:
+        raise click.ClickException(f"Unknown backend type: {backend_type}")
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def main() -> None:
+    """Tapper - A microservices framework for FastAPI."""
+    pass
+
+
+@main.command()
+@click.option(
+    "--host",
+    default="0.0.0.0",
+    help="Host to bind the server to",
+)
+@click.option(
+    "--port",
+    default=8001,
+    type=int,
+    help="Port to bind the server to",
+)
+@click.option(
+    "--backend",
+    default="memory",
+    type=click.Choice(["memory", "redis"]),
+    help="Storage backend for the registry",
+)
+@click.option(
+    "--redis-url",
+    default=None,
+    help="Redis URL (only used with redis backend)",
+)
+@click.option(
+    "--reload",
+    is_flag=True,
+    default=False,
+    help="Enable auto-reload for development",
+)
+@click.option(
+    "--cleanup-interval",
+    default=30,
+    type=int,
+    help="Seconds between stale instance cleanup",
+)
+@click.option(
+    "--stale-threshold",
+    default=60,
+    type=int,
+    help="Seconds after which an instance is considered stale",
+)
+def registry(
+    host: str,
+    port: int,
+    backend: str,
+    redis_url: str | None,
+    reload: bool,
+    cleanup_interval: int,
+    stale_threshold: int,
+) -> None:
+    """Run the Tapper service registry server."""
+    click.echo(f"Starting Tapper registry on {host}:{port}")
+    click.echo(f"Backend: {backend}")
+
+    if reload:
+        uvicorn.run(
+            "tapper.registry.server:create_registry_app",
+            factory=True,
+            host=host,
+            port=port,
+            reload=reload,
+        )
+    else:
+        from tapper.registry.server import create_registry_app
+
+        backend_instance = get_backend(backend, redis_url)
+        app = create_registry_app(
+            backend=backend_instance,
+            cleanup_interval=cleanup_interval,
+            stale_threshold=stale_threshold,
+        )
+        uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

tapper/exceptions.py

@@ -0,0 +1,35 @@
+"""Custom exceptions for the Tapper framework."""
+
+
+class TapperException(Exception):
+    """Base exception for all Tapper-related errors."""
+
+    pass
+
+
+class RegistryError(TapperException):
+    """Raised when there's an error communicating with the registry."""
+
+    pass
+
+
+class ServiceNotFoundError(TapperException):
+    """Raised when a requested service is not found in the registry."""
+
+    def __init__(self, service_name: str):
+        self.service_name = service_name
+        super().__init__(f"Service not found: {service_name}")
+
+
+class NoHealthyInstanceError(TapperException):
+    """Raised when no healthy instances are available for a service."""
+
+    def __init__(self, service_name: str):
+        self.service_name = service_name
+        super().__init__(f"No healthy instances available for service: {service_name}")
+
+
+class LoadBalancerError(TapperException):
+    """Raised when there's an error in load balancer selection."""
+
+    pass

tapper/gateway.py

@@ -0,0 +1,294 @@
+"""API Gateway for routing requests to registered services."""
+
+import asyncio
+import logging
+import os
+import re
+from typing import Any, Callable
+
+import httpx
+from starlette.datastructures import Headers
+from starlette.requests import Request
+from starlette.responses import Response, StreamingResponse
+from starlette.routing import compile_path
+
+from tapper.exceptions import NoHealthyInstanceError, ServiceNotFoundError
+from tapper.load_balancer import LoadBalancer, get_load_balancer
+from tapper.models import ServiceInfo
+from tapper.registry.client import RegistryClient
+
+logger = logging.getLogger(__name__)
+
+Scope = dict[str, Any]
+Receive = Callable[[], Any]
+Send = Callable[[dict[str, Any]], Any]
+
+
+class RouteEntry:
+    """A compiled route entry for matching incoming requests."""
+
+    def __init__(self, path_pattern: str, methods: set[str], service: ServiceInfo):
+        self.path_pattern = path_pattern
+        self.methods = methods
+        self.service = service
+        self._regex, _, self._convertors = compile_path(path_pattern)
+
+    def match(self, path: str, method: str) -> dict[str, Any] | None:
+        """Check if the given path and method match this route.
+
+        Returns path parameters if matched, None otherwise.
+        """
+        if method not in self.methods:
+            return None
+
+        match = self._regex.match(path)
+        if match:
+            params = {}
+            for key, value in match.groupdict().items():
+                if key in self._convertors:
+                    params[key] = self._convertors[key].convert(value)
+                else:
+                    params[key] = value
+            return params
+        return None
+
+
+class TapperGateway:
+    """ASGI application that acts as an API gateway.
+
+    Routes incoming requests to registered services based on their
+    declared routes, with load balancing across available instances.
+    """
+
+    def __init__(
+        self,
+        registry_url: str | None = None,
+        discovery_interval: int = 30,
+        timeout: float = 30.0,
+        load_balancer: LoadBalancer | str = "round-robin",
+    ) -> None:
+        """Initialize the gateway.
+
+        Args:
+            registry_url: URL of the registry server.
+                         Defaults to TAPPER_REGISTRY_URL env var.
+            discovery_interval: Seconds between service discovery refreshes.
+            timeout: Request timeout in seconds.
+            load_balancer: Load balancer instance or strategy name.
+        """
+        self.registry_url = registry_url or os.environ.get(
+            "TAPPER_REGISTRY_URL", "http://localhost:8001"
+        )
+        self.discovery_interval = discovery_interval
+        self.timeout = timeout
+        self.load_balancer = get_load_balancer(load_balancer)
+
+        self._client: RegistryClient | None = None
+        self._http_client: httpx.AsyncClient | None = None
+        self._services: list[ServiceInfo] = []
+        self._routes: list[RouteEntry] = []
+        self._discovery_task: asyncio.Task | None = None
+        self._started = False
+
+    async def _get_client(self) -> RegistryClient:
+        """Get or create the registry client."""
+        if self._client is None:
+            self._client = RegistryClient(self.registry_url)
+        return self._client
+
+    async def _get_http_client(self) -> httpx.AsyncClient:
+        """Get or create the HTTP client for proxying."""
+        if self._http_client is None:
+            self._http_client = httpx.AsyncClient(timeout=self.timeout)
+        return self._http_client
+
+    async def _refresh_services(self) -> None:
+        """Refresh the service list from the registry."""
+        try:
+            client = await self._get_client()
+            self._services = await client.get_services()
+            self._build_route_table()
+            logger.debug(f"Refreshed services: {[s.name for s in self._services]}")
+        except Exception as e:
+            logger.error(f"Failed to refresh services: {e}")
+
+    def _build_route_table(self) -> None:
+        """Build the route table from registered services."""
+        routes = []
+        for service in self._services:
+            for route in service.routes:
+                routes.append(RouteEntry(
+                    path_pattern=route.path,
+                    methods=set(route.methods),
+                    service=service,
+                ))
+        self._routes = routes
+
+    def _match_route(self, path: str, method: str) -> tuple[ServiceInfo, dict[str, Any]] | None:
+        """Find a matching route for the given path and method."""
+        for entry in self._routes:
+            params = entry.match(path, method)
+            if params is not None:
+                return entry.service, params
+        return None
+
+    async def _discovery_loop(self) -> None:
+        """Periodically refresh the service list."""
+        while True:
+            await self._refresh_services()
+            await asyncio.sleep(self.discovery_interval)
+
+    async def _startup(self) -> None:
+        """Start background tasks."""
+        if self._started:
+            return
+
+        await self._refresh_services()
+        self._discovery_task = asyncio.create_task(self._discovery_loop())
+        self._started = True
+
+    async def _shutdown(self) -> None:
+        """Clean up resources."""
+        if self._discovery_task:
+            self._discovery_task.cancel()
+            try:
+                await self._discovery_task
+            except asyncio.CancelledError:
+                pass
+
+        if self._client:
+            await self._client.close()
+
+        if self._http_client:
+            await self._http_client.aclose()
+
+    async def _proxy_request(
+        self,
+        request: Request,
+        service: ServiceInfo,
+    ) -> Response:
+        """Proxy a request to a service instance."""
+        if not service.instances:
+            raise NoHealthyInstanceError(service.name)
+
+        instance = self.load_balancer.select_instance(
+            service.instances,
+            service.name,
+        )
+
+        target_url = f"{instance.url.rstrip('/')}{request.url.path}"
+        if request.url.query:
+            target_url = f"{target_url}?{request.url.query}"
+
+        headers = dict(request.headers)
+        headers.pop("host", None)
+
+        body = await request.body()
+
+        http_client = await self._get_http_client()
+
+        try:
+            response = await http_client.request(
+                method=request.method,
+                url=target_url,
+                headers=headers,
+                content=body,
+            )
+
+            response_headers = dict(response.headers)
+            response_headers.pop("content-encoding", None)
+            response_headers.pop("content-length", None)
+            response_headers.pop("transfer-encoding", None)
+
+            return Response(
+                content=response.content,
+                status_code=response.status_code,
+                headers=response_headers,
+            )
+
+        except httpx.TimeoutException:
+            logger.error(f"Timeout proxying to {target_url}")
+            return Response(
+                content=b'{"error": "Gateway timeout"}',
+                status_code=504,
+                media_type="application/json",
+            )
+        except httpx.RequestError as e:
+            logger.error(f"Error proxying to {target_url}: {e}")
+            return Response(
+                content=b'{"error": "Bad gateway"}',
+                status_code=502,
+                media_type="application/json",
+            )
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """ASGI application entry point."""
+        if scope["type"] == "lifespan":
+            await self._handle_lifespan(scope, receive, send)
+            return
+
+        if scope["type"] != "http":
+            return
+
+        await self._startup()
+
+        request = Request(scope, receive, send)
+
+        if request.url.path == "/health":
+            response = Response(
+                content=b'{"status": "healthy"}',
+                status_code=200,
+                media_type="application/json",
+            )
+            await response(scope, receive, send)
+            return
+
+        match = self._match_route(request.url.path, request.method)
+
+        if match is None:
+            response = Response(
+                content=b'{"error": "Not found"}',
+                status_code=404,
+                media_type="application/json",
+            )
+            await response(scope, receive, send)
+            return
+
+        service, _ = match
+
+        try:
+            response = await self._proxy_request(request, service)
+            await response(scope, receive, send)
+        except NoHealthyInstanceError:
+            response = Response(
+                content=b'{"error": "Service unavailable"}',
+                status_code=503,
+                media_type="application/json",
+            )
+            await response(scope, receive, send)
+
+    async def _handle_lifespan(
+        self,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+    ) -> None:
+        """Handle ASGI lifespan events."""
+        while True:
+            message = await receive()
+
+            if message["type"] == "lifespan.startup":
+                try:
+                    await self._startup()
+                    await send({"type": "lifespan.startup.complete"})
+                except Exception as e:
+                    await send({
+                        "type": "lifespan.startup.failed",
+                        "message": str(e),
+                    })
+                    return
+
+            elif message["type"] == "lifespan.shutdown":
+                await self._shutdown()
+                await send({"type": "lifespan.shutdown.complete"})
+                return

tapper/load_balancer.py

@@ -0,0 +1,148 @@
+"""Load balancing strategies for service instances."""
+
+import random
+from abc import ABC, abstractmethod
+from collections import defaultdict
+
+from tapper.exceptions import NoHealthyInstanceError
+from tapper.models import ServiceInstance
+
+
+class LoadBalancer(ABC):
+    """Abstract base class for load balancing strategies."""
+
+    @abstractmethod
+    def select_instance(
+        self,
+        instances: list[ServiceInstance],
+        service_name: str = "",
+    ) -> ServiceInstance:
+        """Select an instance from the list of available instances.
+
+        Args:
+            instances: List of available service instances.
+            service_name: Name of the service (for stateful balancers).
+
+        Returns:
+            The selected instance.
+
+        Raises:
+            NoHealthyInstanceError: If no healthy instances are available.
+        """
+        pass
+
+    def _filter_healthy(self, instances: list[ServiceInstance]) -> list[ServiceInstance]:
+        """Filter to only healthy instances."""
+        return [inst for inst in instances if inst.healthy]
+
+
+class RoundRobinBalancer(LoadBalancer):
+    """Round-robin load balancing strategy.
+
+    Distributes requests evenly across all healthy instances.
+    """
+
+    def __init__(self) -> None:
+        self._counters: dict[str, int] = defaultdict(int)
+
+    def select_instance(
+        self,
+        instances: list[ServiceInstance],
+        service_name: str = "",
+    ) -> ServiceInstance:
+        healthy = self._filter_healthy(instances)
+        if not healthy:
+            raise NoHealthyInstanceError(service_name)
+
+        index = self._counters[service_name] % len(healthy)
+        self._counters[service_name] += 1
+        return healthy[index]
+
+
+class RandomBalancer(LoadBalancer):
+    """Random load balancing strategy.
+
+    Randomly selects from healthy instances.
+    """
+
+    def select_instance(
+        self,
+        instances: list[ServiceInstance],
+        service_name: str = "",
+    ) -> ServiceInstance:
+        healthy = self._filter_healthy(instances)
+        if not healthy:
+            raise NoHealthyInstanceError(service_name)
+
+        return random.choice(healthy)
+
+
+class LeastConnectionsBalancer(LoadBalancer):
+    """Least connections load balancing strategy.
+
+    Selects the instance with the fewest active connections.
+    Note: Requires external connection tracking.
+    """
+
+    def __init__(self) -> None:
+        self._connections: dict[str, int] = defaultdict(int)
+
+    def select_instance(
+        self,
+        instances: list[ServiceInstance],
+        service_name: str = "",
+    ) -> ServiceInstance:
+        healthy = self._filter_healthy(instances)
+        if not healthy:
+            raise NoHealthyInstanceError(service_name)
+
+        min_connections = float("inf")
+        selected = healthy[0]
+
+        for inst in healthy:
+            conn_count = self._connections[inst.url]
+            if conn_count < min_connections:
+                min_connections = conn_count
+                selected = inst
+
+        return selected
+
+    def increment(self, url: str) -> None:
+        """Increment the connection count for an instance."""
+        self._connections[url] += 1
+
+    def decrement(self, url: str) -> None:
+        """Decrement the connection count for an instance."""
+        if self._connections[url] > 0:
+            self._connections[url] -= 1
+
+
+def get_load_balancer(strategy: str | LoadBalancer) -> LoadBalancer:
+    """Get a load balancer instance by name or return the provided instance.
+
+    Args:
+        strategy: Either a LoadBalancer instance or a string name
+                 ("round-robin", "random", "least-connections").
+
+    Returns:
+        A LoadBalancer instance.
+
+    Raises:
+        ValueError: If the strategy name is unknown.
+    """
+    if isinstance(strategy, LoadBalancer):
+        return strategy
+
+    strategies = {
+        "round-robin": RoundRobinBalancer,
+        "random": RandomBalancer,
+        "least-connections": LeastConnectionsBalancer,
+    }
+
+    if strategy not in strategies:
+        raise ValueError(
+            f"Unknown load balancer strategy: {strategy}. "
+            f"Available: {list(strategies.keys())}"
+        )
+
+    return strategies[strategy]()

tapper/models.py

@@ -0,0 +1,53 @@
+"""Pydantic models for the Tapper framework."""
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, Field
+
+
+class Route(BaseModel):
+    """Represents an API route exposed by a service."""
+
+    path: str = Field(..., description="Route path pattern, e.g., '/users/{user_id}'")
+    methods: list[str] = Field(..., description="HTTP methods, e.g., ['GET', 'POST']")
+
+
+class ServiceInstance(BaseModel):
+    """Represents a running instance of a service."""
+
+    url: str = Field(..., description="Base URL of the instance, e.g., 'http://localhost:8001'")
+    health_endpoint: str = Field(default="/health", description="Health check endpoint path")
+    last_heartbeat: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    healthy: bool = Field(default=True)
+
+
+class ServiceInfo(BaseModel):
+    """Complete information about a registered service."""
+
+    name: str = Field(..., description="Unique service name")
+    version: str = Field(..., description="Service version")
+    description: str | None = Field(default=None)
+    prefix: str | None = Field(default=None, description="URL prefix for routing")
+    routes: list[Route] = Field(default_factory=list)
+    instances: list[ServiceInstance] = Field(default_factory=list)
+    tags: list[str] = Field(default_factory=list)
+
+
+class RegisterRequest(BaseModel):
+    """Request body for service registration."""
+
+    service: ServiceInfo
+    instance: ServiceInstance
+
+
+class HeartbeatRequest(BaseModel):
+    """Request body for heartbeat updates."""
+
+    instance_url: str
+
+
+class UnregisterRequest(BaseModel):
+    """Request body for service unregistration."""
+
+    name: str
+    instance_url: str