flowmine-studio 0.1.0__py3-none-any.whl

flowmine_studio/api/audit.py

@@ -0,0 +1,27 @@
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy.orm import Session
+
+from flowmine_studio.api.models import AuditLog
+
+
+def audit(
+    db: Session,
+    action: str,
+    user_id: UUID | None = None,
+    workspace_id: UUID | None = None,
+    object_type: str | None = None,
+    object_id: UUID | None = None,
+    detail: dict[str, Any] | None = None,
+) -> None:
+    db.add(
+        AuditLog(
+            user_id=user_id,
+            workspace_id=workspace_id,
+            action=action,
+            object_type=object_type,
+            object_id=object_id,
+            detail=detail,
+        )
+    )

flowmine_studio/api/auth/providers.py

@@ -0,0 +1,36 @@
+"""Auth providers. CE ships local username/password auth with workspace RBAC."""
+from typing import Protocol
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from flowmine_studio.api.errors import UnauthorizedError
+from flowmine_studio.api.models import User
+from flowmine_studio.api.security import verify_password
+
+
+class AuthProvider(Protocol):
+    name: str
+
+    def authenticate(self, db: Session, username: str, password: str) -> User: ...
+
+
+class LocalProvider:
+    name = "local"
+
+    def authenticate(self, db: Session, username: str, password: str) -> User:
+        user = db.scalar(select(User).where(User.username == username))
+        if user is None or user.password_hash is None:
+            raise UnauthorizedError("Invalid username or password")
+        if not verify_password(password, user.password_hash):
+            raise UnauthorizedError("Invalid username or password")
+        if not user.is_active:
+            raise UnauthorizedError("Account is disabled")
+        return user
+
+
+_PROVIDERS: dict[str, AuthProvider] = {"local": LocalProvider()}
+
+
+def get_provider() -> AuthProvider:
+    return _PROVIDERS["local"]

flowmine_studio/api/cli.py

@@ -0,0 +1,71 @@
+"""The `flowmine-studio` command: zero-config launch on http://localhost:8080.
+
+First run: creates the SQLite database and artifact store in the user data
+directory, seeds the admin account (admin/admin) and the demo dataset, runs the
+demo analysis, then starts the server and opens the browser.
+"""
+import argparse
+import threading
+import webbrowser
+
+from flowmine_studio.api.config import data_dir, get_settings
+from flowmine_studio.api.logging_setup import get_logger, setup_logging
+
+log = get_logger("cli")
+
+
+def _first_run_setup() -> None:
+    from flowmine_studio.api.db import init_db
+
+    init_db()
+    from flowmine_studio.scripts.seed import main as seed_main
+
+    seed_main()
+
+
+def _open_browser(url: str) -> None:
+    try:
+        webbrowser.open(url)
+    except Exception:  # noqa: BLE001 — headless environments have no browser
+        pass
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="flowmine-studio",
+        description="FlowMine Studio — process mining. Starts the app on localhost.",
+    )
+    parser.add_argument("--host", default=None, help="bind host (default 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=None, help="port (default 8080)")
+    parser.add_argument("--no-browser", action="store_true", help="do not open the browser")
+    parser.add_argument("--no-seed", action="store_true", help="skip demo data seeding")
+    args = parser.parse_args()
+
+    setup_logging()
+    settings = get_settings()
+    host = args.host or settings.host
+    port = args.port or settings.port
+
+    log.info("data_dir", path=str(data_dir()))
+    if args.no_seed:
+        from flowmine_studio.api.db import init_db
+
+        init_db()
+    else:
+        _first_run_setup()
+
+    url = f"http://{'localhost' if host in ('0.0.0.0', '127.0.0.1') else host}:{port}"  # noqa: S104
+    print()  # noqa: T201 — deliberate console UX
+    print(f"  FlowMine Studio → {url}   (admin / admin)")  # noqa: T201
+    print(f"  Данные: {data_dir()}")  # noqa: T201
+    print()  # noqa: T201
+    if not args.no_browser:
+        threading.Timer(1.5, _open_browser, args=(url,)).start()
+
+    import uvicorn
+
+    uvicorn.run("flowmine_studio.api.main:app", host=host, port=port, log_level="warning")
+
+
+if __name__ == "__main__":
+    main()

flowmine_studio/api/config.py

@@ -0,0 +1,70 @@
+"""Settings. Zero-config by default: everything lives under the user data directory
+(~/.flowmine-studio or the OS equivalent). Every knob can be overridden with a
+STUDIO_* environment variable."""
+import secrets
+from functools import lru_cache
+from pathlib import Path
+
+from platformdirs import user_data_dir
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def data_dir() -> Path:
+    d = Path(user_data_dir("flowmine-studio", appauthor=False))
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _default_secret_key() -> str:
+    """Persist a generated key on first run so encrypted secrets survive restarts."""
+    key_file = data_dir() / "secret_key"
+    if key_file.exists():
+        return key_file.read_text().strip()
+    key = secrets.token_urlsafe(48)
+    key_file.write_text(key)
+    try:
+        key_file.chmod(0o600)
+    except OSError:  # Windows
+        pass
+    return key
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="STUDIO_")
+
+    database_url: str = ""  # default resolved to sqlite in data_dir (see resolved_database_url)
+    secret_key: str = ""  # default resolved from persisted key file
+
+    access_token_ttl_seconds: int = 900
+    refresh_token_ttl_days: int = 7
+
+    artifact_local_path: str = ""  # default resolved to data_dir/artifacts
+
+    host: str = "127.0.0.1"
+    port: int = 8080
+    upload_max_mb: int = 200
+    cors_origins: list[str] = []
+
+    job_workers: int = 2
+    jobs_sync: bool = False  # inline job execution (tests, first-run seed)
+
+    environment: str = "dev"
+
+    @property
+    def resolved_database_url(self) -> str:
+        if self.database_url:
+            return self.database_url
+        return f"sqlite:///{data_dir() / 'studio.db'}"
+
+    @property
+    def resolved_secret_key(self) -> str:
+        return self.secret_key or _default_secret_key()
+
+    @property
+    def resolved_artifact_path(self) -> str:
+        return self.artifact_local_path or str(data_dir() / "artifacts")
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

