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

tapper/service.py

@@ -0,0 +1,156 @@
+"""Service decorator for automatic service registration."""
+
+import logging
+import os
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from typing import AsyncIterator, Callable
+
+from fastapi import FastAPI
+from fastapi.routing import APIRoute
+
+from tapper.models import Route, ServiceInfo, ServiceInstance
+from tapper.registry.client import RegistryClient
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_routes(app: FastAPI, prefix: str | None = None) -> list[Route]:
+    """Extract API routes from a FastAPI application."""
+    routes = []
+    for route in app.routes:
+        if isinstance(route, APIRoute):
+            path = route.path
+            if prefix and not path.startswith(prefix):
+                path = f"{prefix.rstrip('/')}/{path.lstrip('/')}"
+            routes.append(Route(path=path, methods=list(route.methods)))
+    return routes
+
+
+class Service:
+    """Decorator to register a FastAPI application as a service.
+
+    Usage:
+        @Service(name="user-service", version="1.0.0")
+        app = FastAPI()
+
+    Or as a function call:
+        app = FastAPI()
+        app = Service(name="user-service", version="1.0.0")(app)
+
+    The decorator wraps the app's lifespan to:
+    - Register the service with the registry on startup
+    - Start a background heartbeat task
+    - Unregister the service on shutdown
+    """
+
+    def __init__(
+        self,
+        name: str,
+        version: str = "1.0.0",
+        description: str | None = None,
+        prefix: str | None = None,
+        health_endpoint: str = "/health",
+        tags: list[str] | None = None,
+        registry_url: str | None = None,
+        url: str | None = None,
+        heartbeat_interval: float = 30.0,
+    ) -> None:
+        """Initialize the Service decorator.
+
+        Args:
+            name: Unique name for the service.
+            version: Service version.
+            description: Human-readable description.
+            prefix: URL prefix for routing.
+            health_endpoint: Path to health check endpoint.
+            tags: List of tags for categorization.
+            registry_url: URL of the registry server.
+                         Defaults to TAPPER_REGISTRY_URL env var.
+            url: Explicit URL for this instance.
+                 If not provided, attempts to auto-detect from uvicorn.
+            heartbeat_interval: Seconds between heartbeats.
+        """
+        self.name = name
+        self.version = version
+        self.description = description
+        self.prefix = prefix
+        self.health_endpoint = health_endpoint
+        self.tags = tags or []
+        self.registry_url = registry_url or os.environ.get(
+            "TAPPER_REGISTRY_URL", "http://localhost:8001"
+        )
+        self.url = url
+        self.heartbeat_interval = heartbeat_interval
+
+    def __call__(self, app: FastAPI) -> FastAPI:
+        """Apply the decorator to a FastAPI application."""
+        original_lifespan = app.router.lifespan_context
+        service_decorator = self
+
+        @asynccontextmanager
+        async def wrapped_lifespan(app: FastAPI) -> AsyncIterator[None]:
+            client = RegistryClient(service_decorator.registry_url)
+            instance_url = service_decorator._get_instance_url()
+
+            service_info = ServiceInfo(
+                name=service_decorator.name,
+                version=service_decorator.version,
+                description=service_decorator.description,
+                prefix=service_decorator.prefix,
+                routes=_extract_routes(app, service_decorator.prefix),
+                tags=service_decorator.tags,
+            )
+
+            instance = ServiceInstance(
+                url=instance_url,
+                health_endpoint=service_decorator.health_endpoint,
+                last_heartbeat=datetime.now(UTC),
+            )
+
+            try:
+                await client.register(service_info, instance)
+                logger.info(f"Registered service '{service_decorator.name}' at {instance_url}")
+                client.start_heartbeat(
+                    service_decorator.name,
+                    instance_url,
+                    service_decorator.heartbeat_interval,
+                )
+            except Exception as e:
+                logger.error(f"Failed to register service: {e}")
+
+            try:
+                if original_lifespan is not None:
+                    async with original_lifespan(app):
+                        yield
+                else:
+                    yield
+            finally:
+                try:
+                    await client.stop_heartbeat()
+                    await client.unregister(service_decorator.name, instance_url)
+                    logger.info(f"Unregistered service '{service_decorator.name}'")
+                except Exception as e:
+                    logger.error(f"Failed to unregister service: {e}")
+                finally:
+                    await client.close()
+
+        app.router.lifespan_context = wrapped_lifespan
+        return app
+
+    def _get_instance_url(self) -> str:
+        """Get the URL for this service instance.
+
+        Returns the explicitly configured URL, or attempts to detect
+        from environment variables commonly set by uvicorn.
+        """
+        if self.url:
+            return self.url
+
+        host = os.environ.get("UVICORN_HOST", os.environ.get("HOST", "127.0.0.1"))
+        port = os.environ.get("UVICORN_PORT", os.environ.get("PORT", "8000"))
+
+        if host == "0.0.0.0":
+            host = "127.0.0.1"
+
+        return f"http://{host}:{port}"

