runrail 0.3.1__py3-none-any.whl

runrail/__init__.py

@@ -0,0 +1,4 @@
+"""RunRail workflow control plane."""
+
+__version__ = "0.1.0"
+

runrail/api/__init__.py

@@ -0,0 +1 @@
+

runrail/api/app.py

@@ -0,0 +1,52 @@
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from runrail.api.routes_resources import router as resources_router
+from runrail.api.routes_runs import router as runs_router
+from runrail.api.routes_workflows import router as workflows_router
+from runrail.api.routes_ws import router as ws_router
+from runrail.api.ws import manager as ws_manager
+from runrail.db import init_db
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    import asyncio
+    ws_manager.set_loop(asyncio.get_running_loop())
+    init_db()
+    yield
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="RunRail", version="0.3.1", lifespan=lifespan)
+    app.include_router(ws_router)
+    app.include_router(resources_router); app.include_router(workflows_router); app.include_router(runs_router)
+
+    @app.get("/api/health")
+    def health(): return {"status": "ok", "service": "runrail"}
+
+    static = Path(__file__).parents[1] / "web" / "static"
+    assets = static / "assets"
+    if assets.is_dir(): app.mount("/assets", StaticFiles(directory=assets), name="assets")
+
+    @app.get("/{path:path}", include_in_schema=False)
+    def frontend(path: str):
+        # Unknown API paths must not fall through to the SPA index page.
+        if path == "api" or path.startswith("api/"):
+            raise HTTPException(404, "Not found")
+        if path:
+            requested = (static / path).resolve()
+            # Confine file serving to the static directory (no path traversal).
+            if requested.is_relative_to(static.resolve()) and requested.is_file():
+                return FileResponse(requested)
+        index = static / "index.html"
+        if index.is_file(): return FileResponse(index)
+        return {"message": "RunRail API is running; frontend assets are not built."}
+    return app
+
+
+app = create_app()

runrail/api/crud.py

@@ -0,0 +1,75 @@
+from datetime import date, timedelta
+from typing import Any
+
+from fastapi import HTTPException
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from runrail.models import Environment, EnvironmentStatus, TriggerType, Workflow, WorkflowRun
+
+
+def save(db: Session, obj):
+    try:
+        db.add(obj)
+        db.commit()
+        db.refresh(obj)
+        return obj
+    except IntegrityError as exc:
+        db.rollback()
+        raise HTTPException(409, "A record with that name already exists") from exc
+
+
+def get_or_404(db: Session, model, object_id: int):
+    obj = db.get(model, object_id)
+    if obj is None:
+        raise HTTPException(404, f"{model.__name__} not found")
+    return obj
+
+
+def apply_update(obj, data: dict[str, Any]):
+    for key, value in data.items():
+        setattr(obj, key, value)
+    return obj
+
+
+def ensure_environment_ready(db: Session, environment_id: int | None) -> None:
+    if environment_id is None:
+        return
+    environment = get_or_404(db, Environment, environment_id)
+    if environment.status not in (EnvironmentStatus.ready, EnvironmentStatus.degraded):
+        raise HTTPException(
+            409,
+            f"Environment '{environment.name}' is not ready: "
+            f"{environment.last_error or environment.status.value}",
+        )
+
+
+def create_run(db: Session, workflow: Workflow, trigger: TriggerType, params=None, run_key=None):
+    return save(db, WorkflowRun(
+        workflow_id=workflow.id, status="queued", trigger_type=trigger,
+        parameters_json=params or {}, run_key=run_key,
+    ))
+
+
+def create_backfill(db: Session, workflow: Workflow, start: date, end: date, params=None):
+    if end < start:
+        raise HTTPException(400, "Backfill 'to' date must be on or after 'from' date")
+    existing = set(db.scalars(select(WorkflowRun.run_key).where(
+        WorkflowRun.run_key.like(f"backfill:{workflow.id}:%")
+    )))
+    runs = []
+    day = start
+    while day <= end:
+        key = f"backfill:{workflow.id}:{day.isoformat()}"
+        if key not in existing:
+            values = dict(params or {})
+            values["ds"] = day.isoformat()
+            runs.append(WorkflowRun(workflow_id=workflow.id, trigger_type=TriggerType.backfill,
+                                    status="queued", parameters_json=values, run_key=key))
+        day += timedelta(days=1)
+    db.add_all(runs)
+    db.commit()
+    for run in runs:
+        db.refresh(run)
+    return runs

