roborean-api-fastapi 0.1.2__tar.gz

roborean_api_fastapi-0.1.2/.gitignore

@@ -0,0 +1,27 @@
+venv/
+venv-qt5/
+venv-qt6/
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+*.tsbuildinfo
+node_modules/
+.pnpm-store/
+.DS_Store
+.idea/
+.vscode/*.local
+playground/
+.e2e-ai/
+**/test-results/
+**/playwright-report/
+research/
+.roborean/
+.roborean-sql-artifacts/
+*.db

roborean_api_fastapi-0.1.2/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- FastAPI application factory with project CRUD, compile, durable runs,
+  artifact download, and document preview endpoints.
+- Client redaction for workspace secrets and run results.
+- Optional auth stub via `X-Roborean-Principal`.
+
+### Changed
+
+### Fixed
+
+- Lower inter-package dependency pins to `>=0.1.1` to match lockstep
+  release versions.
+- Omit null optional fields when redacting projects for clients so
+  browser compile/validate matches JSON Schema string optionals.

roborean_api_fastapi-0.1.2/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: roborean-api-fastapi
+Version: 0.1.2
+Summary: FastAPI HTTP surface for Roborean projects, runs, and previews
+Project-URL: Homepage, https://github.com/TNick/roborean
+Project-URL: Repository, https://github.com/TNick/roborean
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: roborean-engine>=0.1.1
+Requires-Dist: roborean-storage-base>=0.1.1
+Requires-Dist: roborean-storage-dict>=0.1.1
+Requires-Dist: roborean-storage-sqlalchemy>=0.1.1
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: flake8>=7.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: isort>=5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

roborean_api_fastapi-0.1.2/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roborean-api-fastapi"
+version = "0.1.2"
+description = "FastAPI HTTP surface for Roborean projects, runs, and previews"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+  "fastapi>=0.115.0",
+  "pydantic-settings>=2.0.0",
+  "roborean-engine>=0.1.1",
+  "roborean-storage-base>=0.1.1",
+  "roborean-storage-dict>=0.1.1",
+  "roborean-storage-sqlalchemy>=0.1.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24.0", "httpx>=0.27.0", "black>=24.0", "isort>=5.0", "flake8>=7.0"]
+
+
+[project.urls]
+Homepage = "https://github.com/TNick/roborean"
+Repository = "https://github.com/TNick/roborean"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/roborean_api_fastapi"]

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/__init__.py

@@ -0,0 +1,7 @@
+"""Roborean FastAPI HTTP API."""
+
+from .app import create_app
+
+__version__ = "0.4.0"
+
+__all__ = ["create_app", "__version__"]

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/app.py

@@ -0,0 +1,48 @@
+"""FastAPI application factory."""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.openapi.utils import get_openapi
+
+from .deps import attach_app_state
+from .errors import install_exception_handlers
+from .openapi.customize import customize_openapi
+from .routers import artifacts, compile, health, previews, projects, runs
+from .settings import Settings
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    """Build the Roborean HTTP API."""
+    app = FastAPI(title="Roborean API", version="0.4.0")
+    resolved = attach_app_state(app, settings)
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=resolved.cors_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    install_exception_handlers(app)
+
+    app.include_router(health.router)
+    app.include_router(projects.router)
+    app.include_router(compile.router)
+    app.include_router(runs.router)
+    app.include_router(artifacts.router)
+    app.include_router(previews.router)
+
+    def custom_openapi() -> dict:
+        if app.openapi_schema:
+            return app.openapi_schema
+        schema = get_openapi(
+            title=app.title,
+            version=app.version,
+            routes=app.routes,
+        )
+        app.openapi_schema = customize_openapi(schema)
+        return app.openapi_schema
+
+    app.openapi = custom_openapi
+    _ = resolved
+    return app

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/deps.py