flowmine_studio/api/db.py

@@ -0,0 +1,57 @@
+from fastapi import Request
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+from flowmine_studio.api.config import get_settings
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def _engine():  # type: ignore[no-untyped-def]
+    url = get_settings().resolved_database_url
+    if url.startswith("sqlite"):
+        engine = create_engine(url, connect_args={"check_same_thread": False})
+        from sqlalchemy import event
+
+        @event.listens_for(engine, "connect")
+        def _sqlite_pragmas(dbapi_conn, _record):  # type: ignore[no-untyped-def]
+            cursor = dbapi_conn.cursor()
+            cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.execute("PRAGMA journal_mode=WAL")
+            cursor.close()
+
+        return engine
+    return create_engine(url, pool_pre_ping=True)
+
+
+_engine_instance = None
+_session_factory: sessionmaker[Session] | None = None
+
+
+def get_session_factory() -> sessionmaker[Session]:
+    global _engine_instance, _session_factory
+    if _session_factory is None:
+        _engine_instance = _engine()
+        _session_factory = sessionmaker(bind=_engine_instance, expire_on_commit=False)
+    return _session_factory
+
+
+def get_db(request: Request) -> Session:
+    """Request-scoped session. Committed/rolled back and closed by the db middleware
+    in api.main BEFORE the response is sent — never in dependency teardown, which
+    FastAPI runs after the response and which therefore races follow-up requests."""
+    db = getattr(request.state, "db", None)
+    if db is None:
+        db = get_session_factory()()
+        request.state.db = db
+    return db  # type: ignore[no-any-return]
+
+
+def init_db() -> None:
+    """Create all tables (idempotent). CE bootstraps the schema at startup."""
+    from flowmine_studio.api import models  # noqa: F401 — register tables
+
+    factory = get_session_factory()
+    Base.metadata.create_all(factory.kw["bind"])

flowmine_studio/api/dbtypes.py

