funmill-api 0.1.2__py3-none-any.whl

funmill/api/__init__.py

@@ -0,0 +1,44 @@
+from .app import app, backend_dependency
+from .backends import (
+    BACKEND_SPECS,
+    BackendError,
+    TaskBackend,
+    get_backend,
+    list_backends,
+)
+from .models import (
+    CancelRequest,
+    RetryPolicy,
+    TaskAccepted,
+    TaskInfo,
+    TaskLanguage,
+    TaskLogs,
+    TaskProgress,
+    TaskResult,
+    TaskStatus,
+    TaskSubmit,
+    WorkflowSubmit,
+    WorkflowTask,
+)
+
+__all__ = [
+    "BACKEND_SPECS",
+    "BackendError",
+    "CancelRequest",
+    "RetryPolicy",
+    "TaskAccepted",
+    "TaskBackend",
+    "TaskInfo",
+    "TaskLanguage",
+    "TaskLogs",
+    "TaskProgress",
+    "TaskResult",
+    "TaskStatus",
+    "TaskSubmit",
+    "WorkflowSubmit",
+    "WorkflowTask",
+    "app",
+    "backend_dependency",
+    "get_backend",
+    "list_backends",
+]

funmill/api/app.py

@@ -0,0 +1,103 @@
+import os
+import secrets
+from contextlib import asynccontextmanager
+from functools import lru_cache
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, FastAPI
+from fastapi.responses import JSONResponse
+from fastapi.security import APIKeyHeader
+
+from funmill.api.backends import BackendError, TaskBackend, get_backend
+from funmill.api.models import (
+    CancelRequest,
+    TaskAccepted,
+    TaskInfo,
+    TaskLogs,
+    TaskProgress,
+    TaskResult,
+    TaskSubmit,
+    WorkflowSubmit,
+)
+
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+
+def require_api_key(api_key: Annotated[str | None, Depends(api_key_header)]) -> None:
+    expected = os.getenv("FUNMILL_API_KEY", "")
+    if not expected:
+        raise BackendError("FUNMILL_API_KEY is not configured", 503)
+    if api_key is None or not secrets.compare_digest(api_key, expected):
+        raise BackendError("invalid API key", 401)
+
+
+@lru_cache
+def backend_dependency() -> TaskBackend:
+    return get_backend()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    yield
+    if backend_dependency.cache_info().currsize:
+        backend_dependency().close()
+        backend_dependency.cache_clear()
+
+
+app = FastAPI(title="Funmill", version="0.1.0", lifespan=lifespan)
+router = APIRouter(prefix="/v1", dependencies=[Depends(require_api_key)])
+Backend = Annotated[TaskBackend, Depends(backend_dependency)]
+
+
+@app.exception_handler(BackendError)
+async def backend_error_handler(_, exc: BackendError):
+    return JSONResponse(status_code=exc.status_code, content={"detail": str(exc)})
+
+
+@app.get("/health")
+def health(backend: Backend):
+    backend.health_check()
+    return {"status": "ok", "backend": os.getenv("FUNMILL_BACKEND", "windmill")}
+
+
+@router.post("/tasks", response_model=TaskAccepted, status_code=202)
+def submit_task(task: TaskSubmit, backend: Backend):
+    return TaskAccepted(task_id=backend.submit_task(task))
+
+
+@router.post("/workflows", response_model=TaskAccepted, status_code=202)
+def submit_workflow(workflow: WorkflowSubmit, backend: Backend):
+    return TaskAccepted(task_id=backend.submit_workflow(workflow))
+
+
+@router.get("/tasks/{task_id}", response_model=TaskInfo)
+def get_task(task_id: str, backend: Backend):
+    return backend.get_task(task_id)
+
+
+@router.get("/tasks/{task_id}/progress", response_model=TaskProgress)
+def get_progress(task_id: str, backend: Backend):
+    return backend.get_progress(task_id)
+
+
+@router.get("/tasks/{task_id}/logs", response_model=TaskLogs)
+def get_logs(task_id: str, backend: Backend):
+    return backend.get_logs(task_id)
+
+
+@router.get("/tasks/{task_id}/result", response_model=TaskResult)
+def get_result(task_id: str, backend: Backend):
+    return backend.get_result(task_id)
+
+
+@router.post("/tasks/{task_id}/cancel", status_code=204)
+def cancel(task_id: str, request: CancelRequest, backend: Backend) -> None:
+    backend.cancel(task_id, request.reason)
+
+
+@router.post("/tasks/{task_id}/rerun", response_model=TaskAccepted, status_code=202)
+def rerun(task_id: str, backend: Backend):
+    return TaskAccepted(task_id=backend.rerun(task_id), rerun_of=task_id)
+
+
+app.include_router(router)

funmill/api/backends/__init__.py

@@ -0,0 +1,42 @@
+import importlib
+import os
+from typing import Any, NamedTuple
+
+from .base import BackendError, TaskBackend
+
+
+class BackendSpec(NamedTuple):
+    module: str
+    cls: str
+    service: str | None = None
+
+
+BACKEND_SPECS = {
+    "dagu": BackendSpec(".dagu", "DaguBackend", ".dagu.service"),
+    "windmill": BackendSpec(".windmill", "WindmillBackend", ".windmill.service"),
+}
+
+
+def get_backend(backend_type: str | None = None, **kwargs: Any) -> TaskBackend:
+    key = (backend_type or os.getenv("FUNMILL_BACKEND", "windmill")).lower()
+    spec = BACKEND_SPECS.get(key)
+    if spec is None:
+        raise ValueError(
+            f"unsupported backend {key!r}; available: {', '.join(BACKEND_SPECS)}"
+        )
+    module = importlib.import_module(spec.module, __name__)
+    backend_class = getattr(module, spec.cls)
+    return backend_class(**kwargs) if kwargs else backend_class.from_env()
+
+
+def list_backends() -> list[str]:
+    return list(BACKEND_SPECS)
+
+
+__all__ = [
+    "BACKEND_SPECS",
+    "BackendError",
+    "TaskBackend",
+    "get_backend",
+    "list_backends",
+]