@@ -0,0 +1,122 @@
+"""FastAPI dependency wiring."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from fastapi import Depends, Request
+from roborean_engine import RunService
+from roborean_engine.bits.registry import BitTypeRegistry, builtin_registry
+from roborean_engine.documents import default_driver_registry
+from roborean_storage_base import (
+    ArtifactStore,
+    ProjectRepository,
+    RunRepository,
+)
+from roborean_storage_dict import (
+    DictArtifactStore,
+    DictProjectRepository,
+    DictRunRepository,
+)
+
+from .security import Principal, resolve_principal
+from .settings import Settings, load_settings
+
+
+@dataclass
+class AppState:
+    """Shared repositories and services."""
+
+    settings: Settings
+    projects: ProjectRepository
+    runs: RunRepository
+    artifacts: ArtifactStore
+    run_service: RunService
+
+
+def build_app_state(settings: Settings) -> AppState:
+    """Construct repositories from settings."""
+    if settings.storage_backend == "dict":
+        root = settings.store_path.expanduser().resolve()
+        root.mkdir(parents=True, exist_ok=True)
+        projects = DictProjectRepository(root)
+        runs = DictRunRepository(root)
+        artifacts = DictArtifactStore(settings.artifact_root.resolve())
+    else:
+        from roborean_storage_sqlalchemy import (
+            SqlAlchemyProjectRepository,
+            SqlAlchemyRunRepository,
+            make_engine,
+            make_session_factory,
+            upgrade,
+        )
+
+        if not settings.database_url:
+            raise ValueError("database_url required for sqlalchemy backend")
+        engine = make_engine(settings.database_url)
+        upgrade(engine)
+        factory = make_session_factory(engine)
+        projects = SqlAlchemyProjectRepository(factory)
+        runs = SqlAlchemyRunRepository(factory)
+        artifacts = DictArtifactStore(settings.artifact_root.resolve())
+
+    def package_dir(project_id: str) -> Path | None:
+        if isinstance(projects, DictProjectRepository):
+            path = projects._project_dir(project_id)
+            return path if path.is_dir() else None
+        return None
+
+    run_service = RunService(
+        projects=projects,
+        runs=runs,
+        artifacts=artifacts,
+        registry=builtin_registry(),
+        package_dir_for_project=package_dir,
+    )
+    return AppState(
+        settings=settings,
+        projects=projects,
+        runs=runs,
+        artifacts=artifacts,
+        run_service=run_service,
+    )
+
+
+def get_settings(request: Request) -> Settings:
+    """Settings attached to the app instance."""
+    return request.app.state.roborean_settings
+
+
+def get_state(request: Request) -> AppState:
+    """Repositories attached to the app instance."""
+    return request.app.state.roborean_app_state
+
+
+def get_principal(
+    request: Request,
+    settings: Settings = Depends(get_settings),
+) -> Principal:
+    """Resolve caller identity."""
+    return resolve_principal(request, settings)
+
+
+def get_bit_registry() -> BitTypeRegistry:
+    """Built-in bit registry."""
+    return builtin_registry()
+
+
+def get_document_registry():
+    """Installed document drivers."""
+    return default_driver_registry()
+
+
+def attach_app_state(app, settings: Settings | None = None) -> Settings:
+    """Bind settings and repositories to a FastAPI app."""
+    resolved = settings or load_settings()
+    app.state.roborean_settings = resolved
+    app.state.roborean_app_state = build_app_state(resolved)
+    return resolved
+
+
+def reset_state() -> None:
+    """No-op placeholder for tests (state lives on app)."""
+    return None

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/errors.py

@@ -0,0 +1,81 @@
+"""HTTP error mapping."""
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from roborean_engine.compiler import CompileError
+from roborean_storage_base import ConflictError, NotFoundError
+
+from .schemas.common import DiagnosticDto, ErrorBody
+
+
+class ApiError(Exception):
+    """Structured API failure."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        diagnostics: list[DiagnosticDto] | None = None,
+    ) -> None:
+        """Store HTTP metadata for handlers."""
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.diagnostics = diagnostics or []
+        super().__init__(message)
+
+
+def install_exception_handlers(app: FastAPI) -> None:
+    """Register domain → HTTP mappings."""
+
+    @app.exception_handler(ApiError)
+    async def _api_error(_request: Request, error: ApiError) -> JSONResponse:
+        body = ErrorBody(
+            code=error.code,
+            message=error.message,
+            diagnostics=error.diagnostics,
+        )
+        return JSONResponse(
+            status_code=error.status_code,
+            content=body.model_dump(mode="json", by_alias=True),
+        )
+
+    @app.exception_handler(NotFoundError)
+    async def _not_found(
+        _request: Request, error: NotFoundError
+    ) -> JSONResponse:
+        body = ErrorBody(code="E_NOT_FOUND", message=str(error))
+        return JSONResponse(
+            status_code=404, content=body.model_dump(by_alias=True)
+        )
+
+    @app.exception_handler(ConflictError)
+    async def _conflict(
+        _request: Request, error: ConflictError
+    ) -> JSONResponse:
+        body = ErrorBody(code="E_CONFLICT", message=str(error))
+        return JSONResponse(
+            status_code=409, content=body.model_dump(by_alias=True)
+        )
+
+    @app.exception_handler(CompileError)
+    async def _compile(_request: Request, error: CompileError) -> JSONResponse:
+        diagnostics = [
+            DiagnosticDto(
+                severity=item.severity,
+                code=item.code,
+                message=item.message,
+                path=item.path,
+            )
+            for item in error.diagnostics
+        ]
+        body = ErrorBody(
+            code="E_COMPILE",
+            message=str(error),
+            diagnostics=diagnostics,
+        )
+        return JSONResponse(
+            status_code=400, content=body.model_dump(by_alias=True)
+        )

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/openapi/customize.py

