fastuator 0.0.1__tar.gz

fastuator-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,41 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        allow-prereleases: true
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        pip install pytest pytest-cov pytest-asyncio httpx
+
+    - name: Run tests with coverage
+      run: |
+        pytest -v --cov=fastuator --cov-report=xml --cov-report=term
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      if: matrix.python-version == '3.12'
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false

fastuator-0.0.1/.gitignore

@@ -0,0 +1,56 @@
+# IDE
+.idea
+.vscode
+.mypy_cache
+
+# Python
+__pycache__
+*.py[cod]
+*.so
+*.egg
+*.egg-info/
+.Python
+.pytest_cache
+.coverage*
+coverage.xml
+htmlcov
+
+# Virtual environments
+venv/
+env/
+env3.*
+.venv/
+
+# Build
+dist/
+build/
+site/
+docs_build/
+site_build/
+
+# Testing
+.cache
+test.db
+log.txt
+
+# Jupyter
+.ipynb_checkpoints
+
+# Package files
+Pipfile.lock
+docs.zip
+archive.zip
+
+# vim
+*~
+.*.sw?
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+
+# Misc
+.netlify
+.codspeed

fastuator-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noh Hyeon Nam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastuator-0.0.1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: fastuator
+Version: 0.0.1
+Summary: Production-ready actuator endpoints for FastAPI (health, metrics, info)
+Project-URL: Homepage, https://github.com/fastuator/fastuator
+Project-URL: Repository, https://github.com/fastuator/fastuator
+Author-email: Noh Hyeon Nam <shgusska12@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: prometheus-client>=0.20.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: httpx>=0.25.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Fastuator
+
+[![CI](https://github.com/fastuator/fastuator/actions/workflows/test.yml/badge.svg)](https://github.com/fastuator/fastuator/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/fastuator/fastuator)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Production-ready monitoring toolkit for FastAPI applications.  
+Kubernetes probes, Prometheus metrics, and health checks in one line.
+
+## ✨ Features
+
+- 🏥 **Health Checks**: Aggregated health status with customizable checks
+- 🔍 **K8s Probes**: Built-in liveness and readiness endpoints
+- 📊 **Prometheus Metrics**: Auto-instrumented HTTP metrics
+- ℹ️ **System Info**: Build version and platform details
+- 🎯 **Zero Config**: Works out of the box with sensible defaults
+- ⚡ **100% Test Coverage**: Battle-tested and production-ready
+
+## 📦 Installation
+
+```bash
+pip install fastuator
+```
+
+## 🚀 Quick Start
+
+```python
+from fastapi import FastAPI
+from fastuator import Fastuator
+
+app = FastAPI()
+Fastuator(app)  # That's it!
+```
+
+**Available Endpoints:**
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /fastuator/health` | Aggregated health status with optional details |
+| `GET /fastuator/liveness` | Kubernetes liveness probe (critical checks only) |
+| `GET /fastuator/readiness` | Kubernetes readiness probe (all dependencies) |
+| `GET /fastuator/metrics` | Prometheus-compatible metrics |
+| `GET /fastuator/info` | Application and system information |
+
+## 📖 Usage
+
+### Basic Setup
+
+```python
+from fastapi import FastAPI
+from fastuator import Fastuator
+
+app = FastAPI()
+
+# Use default configuration
+Fastuator(app)
+
+# Custom prefix
+Fastuator(app, prefix="/monitoring")
+```
+
+### Custom Health Checks
+
+```python
+from fastuator import Fastuator
+
+app = FastAPI()
+
+# Define custom health checks
+async def database_health():
+    try:
+        # Check database connection
+        await db.execute("SELECT 1")
+        return {"status": "UP", "database": "connected"}
+    except Exception as e:
+        return {"status": "DOWN", "database": str(e)}
+
+async def redis_health():
+    try:
+        await redis.ping()
+        return {"status": "UP", "redis": "connected"}
+    except Exception:
+        return {"status": "DOWN", "redis": "unreachable"}
+
+# Register custom checks
+Fastuator(
+    app,
+    health_checks=[database_health, redis_health],
+    readiness_checks=[database_health, redis_health],
+    liveness_checks=[],  # No external dependencies for liveness
+)
+```
+
+### Health Check Response
+
+**Without details:**
+```bash
+curl http://localhost:8000/fastuator/health
+```
+```json
+{"status": "UP"}
+```
+
+**With details:**
+```bash
+curl http://localhost:8000/fastuator/health?show_details=true
+```
+```json
+{
+  "status": "UP",
+  "components": {
+    "check_0": {
+      "status": "UP",
+      "cpu_percent": 45.2
+    },
+    "check_1": {
+      "status": "UP",
+      "memory_percent": 62.1,
+      "memory_available_mb": 4096
+    }
+  }
+}
+```
+
+## ☸️ Kubernetes Integration
+
+### Deployment Example
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: fastapi-app
+spec:
+  template:
+    spec:
+      containers:
+      - name: app
+        image: myapp:latest
+        ports:
+        - containerPort: 8000
+        livenessProbe:
+          httpGet:
+            path: /fastuator/liveness
+            port: 8000
+          initialDelaySeconds: 10
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /fastuator/readiness
+            port: 8000
+          initialDelaySeconds: 5
+          periodSeconds: 5
+```
+
+## 📊 Prometheus Metrics
+
+Fastuator automatically collects the following metrics:
+
+- `http_requests_total`: Total HTTP requests (counter)
+- `http_request_duration_seconds`: Request duration histogram
+- `app_health_status`: Health status gauge (1=UP, 0=DOWN)
+
+**Scrape configuration:**
+```yaml
+scrape_configs:
+  - job_name: 'fastapi'
+    static_configs:
+      - targets: ['localhost:8000']
+    metrics_path: '/fastuator/metrics'
+```
+
+## ⚙️ Configuration
+
+```python
+Fastuator(
+    app,
+    prefix="/fastuator",              # URL prefix for all endpoints
+    health_checks=[...],               # List of health check functions
+    liveness_checks=[...],             # Checks for liveness probe
+    readiness_checks=[...],            # Checks for readiness probe
+    enable_metrics=True,               # Enable Prometheus metrics
+)
+```
+
+## 🧪 Built-in Health Checks
+
+Fastuator includes these health checks by default:
+
+- **CPU Usage**: Reports DOWN if CPU > 90%
+- **Memory Usage**: Reports DOWN if memory > 90%
+- **Disk Usage**: Reports DOWN if disk > 90%
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests (`pytest --cov=fastuator`)
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+Inspired by [Spring Boot Actuator](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html).
+
+## 📚 Related Projects
+
+- [FastAPI](https://fastapi.tiangolo.com/) - Modern web framework for Python
+- [Prometheus](https://prometheus.io/) - Monitoring and alerting toolkit
+- [Kubernetes](https://kubernetes.io/) - Container orchestration platform

fastuator-0.0.1/README.md

@@ -0,0 +1,218 @@
+# Fastuator
+
+[![CI](https://github.com/fastuator/fastuator/actions/workflows/test.yml/badge.svg)](https://github.com/fastuator/fastuator/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/fastuator/fastuator)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Production-ready monitoring toolkit for FastAPI applications.  
+Kubernetes probes, Prometheus metrics, and health checks in one line.
+
+## ✨ Features
+
+- 🏥 **Health Checks**: Aggregated health status with customizable checks
+- 🔍 **K8s Probes**: Built-in liveness and readiness endpoints
+- 📊 **Prometheus Metrics**: Auto-instrumented HTTP metrics
+- ℹ️ **System Info**: Build version and platform details
+- 🎯 **Zero Config**: Works out of the box with sensible defaults
+- ⚡ **100% Test Coverage**: Battle-tested and production-ready
+
+## 📦 Installation
+
+```bash
+pip install fastuator
+```
+
+## 🚀 Quick Start
+
+```python
+from fastapi import FastAPI
+from fastuator import Fastuator
+
+app = FastAPI()
+Fastuator(app)  # That's it!
+```
+
+**Available Endpoints:**
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /fastuator/health` | Aggregated health status with optional details |
+| `GET /fastuator/liveness` | Kubernetes liveness probe (critical checks only) |
+| `GET /fastuator/readiness` | Kubernetes readiness probe (all dependencies) |
+| `GET /fastuator/metrics` | Prometheus-compatible metrics |
+| `GET /fastuator/info` | Application and system information |
+
+## 📖 Usage
+
+### Basic Setup
+
+```python
+from fastapi import FastAPI
+from fastuator import Fastuator
+
+app = FastAPI()
+
+# Use default configuration
+Fastuator(app)
+
+# Custom prefix
+Fastuator(app, prefix="/monitoring")
+```
+
+### Custom Health Checks
+
+```python
+from fastuator import Fastuator
+
+app = FastAPI()
+
+# Define custom health checks
+async def database_health():
+    try:
+        # Check database connection
+        await db.execute("SELECT 1")
+        return {"status": "UP", "database": "connected"}
+    except Exception as e:
+        return {"status": "DOWN", "database": str(e)}
+
+async def redis_health():
+    try:
+        await redis.ping()
+        return {"status": "UP", "redis": "connected"}
+    except Exception:
+        return {"status": "DOWN", "redis": "unreachable"}
+
+# Register custom checks
+Fastuator(
+    app,
+    health_checks=[database_health, redis_health],
+    readiness_checks=[database_health, redis_health],
+    liveness_checks=[],  # No external dependencies for liveness
+)
+```
+
+### Health Check Response
+
+**Without details:**
+```bash
+curl http://localhost:8000/fastuator/health
+```
+```json
+{"status": "UP"}
+```
+
+**With details:**
+```bash
+curl http://localhost:8000/fastuator/health?show_details=true
+```
+```json
+{
+  "status": "UP",
+  "components": {
+    "check_0": {
+      "status": "UP",
+      "cpu_percent": 45.2
+    },
+    "check_1": {
+      "status": "UP",
+      "memory_percent": 62.1,
+      "memory_available_mb": 4096
+    }
+  }
+}
+```
+
+## ☸️ Kubernetes Integration
+
+### Deployment Example
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: fastapi-app
+spec:
+  template:
+    spec:
+      containers:
+      - name: app
+        image: myapp:latest
+        ports:
+        - containerPort: 8000
+        livenessProbe:
+          httpGet:
+            path: /fastuator/liveness
+            port: 8000
+          initialDelaySeconds: 10
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /fastuator/readiness
+            port: 8000
+          initialDelaySeconds: 5
+          periodSeconds: 5
+```
+
+## 📊 Prometheus Metrics
+
+Fastuator automatically collects the following metrics:
+
+- `http_requests_total`: Total HTTP requests (counter)
+- `http_request_duration_seconds`: Request duration histogram
+- `app_health_status`: Health status gauge (1=UP, 0=DOWN)
+
+**Scrape configuration:**
+```yaml
+scrape_configs:
+  - job_name: 'fastapi'
+    static_configs:
+      - targets: ['localhost:8000']
+    metrics_path: '/fastuator/metrics'
+```
+
+## ⚙️ Configuration
+
+```python
+Fastuator(
+    app,
+    prefix="/fastuator",              # URL prefix for all endpoints
+    health_checks=[...],               # List of health check functions
+    liveness_checks=[...],             # Checks for liveness probe
+    readiness_checks=[...],            # Checks for readiness probe
+    enable_metrics=True,               # Enable Prometheus metrics
+)
+```
+
+## 🧪 Built-in Health Checks
+
+Fastuator includes these health checks by default:
+
+- **CPU Usage**: Reports DOWN if CPU > 90%
+- **Memory Usage**: Reports DOWN if memory > 90%
+- **Disk Usage**: Reports DOWN if disk > 90%
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests (`pytest --cov=fastuator`)
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+Inspired by [Spring Boot Actuator](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html).
+
+## 📚 Related Projects
+
+- [FastAPI](https://fastapi.tiangolo.com/) - Modern web framework for Python
+- [Prometheus](https://prometheus.io/) - Monitoring and alerting toolkit
+- [Kubernetes](https://kubernetes.io/) - Container orchestration platform

fastuator-0.0.1/examples/basic_app.py

@@ -0,0 +1,9 @@
+from fastapi import FastAPI
+from fastuator import Fastuator
+
+app = FastAPI()
+Fastuator(app)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

fastuator-0.0.1/fastuator/__init__.py

@@ -0,0 +1,11 @@
+"""
+fastuator - Production-ready monitoring for FastAPI
+K8s probes, Prometheus metrics, health checks in 1 line.
+"""
+
+__version__ = "0.0.1"
+
+from .core import Fastuator
+from .checks import cpu_health, disk_health, memory_health
+
+__all__ = ["Fastuator", "cpu_health", "disk_health", "memory_health"]

fastuator-0.0.1/fastuator/checks.py

@@ -0,0 +1,36 @@
+"""Default health check implementations."""
+
+from typing import Any
+import psutil
+
+
+async def cpu_health() -> dict[str, Any]:
+    """Check CPU usage."""
+    cpu_percent = psutil.cpu_percent(interval=0.1)
+    status = "UP" if cpu_percent < 90 else "DOWN"
+    return {
+        "status": status,
+        "cpu_percent": cpu_percent,
+    }
+
+
+async def memory_health() -> dict[str, Any]:
+    """Check memory usage."""
+    memory = psutil.virtual_memory()
+    status = "UP" if memory.percent < 90 else "DOWN"
+    return {
+        "status": status,
+        "memory_percent": memory.percent,
+        "memory_available_mb": memory.available // (1024 * 1024),
+    }
+
+
+async def disk_health() -> dict[str, Any]:
+    """Check disk usage."""
+    disk = psutil.disk_usage("/")
+    status = "UP" if disk.percent < 90 else "DOWN"
+    return {
+        "status": status,
+        "disk_percent": disk.percent,
+        "disk_free_gb": disk.free // (1024 ** 3),
+    }

fastuator-0.0.1/fastuator/core.py

@@ -0,0 +1,266 @@
+"""
+Core implementation of Fastuator monitoring toolkit.
+
+This module provides the main Fastuator class that automatically registers
+health check, metrics, and info endpoints for FastAPI applications.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+import asyncio
+import time
+
+from fastapi import APIRouter, FastAPI, HTTPException, Request
+from prometheus_client import Counter, Gauge, Histogram, make_asgi_app
+import psutil
+
+# Prometheus metrics collectors
+REQUEST_COUNT = Counter(
+    "http_requests_total",
+    "Total HTTP requests",
+    ["method", "endpoint", "status"],
+)
+REQUEST_DURATION = Histogram(
+    "http_request_duration_seconds",
+    "HTTP request duration in seconds",
+)
+HEALTH_STATUS = Gauge(
+    "app_health_status",
+    "Application health status (1=UP, 0=DOWN)",
+)
+
+
+class Fastuator:
+    """
+    Production-ready monitoring toolkit for FastAPI applications.
+
+    Fastuator automatically registers the following endpoints:
+    - /fastuator/health: Aggregated health check with optional details
+    - /fastuator/liveness: Kubernetes liveness probe
+    - /fastuator/readiness: Kubernetes readiness probe
+    - /fastuator/info: Build and system information
+    - /fastuator/metrics: Prometheus metrics (optional)
+
+    The health check aggregation follows the Spring Boot Actuator pattern:
+    if any component is DOWN, the overall status is DOWN.
+
+    Example:
+        >>> from fastapi import FastAPI
+        >>> from fastuator import Fastuator
+        >>>
+        >>> app = FastAPI()
+        >>> Fastuator(app)  # Registers all fastuator endpoints
+        >>>
+        >>> # With custom health checks
+        >>> async def redis_health():
+        ...     return {"status": "UP", "redis": "connected"}
+        >>>
+        >>> Fastuator(app, health_checks=[redis_health])
+
+    Args:
+        app: FastAPI application instance
+        prefix: URL prefix for fastuator endpoints (default: "/fastuator")
+        health_checks: Custom health check functions (async callables)
+        liveness_checks: Health checks for K8s liveness probe (default: CPU only)
+        readiness_checks: Health checks for K8s readiness probe (default: all checks)
+        enable_metrics: Enable Prometheus metrics collection (default: True)
+    """
+
+    def __init__(
+        self,
+        app: FastAPI,
+        prefix: str = "/fastuator",
+        health_checks: list[Callable[[], Awaitable[dict[str, Any]]]] | None = None,
+        liveness_checks: list[Callable[[], Awaitable[dict[str, Any]]]] | None = None,
+        readiness_checks: list[Callable[[], Awaitable[dict[str, Any]]]] | None = None,
+        enable_metrics: bool = True,
+    ) -> None:
+        self.app = app
+        self.prefix = prefix
+        self.router = APIRouter(prefix=prefix, tags=["fastuator"])
+
+        # Import default health checks
+        from .checks import cpu_health, disk_health, memory_health
+
+        # Configure health check functions
+        self.health_checks = health_checks or [cpu_health, disk_health, memory_health]
+        self.liveness_checks = liveness_checks or [cpu_health]
+        self.readiness_checks = readiness_checks or self.health_checks
+
+        # Setup endpoints
+        self._register_health_endpoints()
+
+        # Setup Prometheus metrics if enabled
+        if enable_metrics:
+            self._register_metrics_endpoint(app, prefix)
+            self._register_metrics_middleware(app)
+
+        # Register router with FastAPI app
+        app.include_router(self.router)
+
+    def _register_health_endpoints(self) -> None:
+        """Register health check, liveness, readiness, and info endpoints."""
+
+        @self.router.get("/health")
+        async def health(show_details: bool = False) -> dict[str, Any]:
+            """
+            Aggregate health check endpoint.
+
+            Returns overall status based on all registered health checks.
+            If any check returns DOWN, the overall status is DOWN.
+
+            Query Parameters:
+                show_details: Include detailed component status (default: False)
+
+            Returns:
+                {"status": "UP"} or {"status": "DOWN", "components": {...}}
+            """
+            checks = await asyncio.gather(
+                *[check() for check in self.health_checks],
+                return_exceptions=True,
+            )
+
+            # Handle exceptions in health checks
+            processed_checks = []
+            for i, check_result in enumerate(checks):
+                if isinstance(check_result, Exception):
+                    processed_checks.append(
+                        {
+                            "status": "DOWN",
+                            "error": str(check_result),
+                        }
+                    )
+                else:
+                    processed_checks.append(check_result)
+
+            # Aggregate status: DOWN if any component is DOWN
+            statuses = [c.get("status", "DOWN") for c in processed_checks]
+            overall_status = "DOWN" if "DOWN" in statuses else "UP"
+
+            # Update Prometheus gauge
+            HEALTH_STATUS.set(1 if overall_status == "UP" else 0)
+
+            result = {"status": overall_status}
+            if show_details:
+                result["components"] = {
+                    f"check_{i}": check for i, check in enumerate(processed_checks)
+                }
+
+            return result
+
+        @self.router.get("/liveness")
+        async def liveness() -> dict[str, str]:
+            """
+            Kubernetes liveness probe endpoint.
+
+            Checks only critical system components (e.g., CPU).
+            Returns 503 if any liveness check fails.
+
+            This follows the isolation pattern: external dependencies
+            (DB, Redis) should not affect liveness to prevent cascading failures.
+
+            Returns:
+                {"status": "UP"} or raises HTTPException(503)
+            """
+            checks = await asyncio.gather(
+                *[check() for check in self.liveness_checks],
+                return_exceptions=True,
+            )
+
+            for check_result in checks:
+                if isinstance(check_result, Exception) or check_result.get("status") != "UP":
+                    raise HTTPException(
+                        status_code=503,
+                        detail="Liveness check failed",
+                    )
+
+            return {"status": "UP"}
+
+        @self.router.get("/readiness")
+        async def readiness() -> dict[str, str]:
+            """
+            Kubernetes readiness probe endpoint.
+
+            Checks all dependencies including external services.
+            Returns 503 if any readiness check fails.
+
+            Returns:
+                {"status": "UP"} or raises HTTPException(503)
+            """
+            checks = await asyncio.gather(
+                *[check() for check in self.readiness_checks],
+                return_exceptions=True,
+            )
+
+            for check_result in checks:
+                if isinstance(check_result, Exception) or check_result.get("status") != "UP":
+                    raise HTTPException(
+                        status_code=503,
+                        detail="Readiness check failed",
+                    )
+
+            return {"status": "UP"}
+
+        @self.router.get("/info")
+        async def info() -> dict[str, Any]:
+            """
+            Application and system information endpoint.
+
+            Returns build version, Python version, and platform details.
+
+            Returns:
+                Dictionary with build and system information
+            """
+            import platform
+
+            return {
+                "build": {
+                    "version": "0.0.1",
+                    "python": platform.python_version(),
+                },
+                "system": {
+                    "platform": platform.platform(),
+                    "python_implementation": platform.python_implementation(),
+                },
+            }
+
+    def _register_metrics_endpoint(self, app: FastAPI, prefix: str) -> None:
+        """
+        Mount Prometheus metrics endpoint.
+
+        Args:
+            app: FastAPI application instance
+            prefix: Fastuator URL prefix
+        """
+        metrics_app = make_asgi_app()
+        app.mount(f"{prefix}/metrics", metrics_app)
+
+    def _register_metrics_middleware(self, app: FastAPI) -> None:
+        """
+        Register middleware for automatic metrics collection.
+
+        Collects HTTP request count and duration for all endpoints.
+
+        Args:
+            app: FastAPI application instance
+        """
+
+        @app.middleware("http")
+        async def metrics_middleware(request: Request, call_next):
+            """Collect HTTP request metrics."""
+            start_time = time.time()
+
+            # Process request
+            response = await call_next(request)
+
+            # Record metrics
+            duration = time.time() - start_time
+            REQUEST_COUNT.labels(
+                method=request.method,
+                endpoint=request.url.path,
+                status=response.status_code,
+            ).inc()
+            REQUEST_DURATION.observe(duration)
+
+            return response

fastuator-0.0.1/main.py

@@ -0,0 +1,16 @@
+# This is a sample Python script.
+
+# Press Shift+F10 to execute it or replace it with your code.
+# Press Double Shift to search everywhere for classes, files, tool windows, actions, and settings.
+
+
+def print_hi(name):
+    # Use a breakpoint in the code line below to debug your script.
+    print(f'Hi, {name}')  # Press Ctrl+F8 to toggle the breakpoint.
+
+
+# Press the green button in the gutter to run the script.
+if __name__ == '__main__':
+    print_hi('PyCharm')
+
+# See PyCharm help at https://www.jetbrains.com/help/pycharm/

fastuator-0.0.1/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastuator"
+version = "0.0.1"
+description = "Production-ready actuator endpoints for FastAPI (health, metrics, info)"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "Noh Hyeon Nam", email = "shgusska12@gmail.com"}]
+
+dependencies = [
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "psutil>=5.9.0",
+    "prometheus-client>=0.20.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.1.0",
+    "httpx>=0.25.0",
+    "uvicorn[standard]>=0.32.0",
+    "black>=24.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/fastuator/fastuator"
+Repository = "https://github.com/fastuator/fastuator"
+
+[tool.hatch.build.targets.wheel]
+packages = ["fastuator"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.venv",
+    "/.git",
+    "/__pycache__",
+    "*.pyc",
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = []

fastuator-0.0.1/pytest.ini

@@ -0,0 +1,13 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+addopts =
+    -v
+    --strict-markers
+    --tb=short
+    --cov=fastuator
+    --cov-report=term-missing
+    --cov-report=html
+asyncio_mode = auto

fastuator-0.0.1/tests/conftest.py

@@ -0,0 +1,91 @@
+"""Test configuration and fixtures."""
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from fastuator import Fastuator
+
+
+@pytest.fixture
+def client():
+    """Create a test client with default health checks.
+
+    Uses real CPU/memory/disk checks - may fail if system resources are high.
+    """
+    app = FastAPI()
+    Fastuator(app)
+    return TestClient(app)
+
+
+@pytest.fixture
+def success_client():
+    """Create a test client with always-passing checks.
+
+    Guarantees 200 OK responses for testing happy paths.
+    """
+    app = FastAPI()
+
+    async def passing_check():
+        return {"status": "UP"}
+
+    Fastuator(
+        app,
+        health_checks=[passing_check],
+        readiness_checks=[passing_check],
+        liveness_checks=[passing_check],
+    )
+
+    return TestClient(app)
+
+
+@pytest.fixture
+def failing_client():
+    """Create a test client with always-failing checks.
+
+    Returns DOWN status without exceptions.
+    """
+    app = FastAPI()
+
+    async def failing_check():
+        return {"status": "DOWN", "reason": "Test failure"}
+
+    Fastuator(
+        app,
+        health_checks=[failing_check],
+        readiness_checks=[failing_check],
+        liveness_checks=[failing_check],
+    )
+
+    return TestClient(app)
+
+
+@pytest.fixture
+def exception_client():
+    """Create a test client with exception-raising health checks.
+
+    Tests exception handling in health endpoint (line 128 in core.py).
+    """
+    app = FastAPI()
+
+    async def exception_check():
+        raise RuntimeError("Database connection failed")
+
+    Fastuator(app, health_checks=[exception_check])
+
+    return TestClient(app)
+
+
+@pytest.fixture
+def exception_readiness_client():
+    """Create a test client with exception-raising readiness checks.
+
+    Tests exception handling in readiness endpoint (line 207 in core.py).
+    """
+    app = FastAPI()
+
+    async def exception_check():
+        raise RuntimeError("Service unavailable")
+
+    Fastuator(app, readiness_checks=[exception_check])
+
+    return TestClient(app)

fastuator-0.0.1/tests/test_endpoints.py

@@ -0,0 +1,119 @@
+"""Test basic Fastuator endpoints."""
+
+from fastapi.testclient import TestClient
+
+
+def test_health_endpoint(client: TestClient):
+    """Test health check endpoint returns UP status."""
+    response = client.get("/fastuator/health")
+    assert response.status_code == 200
+
+    data = response.json()
+    assert data["status"] in ["UP", "DOWN"]
+
+
+def test_liveness_endpoint(success_client: TestClient):
+    """Test liveness probe endpoint."""
+    response = success_client.get("/fastuator/liveness")
+    assert response.status_code == 200
+    assert response.json()["status"] == "UP"
+
+
+def test_readiness_endpoint_flexible(client: TestClient):
+    """Test readiness with real health checks (may vary)."""
+    response = client.get("/fastuator/readiness")
+    assert response.status_code in [200, 503]
+
+    if response.status_code == 200:
+        assert response.json() == {"status": "UP"}
+    else:
+        assert "detail" in response.json()
+
+
+def test_readiness_success(success_client: TestClient):
+    """Test readiness returns UP when all checks pass."""
+    response = success_client.get("/fastuator/readiness")
+    assert response.status_code == 200
+    assert response.json() == {"status": "UP"}
+
+
+def test_info_endpoint(client: TestClient):
+    """Test system info endpoint."""
+    response = client.get("/fastuator/info")
+    assert response.status_code == 200
+
+    data = response.json()
+
+    assert "build" in data
+    assert "system" in data
+    assert "version" in data["build"]
+    assert "python" in data["build"]
+    assert "platform" in data["system"]
+
+
+def test_metrics_endpoint(client: TestClient):
+    """Test Prometheus metrics endpoint."""
+    response = client.get("/fastuator/metrics")
+    assert response.status_code == 200
+
+    assert "text/plain" in response.headers["content-type"]
+
+    content = response.text
+    assert len(content) > 0
+
+
+def test_health_with_details(client: TestClient):
+    """Test health endpoint with show_details parameter."""
+    response = client.get("/fastuator/health?show_details=true")
+    assert response.status_code in [200, 503]
+
+    data = response.json()
+    assert "status" in data
+    assert "components" in data
+    assert isinstance(data["components"], dict)
+
+
+def test_health_with_exception(exception_client: TestClient):
+    """Test health endpoint handles exceptions from checks."""
+    response = exception_client.get("/fastuator/health")
+    assert response.status_code == 200
+
+    data = response.json()
+    assert data["status"] == "DOWN"
+
+
+def test_health_with_exception_details(exception_client: TestClient):
+    """Test health endpoint captures exception in components when show_details=true."""
+    response = exception_client.get("/fastuator/health?show_details=true")
+
+    data = response.json()
+    assert "components" in data
+    components = data["components"]
+    assert any("error" in comp for comp in components.values())
+
+
+def test_failing_liveness(failing_client: TestClient):
+    """Test liveness with failing check returns 503."""
+    response = failing_client.get("/fastuator/liveness")
+    assert response.status_code == 503
+
+    data = response.json()
+    assert "detail" in data
+
+
+def test_failing_readiness(failing_client: TestClient):
+    """Test readiness with failing check returns 503."""
+    response = failing_client.get("/fastuator/readiness")
+    assert response.status_code == 503
+
+    data = response.json()
+    assert "detail" in data
+
+
+def test_readiness_with_exception(exception_readiness_client: TestClient):
+    """Test readiness with exception returns 503."""
+    response = exception_readiness_client.get("/fastuator/readiness")
+    assert response.status_code == 503
+
+    data = response.json()
+    assert "detail" in data

fastuator-0.0.1/tests/test_health_checks.py

@@ -0,0 +1,79 @@
+"""Test health check implementations."""
+
+import pytest
+from fastuator.checks import cpu_health, memory_health, disk_health
+
+
+@pytest.mark.asyncio
+async def test_cpu_health():
+    """Test CPU health check returns correct format."""
+    result = await cpu_health()
+
+    assert "status" in result
+    assert result["status"] in ["UP", "DOWN"]
+    assert "cpu_percent" in result
+    assert isinstance(result["cpu_percent"], (int, float))
+    assert 0 <= result["cpu_percent"] <= 100
+
+
+@pytest.mark.asyncio
+async def test_memory_health():
+    """Test memory health check returns correct format."""
+    result = await memory_health()
+
+    assert "status" in result
+    assert result["status"] in ["UP", "DOWN"]
+    assert "memory_percent" in result
+    assert "memory_available_mb" in result
+    assert isinstance(result["memory_percent"], (int, float))
+    assert isinstance(result["memory_available_mb"], int)
+    assert 0 <= result["memory_percent"] <= 100
+    assert result["memory_available_mb"] >= 0
+
+
+@pytest.mark.asyncio
+async def test_disk_health():
+    """Test disk health check returns correct format."""
+    result = await disk_health()
+
+    assert "status" in result
+    assert result["status"] in ["UP", "DOWN"]
+    assert "disk_percent" in result
+    assert "disk_free_gb" in result
+    assert isinstance(result["disk_percent"], (int, float))
+    assert isinstance(result["disk_free_gb"], int)
+    assert 0 <= result["disk_percent"] <= 100
+    assert result["disk_free_gb"] >= 0
+
+
+@pytest.mark.asyncio
+async def test_cpu_health_status_logic():
+    """Test CPU health returns DOWN when usage is high."""
+    result = await cpu_health()
+
+    if result["cpu_percent"] < 90:
+        assert result["status"] == "UP"
+    else:
+        assert result["status"] == "DOWN"
+
+
+@pytest.mark.asyncio
+async def test_memory_health_status_logic():
+    """Test memory health returns DOWN when usage is high."""
+    result = await memory_health()
+
+    if result["memory_percent"] < 90:
+        assert result["status"] == "UP"
+    else:
+        assert result["status"] == "DOWN"
+
+
+@pytest.mark.asyncio
+async def test_disk_health_status_logic():
+    """Test disk health returns DOWN when usage is high."""
+    result = await disk_health()
+
+    if result["disk_percent"] < 90:
+        assert result["status"] == "UP"
+    else:
+        assert result["status"] == "DOWN"