funmill/api/backends/base.py

@@ -0,0 +1,51 @@
+from abc import ABC, abstractmethod
+
+from funmill.api.models import (
+    TaskInfo,
+    TaskLogs,
+    TaskProgress,
+    TaskResult,
+    TaskSubmit,
+    WorkflowSubmit,
+)
+
+
+class BackendError(RuntimeError):
+    def __init__(self, message: str, status_code: int = 502) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class TaskBackend(ABC):
+    name: str
+
+    @abstractmethod
+    def health_check(self) -> None:
+        """Raise BackendError if the backend is unreachable or misconfigured."""
+
+    @abstractmethod
+    def submit_task(self, task: TaskSubmit) -> str: ...
+
+    @abstractmethod
+    def submit_workflow(self, workflow: WorkflowSubmit) -> str: ...
+
+    @abstractmethod
+    def get_task(self, task_id: str) -> TaskInfo: ...
+
+    @abstractmethod
+    def get_progress(self, task_id: str) -> TaskProgress: ...
+
+    @abstractmethod
+    def get_logs(self, task_id: str) -> TaskLogs: ...
+
+    @abstractmethod
+    def get_result(self, task_id: str) -> TaskResult: ...
+
+    @abstractmethod
+    def cancel(self, task_id: str, reason: str) -> None: ...
+
+    @abstractmethod
+    def rerun(self, task_id: str) -> str: ...
+
+    @abstractmethod
+    def close(self) -> None: ...

funmill/api/backends/dagu/README.md

@@ -0,0 +1,83 @@
+# Dagu 简单部署
+
+以下方式不使用 Docker，适用于 macOS 和 Linux 的 x86_64、ARM64 平台。
+Funmill 当前固定安装 Dagu `v2.16.3`，运行任务还需要 `python3` 和 Bash。
+
+## 1. 安装 Funmill 和 Dagu
+
+```bash
+uv sync
+uv run funmill install dagu
+```
+
+Dagu 二进制会放在 `~/.farfarfun/funmill/services/dagu/dagu`，运行数据会放在
+同目录的 `data/`。安装器会分别校验官方发行包和二进制的 SHA-256；设置
+`FUNMILL_HOME` 可以修改 Funmill 的数据根目录。
+
+如果已有文件未通过校验，可明确覆盖安装：
+
+```bash
+uv run funmill install dagu --force
+```
+
+## 2. 启动 Dagu
+
+```bash
+uv run funmill start dagu
+```
+
+该命令会在后台启动 Dagu，并打印 PID 和日志路径。PID 与日志分别保存在
+`~/.farfarfun/funmill/services/dagu/dagu.pid` 和 `dagu.log`。
+
+Dagu 的 Web 界面和原生 API 固定监听 `0.0.0.0:8813`；本机仍使用
+<http://127.0.0.1:8813> 访问。`0.0.0.0` 是监听地址，不能作为客户端地址。
+本地启动默认设置 `DAGU_AUTH_MODE=none`，不需要外部数据库；未使用的 Dagu
+coordinator 默认关闭。
+
+## 3. 启动 Funmill API
+
+在另一个终端执行：
+
+```bash
+FUNMILL_API_KEY='自行设置的接口密钥' \
+FUNMILL_BACKEND=dagu \
+DAGU_URL='http://127.0.0.1:8813' \
+uv run funmill start
+```
+
+Funmill API 固定监听 `0.0.0.0:8812`，并保持前台运行。
+`DAGU_TIMEOUT` 可以修改 Funmill 请求 Dagu 的超时秒数，默认值为 `30`。
+若自行启用了 Dagu 认证，两个启动命令都需要设置相同的 `DAGU_TOKEN`；
+Funmill 会将其作为 Bearer Token 使用，并传给等待跨任务依赖的 Dagu 任务。
+
+## 4. 验证
+
+```bash
+curl http://127.0.0.1:8812/health
+FUNMILL_API_KEY='自行设置的接口密钥' ./scripts/smoke.sh
+```
+
+smoke 脚本会验证 Python、Bash 和并行 DAG 的提交、状态、进度、日志与结果。
+设置 `FUNMILL_CALLBACK_URL` 还会验证回调；该地址必须能从 Dagu 任务进程访问。
+
+## 5. 管理后台服务
+
+```bash
+uv run funmill status dagu
+uv run funmill restart dagu
+uv run funmill stop dagu
+tail -f ~/.farfarfun/funmill/services/dagu/dagu.log
+```
+
+重复启动会被 PID 文件拦截。`stop` 会向 Dagu 的独立进程组发送 `SIGTERM`，
+等待正常退出后删除 PID 文件；服务异常退出后，`status` 会清理失效 PID。
+
+## 安全与长期运行
+
+Dagu 默认无认证且监听所有网络接口，必须使用防火墙限制 `8813`，或启用 Dagu
+认证并配置 `DAGU_TOKEN`。Dagu 会以启动服务的宿主机用户权限直接执行
+Funmill 提交的源码，只应接收可信任务。接受不可信代码前必须使用隔离 Worker
+或容器，不要仅依赖 Funmill 的 API Key。
+
+Funmill 自带的后台模式适合简单部署。需要开机启动、自动重启和日志轮转时，
+使用现有的 launchd、systemd 或进程管理器直接管理已安装的 Dagu 二进制。