@@ -0,0 +1,11 @@
+"""OpenAPI post-processing."""
+
+from typing import Any
+
+
+def customize_openapi(schema: dict[str, Any]) -> dict[str, Any]:
+    """Apply stable metadata for generated clients."""
+    info = schema.setdefault("info", {})
+    info["title"] = info.get("title") or "Roborean API"
+    info["version"] = info.get("version") or "0.4.0"
+    return schema

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/redaction.py

@@ -0,0 +1,101 @@
+"""Redact workspace values for client responses."""
+
+from typing import Any
+
+from roborean_spec import (
+    Exposure,
+    Project,
+    PublicLiteral,
+    Redacted,
+    RunResults,
+    SecretRefValue,
+    Variable,
+    WorkspaceValue,
+)
+
+
+def redact_workspace_value(
+    value: WorkspaceValue,
+    *,
+    exposure: Exposure | None = None,
+) -> WorkspaceValue:
+    """Replace secret-bearing values according to exposure."""
+    if exposure in (Exposure.BACKEND_ONLY, Exposure.REDACTED_TO_CLIENT):
+        return Redacted(kind="redacted", reason="secret")
+    if isinstance(value, SecretRefValue):
+        return Redacted(kind="redacted", reason="secret")
+    if isinstance(value, PublicLiteral):
+        return value
+    return Redacted(kind="redacted", reason="policy")
+
+
+def redact_project_for_client(project: Project) -> dict[str, Any]:
+    """Return a JSON-serializable project safe for browsers."""
+    if isinstance(project, dict):
+        project = Project.model_validate(project)
+
+    # Omit null optional fields so Draft 2020-12 schemas stay valid.
+    data = project.model_dump(mode="json", by_alias=True, exclude_none=True)
+    variables = []
+    for variable in project.workspace.get("variables", []):
+        if isinstance(variable, dict):
+            variable = Variable.model_validate(variable)
+        item = variable.model_dump(
+            mode="json", by_alias=True, exclude_none=True
+        )
+        item["defaultValue"] = redact_workspace_value(
+            variable.default_value,
+            exposure=variable.exposure,
+        ).model_dump(mode="json", by_alias=True, exclude_none=True)
+        variables.append(item)
+    data["workspace"]["variables"] = variables
+    return data
+
+
+def _redact_patch_ops(payload: dict[str, Any]) -> dict[str, Any]:
+    """Redact workspace patch operations in run results."""
+    bit_results = []
+    for item in payload.get("bitResults", []):
+        patch = item.get("workspacePatch") or {}
+        ops = []
+        for op in patch.get("ops", []):
+            if op.get("op") == "set" and "value" in op:
+                value = op["value"]
+                if (
+                    isinstance(value, dict)
+                    and value.get("kind") == "secret_ref"
+                ):
+                    op = {
+                        **op,
+                        "value": {"kind": "redacted", "reason": "secret"},
+                    }
+            ops.append(op)
+        item = {**item, "workspacePatch": {**patch, "ops": ops}}
+        bit_results.append(item)
+    payload["bitResults"] = bit_results
+    return payload
+
+
+def redact_run_results_for_client(results: RunResults) -> dict[str, Any]:
+    """Return run results without resolved secret literals."""
+    payload = results.model_dump(mode="json", by_alias=True, exclude_none=True)
+    return _redact_patch_ops(payload)
+
+
+def assert_no_backend_only_literals(payload: dict[str, Any]) -> None:
+    """Fail tests when raw secret literals leak to clients."""
+    stack = [payload]
+    while stack:
+        current = stack.pop()
+        if isinstance(current, dict):
+            kind = current.get("kind")
+            if kind == "public_literal" and current.get("value") not in (
+                None,
+                "",
+            ):
+                exposure = current.get("exposure")
+                if exposure == "backendOnly":
+                    raise AssertionError("backendOnly literal leaked")
+            stack.extend(current.values())
+        elif isinstance(current, list):
+            stack.extend(current)

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/routers/__init__.py

