hof-engine 0.1.0__py3-none-any.whl

hof/__init__.py

@@ -0,0 +1,35 @@
+"""hof-engine: Full-stack Python + React framework."""
+
+from hof.app import HofApp
+from hof.config import Config
+from hof.core.registry import registry
+from hof.core.types import types
+from hof.cron.scheduler import cron
+from hof.db.table import Column, ForeignKey, Table
+from hof.errors import HofError
+from hof.flows.flow import Flow
+from hof.flows.human import human_node
+from hof.flows.node import node
+from hof.functions import function
+from hof.logging_config import configure_logging
+from hof.scaffold import get_project_files
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HofApp",
+    "Config",
+    "configure_logging",
+    "Table",
+    "Column",
+    "ForeignKey",
+    "Flow",
+    "node",
+    "human_node",
+    "function",
+    "cron",
+    "types",
+    "registry",
+    "HofError",
+    "get_project_files",
+]

hof/api/__init__.py

@@ -0,0 +1 @@
+"""API layer: FastAPI server and auto-generated routes."""

hof/api/auth.py

@@ -0,0 +1,228 @@
+"""Authentication and role-based access control for the hof API.
+
+Supported authentication methods (tried in order):
+1. Bearer JWT token  — ``Authorization: Bearer <token>``
+2. API key header    — ``X-API-Key: <key>``
+3. HTTP Basic auth   — username / password
+
+JWT tokens are issued via ``POST /api/auth/token`` and carry the user's roles
+as a claim.  When no credentials are configured, all requests are allowed as
+``anonymous``.
+
+Roles
+-----
+Roles are configured in ``hof.config.py``:
+
+    config = Config(
+        admin_username="admin",
+        admin_password="secret",
+        user_roles={
+            "admin": ["admin", "viewer"],
+            "readonly": ["viewer"],
+        },
+    )
+
+Built-in roles:
+- ``admin``  — full access to all endpoints
+- ``viewer`` — read-only access (GET requests only)
+
+Custom roles can be defined and checked with ``require_role()``.
+"""
+
+from __future__ import annotations
+
+import secrets
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+
+from fastapi import Depends, HTTPException, Request, Security, status
+from fastapi.security import (
+    APIKeyHeader,
+    HTTPBasic,
+    HTTPBasicCredentials,
+    OAuth2PasswordBearer,
+    OAuth2PasswordRequestForm,
+)
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from hof.config import Config
+
+_config: Config | None = None
+
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+basic_auth = HTTPBasic(auto_error=False)
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/token", auto_error=False)
+
+
+# ---------------------------------------------------------------------------
+# Setup
+# ---------------------------------------------------------------------------
+
+
+def setup_auth(app: FastAPI, config: Config) -> None:
+    """Configure authentication on the FastAPI app and register the token endpoint."""
+    global _config
+    _config = config
+
+    from fastapi import APIRouter
+
+    auth_router = APIRouter()
+
+    @auth_router.post("/token")
+    async def login(form_data: OAuth2PasswordRequestForm = Depends()) -> dict:
+        """Issue a JWT access token for valid credentials."""
+        cfg = _config
+        if cfg is None:
+            raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "Auth not configured")
+
+        username_ok = secrets.compare_digest(form_data.username, cfg.admin_username)
+        password_ok = secrets.compare_digest(form_data.password, cfg.admin_password)
+
+        if not (username_ok and password_ok):
+            raise HTTPException(
+                status.HTTP_401_UNAUTHORIZED,
+                detail="Incorrect username or password",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        roles = cfg.user_roles.get(form_data.username, ["admin"])
+        token = _create_access_token(
+            subject=form_data.username,
+            roles=roles,
+            secret=cfg.jwt_secret_key or cfg.admin_password,
+            algorithm=cfg.jwt_algorithm,
+            expires_minutes=cfg.jwt_access_token_expire_minutes,
+        )
+        return {"access_token": token, "token_type": "bearer"}
+
+    app.include_router(auth_router, prefix="/api/auth", tags=["auth"])
+
+
+# ---------------------------------------------------------------------------
+# JWT helpers
+# ---------------------------------------------------------------------------
+
+
+def _create_access_token(
+    *,
+    subject: str,
+    roles: list[str],
+    secret: str,
+    algorithm: str,
+    expires_minutes: int,
+) -> str:
+    try:
+        from jose import jwt
+    except ImportError:
+        raise ImportError("python-jose[cryptography] is required for JWT auth.")
+
+    expire = datetime.now(UTC) + timedelta(minutes=expires_minutes)
+    payload = {
+        "sub": subject,
+        "roles": roles,
+        "exp": expire,
+    }
+    return jwt.encode(payload, secret, algorithm=algorithm)
+
+
+def _decode_jwt(token: str) -> dict[str, Any] | None:
+    if _config is None:
+        return None
+    secret = _config.jwt_secret_key or _config.admin_password
+    if not secret:
+        return None
+    try:
+        from jose import jwt
+
+        return jwt.decode(token, secret, algorithms=[_config.jwt_algorithm])
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Dependency: verify authentication
+# ---------------------------------------------------------------------------
+
+
+async def verify_auth(
+    request: Request,
+    bearer_token: str | None = Depends(oauth2_scheme),
+    api_key: str | None = Security(api_key_header),
+    credentials: HTTPBasicCredentials | None = Depends(basic_auth),
+) -> str:
+    """Verify authentication via JWT Bearer token, API key, or Basic auth.
+
+    Returns the authenticated identity (username or ``"api-key"``).
+    When no credentials are configured, returns ``"anonymous"``.
+    """
+    if _config is None:
+        return "anonymous"
+
+    if not _config.admin_password and not _config.api_key and not _config.jwt_secret_key:
+        return "anonymous"
+
+    # 1. JWT Bearer token
+    if bearer_token:
+        payload = _decode_jwt(bearer_token)
+        if payload and "sub" in payload:
+            return payload["sub"]
+
+    # 2. API key
+    if api_key and _config.api_key:
+        if secrets.compare_digest(api_key, _config.api_key):
+            return "api-key"
+
+    # 3. HTTP Basic auth
+    if credentials and _config.admin_password:
+        username_ok = secrets.compare_digest(credentials.username, _config.admin_username)
+        password_ok = secrets.compare_digest(credentials.password, _config.admin_password)
+        if username_ok and password_ok:
+            return credentials.username
+
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid or missing credentials",
+        headers={"WWW-Authenticate": 'Bearer, Basic realm="hof"'},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Dependency: require specific role(s)
+# ---------------------------------------------------------------------------
+
+
+def require_role(*required_roles: str):
+    """FastAPI dependency factory that enforces role-based access.
+
+    Usage:
+        @router.delete("/{id}")
+        async def delete_item(user: str = Depends(require_role("admin"))):
+            ...
+    """
+
+    async def _check_role(user: str = Depends(verify_auth)) -> str:
+        if _config is None or not required_roles:
+            return user
+
+        # API key and anonymous get admin-level access when no RBAC is configured
+        if user in ("api-key", "anonymous"):
+            return user
+
+        user_role_list = _config.user_roles.get(user, [])
+        if not any(r in user_role_list for r in required_roles):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Role(s) required: {', '.join(required_roles)}",
+            )
+        return user
+
+    return _check_role
+
+
+def get_user_roles(username: str) -> list[str]:
+    """Return the roles assigned to a user."""
+    if _config is None:
+        return []
+    return _config.user_roles.get(username, [])