@@ -0,0 +1,36 @@
+"""Dialect-agnostic column types: identical behavior on SQLite and PostgreSQL."""
+from datetime import UTC, datetime
+from typing import Any
+
+import sqlalchemy as sa
+from sqlalchemy.types import TypeDecorator
+
+
+class TZDateTime(TypeDecorator):
+    """Stores UTC-naive, returns UTC-aware — safe on SQLite, correct on Postgres."""
+
+    impl = sa.DateTime
+    cache_ok = True
+
+    def process_bind_param(self, value: datetime | None, dialect: Any) -> datetime | None:
+        if value is None:
+            return None
+        if value.tzinfo is not None:
+            value = value.astimezone(UTC).replace(tzinfo=None)
+        return value
+
+    def process_result_value(self, value: datetime | None, dialect: Any) -> datetime | None:
+        if value is None:
+            return None
+        return value.replace(tzinfo=UTC)
+
+
+def StrEnumType(py_enum: type, name: str) -> sa.Enum:  # noqa: N802 — type factory
+    """Enum stored as VARCHAR + CHECK constraint: portable across SQLite/Postgres."""
+    return sa.Enum(
+        py_enum,
+        name=name,
+        native_enum=False,
+        length=32,
+        values_callable=lambda e: [m.value for m in e],
+    )

flowmine_studio/api/deps.py