@@ -0,0 +1,5 @@
+"""Router exports."""
+
+from . import artifacts, compile, health, previews, projects, runs
+
+__all__ = ["artifacts", "compile", "health", "previews", "projects", "runs"]

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/routers/artifacts.py

@@ -0,0 +1,45 @@
+"""Artifact download."""
+
+from fastapi import APIRouter, Depends, Response
+from roborean_storage_base import NotFoundError
+
+from ..deps import AppState, get_principal, get_state
+from ..errors import ApiError
+from ..security import Principal
+
+router = APIRouter(prefix="/v1/runs", tags=["artifacts"])
+
+
+@router.get("/{run_id}/artifacts/{artifact_id}")
+def download_artifact(
+    run_id: str,
+    artifact_id: str,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> Response:
+    """Stream one stored artifact (document id)."""
+    record = state.run_service.get(run_id)
+    media_type = "application/octet-stream"
+    for item in record.results.artifacts if record.results else []:
+        doc_id = (
+            item.get("documentId")
+            if isinstance(item, dict)
+            else item.document_id
+        )
+        if doc_id == artifact_id:
+            media_type = (
+                item.get("mediaType")
+                if isinstance(item, dict)
+                else item.media_type
+            )
+            break
+    key = f"{run_id}/{artifact_id}"
+    try:
+        payload = state.artifacts.get_bytes(key)
+    except (NotFoundError, FileNotFoundError, KeyError) as error:
+        raise ApiError(
+            status_code=404,
+            code="E_NOT_FOUND",
+            message=f"artifact not found: {artifact_id}",
+        ) from error
+    return Response(content=payload, media_type=media_type)

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/routers/compile.py

@@ -0,0 +1,32 @@
+"""Compile route."""
+
+from fastapi import APIRouter, Depends
+
+from ..deps import AppState, get_bit_registry, get_principal, get_state
+from ..schemas.runs import CompileRequest, CompileResponse
+from ..security import Principal
+from ..services import compile_service
+
+router = APIRouter(prefix="/v1/projects", tags=["compile"])
+
+
+@router.post("/{project_id}/compile", response_model=CompileResponse)
+def compile_project(
+    project_id: str,
+    body: CompileRequest | None = None,
+    state: AppState = Depends(get_state),
+    registry=Depends(get_bit_registry),
+    _principal: Principal = Depends(get_principal),
+) -> CompileResponse:
+    """Compile a stored project."""
+    request = body or CompileRequest()
+    package_dir = None
+    if state.run_service.package_dir_for_project:
+        package_dir = state.run_service.package_dir_for_project(project_id)
+    return compile_service.compile_stored_project(
+        state.projects,
+        project_id,
+        body=request,
+        registry=registry,
+        package_dir=package_dir,
+    )

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/routers/health.py

@@ -0,0 +1,12 @@
+"""Health probe."""
+
+from fastapi import APIRouter
+from roborean_engine.version import ENGINE_VERSION
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    """Return liveness and engine version."""
+    return {"status": "ok", "engineVersion": ENGINE_VERSION}

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/routers/previews.py

@@ -0,0 +1,29 @@
+"""Preview route."""
+
+from fastapi import APIRouter, Depends
+
+from ..deps import AppState, get_principal, get_state
+from ..schemas.previews import PreviewRequest, PreviewResponse
+from ..security import Principal
+from ..services import preview_service
+
+router = APIRouter(prefix="/v1/projects", tags=["previews"])
+
+
+@router.post("/{project_id}/preview", response_model=PreviewResponse)
+def preview_document(
+    project_id: str,
+    body: PreviewRequest,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> PreviewResponse:
+    """Return a browser-safe document preview."""
+    package_dir = None
+    if state.run_service.package_dir_for_project:
+        package_dir = state.run_service.package_dir_for_project(project_id)
+    return preview_service.build_preview(
+        state.projects,
+        project_id,
+        body,
+        package_dir=package_dir,
+    )

roborean_api_fastapi-0.1.2/src/roborean_api_fastapi/routers/projects.py

@@ -0,0 +1,76 @@
+"""Project CRUD routes."""
+
+from fastapi import APIRouter, Depends, Response, status
+
+from ..deps import AppState, get_principal, get_state
+from ..errors import ApiError
+from ..schemas.projects import (
+    ProjectCreate,
+    ProjectDetail,
+    ProjectSummary,
+    ProjectUpdate,
+)
+from ..security import Principal
+from ..services import project_service
+
+router = APIRouter(prefix="/v1/projects", tags=["projects"])
+
+
+@router.get("", response_model=list[ProjectSummary])
+def list_projects(
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> list[ProjectSummary]:
+    """List project summaries."""
+    return project_service.list_projects(state.projects)
+
+
+@router.post(
+    "", response_model=ProjectDetail, status_code=status.HTTP_201_CREATED
+)
+def create_project(
+    body: ProjectCreate,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> ProjectDetail:
+    """Create a stored project."""
+    return project_service.create_project(state.projects, body)
+
+
+@router.get("/{project_id}", response_model=ProjectDetail)
+def get_project(
+    project_id: str,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> ProjectDetail:
+    """Fetch one project."""
+    return project_service.get_project(state.projects, project_id)
+
+
+@router.put("/{project_id}", response_model=ProjectDetail)
+def update_project(
+    project_id: str,
+    body: ProjectUpdate,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> ProjectDetail:
+    """Replace a project."""
+    try:
+        return project_service.update_project(state.projects, project_id, body)
+    except ValueError as error:
+        raise ApiError(
+            status_code=400,
+            code="E_SCHEMA",
+            message=str(error),
+        ) from error
+
+
+@router.delete("/{project_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_project(
+    project_id: str,
+    state: AppState = Depends(get_state),
+    _principal: Principal = Depends(get_principal),
+) -> Response:
+    """Delete a project."""
+    project_service.delete_project(state.projects, project_id)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)