celery-dag 1.0.0__py3-none-any.whl

celery_dag/__init__.py

@@ -0,0 +1,8 @@
+from celery_dag.core.dag import DAGBuilder
+from celery_dag.engine.executor import DAGExecutor
+from celery_dag.persistence.database import create_tables
+from celery_dag.registry import task_hub
+
+__version__ = "1.0.0"
+__all__ = ["DAGBuilder", "DAGExecutor", "create_tables", "task_hub"]
+

celery_dag/api/__init__.py

@@ -0,0 +1,15 @@
+"""FastAPI REST API package for the DAG orchestrator."""
+
+try:
+    import fastapi  # noqa: F401
+except ImportError as exc:
+    raise ImportError(
+        "The REST API components of celery_dag require FastAPI and Uvicorn. "
+        "Install them using: pip install 'celery-dag[api]'"
+    ) from exc
+
+from celery_dag.api.app import create_api_app
+
+__all__ = ["create_api_app"]
+
+

celery_dag/api/app.py

@@ -0,0 +1,88 @@
+"""FastAPI application setup."""
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from redis import Redis
+
+from celery_dag.api.routes.dlq import router as dlq_router
+from celery_dag.api.routes.metrics import router as metrics_router
+from celery_dag.api.routes.tasks import router as tasks_router
+from celery_dag.api.routes.triggers import router as triggers_router
+from celery_dag.api.routes.workflows import router as workflows_router
+from celery_dag.config.settings import Settings, get_settings
+from celery_dag.observability.logging import setup_logging
+from celery_dag.persistence.unit_of_work import UnitOfWork
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Lifespan handler for FastAPI application startup and shutdown."""
+    setup_logging()
+    yield
+
+
+def create_api_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or get_settings()
+    app = FastAPI(
+        title="Celery DAG Orchestrator API",
+        description="Production-grade resilient DAG Workflow Orchestrator REST API",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @app.get("/healthz", tags=["Health"], summary="Comprehensive service readiness & liveness probe")
+    def health_check() -> dict[str, Any]:
+        checks: dict[str, str] = {}
+        is_healthy = True
+
+        # Database Check
+        try:
+            with UnitOfWork() as uow:
+                uow.workflows.running_ids(limit=1)
+            checks["database"] = "ok"
+        except Exception as exc:
+            checks["database"] = f"error: {exc}"
+            is_healthy = False
+
+        # Redis Check
+        try:
+            r = Redis.from_url(settings.redis_url, socket_connect_timeout=1.0)
+            r.ping()
+            r.close()
+            checks["redis"] = "ok"
+        except Exception as exc:
+            checks["redis"] = f"error: {exc}"
+            is_healthy = False
+
+        status_str = "healthy" if is_healthy else "degraded"
+        return {
+            "status": status_str,
+            "checks": checks,
+            "environment": settings.environment,
+            "app_name": settings.app_name,
+        }
+
+    app.include_router(workflows_router, prefix="/api/v1")
+    app.include_router(dlq_router, prefix="/api/v1")
+    app.include_router(tasks_router, prefix="/api/v1")
+    app.include_router(triggers_router, prefix="/api/v1")
+    app.include_router(metrics_router, prefix="/api/v1")
+
+    return app
+
+
+app = create_api_app()
+

celery_dag/api/routes/__init__.py

@@ -0,0 +1,2 @@
+"""Routes package for REST API."""
+

celery_dag/api/routes/dlq.py

@@ -0,0 +1,58 @@
+"""Dead-Letter Queue (DLQ) management endpoints."""
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import APIRouter, HTTPException, Query, status
+
+from celery_dag.api.schemas import DLQRecordResponse, ReplayDLQResponse
+from celery_dag.engine.dispatcher import DAGDispatcher
+from celery_dag.persistence.unit_of_work import UnitOfWork
+
+router = APIRouter(prefix="/dlq", tags=["Dead-Letter Queue"])
+
+
+@router.get(
+    "",
+    response_model=list[DLQRecordResponse],
+    summary="List dead-lettered outbox records",
+)
+def list_dead_letters(
+    limit: int = Query(default=50, ge=1, le=200),
+) -> list[DLQRecordResponse]:
+    with UnitOfWork() as uow:
+        records = uow.dispatch_outbox.dead_letters(limit=limit)
+        return [
+            DLQRecordResponse(
+                id=rec.id,
+                workflow_run_id=rec.workflow_run_id,
+                task_run_id=rec.task_run_id,
+                task_name=rec.task_name,
+                payload=rec.payload,
+                publish_attempts=rec.publish_attempts,
+                last_error=rec.last_error,
+                created_at=rec.created_at,
+            )
+            for rec in records
+        ]
+
+
+@router.post(
+    "/{outbox_id}/replay",
+    response_model=ReplayDLQResponse,
+    summary="Replay a dead-lettered message and attempt immediate re-publication",
+)
+def replay_dead_letter(outbox_id: UUID) -> ReplayDLQResponse:
+    dispatcher = DAGDispatcher(uow_factory=UnitOfWork)
+    success = dispatcher.replay_dead_letter(outbox_id)
+    if success:
+        return ReplayDLQResponse(
+            outbox_id=outbox_id,
+            replayed=True,
+            message="Outbox record successfully replayed and published.",
+        )
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail=f"Dead-letter record {outbox_id} not found or is not dead-lettered.",
+    )
+

celery_dag/api/routes/metrics.py

@@ -0,0 +1,31 @@
+"""Metrics API endpoints for KEDA and Prometheus monitoring."""
+from __future__ import annotations
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from celery_dag.models.enums import TaskStatus, WorkflowStatus
+from celery_dag.persistence.unit_of_work import UnitOfWork
+
+router = APIRouter(prefix="/metrics", tags=["Metrics"])
+
+
+class SystemMetricsResponse(BaseModel):
+    running_workflows_count: int
+    pending_outbox_count: int
+    dead_letters_count: int
+
+
+@router.get("", response_model=SystemMetricsResponse, summary="Get system metrics for KEDA/Prometheus autoscaling")
+def get_metrics() -> SystemMetricsResponse:
+    with UnitOfWork() as uow:
+        running_ids = uow.workflows.running_ids(limit=10000)
+        pending_outbox = uow.dispatch_outbox.pending(limit=10000)
+        dead_letters = uow.dispatch_outbox.dead_letters(limit=10000)
+
+        return SystemMetricsResponse(
+            running_workflows_count=len(running_ids),
+            pending_outbox_count=len(pending_outbox),
+            dead_letters_count=len(dead_letters),
+        )
+

celery_dag/api/routes/tasks.py

@@ -0,0 +1,19 @@
+"""Registered tasks endpoint."""
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from celery_dag.api.schemas import RegisteredTasksResponse
+from celery_dag.registry.task_registry import task_hub
+
+router = APIRouter(prefix="/tasks", tags=["Tasks"])
+
+
+@router.get(
+    "",
+    response_model=RegisteredTasksResponse,
+    summary="List all registered task callables available for DAG nodes",
+)
+def list_registered_tasks() -> RegisteredTasksResponse:
+    return RegisteredTasksResponse(tasks=list(task_hub.names()))
+

celery_dag/api/routes/triggers.py

@@ -0,0 +1,89 @@
+"""Workflow triggers API endpoints."""
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from fastapi import APIRouter, HTTPException, Query, status
+from pydantic import BaseModel, Field
+
+from celery_dag.engine.trigger_service import TriggerService
+from celery_dag.persistence.unit_of_work import UnitOfWork
+
+router = APIRouter(prefix="/triggers", tags=["Triggers"])
+
+
+class CreateTriggerRequest(BaseModel):
+    name: str = Field(..., description="Unique trigger name.")
+    trigger_type: str = Field(..., description="CRON or WEBHOOK")
+    cron_expression: str | None = Field(default=None, description="Standard 5-part cron expression for CRON trigger.")
+    dag_definition: dict[str, Any] = Field(..., description="Complete DAG definition dictionary.")
+
+
+class TriggerResponse(BaseModel):
+    id: UUID
+    name: str
+    trigger_type: str
+    cron_expression: str | None = None
+    is_active: bool
+    last_triggered_at: Any | None = None
+
+
+class FireWebhookResponse(BaseModel):
+    trigger_name: str
+    workflow_run_id: UUID
+    message: str
+
+
+@router.post("", response_model=TriggerResponse, status_code=status.HTTP_201_CREATED, summary="Create a Workflow Trigger")
+def create_trigger(request: CreateTriggerRequest) -> TriggerResponse:
+    try:
+        trigger = TriggerService().create_trigger(
+            name=request.name,
+            trigger_type=request.trigger_type,
+            dag_definition=request.dag_definition,
+            cron_expression=request.cron_expression,
+        )
+        return TriggerResponse(
+            id=trigger.id,
+            name=trigger.name,
+            trigger_type=trigger.trigger_type,
+            cron_expression=trigger.cron_expression,
+            is_active=trigger.is_active,
+            last_triggered_at=trigger.last_triggered_at,
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+
+
+@router.get("", response_model=list[TriggerResponse], summary="List all Workflow Triggers")
+def list_triggers(limit: int = Query(default=50, ge=1, le=200)) -> list[TriggerResponse]:
+    with UnitOfWork() as uow:
+        triggers = uow.triggers.list_triggers(limit=limit)
+        return [
+            TriggerResponse(
+                id=tr.id,
+                name=tr.name,
+                trigger_type=tr.trigger_type,
+                cron_expression=tr.cron_expression,
+                is_active=tr.is_active,
+                last_triggered_at=tr.last_triggered_at,
+            )
+            for tr in triggers
+        ]
+
+
+@router.post("/{trigger_name}/event", response_model=FireWebhookResponse, summary="Fire a Webhook trigger")
+def fire_webhook(trigger_name: str, event_payload: dict[str, Any] | None = None) -> FireWebhookResponse:
+    run_id = TriggerService().fire_webhook_trigger(trigger_name, event_payload=event_payload)
+    if run_id:
+        return FireWebhookResponse(
+            trigger_name=trigger_name,
+            workflow_run_id=run_id,
+            message="Webhook trigger fired successfully; workflow run initiated.",
+        )
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail=f"Active webhook trigger {trigger_name!r} not found.",
+    )
+

celery_dag/api/routes/workflows.py

@@ -0,0 +1,336 @@
+"""Workflow management endpoints."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import UUID
+
+from fastapi import APIRouter, HTTPException, Query, status
+
+from celery_dag.api.schemas import (
+    CancelWorkflowRequest,
+    CancelWorkflowResponse,
+    CleanupWorkflowsResponse,
+    SubmitWorkflowRequest,
+    SubmitWorkflowResponse,
+    TaskRunResponse,
+    WorkflowControlActionResponse,
+    WorkflowRunDetailResponse,
+    WorkflowRunResponse,
+)
+from celery_dag.core.dag import DAGBuilder
+from celery_dag.core.exceptions import (
+    DAGValidationError,
+    DuplicateNodeError,
+    UnknownNodeError,
+    WorkflowNotFoundError,
+)
+from celery_dag.engine.cancellation import cancel_workflow
+from celery_dag.engine.executor import DAGExecutor
+from celery_dag.engine.workflow_control import pause_workflow, resume_workflow
+from celery_dag.middleware.retry_policy import RetryPolicy
+from celery_dag.models.enums import WorkflowStatus
+from celery_dag.persistence.unit_of_work import UnitOfWork
+
+router = APIRouter(prefix="/workflows", tags=["Workflows"])
+
+
+@router.post(
+    "/submit",
+    response_model=SubmitWorkflowResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Submit a new DAG workflow run",
+)
+def submit_workflow(request: SubmitWorkflowRequest) -> SubmitWorkflowResponse:
+    try:
+        builder = DAGBuilder(
+            dag_id=request.dag_id,
+            version=request.version,
+            timeout=request.timeout,
+            metadata=request.metadata,
+        )
+        for node in request.nodes:
+            builder.add_node(
+                node_id=node.node_id,
+                task_name=node.task_name,
+                depends_on=node.dependencies,
+                retry_policy=RetryPolicy(
+                    max_retries=node.retry_policy.max_retries,
+                    delay=node.retry_policy.delay,
+                    backoff=node.retry_policy.backoff,
+                    max_delay=node.retry_policy.max_delay,
+                    jitter=node.retry_policy.jitter,
+                ),
+                timeout=node.timeout,
+                priority=node.priority,
+                queue=node.queue,
+                payload=node.payload,
+            )
+        dag = builder.build()
+        run_id = DAGExecutor().submit(dag)
+        return SubmitWorkflowResponse(
+            workflow_run_id=run_id,
+            dag_id=dag.dag_id,
+            version=dag.version,
+            status=WorkflowStatus.RUNNING if dag.nodes else WorkflowStatus.COMPLETED,
+            submitted_at=datetime.now(timezone.utc),
+        )
+    except (DAGValidationError, DuplicateNodeError, UnknownNodeError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)
+        ) from exc
+
+
+@router.get(
+    "",
+    response_model=list[WorkflowRunResponse],
+    summary="List workflow runs with filtering and pagination",
+)
+def list_workflows(
+    status_filter: WorkflowStatus | None = Query(default=None, alias="status"),
+    dag_id: str | None = Query(default=None, alias="dag_id"),
+    limit: int = Query(default=50, ge=1, le=200),
+    offset: int = Query(default=0, ge=0),
+) -> list[WorkflowRunResponse]:
+    with UnitOfWork() as uow:
+        runs = uow.workflows.list(
+            status=status_filter, dag_id=dag_id, limit=limit, offset=offset
+        )
+        return [
+            WorkflowRunResponse(
+                id=run.id,
+                dag_id=run.dag_id,
+                version=run.version,
+                status=run.status,
+                timeout_seconds=run.timeout_seconds,
+                run_metadata=run.run_metadata,
+                error=run.error,
+                created_at=run.created_at,
+                started_at=run.started_at,
+                finished_at=run.finished_at,
+                cancelled_at=run.cancelled_at,
+                cancellation_reason=run.cancellation_reason,
+            )
+            for run in runs
+        ]
+
+
+@router.post(
+    "/cleanup",
+    response_model=CleanupWorkflowsResponse,
+    summary="Purge completed/failed/cancelled workflows past retention period",
+)
+def cleanup_workflows(
+    retention_days: int = Query(default=30, ge=1, le=365, description="Retention window in days."),
+) -> CleanupWorkflowsResponse:
+    with UnitOfWork() as uow:
+        count = uow.workflows.delete_expired_workflows(retention_days=retention_days)
+        uow.commit()
+    return CleanupWorkflowsResponse(
+        deleted_count=count,
+        retention_days=retention_days,
+        message=f"Purged {count} expired workflows older than {retention_days} days.",
+    )
+
+
+@router.get(
+    "/{run_id}",
+    response_model=WorkflowRunDetailResponse,
+    summary="Get detailed workflow run info and all task runs",
+)
+def get_workflow(run_id: UUID) -> WorkflowRunDetailResponse:
+    with UnitOfWork() as uow:
+        try:
+            workflow = uow.workflows.get(run_id)
+            task_runs = uow.task_runs.list_for_workflow(run_id)
+            return WorkflowRunDetailResponse(
+                id=workflow.id,
+                dag_id=workflow.dag_id,
+                version=workflow.version,
+                status=workflow.status,
+                timeout_seconds=workflow.timeout_seconds,
+                run_metadata=workflow.run_metadata,
+                error=workflow.error,
+                created_at=workflow.created_at,
+                started_at=workflow.started_at,
+                finished_at=workflow.finished_at,
+                cancelled_at=workflow.cancelled_at,
+                cancellation_reason=workflow.cancellation_reason,
+                dag_definition=workflow.dag_definition,
+                task_runs=[
+                    TaskRunResponse(
+                        id=tr.id,
+                        workflow_run_id=tr.workflow_run_id,
+                        node_id=tr.node_id,
+                        task_name=tr.task_name,
+                        status=tr.status,
+                        attempt=tr.attempt,
+                        input_data=tr.input_data,
+                        result=tr.result,
+                        error=tr.error,
+                        started_at=tr.started_at,
+                        finished_at=tr.finished_at,
+                    )
+                    for tr in task_runs
+                ],
+            )
+        except WorkflowNotFoundError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+            ) from exc
+
+
+@router.post(
+    "/{run_id}/pause",
+    response_model=WorkflowControlActionResponse,
+    summary="Pause execution of a running workflow",
+)
+def pause_workflow_endpoint(run_id: UUID) -> WorkflowControlActionResponse:
+    success = pause_workflow(run_id)
+    if success:
+        return WorkflowControlActionResponse(
+            workflow_run_id=run_id,
+            action="pause",
+            success=True,
+            message="Workflow paused successfully. New nodes will not be queued until resumed.",
+        )
+    return WorkflowControlActionResponse(
+        workflow_run_id=run_id,
+        action="pause",
+        success=False,
+        message="Workflow is not currently in RUNNING status.",
+    )
+
+
+@router.post(
+    "/{run_id}/resume",
+    response_model=WorkflowControlActionResponse,
+    summary="Resume execution of a paused workflow",
+)
+def resume_workflow_endpoint(run_id: UUID) -> WorkflowControlActionResponse:
+    success = resume_workflow(run_id)
+    if success:
+        return WorkflowControlActionResponse(
+            workflow_run_id=run_id,
+            action="resume",
+            success=True,
+            message="Workflow resumed successfully. Ready nodes have been scheduled.",
+        )
+    return WorkflowControlActionResponse(
+        workflow_run_id=run_id,
+        action="resume",
+        success=False,
+        message="Workflow is not currently in PAUSED status.",
+    )
+
+
+@router.post(
+    "/{run_id}/cancel",
+    response_model=CancelWorkflowResponse,
+    summary="Request cancellation of a running workflow",
+)
+def request_cancellation(
+    run_id: UUID, request: CancelWorkflowRequest | None = None
+) -> CancelWorkflowResponse:
+    reason = request.reason if request else None
+    cancelled = cancel_workflow(run_id, reason=reason)
+    if cancelled:
+        return CancelWorkflowResponse(
+            workflow_run_id=run_id,
+            cancelled=True,
+            message="Workflow cancellation initiated successfully.",
+        )
+    return CancelWorkflowResponse(
+        workflow_run_id=run_id,
+        cancelled=False,
+        message="Workflow was already cancelled or in terminal state.",
+    )
+
+
+@router.get(
+    "/{run_id}/tasks/{node_id}",
+    response_model=TaskRunResponse,
+    summary="Get status and details of a specific task node",
+)
+def get_task_node(run_id: UUID, node_id: str) -> TaskRunResponse:
+    with UnitOfWork() as uow:
+        try:
+            tr = uow.task_runs.get_for_node(run_id, node_id)
+            return TaskRunResponse(
+                id=tr.id,
+                workflow_run_id=tr.workflow_run_id,
+                node_id=tr.node_id,
+                task_name=tr.task_name,
+                status=tr.status,
+                attempt=tr.attempt,
+                input_data=tr.input_data,
+                result=tr.result,
+                error=tr.error,
+                started_at=tr.started_at,
+                finished_at=tr.finished_at,
+            )
+        except Exception as exc:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Task node {node_id!r} not found for workflow {run_id}",
+            ) from exc
+
+
+@router.post(
+    "/{run_id}/resume-failed",
+    response_model=WorkflowControlActionResponse,
+    summary="Resume execution of a FAILED or CANCELLED workflow from point of failure",
+)
+def resume_failed_workflow(run_id: UUID) -> WorkflowControlActionResponse:
+    try:
+        executor = DAGExecutor()
+        executor.resume_from_failure(run_id)
+        return WorkflowControlActionResponse(
+            workflow_run_id=run_id,
+            action="resume-failed",
+            success=True,
+            message="Workflow resumed successfully from point of failure.",
+        )
+    except ValueError as exc:
+        return WorkflowControlActionResponse(
+            workflow_run_id=run_id,
+            action="resume-failed",
+            success=False,
+            message=str(exc),
+        )
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to resume workflow: {exc}",
+        ) from exc
+
+
+@router.get(
+    "/{run_id}/visualization",
+    summary="Generate live Mermaid diagram or Cytoscape JSON visualization of DAG run",
+)
+def get_workflow_visualization(
+    run_id: UUID,
+    format: str = Query(default="mermaid", description="Format: 'mermaid' or 'json'"),
+) -> Any:
+    from celery_dag.observability.dag_visualizer import (
+        generate_cytoscape_json,
+        generate_mermaid_diagram,
+    )
+
+    with UnitOfWork() as uow:
+        try:
+            workflow = uow.workflows.get(run_id)
+            task_runs = uow.task_runs.list_for_workflow(run_id)
+            dag = DAG.from_dict(workflow.dag_definition)
+        except Exception as exc:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Workflow run not found: {run_id}",
+            ) from exc
+
+    if format.lower() == "json":
+        return generate_cytoscape_json(dag, task_runs)
+    
+    mermaid_diagram = generate_mermaid_diagram(dag, task_runs)
+    return {"run_id": run_id, "format": "mermaid", "diagram": mermaid_diagram}
+