@@ -0,0 +1,65 @@
+"""FastAPI dependencies: current user, workspace resolution, RBAC guards."""
+from collections.abc import Callable
+from dataclasses import dataclass
+from uuid import UUID
+
+from fastapi import Depends, Header, Request
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from flowmine_studio.api.db import get_db
+from flowmine_studio.api.errors import ForbiddenError, UnauthorizedError
+from flowmine_studio.api.models import Membership, User, Workspace
+from flowmine_studio.api.security import decode_access_token
+from flowmine_studio.shared.enums import ROLE_ORDER, Role
+
+
+def get_current_user(request: Request, db: Session = Depends(get_db)) -> User:
+    auth = request.headers.get("Authorization", "")
+    if not auth.startswith("Bearer "):
+        raise UnauthorizedError("Missing bearer token")
+    user_id = decode_access_token(auth.removeprefix("Bearer ").strip())
+    user = db.get(User, user_id)
+    if user is None or not user.is_active:
+        raise UnauthorizedError("Unknown or disabled user")
+    return user
+
+
+@dataclass
+class WorkspaceContext:
+    user: User
+    workspace: Workspace
+    role: Role
+
+
+def get_workspace_context(
+    x_workspace: str = Header(..., description="Workspace UUID"),
+    user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> WorkspaceContext:
+    try:
+        ws_id = UUID(x_workspace)
+    except ValueError as exc:
+        raise ForbiddenError("X-Workspace must be a UUID") from exc
+    ws = db.get(Workspace, ws_id)
+    if ws is None:
+        raise ForbiddenError("Workspace not found or no access")
+    if user.is_superuser:
+        return WorkspaceContext(user=user, workspace=ws, role=Role.admin)
+    membership = db.scalar(
+        select(Membership).where(
+            Membership.user_id == user.id, Membership.workspace_id == ws_id
+        )
+    )
+    if membership is None:
+        raise ForbiddenError("Workspace not found or no access")
+    return WorkspaceContext(user=user, workspace=ws, role=membership.role)
+
+
+def require_role(minimum: Role) -> Callable[..., WorkspaceContext]:
+    def guard(ctx: WorkspaceContext = Depends(get_workspace_context)) -> WorkspaceContext:
+        if ROLE_ORDER[ctx.role] < ROLE_ORDER[minimum]:
+            raise ForbiddenError(f"Requires role '{minimum.value}' or higher")
+        return ctx
+
+    return guard

flowmine_studio/api/errors.py

@@ -0,0 +1,53 @@
+"""Typed error hierarchy mapped to the openapi error envelope by api.main handlers."""
+from typing import Any
+
+
+class StudioError(Exception):
+    code = "internal_error"
+    status = 500
+
+    def __init__(self, message: str, detail: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.detail = detail
+
+    def envelope(self) -> dict[str, Any]:
+        body: dict[str, Any] = {"code": self.code, "message": self.message}
+        if self.detail is not None:
+            body["detail"] = self.detail
+        return {"error": body}
+
+
+class NotFoundError(StudioError):
+    code = "not_found"
+    status = 404
+
+
+class ForbiddenError(StudioError):
+    code = "forbidden"
+    status = 403
+
+
+class UnauthorizedError(StudioError):
+    code = "unauthorized"
+    status = 401
+
+
+class ValidationFailed(StudioError):
+    code = "validation_error"
+    status = 422
+
+
+class ConflictError(StudioError):
+    code = "conflict"
+    status = 409
+
+
+class NotImplementedFeature(StudioError):
+    code = "not_implemented"
+    status = 501
+
+
+class ConnectorFailure(StudioError):
+    code = "connector_error"
+    status = 502

flowmine_studio/api/logging_setup.py

@@ -0,0 +1,25 @@
+"""structlog JSON logging for api and worker processes."""
+import logging
+import sys
+
+import structlog
+
+
+def setup_logging(level: int = logging.INFO) -> None:
+    logging.basicConfig(stream=sys.stdout, level=level, format="%(message)s")
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso", utc=True),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(level),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+    return structlog.get_logger(name)

flowmine_studio/api/main.py

@@ -0,0 +1,134 @@
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from flowmine_studio.api.config import get_settings
+from flowmine_studio.api.errors import StudioError
+from flowmine_studio.api.logging_setup import get_logger, setup_logging
+from flowmine_studio.api.routers import (
+    admin_users,
+    artifacts,
+    auth,
+    connections,
+    datasets,
+    health,
+    jobs,
+    projects,
+    workspaces,
+)
+
+setup_logging()
+log = get_logger("api")
+
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+def create_app() -> FastAPI:
+    from contextlib import asynccontextmanager
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):  # type: ignore[no-untyped-def]
+        from flowmine_studio.api import runner
+        from flowmine_studio.api.db import init_db
+
+        init_db()
+        yield
+        runner.shutdown()
+
+    app = FastAPI(
+        lifespan=lifespan,
+        title="FlowMine Studio API",
+        version="0.1.0",
+        openapi_url="/api/v1/openapi.json",
+        docs_url="/api/v1/docs",
+    )
+    settings = get_settings()
+    if settings.cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=settings.cors_origins,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    @app.middleware("http")
+    async def db_lifecycle(request: Request, call_next):  # type: ignore[no-untyped-def]
+        try:
+            response = await call_next(request)
+        except Exception:
+            db = getattr(request.state, "db", None)
+            if db is not None:
+                db.rollback()
+                db.close()
+            raise
+        db = getattr(request.state, "db", None)
+        if db is not None:
+            try:
+                if response.status_code < 400:
+                    db.commit()
+                else:
+                    db.rollback()
+            finally:
+                db.close()
+        return response
+
+    prefix = "/api/v1"
+    for router in (
+        health.router,
+        auth.router,
+        workspaces.router,
+        connections.router,
+        datasets.router,
+        projects.router,
+        jobs.router,
+        artifacts.router,
+        admin_users.router,
+    ):
+        app.include_router(router, prefix=prefix)
+
+    @app.exception_handler(StudioError)
+    async def studio_error_handler(request: Request, exc: StudioError) -> JSONResponse:
+        if exc.status >= 500:
+            log.error("request_failed", path=request.url.path, code=exc.code, msg=exc.message)
+        return JSONResponse(status_code=exc.status, content=exc.envelope())
+
+    # --- packaged UI: static SPA with /api passthrough ---
+    if (STATIC_DIR / "index.html").exists():
+        app.mount("/assets", StaticFiles(directory=STATIC_DIR / "assets"), name="assets")
+
+        @app.get("/{spa_path:path}", include_in_schema=False)
+        async def spa(spa_path: str):  # type: ignore[no-untyped-def]
+            if spa_path.startswith(("api/", "api")) and spa_path.split("/")[0] == "api":
+                return JSONResponse(
+                    status_code=404,
+                    content={"error": {"code": "not_found", "message": "Unknown API path"}},
+                )
+            candidate = STATIC_DIR / spa_path
+            if spa_path and candidate.is_file():
+                return FileResponse(candidate)
+            return FileResponse(STATIC_DIR / "index.html")
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_handler(
+        request: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        return JSONResponse(
+            status_code=422,
+            content={
+                "error": {
+                    "code": "validation_error",
+                    "message": "Request validation failed",
+                    "detail": exc.errors(),
+                }
+            },
+        )
+
+    return app
+
+
+app = create_app()