tyler_ag_tapper-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: tyler-ag-tapper
+Version: 0.1.0
+Summary: A Python microservices framework for FastAPI with service discovery and API gateway routing
+Project-URL: Homepage, https://github.com/tapper/tapper
+Project-URL: Documentation, https://tapper.readthedocs.io
+Author: Tapper Team
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn>=0.23.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+
+# Tapper - Python Microservices Framework
+
+[![PyPI version](https://badge.fury.io/py/tapper.svg)](https://badge.fury.io/py/tapper)
+[![Python Versions](https://img.shields.io/pypi/pyversions/tapper.svg)](https://pypi.org/project/tapper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Tapper** is a lightweight, elegant Python framework that simplifies **service discovery** and **API gateway routing** for **FastAPI**-based microservices.
+
+With a single `@Service` decorator placed on your service's `main.py`, Tapper automatically registers your service and provides a powerful **API gateway** that discovers all services and intelligently routes requests to the correct backend.
+
+## Features
+
+- **Zero-boilerplate registration** with `@tapper.Service`
+- **Automatic service discovery** and registration
+- **Built-in dynamic API gateway** with path-based routing
+- **Transparent proxying** of requests (path params, query strings, headers, body)
+- **Health checks** and service status monitoring
+- **Load balancing** (round-robin by default)
+- **Seamless integration** with existing FastAPI apps
+- **Minimal configuration** — focus on your business logic
+
+## Installation
+
+```bash
+pip install tapper
+```
+
+## Quick Start
+
+### 1. Annotate Your Service (in `main.py` of each microservice)
+
+```python
+from fastapi import FastAPI
+from tapper import Service
+
+app = FastAPI()
+
+@Service(name="user-service", version="1.0.0", description="User management service")
+@app.get("/users/{user_id}")
+async def get_user(user_id: int):
+    return {"user_id": user_id, "name": "Jane Doe"}
+
+@app.post("/users/")
+async def create_user(user: dict):
+    return {"message": "User created", "user": user}
+```
+
+That's all! The `@Service` decorator registers your service automatically.
+
+### 2. Run the API Gateway
+
+Create a separate gateway application (e.g., `gateway.py`):
+
+```python
+from fastapi import FastAPI
+from tapper import TapperGateway
+
+app = FastAPI(title="Tapper API Gateway")
+
+# Initialize the gateway (you can pass registry_url or use env vars)
+gateway = TapperGateway()
+
+# Mount the gateway at the root
+app.mount("/", gateway)
+
+# Optional: expose gateway health
+@app.get("/health")
+async def health():
+    return {"status": "healthy", "services": gateway.get_service_status()}
+```
+
+Run it:
+
+```bash
+uvicorn gateway:app --port 8000
+```
+
+Now your gateway at `http://localhost:8000` will automatically discover and route to all `@Service`-decorated FastAPI apps.
+
+## How It Works
+
+1. Each microservice uses the `@Service` decorator on its `FastAPI` instance.
+2. Tapper registers the service (name, version, endpoints) with a central registry.
+3. The **TapperGateway** periodically discovers available services.
+4. Incoming requests are matched against registered service routes.
+5. Requests are proxied transparently to the correct service instance.
+
+## Configuration Options
+
+### Service Decorator
+
+```python
+@Service(
+    name="payment-service",
+    version="2.1.0",
+    description="Handles all payment operations",
+    prefix="/payments",           # optional: prefix all routes
+    health_endpoint="/health",    # optional: custom health check path
+    tags=["payments", "finance"]  # optional: OpenAPI tags
+)
+```
+
+### Gateway Configuration
+
+```python
+gateway = TapperGateway(
+    registry_url="http://registry:8001",   # or via TAPER_REGISTRY_URL env var
+    discovery_interval=30,                 # seconds
+    timeout=5,                             # request timeout in seconds
+    load_balancer="round-robin",           # or "random", "least-connections", custom
+    # auth_provider=YourAuthProvider(),    # optional
+)
+```
+
+## Advanced Usage
+
+### Custom Load Balancer
+
+```python
+from tapper import LoadBalancer
+
+class CustomBalancer(LoadBalancer):
+    def select_instance(self, instances):
+        # Your custom logic
+        return instances[0]
+
+gateway = TapperGateway(load_balancer=CustomBalancer())
+```
+
+### Supported Registries
+
+- In-memory (development)
+- Redis
+- Consul
+- etcd
+- Custom backend (extend `tapper.registry.RegistryBackend`)
+
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.
+
+## Acknowledgments
+
+- Built on the amazing [FastAPI](https://fastapi.tiangolo.com/)
+- Inspired by service discovery patterns from Kubernetes, Consul, and Spring Cloud
+
+---
+
+Happy microservicing with **Tapper**! 🚀
+```
+
+Feel free to customize badges, add a real logo, or adjust the configuration details as you implement the actual framework!

tyler_ag_tapper-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+tapper/__init__.py,sha256=enQqpwbbHcIhUQ71Ew5ViL-unZFpTRcBjdUkf1Jz410,1481
+tapper/cli.py,sha256=htnKiQZkVy-nC69TbEKiIYZN2Ik4OsC3NTaNvBaeia4,2755
+tapper/exceptions.py,sha256=YWYkD5-viKcqyeJawrPlFjxGsoWvJWjhRsVDkvZqK2E,956
+tapper/gateway.py,sha256=F4Hhly2Yr3QuOPhzB0VONj-xXpf5VegcFgFXFMndn2w,9826
+tapper/load_balancer.py,sha256=AbIwhJLw9ZUbgO3qNhu2UtRBkCtok6Tncpv0bLWeYIw,4221
+tapper/models.py,sha256=Y-rEySBLkSjO1aIQwW3ZxMiWtxz6Gwf0sOm3ZyERm1A,1674
+tapper/service.py,sha256=XiC6H9VPCcvfB_lRwK0rRUhxoek1xFRhxejP6TOtyXs,5555
+tapper/registry/__init__.py,sha256=WGZgbvCQKCkyeej4-qaaEwsru0dHM59S4Y-WDltzeJY,455
+tapper/registry/client.py,sha256=JrMyi2rBzGA5yLGTuilZ9Qpv-ZmNL_kPSIm_7Y830dc,6124
+tapper/registry/server.py,sha256=K_O_6hYm2Uxw7Kb4gZypGT0nb-S_wIY0PHUFRCOYL0g,3703
+tapper/registry/backends/__init__.py,sha256=4Xo1Ug7ulH8rTm2dLJY6IjgR2vAxy3cvsRBLZvre7hU,339
+tapper/registry/backends/base.py,sha256=ACzIOHWKI2VCtrdQzypb9HwXExRH3hqYNP9pQl8VSfY,1355
+tapper/registry/backends/memory.py,sha256=TvTVll83gPqvdzI_8-6SYIvpurK0UekFzFxeBIcdKKo,3816
+tapper/registry/backends/redis.py,sha256=2c0whwWeIkBJL7w_6mDUftEcb_MeRxVvUoHcMwYbFAE,5824
+tyler_ag_tapper-0.1.0.dist-info/METADATA,sha256=iEB6ad4PAyeACX2nFNB5pbm3eWTL8TrF_hR9kaEFruU,6056
+tyler_ag_tapper-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tyler_ag_tapper-0.1.0.dist-info/entry_points.txt,sha256=HBib8RsAMXx7LEF6hl7KDIPeA8dOgmh7ds9WdtlAUq0,43
+tyler_ag_tapper-0.1.0.dist-info/RECORD,,

tyler_ag_tapper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tyler_ag_tapper-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tapper = tapper.cli:main