celery-fastapi 0.1.3__tar.gz → 0.1.5__tar.gz

{celery_fastapi-0.1.3 → celery_fastapi-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celery-fastapi
-Version: 0.1.3
+Version: 0.1.5
 Summary: Automatic REST API generation for Celery tasks with FastAPI
 License: MIT
 License-File: LICENSE
@@ -35,7 +35,7 @@ Provides-Extra: server
 Provides-Extra: standard
 Provides-Extra: ujson
 Provides-Extra: uvicorn
-Requires-Dist: celery (>=5.3.0)
+Requires-Dist: celery (>=5.3.0,<=5.6.3)
 Requires-Dist: eventlet (>=0.33.0) ; extra == "eventlet"
 Requires-Dist: fastapi (>=0.100.0)
 Requires-Dist: gevent (>=23.0.0) ; extra == "gevent"
@@ -60,8 +60,12 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/karailker/celery-fastapi/actions/workflows/ci.yml/badge.svg)](https://github.com/karailker/celery-fastapi/actions/workflows/ci.yml)
 [![PyPI version](https://badge.fury.io/py/celery-fastapi.svg)](https://badge.fury.io/py/celery-fastapi)
 [![Python Version](https://img.shields.io/pypi/pyversions/celery-fastapi.svg)](https://pypi.org/project/celery-fastapi/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/celery-fastapi?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/celery-fastapi)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+![GitHub Repo stars](https://img.shields.io/github/stars/karailker/celery-fastapi)
+<!-- ![GitHub forks](https://img.shields.io/github/forks/karailker/celery-fastapi) -->
+
 Automatic REST API generation for Celery tasks with FastAPI. This package seamlessly bridges Celery and FastAPI, automatically creating REST endpoints for all your registered Celery tasks.
 
 ## Features
@@ -77,6 +81,9 @@ Automatic REST API generation for Celery tasks with FastAPI. This package seamle
 - 🔒 **Production ready** - Full uvicorn/gunicorn support with SSL, workers, and all options
 - ⚡ **Full Celery options** - All task options (countdown, eta, priority, etc.)
 - 🔌 **Pool support** - Compatible with eventlet, gevent, prefork, and solo pools
+- 🧮 **Batch execution** - Submit groups of tasks in a single request via `/tasks/batch`
+- 🛡️ **Input validation** - Pydantic-driven validation on task_name/queue at trust boundary
+- 🔌 **WebSocket streaming** - Live task status updates via `/tasks/{task_id}/ws`
 
 ## Requirements
 
@@ -160,25 +167,29 @@ uvicorn myapp:app --reload
 
 ```bash
 # Start the server (development)
-celery-fastapi serve myapp.celery:celery_app --port 8000 --reload
+celery-fastapi serve examples.celery_app:celery_app --port 8000 --reload
 
 # Production with multiple workers
-celery-fastapi serve myapp.celery:celery_app -w 4 --host 0.0.0.0
+celery-fastapi serve examples.celery_app:celery_app -w 4 --host 0.0.0.0
+
+# With custom worker hostname (for health checks)
+export CELERY_WORKER_HOSTNAME="celery@worker1"
+celery-fastapi serve examples.celery_app:celery_app --port 8000
 
 # With SSL
-celery-fastapi serve myapp.celery:celery_app --ssl-keyfile key.pem --ssl-certfile cert.pem
+celery-fastapi serve examples.celery_app:celery_app --ssl-keyfile key.pem --ssl-certfile cert.pem
 
 # Using gunicorn (production)
-celery-fastapi serve-gunicorn myapp.celery:celery_app -w 4 -k uvicorn.workers.UvicornWorker
+celery-fastapi serve-gunicorn examples.celery_app:celery_app -w 4 -k uvicorn.workers.UvicornWorker
 
 # List available routes
-celery-fastapi routes myapp.celery:celery_app
+celery-fastapi routes examples.celery_app:celery_app
 
 # List registered tasks
-celery-fastapi tasks myapp.celery:celery_app
+celery-fastapi tasks examples.celery_app:celery_app
 
 # Show active workers
-celery-fastapi workers myapp.celery:celery_app
+celery-fastapi workers examples.celery_app:celery_app
 ```
 
 ## API Endpoints
@@ -272,6 +283,44 @@ GET /queues
 POST /purge
 ```
 
+### Health Check and Monitoring
+
+```bash
+# Health check for local Celery worker
+GET /healthz
+
+# Response
+{
+    "status": "healthy",
+    "celery_app": "example_tasks",
+    "broker_connected": true,
+    "worker_hostname": "celery@worker1",
+    "worker_online": true
+}
+
+# Ping local Celery worker
+GET /ping
+
+# Response
+{
+    "worker_hostname": "celery@worker1",
+    "online": true,
+    "response": {"ok": "pong"}
+}
+```
+
+**Note:** Health and ping endpoints automatically discover the local worker using:
+1. `CELERY_WORKER_HOSTNAME` environment variable (recommended for custom hostnames)
+2. Hostname matching (when worker and API share the same hostname)
+3. Single worker fallback (when only one worker has this app's tasks)
+
+**For custom worker hostnames**, set the environment variable:
+```bash
+export CELERY_WORKER_HOSTNAME="celery@worker1"
+celery -A examples.celery_app worker --hostname worker1
+celery-fastapi serve examples.celery_app:celery_app --port 8000
+```
+
 ### List All Tasks
 
 ```bash
@@ -351,7 +400,7 @@ Commands:
   workers          Show active Celery workers
 
 # Serve options (uvicorn)
-celery-fastapi serve myapp:celery_app \
+celery-fastapi serve examples.celery_app:celery_app \
     --host 0.0.0.0 \
     --port 8000 \
     --reload \
@@ -364,7 +413,7 @@ celery-fastapi serve myapp:celery_app \
     --forwarded-allow-ips '*'
 
 # Serve options (gunicorn)
-celery-fastapi serve-gunicorn myapp:celery_app \
+celery-fastapi serve-gunicorn examples.celery_app:celery_app \
     --bind 0.0.0.0:8000 \
     --workers 4 \
     --worker-class uvicorn.workers.UvicornWorker \

{celery_fastapi-0.1.3 → celery_fastapi-0.1.5}/README.md

@@ -3,8 +3,12 @@
 [![CI](https://github.com/karailker/celery-fastapi/actions/workflows/ci.yml/badge.svg)](https://github.com/karailker/celery-fastapi/actions/workflows/ci.yml)
 [![PyPI version](https://badge.fury.io/py/celery-fastapi.svg)](https://badge.fury.io/py/celery-fastapi)
 [![Python Version](https://img.shields.io/pypi/pyversions/celery-fastapi.svg)](https://pypi.org/project/celery-fastapi/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/celery-fastapi?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/celery-fastapi)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+![GitHub Repo stars](https://img.shields.io/github/stars/karailker/celery-fastapi)
+<!-- ![GitHub forks](https://img.shields.io/github/forks/karailker/celery-fastapi) -->
+
 Automatic REST API generation for Celery tasks with FastAPI. This package seamlessly bridges Celery and FastAPI, automatically creating REST endpoints for all your registered Celery tasks.
 
 ## Features
@@ -20,6 +24,9 @@ Automatic REST API generation for Celery tasks with FastAPI. This package seamle
 - 🔒 **Production ready** - Full uvicorn/gunicorn support with SSL, workers, and all options
 - ⚡ **Full Celery options** - All task options (countdown, eta, priority, etc.)
 - 🔌 **Pool support** - Compatible with eventlet, gevent, prefork, and solo pools
+- 🧮 **Batch execution** - Submit groups of tasks in a single request via `/tasks/batch`
+- 🛡️ **Input validation** - Pydantic-driven validation on task_name/queue at trust boundary
+- 🔌 **WebSocket streaming** - Live task status updates via `/tasks/{task_id}/ws`
 
 ## Requirements
 
@@ -103,25 +110,29 @@ uvicorn myapp:app --reload
 
 ```bash
 # Start the server (development)
-celery-fastapi serve myapp.celery:celery_app --port 8000 --reload
+celery-fastapi serve examples.celery_app:celery_app --port 8000 --reload
 
 # Production with multiple workers
-celery-fastapi serve myapp.celery:celery_app -w 4 --host 0.0.0.0
+celery-fastapi serve examples.celery_app:celery_app -w 4 --host 0.0.0.0
+
+# With custom worker hostname (for health checks)
+export CELERY_WORKER_HOSTNAME="celery@worker1"
+celery-fastapi serve examples.celery_app:celery_app --port 8000
 
 # With SSL
-celery-fastapi serve myapp.celery:celery_app --ssl-keyfile key.pem --ssl-certfile cert.pem
+celery-fastapi serve examples.celery_app:celery_app --ssl-keyfile key.pem --ssl-certfile cert.pem
 
 # Using gunicorn (production)
-celery-fastapi serve-gunicorn myapp.celery:celery_app -w 4 -k uvicorn.workers.UvicornWorker
+celery-fastapi serve-gunicorn examples.celery_app:celery_app -w 4 -k uvicorn.workers.UvicornWorker
 
 # List available routes
-celery-fastapi routes myapp.celery:celery_app
+celery-fastapi routes examples.celery_app:celery_app
 
 # List registered tasks
-celery-fastapi tasks myapp.celery:celery_app
+celery-fastapi tasks examples.celery_app:celery_app
 
 # Show active workers
-celery-fastapi workers myapp.celery:celery_app
+celery-fastapi workers examples.celery_app:celery_app
 ```
 
 ## API Endpoints
@@ -215,6 +226,44 @@ GET /queues
 POST /purge
 ```
 
+### Health Check and Monitoring
+
+```bash
+# Health check for local Celery worker
+GET /healthz
+
+# Response
+{
+    "status": "healthy",
+    "celery_app": "example_tasks",
+    "broker_connected": true,
+    "worker_hostname": "celery@worker1",
+    "worker_online": true
+}
+
+# Ping local Celery worker
+GET /ping
+
+# Response
+{
+    "worker_hostname": "celery@worker1",
+    "online": true,
+    "response": {"ok": "pong"}
+}
+```
+
+**Note:** Health and ping endpoints automatically discover the local worker using:
+1. `CELERY_WORKER_HOSTNAME` environment variable (recommended for custom hostnames)
+2. Hostname matching (when worker and API share the same hostname)
+3. Single worker fallback (when only one worker has this app's tasks)
+
+**For custom worker hostnames**, set the environment variable:
+```bash
+export CELERY_WORKER_HOSTNAME="celery@worker1"
+celery -A examples.celery_app worker --hostname worker1
+celery-fastapi serve examples.celery_app:celery_app --port 8000
+```
+
 ### List All Tasks
 
 ```bash
@@ -294,7 +343,7 @@ Commands:
   workers          Show active Celery workers
 
 # Serve options (uvicorn)
-celery-fastapi serve myapp:celery_app \
+celery-fastapi serve examples.celery_app:celery_app \
     --host 0.0.0.0 \
     --port 8000 \
     --reload \
@@ -307,7 +356,7 @@ celery-fastapi serve myapp:celery_app \
     --forwarded-allow-ips '*'
 
 # Serve options (gunicorn)
-celery-fastapi serve-gunicorn myapp:celery_app \
+celery-fastapi serve-gunicorn examples.celery_app:celery_app \
     --bind 0.0.0.0:8000 \
     --workers 4 \
     --worker-class uvicorn.workers.UvicornWorker \

{celery_fastapi-0.1.3 → celery_fastapi-0.1.5}/celery_fastapi/__init__.py

@@ -14,7 +14,7 @@ from celery_fastapi.core import (
     TaskStatusResponse,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.1.5"
 __all__ = [
     "CeleryFastAPIBridge",
     "create_app",

{celery_fastapi-0.1.3 → celery_fastapi-0.1.5}/celery_fastapi/app.py

@@ -85,6 +85,7 @@ def create_app(
     prefix: str = "",
     include_status_endpoints: bool = True,
     fastapi_kwargs: dict[str, Any] | None = None,
+    rate_limit: int | None = None,
 ) -> FastAPI:
     """
     Create a FastAPI application with Celery task endpoints.
@@ -143,6 +144,7 @@ def create_app(
         fastapi_app=fastapi_app,
         prefix=prefix,
         include_status_endpoints=include_status_endpoints,
+        rate_limit=rate_limit,
     )
 
     # Register all routes

{celery_fastapi-0.1.3 → celery_fastapi-0.1.5}/celery_fastapi/cli.py

@@ -799,7 +799,7 @@ def workers(
 
 @app.callback()
 def main(
-    version: Annotated[
+    version: Annotated[  # noqa: ARG001
         bool | None,
         typer.Option(
             "--version",
@@ -816,7 +816,6 @@ def main(
     Generate FastAPI endpoints for your Celery tasks automatically.
     Supports uvicorn and gunicorn for production deployment.
     """
-    pass
 
 
 if __name__ == "__main__":

{celery_fastapi-0.1.3 → celery_fastapi-0.1.5}/celery_fastapi/core.py

@@ -1,14 +1,24 @@
 """Core functionality for Celery FastAPI."""
 
+import asyncio
 import inspect
+import time
+from collections import defaultdict, deque
 from collections.abc import Callable
 from datetime import datetime
 from typing import Any, get_type_hints
 
 from celery import Celery
 from celery.result import AsyncResult
-from fastapi import FastAPI, HTTPException, Query
-from pydantic import BaseModel, Field, create_model
+from fastapi import (
+    FastAPI,
+    HTTPException,
+    Query,
+    Request,
+    WebSocket,
+    WebSocketDisconnect,
+)
+from pydantic import BaseModel, Field, ValidationInfo, create_model, field_validator
 
 # Celery execution options - shared fields for all task payloads
 CELERY_OPTIONS_FIELDS: dict[str, Any] = {
@@ -142,6 +152,20 @@ class GenericTaskPayload(BaseModel):
         }
     }
 
+    @field_validator("task_name", "queue")
+    @classmethod
+    def _validate_names(cls, value: str, info: ValidationInfo) -> str:
+        # Trust boundary: reject control chars / injection attempts.
+        if not value or not value.strip():
+            raise ValueError("must be a non-empty string")
+        if any(ord(c) < 0x20 for c in value):
+            raise ValueError("control characters are not allowed")
+        if not all(c.isalnum() or c in "._-" for c in value):
+            raise ValueError("only alphanumeric, '.', '_', '-' allowed")
+        if info.field_name == "task_name" and len(value) > 255:
+            raise ValueError("task_name exceeds 255 character limit")
+        return value
+
 
 def _python_type_to_json_type(py_type: type) -> str:
     """Convert Python type to JSON schema type string."""
@@ -271,6 +295,95 @@ class TaskRevokePayload(BaseModel):
     )
 
 
+class BatchTaskItem(BaseModel):
+    """A single task to execute as part of a batch."""
+
+    task_name: str = Field(description="Full task name (e.g., 'myapp.tasks.add')")
+    queue: str | None = Field(default=None, description="Queue override")
+    args: list[Any] = Field(
+        default_factory=list, description="Positional arguments for the task"
+    )
+    kwargs: dict[str, Any] = Field(
+        default_factory=dict, description="Keyword arguments for the task"
+    )
+    countdown: float | None = Field(default=None, description="Seconds to wait")
+
+
+class BatchTaskRequest(BaseModel):
+    """Payload for batch task execution."""
+
+    tasks: list[BatchTaskItem] = Field(
+        description="List of tasks to execute as a group"
+    )
+
+
+class BatchTaskResponse(BaseModel):
+    """Response model for batch task submission."""
+
+    group_id: str = Field(description="Group ID for the submitted batch")
+    task_ids: list[str] = Field(description="Individual task IDs in the group")
+    task_count: int = Field(description="Number of tasks submitted")
+    status: str = Field(default="PENDING", description="Group status")
+
+
+class HealthCheckResponse(BaseModel):
+    """Response model for health check endpoint."""
+
+    status: str = Field(description="Overall health status (healthy/unhealthy)")
+    celery_app: str = Field(description="Celery application name")
+    broker_connected: bool = Field(description="Whether broker connection is active")
+    worker_hostname: str | None = Field(
+        default=None, description="Target worker hostname"
+    )
+    worker_online: bool = Field(description="Whether the target worker is online")
+
+
+class PingResponse(BaseModel):
+    """Response model for worker ping endpoint."""
+
+    worker_hostname: str | None = Field(
+        default=None, description="Target worker hostname"
+    )
+    online: bool = Field(description="Whether the worker responded to ping")
+    response: dict[str, str] | None = Field(
+        default=None, description="Ping response from the worker"
+    )
+
+
+class RateLimiter:
+    """Simple in-memory sliding-window rate limiter.
+
+    Tracks request counts per client key (defaults to client IP) within a
+    fixed time window. When the limit is exceeded, `check` raises HTTP 429.
+
+    ponytail: in-memory, single-process. Replace with Redis-backed limiter
+    (e.g., ``limits`` package) when running multiple uvicorn workers.
+    """
+
+    def __init__(self, limit: int, window_seconds: int = 60) -> None:
+        self.limit = limit
+        self.window_seconds = window_seconds
+        self._hits: dict[str, deque[float]] = defaultdict(deque)
+
+    def check(self, key: str) -> None:
+        """Record a hit for ``key``; raise HTTPException(429) if over limit."""
+        now = time.monotonic()
+        window = self._hits[key]
+        cutoff = now - self.window_seconds
+
+        # Drop hits outside the window
+        while window and window[0] < cutoff:
+            window.popleft()
+
+        if len(window) >= self.limit:
+            raise HTTPException(
+                status_code=429,
+                detail=f"Rate limit exceeded: {self.limit} requests per {self.window_seconds}s",
+            )
+
+        window.append(now)
+
+
 class CeleryFastAPIBridge:
     """
     Bridge class that connects Celery tasks to FastAPI endpoints.
@@ -303,6 +416,7 @@ class CeleryFastAPIBridge:
         prefix: str = "",
         include_status_endpoints: bool = True,
         task_filter: Callable[[str], bool] | None = None,
+        rate_limit: int | None = None,
     ) -> None:
         """
         Initialize the Celery FastAPI Bridge.
@@ -315,12 +429,15 @@ class CeleryFastAPIBridge:
             include_status_endpoints: Whether to include task status and listing endpoints.
             task_filter: Optional callable to filter which tasks to expose.
                         Takes task name, returns True to include, False to exclude.
+            rate_limit: Optional maximum number of requests per minute per client.
+                        If set, requests exceeding the limit get HTTP 429.
         """
         self.celery_app = celery_app
         self.fastapi_app = fastapi_app or FastAPI()
         self.prefix = prefix.rstrip("/")
         self.include_status_endpoints = include_status_endpoints
         self.task_filter = task_filter or (lambda name: not name.startswith("celery."))
+        self.rate_limiter = RateLimiter(rate_limit) if rate_limit else None
         self._registered = False
 
         # Store the registered task names from THIS app only
@@ -380,6 +497,7 @@ class CeleryFastAPIBridge:
 
         # Create the endpoint handler
         async def run_task(
+            request: Request,
             payload: PayloadModel,  # type: ignore[valid-type]
             task_name_override: str | None = Query(
                 default=None,
@@ -393,6 +511,11 @@ class CeleryFastAPIBridge:
             ),
         ) -> TaskResponse:
             """Execute a Celery task asynchronously."""
+            # Rate limit check (per client IP)
+            if self.rate_limiter is not None:
+                client_ip = request.client.host if request.client else "unknown"
+                self.rate_limiter.check(client_ip)
+
             # Determine actual task name and queue
             actual_task_name = task_name_override or task_name
             actual_queue = (
@@ -557,6 +680,39 @@ class CeleryFastAPIBridge:
 
             return result.result
 
+        @self.fastapi_app.websocket(f"{self.prefix}/tasks/{{task_id}}/ws")
+        async def stream_task_status(websocket: WebSocket, task_id: str) -> None:
+            """
+            Stream task status updates via WebSocket.
+
+            Polls the task state every 0.5s and sends JSON frames until the
+            task reaches a terminal state (SUCCESS/FAILURE/REVOKED), then closes.
+
+            ponytail: polling-based. For high-throughput streams, replace with
+            Celery events (celery_app.events.Receiver) or Redis pub/sub.
+            """
+            await websocket.accept()
+            result = AsyncResult(task_id, app=self.celery_app)
+            try:
+                while True:
+                    state = result.state
+                    frame: dict[str, Any] = {
+                        "task_id": task_id,
+                        "state": state,
+                        "ready": result.ready(),
+                    }
+                    if result.ready():
+                        if result.failed():
+                            frame["error"] = str(result.traceback or "task failed")
+                        else:
+                            frame["result"] = result.result
+                        await websocket.send_json(frame)
+                        break
+                    await websocket.send_json(frame)
+                    await asyncio.sleep(0.5)
+            except WebSocketDisconnect:
+                pass
+
         @self.fastapi_app.get(
             f"{self.prefix}/tasks",
             response_model=TaskListResponse,
@@ -672,6 +828,208 @@ class CeleryFastAPIBridge:
             inspector = self.celery_app.control.inspect()
             return {"queues": inspector.active_queues() or {}}
 
+        def _find_local_worker() -> str | None:
+            """
+            Find the Celery worker running on the same host.
+
+            Celery worker hostnames follow the pattern: prefix@hostname
+            where prefix can be any format (e.g., celery, appname_uuid, etc.).
+
+            Matching strategy:
+            1. CELERY_WORKER_HOSTNAME environment variable (RECOMMENDED)
+               Set this to the exact worker name when starting both worker and API
+               Example: export CELERY_WORKER_HOSTNAME="celery@worker1"
+
+            2. Hostname matching (works when worker and API share same hostname):
+               - Exact match: worker hostname part equals socket.gethostname()
+               - Partial match: handles FQDN vs short hostname
+
+            3. Single worker fallback (only when one worker exists for this app)
+
+            Note: When using custom --hostname, always set CELERY_WORKER_HOSTNAME
+            to ensure correct worker discovery.
+
+            Examples:
+            - Standard: celery@myhost (auto-discovered)
+            - Custom: celery@worker1 (needs CELERY_WORKER_HOSTNAME="celery@worker1")
+            - UUID: myapp_abc123@myhost (auto-discovered if hostname matches)
+            """
+            import os
+            import socket
+
+            # Strategy 1: Check for explicit environment variable (RECOMMENDED)
+            env_worker = os.environ.get("CELERY_WORKER_HOSTNAME")
+            if env_worker:
+                try:
+                    inspector = self.celery_app.control.inspect(timeout=1.0)
+                    env_ping_response: dict[str, Any] = inspector.ping() or {}
+                    if env_worker in env_ping_response:
+                        return str(env_worker)
+                    # If env var is set but worker not found, log and continue
+                except Exception:  # noqa: BLE001
+                    pass
+
+            local_hostname = socket.gethostname()
+
+            try:
+                inspector = self.celery_app.control.inspect(timeout=1.0)
+
+                # Get all active workers
+                ping_response: dict[str, Any] = inspector.ping() or {}
+                if not ping_response:
+                    return None
+
+                # Strategy 2: Hostname-based matching
+                # First pass: exact hostname match
+                for worker_name in ping_response:
+                    if "@" in worker_name:
+                        _, worker_host = worker_name.rsplit("@", 1)
+                        if worker_host == local_hostname:
+                            return str(worker_name)
+                    elif worker_name == local_hostname:
+                        return str(worker_name)
+
+                # Second pass: partial hostname match (FQDN vs short name)
+                for worker_name in ping_response:
+                    if "@" in worker_name:
+                        _, worker_host = worker_name.rsplit("@", 1)
+                        if (
+                            local_hostname in worker_host
+                            or worker_host in local_hostname
+                        ):
+                            return str(worker_name)
+
+                # Strategy 3: Filter by app tasks and check for single worker
+                registered: dict[str, list[str]] = inspector.registered() or {}
+                app_workers = []
+                for worker_name in ping_response:
+                    worker_tasks = registered.get(worker_name, [])
+                    if any(task in self._app_task_names for task in worker_tasks):
+                        app_workers.append(worker_name)
+
+                # If only one worker has this app's tasks, assume it's local
+                if len(app_workers) == 1:
+                    return str(app_workers[0])
+
+                # If multiple workers with same tasks exist and hostname doesn't match,
+                # we cannot determine which is local without CELERY_WORKER_HOSTNAME
+                return None
+            except Exception:  # noqa: BLE001
+                return None
+
+        @self.fastapi_app.get(
+            f"{self.prefix}/healthz",
+            response_model=HealthCheckResponse,
+            tags=["health"],
+            summary="Health check",
+        )
+        async def health_check(
+            worker: str | None = Query(
+                default=None,
+                description=(
+                    "Explicit worker hostname to check (e.g., 'celery@worker1'). "
+                    "If provided, bypasses local worker discovery."
+                ),
+            ),
+        ) -> HealthCheckResponse:
+            """
+            Check the health of a Celery worker.
+
+            If a `worker` query parameter is provided, checks that specific worker.
+            Otherwise, automatically discovers the worker running on the same host by
+            matching the system hostname with active Celery worker hostnames.
+
+            Returns:
+                Health status including broker connection and worker availability.
+
+            This endpoint is useful for:
+            - Kubernetes/Docker health probes (sidecar pattern)
+            - Load balancer health checks
+            - Monitoring systems
+            """
+            local_worker = worker  # Use explicit worker if provided
+            try:
+                broker_connected = True
+                if local_worker is None:
+                    local_worker = _find_local_worker()
+                # When a specific worker is requested, verify it's online via inspection.
+                # In environments without active workers, this will be False.
+                inspector = self.celery_app.control.inspect(
+                    destination=[local_worker] if local_worker else None
+                )
+                ping_response = inspector.ping() or {}
+                worker_online = local_worker in ping_response if local_worker else False
+
+            except Exception:  # noqa: BLE001
+                broker_connected = False
+                local_worker = None
+                worker_online = False
+
+            # Determine overall health status
+            status = "healthy" if broker_connected and worker_online else "unhealthy"
+
+            return HealthCheckResponse(
+                status=status,
+                celery_app=self.celery_app.main,
+                broker_connected=broker_connected,
+                worker_hostname=local_worker,
+                worker_online=worker_online,
+            )
+
+        @self.fastapi_app.get(
+            f"{self.prefix}/ping",
+            response_model=PingResponse,
+            tags=["health"],
+            summary="Ping worker",
+        )
+        async def ping_worker(
+            worker: str | None = Query(
+                default=None,
+                description=(
+                    "Explicit worker hostname to ping (e.g., 'celery@worker1'). "
+                    "If provided, bypasses local worker discovery."
+                ),
+            ),
+        ) -> PingResponse:
+            """
+            Ping a Celery worker.
+
+            If a `worker` query parameter is provided, pings that specific worker.
+            Otherwise, automatically discovers the local Celery worker by matching
+            the system hostname with active Celery worker hostnames.
+
+            Returns:
+                Ping response from the discovered or specified worker.
+
+            This endpoint is useful for:
+            - Checking specific worker responsiveness
+            - Diagnosing connection issues
+            - Verifying worker health in containerized deployments
+            """
+            local_worker = worker  # Use explicit worker if provided
+            if not local_worker:
+                local_worker = _find_local_worker()
+
+            if not local_worker:
+                # No worker found or specified
+                return PingResponse(
+                    worker_hostname=None,
+                    online=False,
+                    response=None,
+                )
+
+            # Ping the specific worker
+            inspector = self.celery_app.control.inspect(destination=[local_worker])
+            ping_response = inspector.ping() or {}
+
+            worker_response = ping_response.get(local_worker)
+
+            return PingResponse(
+                worker_hostname=local_worker,
+                online=worker_response is not None,
+                response=worker_response,
+            )
+
         @self.fastapi_app.post(
             f"{self.prefix}/purge",
             tags=["workers"],
@@ -744,6 +1102,79 @@ class CeleryFastAPIBridge:
             result = self.celery_app.send_task(payload.task_name, **send_options)
             return TaskResponse(task_id=result.id, status="PENDING")
 
+        @self.fastapi_app.post(
+            f"{self.prefix}/tasks/batch",
+            response_model=BatchTaskResponse,
+            tags=["tasks"],
+            summary="Execute multiple tasks in a group",
+        )
+        async def batch_execute_tasks(
+            payload: BatchTaskRequest,
+        ) -> BatchTaskResponse:
+            """
+            Execute multiple Celery tasks as a single group.
+
+            The tasks are submitted as a Celery group, enabling coordinated
+            execution and result collection.
+
+            Returns:
+                Group ID, individual task IDs, and count of submitted tasks.
+            """
+            from celery import group
+
+            # Validate: at least one task required
+            if not payload.tasks:
+                raise HTTPException(status_code=422, detail="No tasks provided")
+
+            # Build Celery signatures for each task
+            signatures = []
+            for item in payload.tasks:
+                if not item.task_name:
+                    raise HTTPException(
+                        status_code=422, detail="task_name is required for each task"
+                    )
+                sig = self.celery_app.signature(
+                    item.task_name,
+                    args=item.args,
+                    kwargs=item.kwargs,
+                    queue=item.queue,
+                )
+                signatures.append(sig)
+
+            # Submit the group
+            job = group(*signatures)
+            result = job.apply_async()
+
+            task_ids = [r.id for r in result.children or []]
+
+            return BatchTaskResponse(
+                group_id=result.id,
+                task_ids=task_ids,
+                task_count=len(payload.tasks),
+                status="PENDING",
+            )
+
+        @self.fastapi_app.post(
+            f"{self.prefix}/tasks/batch/revoke",
+            summary="Revoke multiple tasks",
+        )
+        async def batch_revoke_tasks(
+            payload: dict[str, list[str]],
+        ) -> dict[str, Any]:
+            """
+            Revoke multiple tasks by their task IDs.
+
+            Task IDs should be provided in the `task_ids` field.
+            """
+            task_ids = payload.get("task_ids", [])
+            if not task_ids:
+                raise HTTPException(status_code=422, detail="task_ids is required")
+
+            for task_id in task_ids:
+                self.celery_app.control.revoke(task_id)
+
+            return {"status": "revoked", "task_ids": task_ids, "count": len(task_ids)}
+
     def get_registered_routes(self) -> list[dict[str, str]]:
         """
         Get a list of all registered routes.

{celery_fastapi-0.1.3 → celery_fastapi-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "celery-fastapi"
-version = "0.1.3"
+version = "0.1.5" # placeholder; overridden by poetry-dynamic-versioning at build time
 description = "Automatic REST API generation for Celery tasks with FastAPI"
 authors = ["ilkerkara <ilkerkara@outlook.com.tr>"]
 license = "MIT"
@@ -29,7 +29,7 @@ packages = [{ include = "celery_fastapi" }]
 [tool.poetry.dependencies]
 python = "^3.11"
 fastapi = ">=0.100.0"
-celery = ">=5.3.0"
+celery = ">=5.3.0,<=5.6.3"
 pydantic = ">=2.0.0"
 
 # Server dependencies (optional)
@@ -107,8 +107,20 @@ rich = ">=13.0.0"
 celery-fastapi = "celery_fastapi.cli:app"
 
 [build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"
+
+[tool.poetry.requires-plugins]
+poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }
+
+[tool.poetry-dynamic-versioning]
+enable = false
+vcs = "git"
+style = "semver"
+
+[tool.poetry-dynamic-versioning.substitution]
+# Sync __version__ in source with the tag-derived version at build time.
+files = ["celery_fastapi/__init__.py"]
 
 [tool.ruff]
 target-version = "py311"