hof/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API route modules."""

hof/api/routes/admin.py

@@ -0,0 +1,89 @@
+"""Admin API routes for the dashboard."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+
+from hof.api.auth import verify_auth
+from hof.core.registry import registry
+from hof.flows.state import execution_store
+
+router = APIRouter()
+
+
+@router.get("/overview")
+async def admin_overview(user: str = Depends(verify_auth)) -> dict:
+    """Dashboard overview: counts of all registered components and recent activity."""
+    recent_executions = execution_store.list_executions(limit=10)
+
+    return {
+        "registry": registry.summary(),
+        "tables": list(registry.tables.keys()),
+        "functions": list(registry.functions.keys()),
+        "flows": list(registry.flows.keys()),
+        "cron_jobs": list(registry.cron_jobs.keys()),
+        "recent_executions": [e.to_dict() for e in recent_executions],
+    }
+
+
+@router.get("/flows/{flow_name}/dag")
+async def flow_dag(
+    flow_name: str,
+    user: str = Depends(verify_auth),
+) -> dict:
+    """Get the DAG structure for rendering in the flow viewer."""
+    flow = registry.get_flow(flow_name)
+    if flow is None:
+        return {"error": f"Flow '{flow_name}' not found"}
+
+    nodes = []
+    edges = []
+
+    for name, meta in flow.nodes.items():
+        nodes.append(
+            {
+                "id": name,
+                "label": name,
+                "description": meta.fn.__doc__ or "",
+                "is_human": meta.is_human,
+                "human_ui": meta.human_ui,
+                "tags": meta.tags,
+            }
+        )
+        for dep in meta.depends_on:
+            edges.append({"source": dep, "target": name})
+
+    execution_order = flow.get_execution_order()
+
+    return {
+        "name": flow_name,
+        "nodes": nodes,
+        "edges": edges,
+        "execution_order": execution_order,
+    }
+
+
+@router.get("/pending-actions")
+async def pending_actions(user: str = Depends(verify_auth)) -> list[dict]:
+    """List all pending human-in-the-loop actions."""
+    executions = execution_store.list_executions(status="waiting_for_human", limit=50)
+    actions = []
+
+    for execution in executions:
+        for ns in execution.node_states:
+            if ns.status == "waiting_for_human":
+                flow = registry.get_flow(execution.flow_name)
+                node_meta = flow.nodes.get(ns.node_name) if flow else None
+
+                actions.append(
+                    {
+                        "execution_id": execution.id,
+                        "flow_name": execution.flow_name,
+                        "node_name": ns.node_name,
+                        "ui_component": node_meta.human_ui if node_meta else None,
+                        "input_data": ns.input_data,
+                        "started_at": ns.started_at.isoformat() if ns.started_at else None,
+                    }
+                )
+
+    return actions