runrail/api/routes_resources.py

@@ -0,0 +1,202 @@
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from runrail.api.crud import apply_update, ensure_environment_ready, get_or_404, save
+from runrail.config import get_settings
+from runrail.db import get_db
+from runrail.environments import (
+    managed_environment_path,
+    remove_managed_root,
+    validate_external,
+    validate_package_specs,
+)
+from runrail.models import Environment, EnvironmentStatus, EnvironmentType, Project
+from runrail.schemas import (
+    EnvironmentIn,
+    EnvironmentOut,
+    EnvironmentRebuild,
+    EnvironmentUpdate,
+    ProjectIn,
+    ProjectOut,
+)
+
+router = APIRouter(prefix="/api")
+
+
+@router.get("/filesystem")
+def browse_filesystem(
+    path: str | None = None,
+    mode: str = Query("all", pattern="^(all|files|directories)$"),
+):
+    """Browse the configured local root for project and task path selection."""
+    root = get_settings().browse_root.expanduser().resolve()
+    target = Path(path).expanduser().resolve() if path else root
+    if target != root and root not in target.parents:
+        raise HTTPException(403, f"Path must be inside {root}")
+    if not target.is_dir():
+        raise HTTPException(404, "Directory not found")
+    try:
+        children = sorted(target.iterdir(), key=lambda item: (not item.is_dir(), item.name.lower()))
+    except PermissionError as exc:
+        raise HTTPException(403, "Directory cannot be read") from exc
+    entries = []
+    for item in children:
+        try:
+            is_dir = item.is_dir()
+        except OSError:
+            continue
+        if item.name.startswith("."):
+            continue
+        if mode == "directories" and not is_dir:
+            continue
+        entries.append({"name": item.name, "path": str(item), "is_directory": is_dir})
+    return {
+        "root": str(root),
+        "path": str(target),
+        "parent": str(target.parent) if target != root else None,
+        "entries": entries,
+    }
+
+
+@router.get("/projects", response_model=list[ProjectOut])
+def list_projects(db: Session = Depends(get_db)):
+    return db.scalars(select(Project).order_by(Project.name)).all()
+
+
+@router.post("/projects", response_model=ProjectOut, status_code=201)
+def create_project(data: ProjectIn, db: Session = Depends(get_db)):
+    ensure_environment_ready(db, data.default_environment_id)
+    return save(db, Project(**data.model_dump()))
+
+
+@router.get("/projects/{object_id}", response_model=ProjectOut)
+def get_project(object_id: int, db: Session = Depends(get_db)):
+    return get_or_404(db, Project, object_id)
+
+
+@router.put("/projects/{object_id}", response_model=ProjectOut)
+def update_project(object_id: int, data: ProjectIn, db: Session = Depends(get_db)):
+    ensure_environment_ready(db, data.default_environment_id)
+    return save(db, apply_update(get_or_404(db, Project, object_id), data.model_dump()))
+
+
+@router.delete("/projects/{object_id}", status_code=204)
+def delete_project(object_id: int, db: Session = Depends(get_db)):
+    db.delete(get_or_404(db, Project, object_id)); db.commit()
+    return Response(status_code=204)
+
+
+@router.get("/environments", response_model=list[EnvironmentOut])
+def list_environments(db: Session = Depends(get_db)):
+    return db.scalars(select(Environment).order_by(Environment.name)).all()
+
+
+@router.post("/environments", response_model=EnvironmentOut, status_code=201)
+def create_environment(data: EnvironmentIn, db: Session = Depends(get_db)):
+    if db.scalar(select(Environment.id).where(Environment.name == data.name)) is not None:
+        raise HTTPException(409, "An environment with that name already exists")
+    if data.create_venv and data.env_type != EnvironmentType.python:
+        raise HTTPException(400, "Managed environments must use the Python environment type")
+    packages = data.packages
+    if data.create_venv:
+        try:
+            packages = validate_package_specs(data.packages)  # fail fast, not mid-build
+        except ValueError as exc:
+            raise HTTPException(400, str(exc)) from exc
+    values = data.model_dump(exclude={"create_venv", "packages", "base_executable"})
+    environment = Environment(
+        **values,
+        managed=data.create_venv,
+        status=EnvironmentStatus.creating if data.create_venv else EnvironmentStatus.ready,
+        base_executable=data.base_executable,
+        packages_json=packages,
+    )
+    if data.create_venv:
+        return save(db, environment)
+    try:
+        validate_external(environment)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    return save(db, environment)
+
+
+@router.get("/environments/{object_id}", response_model=EnvironmentOut)
+def get_environment(object_id: int, db: Session = Depends(get_db)):
+    return get_or_404(db, Environment, object_id)
+
+
+@router.put("/environments/{object_id}", response_model=EnvironmentOut)
+def update_environment(object_id: int, data: EnvironmentUpdate, db: Session = Depends(get_db)):
+    environment = get_or_404(db, Environment, object_id)
+    if environment.status in (EnvironmentStatus.creating, EnvironmentStatus.building):
+        raise HTTPException(409, "Environment cannot be edited while a build is in progress")
+    values = data.model_dump(exclude_unset=True)
+    if values.get("env_type") is None:
+        values.pop("env_type", None)
+    if environment.managed:
+        values = {
+            key: value for key, value in values.items()
+            if key in {"name", "description", "env_vars_json"}
+        }
+    apply_update(environment, values)
+    if environment.managed:
+        return save(db, environment)
+    try:
+        validate_external(environment)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    return save(db, environment)
+
+
+@router.post("/environments/{object_id}/rebuild", response_model=EnvironmentOut)
+def rebuild_environment(
+    object_id: int, data: EnvironmentRebuild, db: Session = Depends(get_db)
+):
+    environment = get_or_404(db, Environment, object_id)
+    if not environment.managed:
+        raise HTTPException(400, "Only managed environments can be rebuilt")
+    if environment.status in (EnvironmentStatus.creating, EnvironmentStatus.building):
+        raise HTTPException(409, "An environment build is already in progress")
+    if data.packages is not None:
+        try:
+            environment.packages_json = validate_package_specs(data.packages)
+        except ValueError as exc:
+            raise HTTPException(400, str(exc)) from exc
+    if data.base_executable is not None:
+        environment.base_executable = data.base_executable
+    environment.status = EnvironmentStatus.creating
+    environment.last_error = None
+    return save(db, environment)
+
+
+@router.post("/environments/{object_id}/validate", response_model=EnvironmentOut)
+def validate_environment(object_id: int, db: Session = Depends(get_db)):
+    environment = get_or_404(db, Environment, object_id)
+    if environment.managed:
+        if environment.status not in (EnvironmentStatus.ready, EnvironmentStatus.degraded) or not environment.executable:
+            raise HTTPException(400, environment.last_error or "Environment is not ready")
+        return environment
+    try:
+        validate_external(environment)
+    except ValueError as exc:
+        environment.status = EnvironmentStatus.failed
+        environment.last_error = str(exc)
+        db.commit()
+        raise HTTPException(400, str(exc)) from exc
+    return save(db, environment)
+
+
+@router.delete("/environments/{object_id}", status_code=204)
+def delete_environment(object_id: int, db: Session = Depends(get_db)):
+    environment = get_or_404(db, Environment, object_id)
+    if environment.status in (EnvironmentStatus.creating, EnvironmentStatus.building):
+        raise HTTPException(409, "Environment cannot be removed while a build is in progress")
+    # Resolve the on-disk location before the ORM object is invalidated by the delete.
+    managed_root = managed_environment_path(environment) if environment.managed else None
+    db.delete(environment); db.commit()
+    if managed_root is not None:
+        remove_managed_root(managed_root)
+    return Response(status_code=204)

