funmill 0.1.1__py3-none-any.whl

funmill/__init__.py

@@ -0,0 +1,41 @@
+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",
+    "get_backend",
+    "list_backends",
+]

funmill/api.py

@@ -0,0 +1,102 @@
+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.backends import BackendError, TaskBackend, get_backend
+from funmill.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():
+    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/backends/__init__.py

@@ -0,0 +1,41 @@
+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 = {
+    "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/backends/base.py

@@ -0,0 +1,47 @@
+from abc import ABC, abstractmethod
+
+from funmill.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 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/backends/windmill/README.md

@@ -0,0 +1,87 @@
+# Windmill 简单部署
+
+以下方式不使用 Docker，适用于 Linux x86_64。需要一套可用的 PostgreSQL，
+以及 `python3`、`uv` 和 Bash；Windmill 会自动初始化数据库表。
+
+## 1. 安装 Funmill 和 Windmill
+
+```bash
+uv sync
+uv run funmill install windmill
+```
+
+Windmill 会安装到 `~/.farfarfun/funmill/services/windmill/`。安装器会校验
+官方发行包的 SHA-256；设置 `FUNMILL_HOME` 可以修改安装目录。
+
+## 2. 准备数据库
+
+在 PostgreSQL 中创建用户和数据库：
+
+```bash
+sudo -u postgres createuser --pwprompt windmill
+sudo -u postgres createdb --owner=windmill windmill
+```
+
+然后确认下面的连接可以使用：
+
+```text
+postgres://windmill:数据库密码@127.0.0.1:5432/windmill
+```
+
+## 3. 启动 Windmill
+
+`standalone` 模式会在一个进程中同时运行 Server 和一个 Worker：
+
+```bash
+DATABASE_URL='postgres://windmill:数据库密码@127.0.0.1:5432/windmill' \
+MODE=standalone \
+PORT=8001 \
+BASE_URL='http://127.0.0.1:8001' \
+SERVER_BIND_ADDR=127.0.0.1 \
+uv run funmill start windmill
+```
+
+打开 <http://127.0.0.1:8001>，首次登录使用：
+
+```text
+admin@windmill.dev / changeme
+```
+
+立即修改密码，并在 `admins` workspace 中创建 API Token。
+
+## 4. 启动 Funmill API
+
+回到 Funmill 仓库根目录执行：
+
+```bash
+FUNMILL_API_KEY='自行设置的接口密钥' \
+FUNMILL_BACKEND=windmill \
+WINDMILL_URL='http://127.0.0.1:8001' \
+WINDMILL_WORKSPACE=admins \
+WINDMILL_TOKEN='刚创建的Windmill-Token' \
+uv run funmill start
+```
+
+验证：
+
+```bash
+curl http://127.0.0.1:8000/health
+FUNMILL_API_KEY='自行设置的接口密钥' ./scripts/smoke.sh
+```
+
+## 增加 Worker
+
+需要更高并发时，在同一台或其他机器额外启动 Worker。每个进程使用不同的
+`WORKER_SUFFIX`：
+
+```bash
+DATABASE_URL='postgres://windmill:数据库密码@127.0.0.1:5432/windmill' \
+MODE=worker WORKER_SUFFIX=worker2 uv run funmill start windmill
+
+DATABASE_URL='postgres://windmill:数据库密码@127.0.0.1:5432/windmill' \
+MODE=worker WORKER_SUFFIX=worker3 uv run funmill start windmill
+```
+
+正式长期运行时，将上述命令交给现有的 systemd 或进程管理器即可。不要在
+一个普通 Worker 进程中设置 `NUM_WORKERS>1`；Windmill 会因为隔离安全限制将
+它回退为 1，多个独立 Worker 进程更明确。

funmill/backends/windmill/__init__.py

@@ -0,0 +1,393 @@
+import json
+import os
+from typing import Any
+from uuid import UUID
+
+import httpx
+
+from funmill.models import (
+    TaskDefinition,
+    TaskInfo,
+    TaskLanguage,
+    TaskLogs,
+    TaskProgress,
+    TaskResult,
+    TaskStatus,
+    TaskSubmit,
+    WorkflowSubmit,
+)
+
+from ..base import BackendError, TaskBackend
+
+_CALLBACK_SOURCE = """import json
+import os
+from urllib.request import Request, urlopen
+
+def main(callback_url: str, status: str, payload):
+    body = {
+        "task_id": os.environ["WM_ROOT_JOB_ID"],
+        "status": status,
+        "payload": payload,
+    }
+    request = Request(
+        callback_url,
+        data=json.dumps(body, default=str).encode(),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urlopen(request, timeout=10):
+        return payload
+"""
+
+_DEPENDENCY_SOURCE = """from datetime import datetime, timezone
+import os
+from wmill import get_job
+
+def main(dependencies: list[str], timeout_seconds: int):
+    root = get_job(os.environ["WM_ROOT_JOB_ID"])
+    created_at = datetime.fromisoformat(root["created_at"].replace("Z", "+00:00"))
+    if (datetime.now(timezone.utc) - created_at).total_seconds() > timeout_seconds:
+        raise TimeoutError("dependency wait timed out")
+
+    for task_id in dependencies:
+        job = get_job(task_id)
+        if "success" not in job:
+            return False
+        if job.get("canceled"):
+            raise RuntimeError(f"dependency {task_id} was canceled")
+        if not job["success"]:
+            raise RuntimeError(f"dependency {task_id} failed")
+    return True
+"""
+
+_RESULT_SOURCE = """def main(results):
+    return results
+"""
+
+_LANGUAGES = {
+    TaskLanguage.PYTHON: "python3",
+    TaskLanguage.BASH: "bash",
+}
+
+
+class WindmillBackend(TaskBackend):
+    name = "windmill"
+
+    def __init__(
+        self,
+        base_url: str,
+        workspace: str,
+        token: str,
+        timeout: float = 30,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.token = token
+        self.client = client or httpx.Client(
+            base_url=f"{base_url.rstrip('/')}/api/w/{workspace}/",
+            timeout=timeout,
+        )
+
+    @classmethod
+    def from_env(cls) -> "WindmillBackend":
+        return cls(
+            base_url=os.getenv("WINDMILL_URL", "http://windmill_server:8000"),
+            workspace=os.getenv("WINDMILL_WORKSPACE", "admins"),
+            token=os.getenv("WINDMILL_TOKEN", ""),
+            timeout=float(os.getenv("WINDMILL_TIMEOUT", "30")),
+        )
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        if not self.token:
+            raise BackendError("WINDMILL_TOKEN is not configured", 503)
+        try:
+            response = self.client.request(
+                method,
+                path,
+                headers={"Authorization": f"Bearer {self.token}"},
+                **kwargs,
+            )
+        except httpx.TimeoutException as exc:
+            raise BackendError("Windmill request timed out", 504) from exc
+        except httpx.HTTPError as exc:
+            raise BackendError(f"Windmill is unavailable: {exc}", 502) from exc
+        if response.is_error:
+            status_code = 404 if response.status_code == 404 else 502
+            detail = response.text.strip()[:500] or f"HTTP {response.status_code}"
+            raise BackendError(f"Windmill rejected the request: {detail}", status_code)
+        return response
+
+    def _submit_flow(self, value: dict[str, Any], args: dict[str, Any]) -> str:
+        response = self._request(
+            "POST", "jobs/run/preview_flow", json={"value": value, "args": args}
+        )
+        return self._response_task_id(response)
+
+    @staticmethod
+    def _response_task_id(response: httpx.Response) -> str:
+        lines = response.text.strip().splitlines()
+        if not lines:
+            raise BackendError("Windmill returned an empty task ID")
+        try:
+            return str(UUID(lines[0]))
+        except ValueError as exc:
+            raise BackendError(
+                f"Windmill returned an invalid task ID: {lines[0]!r}"
+            ) from exc
+
+    @staticmethod
+    def _task_module(task_id: str, task: TaskDefinition) -> dict[str, Any]:
+        module: dict[str, Any] = {
+            "id": task_id,
+            "value": {
+                "type": "rawscript",
+                "language": _LANGUAGES[task.language],
+                "content": task.source,
+                "input_transforms": {
+                    key: {"type": "static", "value": value}
+                    for key, value in task.args.items()
+                },
+            },
+        }
+        if task.retry.attempts:
+            module["retry"] = {
+                "constant": {
+                    "attempts": task.retry.attempts,
+                    "seconds": task.retry.delay_seconds,
+                }
+            }
+        if task.timeout_seconds:
+            module["timeout"] = {"type": "static", "value": task.timeout_seconds}
+        return module
+
+    @staticmethod
+    def _dependency_module(
+        dependencies: list[str], timeout_seconds: int
+    ) -> dict[str, Any]:
+        # ponytail: polling creates one short Windmill job per interval; replace with
+        # backend completion events when dependency volume makes that measurable.
+        return {
+            "id": "funmill_wait",
+            "value": {
+                "type": "whileloopflow",
+                "skip_failures": False,
+                "modules": [
+                    {
+                        "id": "funmill_check_dependencies",
+                        "value": {
+                            "type": "rawscript",
+                            "language": "python3",
+                            "content": _DEPENDENCY_SOURCE,
+                            "input_transforms": {
+                                "dependencies": {
+                                    "type": "static",
+                                    "value": dependencies,
+                                },
+                                "timeout_seconds": {
+                                    "type": "static",
+                                    "value": timeout_seconds,
+                                },
+                            },
+                        },
+                        "sleep": {"type": "static", "value": 2},
+                        "stop_after_if": {"expr": "result === true"},
+                    }
+                ],
+            },
+        }
+
+    @staticmethod
+    def _add_callback(
+        value: dict[str, Any], callback_url: str | None, result_id: str
+    ) -> None:
+        if callback_url is None:
+            return
+
+        def callback_module(module_id: str, status: str, payload_expr: str):
+            return {
+                "id": module_id,
+                "value": {
+                    "type": "rawscript",
+                    "language": "python3",
+                    "content": _CALLBACK_SOURCE,
+                    "input_transforms": {
+                        "callback_url": {"type": "static", "value": callback_url},
+                        "status": {"type": "static", "value": status},
+                        "payload": {"type": "javascript", "expr": payload_expr},
+                    },
+                },
+                "retry": {"constant": {"attempts": 3, "seconds": 2}},
+            }
+
+        result_expr = f"results[{json.dumps(result_id)}]"
+        value["modules"].append(
+            callback_module("funmill_callback", "succeeded", result_expr)
+        )
+        value["failure_module"] = callback_module("failure", "failed", "error")
+
+    @staticmethod
+    def _result_module(task_results: dict[str, str]) -> dict[str, Any]:
+        entries = ", ".join(
+            f"{json.dumps(task_id)}: {result_expr}"
+            for task_id, result_expr in task_results.items()
+        )
+        return {
+            "id": "funmill_result",
+            "value": {
+                "type": "rawscript",
+                "language": "python3",
+                "content": _RESULT_SOURCE,
+                "input_transforms": {
+                    "results": {
+                        "type": "javascript",
+                        "expr": f"({{{entries}}})",
+                    }
+                },
+            },
+        }
+
+    def submit_task(self, task: TaskSubmit) -> str:
+        modules = []
+        if task.depends_on:
+            modules.append(
+                self._dependency_module(
+                    task.depends_on, task.dependency_timeout_seconds
+                )
+            )
+        modules.append(self._task_module("task", task))
+        value = {"modules": modules}
+        self._add_callback(
+            value,
+            str(task.callback_url) if task.callback_url else None,
+            "task",
+        )
+        return self._submit_flow(value, {})
+
+    def submit_workflow(self, workflow: WorkflowSubmit) -> str:
+        modules = []
+        task_results = {}
+        if workflow.depends_on:
+            modules.append(
+                self._dependency_module(
+                    workflow.depends_on, workflow.dependency_timeout_seconds
+                )
+            )
+
+        for index, layer in enumerate(workflow.topological_layers()):
+            if len(layer) == 1:
+                module = self._task_module(layer[0].key, layer[0])
+                task_results[layer[0].key] = f"results[{json.dumps(layer[0].key)}]"
+            else:
+                layer_id = f"funmill_layer_{index}"
+                module = {
+                    "id": layer_id,
+                    "value": {
+                        "type": "branchall",
+                        "parallel": True,
+                        "branches": [
+                            {
+                                "summary": task.key,
+                                "modules": [self._task_module(task.key, task)],
+                            }
+                            for task in layer
+                        ],
+                    },
+                }
+                for task_index, task in enumerate(layer):
+                    task_results[task.key] = (
+                        f"results[{json.dumps(layer_id)}][{task_index}]"
+                    )
+            modules.append(module)
+
+        result_module = self._result_module(task_results)
+        modules.append(result_module)
+
+        value = {"modules": modules}
+        self._add_callback(
+            value,
+            str(workflow.callback_url) if workflow.callback_url else None,
+            result_module["id"],
+        )
+        return self._submit_flow(value, {})
+
+    def _get_job(self, task_id: str) -> dict[str, Any]:
+        return self._request("GET", f"jobs_u/get/{task_id}").json()
+
+    @staticmethod
+    def _status(job: dict[str, Any]) -> TaskStatus:
+        if job.get("canceled"):
+            return TaskStatus.CANCELED
+        if "success" in job:
+            return TaskStatus.SUCCEEDED if job["success"] else TaskStatus.FAILED
+        return TaskStatus.RUNNING if job.get("running") else TaskStatus.QUEUED
+
+    def get_task(self, task_id: str) -> TaskInfo:
+        job = self._get_job(task_id)
+        return TaskInfo(
+            task_id=task_id,
+            status=self._status(job),
+            created_at=job.get("created_at"),
+            started_at=job.get("started_at"),
+            completed_at=job.get("completed_at"),
+            duration_ms=job.get("duration_ms"),
+        )
+
+    def get_progress(self, task_id: str) -> TaskProgress:
+        job = self._get_job(task_id)
+        status = self._status(job)
+        if status == TaskStatus.SUCCEEDED:
+            return TaskProgress(task_id=task_id, progress=100)
+
+        modules = (job.get("flow_status") or {}).get("modules") or []
+        scores = []
+        for module in modules:
+            if module.get("type") == "Success":
+                scores.append(100)
+            elif module.get("type") == "InProgress":
+                scores.append(module.get("progress") or 0)
+            else:
+                scores.append(0)
+        progress = int(sum(scores) / len(scores)) if scores else None
+        return TaskProgress(task_id=task_id, progress=progress)
+
+    def get_logs(self, task_id: str) -> TaskLogs:
+        job = self._get_job(task_id)
+        if job.get("job_kind") in {"flow", "flowpreview", "singlestepflow"}:
+            response = self._request("GET", f"jobs_u/get_flow_all_logs/{task_id}")
+            logs = response.text
+        else:
+            logs = self._request("GET", f"jobs_u/get_logs/{task_id}").text
+        return TaskLogs(task_id=task_id, logs=logs)
+
+    def get_result(self, task_id: str) -> TaskResult:
+        result = self._request("GET", f"jobs_u/completed/get_result/{task_id}").json()
+        return TaskResult(task_id=task_id, result=result)
+
+    def cancel(self, task_id: str, reason: str) -> None:
+        self._request("POST", f"jobs_u/queue/cancel/{task_id}", json={"reason": reason})
+
+    def rerun(self, task_id: str) -> str:
+        job = self._get_job(task_id)
+        raw_flow = job.get("raw_flow")
+        if raw_flow:
+            return self._submit_flow(raw_flow, job.get("args") or {})
+
+        raw_code = job.get("raw_code")
+        if raw_code:
+            response = self._request(
+                "POST",
+                "jobs/run/preview",
+                json={
+                    "content": raw_code,
+                    "language": job.get("language"),
+                    "kind": "code",
+                    "args": job.get("args") or {},
+                },
+            )
+            return self._response_task_id(response)
+
+        raise BackendError(
+            "task cannot be rerun because its source is unavailable", 409
+        )
+
+    def close(self) -> None:
+        self.client.close()

funmill/backends/windmill/service.py

@@ -0,0 +1,76 @@
+import hashlib
+import os
+import platform
+import shutil
+import tempfile
+from pathlib import Path
+from urllib.request import Request, urlopen
+
+VERSION = "v1.808.0"
+URL = f"https://github.com/windmill-labs/windmill/releases/download/{VERSION}/windmill-amd64"
+SHA256 = "ed48bfb9a391daa437f0c867376f009c7186855530de7fe2f58cf557ff1f7c3a"
+
+
+def _target() -> Path:
+    home = Path(os.getenv("FUNMILL_HOME", Path.home() / ".farfarfun" / "funmill"))
+    return home / "services" / "windmill" / "windmill"
+
+
+def _sha256(path: Path) -> str:
+    with path.open("rb") as file:
+        return hashlib.file_digest(file, "sha256").hexdigest()
+
+
+def install(force: bool = False) -> Path:
+    if platform.system() != "Linux" or platform.machine().lower() not in {
+        "x86_64",
+        "amd64",
+    }:
+        raise RuntimeError("Windmill v1.808.0 installer only supports Linux x86_64")
+
+    target = _target()
+    if target.exists() and _sha256(target) == SHA256:
+        return target
+    if target.exists() and not force:
+        raise RuntimeError(
+            f"{target} exists but has an unexpected checksum; use --force"
+        )
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(dir=target.parent)
+    os.close(descriptor)
+    temporary = Path(temporary_name)
+    try:
+        print(f"downloading Windmill {VERSION}...", flush=True)
+        request = Request(URL, headers={"User-Agent": "funmill"})
+        with urlopen(request, timeout=30) as response, temporary.open("wb") as file:
+            shutil.copyfileobj(response, file)
+        if _sha256(temporary) != SHA256:
+            raise RuntimeError("downloaded Windmill binary failed SHA-256 verification")
+        temporary.chmod(0o755)
+        temporary.replace(target)
+    finally:
+        temporary.unlink(missing_ok=True)
+    return target
+
+
+def start() -> None:
+    executable = _target()
+    if not executable.exists():
+        system_executable = shutil.which("windmill")
+        if system_executable is None:
+            raise RuntimeError(
+                "Windmill is not installed; run: funmill install windmill"
+            )
+        executable = Path(system_executable)
+
+    if not os.getenv("DATABASE_URL"):
+        raise RuntimeError("DATABASE_URL is required")
+
+    environment = os.environ.copy()
+    mode = environment.setdefault("MODE", "standalone")
+    if mode in {"standalone", "server"}:
+        environment.setdefault("PORT", "8001")
+        environment.setdefault("BASE_URL", "http://127.0.0.1:8001")
+    environment.setdefault("SERVER_BIND_ADDR", "127.0.0.1")
+    os.execve(executable, [str(executable)], environment)

funmill/cli.py

@@ -0,0 +1,63 @@
+import argparse
+import importlib
+import os
+from collections.abc import Sequence
+from types import ModuleType
+
+import uvicorn
+
+from funmill.backends import BACKEND_SPECS
+
+
+def _service_names() -> list[str]:
+    return [name for name, spec in BACKEND_SPECS.items() if spec.service]
+
+
+def _service(name: str) -> ModuleType:
+    spec = BACKEND_SPECS[name]
+    return importlib.import_module(spec.service, "funmill.backends")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="funmill")
+    commands = parser.add_subparsers(dest="command")
+
+    commands.add_parser("services", help="列出可安装的第三方服务")
+
+    install = commands.add_parser("install", help="安装第三方服务")
+    install.add_argument("service", choices=_service_names())
+    install.add_argument("--force", action="store_true", help="覆盖现有安装")
+
+    start = commands.add_parser("start", help="启动 Funmill 或第三方服务")
+    start.add_argument(
+        "service", nargs="?", choices=["api", *_service_names()], default="api"
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = _parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "services":
+            print("\n".join(_service_names()))
+        elif args.command == "install":
+            path = _service(args.service).install(force=args.force)
+            print(f"installed {args.service}: {path}")
+        elif args.command == "start" and args.service != "api":
+            _service(args.service).start()
+        elif args.command == "start":
+            uvicorn.run(
+                "funmill.api:app",
+                host=os.getenv("FUNMILL_HOST", "127.0.0.1"),
+                port=int(os.getenv("FUNMILL_PORT", "8000")),
+            )
+        else:
+            parser.print_help()
+    except (OSError, RuntimeError, ValueError) as exc:
+        parser.exit(1, f"error: {exc}\n")
+
+
+if __name__ == "__main__":
+    main()

funmill/models.py

@@ -0,0 +1,120 @@
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated, Any, Self
+
+from pydantic import AnyHttpUrl, BaseModel, Field, model_validator
+
+DependencyId = Annotated[str, Field(min_length=1, max_length=200)]
+
+
+class TaskLanguage(StrEnum):
+    PYTHON = "python"
+    BASH = "bash"
+
+
+class TaskStatus(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELED = "canceled"
+
+
+class RetryPolicy(BaseModel):
+    attempts: int = Field(default=0, ge=0, le=10)
+    delay_seconds: int = Field(default=1, ge=0, le=3600)
+
+
+class TaskDefinition(BaseModel):
+    language: TaskLanguage
+    source: str = Field(min_length=1, max_length=1_000_000)
+    args: dict[str, Any] = Field(default_factory=dict)
+    retry: RetryPolicy = Field(default_factory=RetryPolicy)
+    timeout_seconds: int | None = Field(default=None, ge=1, le=86_400)
+
+
+class TaskSubmit(TaskDefinition):
+    depends_on: list[DependencyId] = Field(default_factory=list, max_length=100)
+    dependency_timeout_seconds: int = Field(default=86_400, ge=1, le=604_800)
+    callback_url: AnyHttpUrl | None = None
+
+
+class WorkflowTask(TaskDefinition):
+    key: str = Field(pattern=r"^[A-Za-z][A-Za-z0-9_-]{0,63}$")
+    depends_on: list[str] = Field(default_factory=list, max_length=100)
+
+
+class WorkflowSubmit(BaseModel):
+    tasks: list[WorkflowTask] = Field(min_length=1, max_length=100)
+    depends_on: list[DependencyId] = Field(default_factory=list, max_length=100)
+    dependency_timeout_seconds: int = Field(default=86_400, ge=1, le=604_800)
+    callback_url: AnyHttpUrl | None = None
+
+    @model_validator(mode="after")
+    def validate_dependencies(self) -> Self:
+        keys = [task.key for task in self.tasks]
+        if len(keys) != len(set(keys)):
+            raise ValueError("workflow task keys must be unique")
+        if any(key == "failure" or key.startswith("funmill_") for key in keys):
+            raise ValueError("task keys cannot be 'failure' or start with 'funmill_'")
+
+        known = set(keys)
+        for task in self.tasks:
+            unknown = set(task.depends_on) - known
+            if unknown:
+                raise ValueError(
+                    f"task {task.key!r} has unknown dependencies: {sorted(unknown)}"
+                )
+        self.topological_layers()
+        return self
+
+    def topological_layers(self) -> list[list[WorkflowTask]]:
+        by_key = {task.key: task for task in self.tasks}
+        remaining = {task.key: set(task.depends_on) for task in self.tasks}
+        layers: list[list[WorkflowTask]] = []
+        while remaining:
+            ready = [key for key, dependencies in remaining.items() if not dependencies]
+            if not ready:
+                raise ValueError("workflow contains a dependency cycle")
+            layers.append([by_key[key] for key in ready])
+            ready_set = set(ready)
+            remaining = {
+                key: dependencies - ready_set
+                for key, dependencies in remaining.items()
+                if key not in ready_set
+            }
+        return layers
+
+
+class TaskAccepted(BaseModel):
+    task_id: str
+    status: TaskStatus = TaskStatus.QUEUED
+    rerun_of: str | None = None
+
+
+class TaskInfo(BaseModel):
+    task_id: str
+    status: TaskStatus
+    created_at: datetime | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    duration_ms: int | None = None
+
+
+class TaskProgress(BaseModel):
+    task_id: str
+    progress: int | None
+
+
+class TaskLogs(BaseModel):
+    task_id: str
+    logs: str
+
+
+class TaskResult(BaseModel):
+    task_id: str
+    result: Any
+
+
+class CancelRequest(BaseModel):
+    reason: str = Field(default="canceled through Funmill", max_length=500)

funmill-0.1.1.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: funmill
+Version: 0.1.1
+Summary: Backend-neutral task execution API
+Project-URL: Organization, https://github.com/farfarfun
+Project-URL: Repository, https://github.com/farfarfun/funmill
+Project-URL: Releases, https://github.com/farfarfun/funmill/releases
+Author-email: 牛哥 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>
+Maintainer-email: 牛哥 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: uvicorn<1,>=0.30
+Description-Content-Type: text/markdown
+
+# Funmill
+
+Funmill provides one stable task API while execution is delegated to a
+replaceable backend. The first backend is self-hosted
+[Windmill](https://github.com/windmill-labs/windmill), pinned to `v1.808.0`.
+
+```text
+client -> Funmill /v1 -> TaskBackend -> Windmill
+                                  -> another backend later
+```
+
+Funmill owns the public request and response models. Backend job IDs remain
+opaque strings, and no Windmill routes or payloads are exposed to clients.
+
+## Start
+
+Install the project and the Windmill binary:
+
+```bash
+uv sync
+uv run funmill install windmill
+```
+
+Start Windmill against an existing PostgreSQL database:
+
+```bash
+DATABASE_URL='postgres://windmill:password@127.0.0.1:5432/windmill' \
+uv run funmill start windmill
+```
+
+Open <http://localhost:8001>, log in with `admin@windmill.dev` / `changeme`,
+change the password, and create an API token in the `admins` workspace. Then
+start Funmill in another terminal:
+
+```bash
+FUNMILL_API_KEY='replace-me' \
+WINDMILL_URL='http://127.0.0.1:8001' \
+WINDMILL_WORKSPACE=admins \
+WINDMILL_TOKEN='replace-me' \
+uv run funmill start
+```
+
+The API is at <http://localhost:8000>; OpenAPI docs are at
+<http://localhost:8000/docs>. All `/v1` routes require `X-API-Key`. See the
+[Windmill deployment guide](src/funmill/backends/windmill/README.md) for
+PostgreSQL setup and additional workers.
+
+Run the end-to-end task and DAG checks with:
+
+```bash
+FUNMILL_API_KEY=the-value-from-env ./scripts/smoke.sh
+```
+
+Set `FUNMILL_CALLBACK_URL` to test callbacks. The URL must be reachable from
+the Windmill workers.
+
+## API
+
+| Operation | Route |
+| --- | --- |
+| Submit Python/Bash | `POST /v1/tasks` |
+| Submit a DAG | `POST /v1/workflows` |
+| Status | `GET /v1/tasks/{task_id}` |
+| Logs | `GET /v1/tasks/{task_id}/logs` |
+| Progress | `GET /v1/tasks/{task_id}/progress` |
+| Result | `GET /v1/tasks/{task_id}/result` |
+| Cancel | `POST /v1/tasks/{task_id}/cancel` |
+| Rerun | `POST /v1/tasks/{task_id}/rerun` |
+
+Submit one task, optionally waiting for existing task IDs:
+
+```json
+{
+  "language": "python",
+  "source": "def main(value: int):\n    return value * 2\n",
+  "args": {"value": 21},
+  "depends_on": ["EXISTING_TASK_ID"],
+  "dependency_timeout_seconds": 3600,
+  "retry": {"attempts": 2, "delay_seconds": 5},
+  "timeout_seconds": 300,
+  "callback_url": "https://example.internal/task-callback"
+}
+```
+
+Submit `A -> [B, C]` as one workflow:
+
+```json
+{
+  "tasks": [
+    {"key": "a", "language": "python", "source": "def main(): return 1"},
+    {"key": "b", "language": "python", "source": "def main(): return 2", "depends_on": ["a"]},
+    {"key": "c", "language": "bash", "source": "main() { echo 3; }", "depends_on": ["a"]}
+  ]
+}
+```
+
+Dependencies inside a workflow are task keys. Top-level `depends_on` values are
+IDs returned by earlier Funmill submissions. The Windmill backend checks those
+dependencies in short jobs separated by Flow sleeps, so waiting does not hold a
+worker process. Failure or cancellation of a dependency fails the waiting task.
+Workflow results and callback payloads are objects keyed by every workflow task
+key. Each topological layer is a synchronization barrier; tasks in the same
+layer run in parallel.
+
+Callbacks contain `task_id`, `status`, and `payload`; success and failure
+delivery retry three times. Delivery is at least once, so callback receivers
+must be idempotent.
+
+## Backends
+
+The public contract is `TaskBackend` in `src/funmill/backends/base.py`. Backend
+selection uses `FUNMILL_BACKEND`; registration lives in
+`src/funmill/backends/__init__.py`, following the same driver pattern as
+`fundrive`. Each third-party adapter lives in its own directory, such as
+`src/funmill/backends/windmill/`.
+
+Changing the backend does not change `/v1`, but it does not migrate old jobs or
+their IDs. Add a Funmill-owned ID mapping database only when jobs must remain
+queryable after a live backend migration.
+
+## Operations
+
+```bash
+funmill services
+funmill install windmill
+funmill start windmill
+funmill start
+```
+
+Both start commands run in the foreground and stop normally with `Ctrl+C`.
+Use systemd or an existing process manager for long-running deployment. Add
+TLS, PostgreSQL backups, callback egress restrictions, and a secrets manager
+before network exposure.

funmill-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+funmill/__init__.py,sha256=8nPJr4q1cpkaKWSURBmqUYnzF1ZFtnP1e3dZUT6OloA,687
+funmill/api.py,sha256=y9B6Q6SH0P1ysBaIkwlUjVvFZBfo2t8vvBA7Ajz80Oo,3094
+funmill/cli.py,sha256=nhjz6IOA9yJqViP-eoW6zukJaBsBz4uwV8DUwt8IWHU,1980
+funmill/models.py,sha256=c0R-gJi2Tfo8TZKDz-Gwmd5Qd4fGmrNE_n5AjV2jmzM,3756
+funmill/backends/__init__.py,sha256=0bpElxJzkCbD13WqujfR_ojG-hGVLMaxvauJ2WvXy5Y,1000
+funmill/backends/base.py,sha256=2_dv5BXEzq8h5WV0lEtk7ccbjzvsrEDnFA4tcJuajEA,1066
+funmill/backends/windmill/README.md,sha256=IXAHqgYwbb_Al7i_Y7mmimtVkTr76MNavIudQg5LofQ,2334
+funmill/backends/windmill/__init__.py,sha256=-0K_z4FRTOxl-gNlBpU3zUIhbzyqMVUcuqUh9SNwZsI,13758
+funmill/backends/windmill/service.py,sha256=hYPC3ZMKLKyqliPVEACUMRLqmeybuij5-luviLVfbpw,2647
+funmill-0.1.1.dist-info/METADATA,sha256=XEkJuyrw4nyyHvxXLGkfQOPTvenPKLQwm8mpqNodHRg,4881
+funmill-0.1.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+funmill-0.1.1.dist-info/entry_points.txt,sha256=EIJo5giXw8ZTlQcpPjbzEiG9A1qaLOd4eiBXHE6fYPE,45
+funmill-0.1.1.dist-info/RECORD,,

funmill-0.1.1.dist-info/WHEEL

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

funmill-0.1.1.dist-info/entry_points.txt

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