hof/api/routes/flows.py

@@ -0,0 +1,100 @@
+"""Flow management and execution routes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from hof.api.auth import verify_auth
+from hof.core.registry import registry
+from hof.flows.state import execution_store
+
+router = APIRouter()
+
+
+@router.get("")
+async def list_flows(user: str = Depends(verify_auth)) -> list[dict]:
+    """List all registered flow definitions."""
+    return [flow.to_dict() for flow in registry.flows.values()]
+
+
+@router.post("/{flow_name}/run")
+async def run_flow(
+    flow_name: str,
+    body: dict[str, Any] | None = None,
+    user: str = Depends(verify_auth),
+) -> dict:
+    """Trigger a new flow execution."""
+    flow = registry.get_flow(flow_name)
+    if flow is None:
+        raise HTTPException(404, f"Flow '{flow_name}' not found")
+
+    input_data = body or {}
+    execution = flow.run(**input_data)
+    return execution.to_dict()
+
+
+@router.get("/{flow_name}/executions")
+async def list_executions(
+    flow_name: str,
+    status: str | None = None,
+    limit: int = 20,
+    user: str = Depends(verify_auth),
+) -> list[dict]:
+    """List executions for a flow."""
+    flow = registry.get_flow(flow_name)
+    if flow is None:
+        raise HTTPException(404, f"Flow '{flow_name}' not found")
+
+    executions = execution_store.list_executions(flow_name=flow_name, status=status, limit=limit)
+    return [e.to_dict() for e in executions]
+
+
+@router.get("/executions/{execution_id}")
+async def get_execution(
+    execution_id: str,
+    user: str = Depends(verify_auth),
+) -> dict:
+    """Get details of a flow execution."""
+    execution = execution_store.get_execution(execution_id)
+    if execution is None:
+        raise HTTPException(404, f"Execution '{execution_id}' not found")
+    return execution.to_dict()
+
+
+@router.post("/executions/{execution_id}/cancel")
+async def cancel_execution(
+    execution_id: str,
+    user: str = Depends(verify_auth),
+) -> dict:
+    """Cancel a running execution."""
+    execution_store.update_status(execution_id, "cancelled")
+    return {"cancelled": True, "id": execution_id}
+
+
+@router.post("/executions/{execution_id}/nodes/{node_name}/submit")
+async def submit_human_input(
+    execution_id: str,
+    node_name: str,
+    body: dict[str, Any],
+    user: str = Depends(verify_auth),
+) -> dict:
+    """Submit human input for a waiting node."""
+    execution = execution_store.get_execution(execution_id)
+    if execution is None:
+        raise HTTPException(404, f"Execution '{execution_id}' not found")
+
+    flow = registry.get_flow(execution.flow_name)
+    if flow is None:
+        raise HTTPException(404, f"Flow '{execution.flow_name}' not found")
+
+    from hof.flows.executor import FlowExecutor
+
+    executor = FlowExecutor(flow)
+    result = executor.resume_after_human(execution_id, node_name, body)
+
+    if result is None:
+        raise HTTPException(400, "Could not submit input (node may not be waiting)")
+
+    return result.to_dict()

hof/api/routes/functions.py

@@ -0,0 +1,98 @@
+"""Auto-generated routes for registered functions."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Security
+from fastapi.security import HTTPBasicCredentials
+from pydantic import ValidationError
+
+from hof.api.auth import api_key_header, basic_auth, oauth2_scheme, verify_auth
+from hof.core.registry import registry
+from hof.db.schemas import build_function_input_schema
+
+router = APIRouter()
+
+
+async def _optional_auth(
+    request: Request,
+    bearer_token: str | None = Depends(oauth2_scheme),
+    api_key: str | None = Security(api_key_header),
+    credentials: HTTPBasicCredentials | None = Depends(basic_auth),
+) -> str:
+    """Resolve auth only when the target function is not public.
+
+    Public functions (``@function(public=True)``) skip authentication entirely.
+    """
+    function_name = request.path_params.get("function_name")
+    if function_name:
+        meta = registry.get_function(function_name)
+        if meta and meta.public:
+            return "anonymous"
+    return await verify_auth(
+        request,
+        bearer_token=bearer_token,
+        api_key=api_key,
+        credentials=credentials,
+    )
+
+
+@router.get("")
+async def list_functions(user: str = Depends(verify_auth)) -> list[dict]:
+    """List all registered functions."""
+    return [meta.to_dict() for meta in registry.functions.values()]
+
+
+@router.post("/{function_name}")
+async def call_function(
+    function_name: str,
+    body: dict[str, Any] | None = None,
+    user: str = Depends(_optional_auth),
+) -> dict:
+    """Execute a registered function. Input is validated against the function signature."""
+    meta = registry.get_function(function_name)
+    if meta is None:
+        raise HTTPException(404, f"Function '{function_name}' not found")
+
+    kwargs = body or {}
+
+    if meta.parameters:
+        schema = build_function_input_schema(meta)
+        try:
+            validated = schema(**kwargs)
+        except ValidationError as exc:
+            raise HTTPException(422, detail=exc.errors())
+        kwargs = validated.model_dump(exclude_none=False)
+
+    start = time.monotonic()
+
+    try:
+        if meta.is_async:
+            result = await meta.fn(**kwargs)
+        else:
+            result = meta.fn(**kwargs)
+    except Exception as exc:
+        raise HTTPException(500, f"Function error: {exc}")
+
+    duration_ms = int((time.monotonic() - start) * 1000)
+
+    return {
+        "result": result,
+        "duration_ms": duration_ms,
+        "function": function_name,
+    }
+
+
+@router.get("/{function_name}/schema")
+async def get_function_schema(
+    function_name: str,
+    user: str = Depends(verify_auth),
+) -> dict:
+    """Get the input/output schema of a function."""
+    meta = registry.get_function(function_name)
+    if meta is None:
+        raise HTTPException(404, f"Function '{function_name}' not found")
+
+    return meta.to_dict()