runrail/api/routes_runs.py

@@ -0,0 +1,193 @@
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi.responses import FileResponse, PlainTextResponse
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session, selectinload
+
+from runrail.api.crud import create_run, get_or_404
+from runrail.api.ws import manager as ws_manager
+from runrail.db import get_db
+from runrail.models import (
+    Artifact,
+    RunStatus,
+    TaskRun,
+    TaskRunStatus,
+    TriggerType,
+    Workflow,
+    WorkflowRun,
+    now,
+)
+from runrail.schemas import TaskRunOut, WorkflowRunDetail, WorkflowRunOut
+
+router = APIRouter(prefix="/api")
+
+
+@router.get("/runs", response_model=list[WorkflowRunOut])
+def list_runs(status: RunStatus | None = None, workflow_id: int | None = None,
+              limit: int = Query(100, ge=1, le=1000), db: Session = Depends(get_db)):
+    stmt = select(WorkflowRun).order_by(WorkflowRun.created_at.desc()).limit(limit)
+    if status: stmt = stmt.where(WorkflowRun.status == status)
+    if workflow_id: stmt = stmt.where(WorkflowRun.workflow_id == workflow_id)
+    return db.scalars(stmt).all()
+
+
+@router.get("/runs/{object_id}", response_model=WorkflowRunDetail)
+def get_run(object_id: int, db: Session = Depends(get_db)):
+    obj = db.scalar(select(WorkflowRun).where(WorkflowRun.id == object_id).options(
+        selectinload(WorkflowRun.task_runs).selectinload(TaskRun.task)))
+    if not obj: raise HTTPException(404, "WorkflowRun not found")
+    return obj
+
+
+@router.post("/runs/{object_id}/cancel", response_model=WorkflowRunOut)
+def cancel_run(object_id: int, db: Session = Depends(get_db)):
+    """Cancel a queued run immediately; a running run stops before its next task."""
+    run = get_or_404(db, WorkflowRun, object_id)
+    if run.status not in (RunStatus.queued, RunStatus.running):
+        raise HTTPException(409, f"Run is already {run.status.value}")
+    was_queued = run.status == RunStatus.queued
+    run.status = RunStatus.cancelled
+    if was_queued:
+        run.finished_at = now()
+        for task_run in db.scalars(select(TaskRun).where(
+                TaskRun.workflow_run_id == run.id, TaskRun.status == TaskRunStatus.queued)):
+            task_run.status = TaskRunStatus.cancelled
+    db.commit()
+    db.refresh(run)
+    ws_manager.notify({"type": "run_updated", "id": run.id})
+    return run
+
+
+@router.post("/runs/{object_id}/retry", response_model=WorkflowRunOut, status_code=201)
+def retry_run(object_id: int, db: Session = Depends(get_db)):
+    """Queue a fresh run of the same workflow with this run's parameters.
+
+    Allowed even when the workflow is disabled/auto-paused: 'enabled' only
+    gates the scheduler, and retrying is how you verify a fix before unpausing.
+    """
+    source = get_or_404(db, WorkflowRun, object_id)
+    if source.status in (RunStatus.queued, RunStatus.running):
+        raise HTTPException(409, "Run is still in progress")
+    workflow = get_or_404(db, Workflow, source.workflow_id)
+    run = create_run(db, workflow, TriggerType.manual, dict(source.parameters_json or {}))
+    ws_manager.notify({"type": "run_created", "id": run.id, "workflow_id": run.workflow_id})
+    return run
+
+
+@router.get("/task-runs/{object_id}", response_model=TaskRunOut)
+def get_task_run(object_id: int, db: Session = Depends(get_db)):
+    return get_or_404(db, TaskRun, object_id)
+
+
+def log_response(task_run: TaskRun, attr: str, tail_bytes: int | None = None):
+    path = getattr(task_run, attr)
+    if not path: return PlainTextResponse("", status_code=200)
+    file = Path(path)
+    if not file.is_file(): raise HTTPException(404, "Log file not found")
+    if tail_bytes is not None:
+        # Serve only the end of the file so huge logs never sit in API memory.
+        size = file.stat().st_size
+        with file.open("rb") as handle:
+            if size > tail_bytes:
+                handle.seek(size - tail_bytes)
+            data = handle.read()
+        return PlainTextResponse(data.decode("utf-8", errors="replace"))
+    return PlainTextResponse(file.read_text(errors="replace"))
+
+
+@router.get("/task-runs/{object_id}/stdout")
+def stdout(object_id: int, tail_bytes: int | None = Query(None, ge=1),
+           db: Session = Depends(get_db)):
+    return log_response(get_or_404(db, TaskRun, object_id), "stdout_log_path", tail_bytes)
+
+
+@router.get("/task-runs/{object_id}/stderr")
+def stderr(object_id: int, tail_bytes: int | None = Query(None, ge=1),
+           db: Session = Depends(get_db)):
+    return log_response(get_or_404(db, TaskRun, object_id), "stderr_log_path", tail_bytes)
+
+
+@router.get("/stats/summary")
+def stats_summary(db: Session = Depends(get_db)):
+    """Dashboard headline metrics, aggregated in SQL.
+
+    The UI previously derived these from a capped /runs fetch, which silently
+    under-counts once a workflow runs often enough to overflow the limit (a
+    5-minute schedule is ~288 runs/day). Aggregating in the database keeps the
+    numbers correct at any volume.
+    """
+    now_utc = datetime.now(timezone.utc).replace(tzinfo=None)
+    since_24h = now_utc - timedelta(days=1)
+    since_7d = now_utc - timedelta(days=7)
+
+    def count(*conditions) -> int:
+        return db.scalar(select(func.count()).select_from(WorkflowRun).where(*conditions)) or 0
+
+    running = count(WorkflowRun.status == RunStatus.running)
+    queued = count(WorkflowRun.status == RunStatus.queued)
+    done_7d = count(WorkflowRun.created_at >= since_7d,
+                    WorkflowRun.status.in_((RunStatus.success, RunStatus.failed)))
+    success_7d = count(WorkflowRun.created_at >= since_7d, WorkflowRun.status == RunStatus.success)
+    avg_24h = db.scalar(
+        select(func.avg(WorkflowRun.duration_seconds)).where(
+            WorkflowRun.created_at >= since_24h, WorkflowRun.duration_seconds.is_not(None)))
+    return {
+        "running": running,
+        "queued": queued,
+        "live": running + queued,
+        "runs_24h": count(WorkflowRun.created_at >= since_24h),
+        "succeeded_24h": count(WorkflowRun.created_at >= since_24h,
+                               WorkflowRun.status == RunStatus.success),
+        "failed_24h": count(WorkflowRun.created_at >= since_24h,
+                            WorkflowRun.status == RunStatus.failed),
+        "avg_duration_24h": float(avg_24h) if avg_24h is not None else None,
+        "done_7d": done_7d,
+        "success_7d": success_7d,
+        "success_rate_7d": round(success_7d / done_7d * 100) if done_7d else None,
+    }
+
+
+@router.get("/stats/daily")
+def daily_stats(days: int = Query(112, ge=1, le=366), workflow_id: int | None = None,
+                db: Session = Depends(get_db)):
+    """Per-day run counts by outcome, for activity heatmaps."""
+    since = datetime.now(timezone.utc).replace(tzinfo=None) - timedelta(days=days)
+    day = func.date(WorkflowRun.created_at)
+    stmt = (select(day.label("day"), WorkflowRun.status, func.count())
+            .where(WorkflowRun.created_at >= since)
+            .group_by(day, WorkflowRun.status))
+    if workflow_id:
+        stmt = stmt.where(WorkflowRun.workflow_id == workflow_id)
+    buckets: dict[str, dict] = {}
+    for value, status, count in db.execute(stmt):
+        entry = buckets.setdefault(str(value), {"date": str(value), "success": 0, "failed": 0, "other": 0})
+        key = getattr(status, "value", str(status))
+        if key in ("success", "failed"):
+            entry[key] += count
+        else:
+            entry["other"] += count
+    return sorted(buckets.values(), key=lambda item: item["date"])
+
+
+@router.get("/artifacts")
+def list_artifacts(workflow_run_id: int | None = None, task_run_id: int | None = None,
+                   limit: int = Query(200, ge=1, le=1000), db: Session = Depends(get_db)):
+    stmt = select(Artifact).order_by(Artifact.created_at.desc()).limit(limit)
+    if workflow_run_id: stmt = stmt.where(Artifact.workflow_run_id == workflow_run_id)
+    if task_run_id: stmt = stmt.where(Artifact.task_run_id == task_run_id)
+    return db.scalars(stmt).all()
+
+
+@router.get("/artifacts/{object_id}")
+def get_artifact(object_id: int, db: Session = Depends(get_db)):
+    return get_or_404(db, Artifact, object_id)
+
+
+@router.get("/artifacts/{object_id}/download")
+def download_artifact(object_id: int, db: Session = Depends(get_db)):
+    artifact = get_or_404(db, Artifact, object_id)
+    path = Path(artifact.path)
+    if not path.is_file(): raise HTTPException(404, "Artifact file not found")
+    return FileResponse(path, filename=artifact.name)