orgm-bt 0.4.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,10 @@
+"""
+calc-bt Backend
+Sistema backend FastAPI para cálculos eléctricos de baja tensión (NEC)
+
+Fases implementadas:
+- Fase 1: Importación de datos TXT/CSV
+- Fase 2: Balance de cargas con algoritmo greedy
+"""
+
+__version__ = "0.2.0"

app/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters de paneles.json a modelos internos del motor."""

app/api.py

@@ -0,0 +1,607 @@
+"""HTTP API for persisted project configuration and serialized remote jobs."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import stat
+import tempfile
+import uuid
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from pathlib import Path, PurePosixPath
+from typing import Annotated, Any, Literal, Mapping
+
+from fastapi import FastAPI, HTTPException, Query, Response, status
+from fastapi import Path as ApiPath
+from fastapi.responses import FileResponse
+
+from app.api_models import (
+    DuRequest,
+    EmptyActionRequest,
+    HealthResponse,
+    InitRequest,
+    JobAccepted,
+    JobLogsResponse,
+    JobResponse,
+    ProjectCreate,
+    ProjectPatch,
+    ProjectResponse,
+    RemoteDirectoryResponse,
+    VersionResponse,
+)
+from app.config import Settings
+from app.services.job_store import JobManifest, JobStatus, JobStore
+from app.services.job_worker import JobWorker
+from app.services.project_store import ProjectStore, normalize_webdav_path
+from app.services.redaction import redact_text
+from app.services.remote_operations import RemoteOperations
+from app.services.webdav_storage import WebDAVStorage
+
+_LOG_TAIL_BYTES = 16 * 1024
+_MANIFEST_ERROR_BYTES = 4 * 1024
+_ACTIONS = frozenset({"init", "calculate", "du", "print-pdf", "finalize"})
+_UUID4_PATTERN = (
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+)
+UUID4Path = Annotated[str, ApiPath(pattern=_UUID4_PATTERN)]
+NumericVersionPath = Annotated[str, ApiPath(pattern=r"^[0-9]+$")]
+
+
+class _UnavailableWebDAVStorage:
+    """Safe degraded default until deployment credentials are configured."""
+
+    def check_connection(self) -> bool:
+        return False
+
+    def __getattr__(self, _: str) -> Any:
+        raise RuntimeError("WebDAV storage is not configured")
+
+
+def create_app(
+    *,
+    settings: Settings | None = None,
+    project_store: ProjectStore | None = None,
+    storage: Any | None = None,
+    job_store: JobStore | None = None,
+    executor: RemoteOperations | None = None,
+    worker: JobWorker | None = None,
+) -> FastAPI:
+    """Build an injectable API application with one managed job worker."""
+    runtime_settings = settings or Settings()
+    projects = project_store or ProjectStore(
+        runtime_settings.CALC_DATA_DIR / "local.json"
+    )
+    if storage is None:
+        try:
+            storage = WebDAVStorage(runtime_settings)
+        except ValueError:
+            storage = _UnavailableWebDAVStorage()
+    jobs = job_store or (
+        worker.store
+        if worker is not None
+        else JobStore(
+            runtime_settings.CALC_JOB_DIR,
+            retention_days=runtime_settings.CALC_JOB_RETENTION_DAYS,
+        )
+    )
+    remote = executor or RemoteOperations(
+        projects, storage, jobs, settings=runtime_settings
+    )
+    job_worker = worker or JobWorker(
+        jobs,
+        remote.run_stage,
+        remote.upload_stage,
+        success_stage=remote.record_success,
+        failure_stage=remote.record_failure,
+        error_sanitizer=remote.sanitize_error,
+    )
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        await asyncio.to_thread(projects.ensure)
+        await job_worker.start()
+        try:
+            yield
+        finally:
+            await job_worker.stop()
+
+    app = FastAPI(title=runtime_settings.PROJECT_NAME, lifespan=lifespan)
+    app.state.settings = runtime_settings
+    app.state.project_store = projects
+    app.state.storage = storage
+    app.state.job_store = jobs
+    app.state.executor = remote
+    app.state.worker = job_worker
+    prefix = runtime_settings.API_V1_PREFIX.rstrip("/")
+
+    @app.get(f"{prefix}/healthz", response_model=HealthResponse)
+    async def healthz() -> HealthResponse:
+        data_ok, jobs_ok = await asyncio.gather(
+            asyncio.to_thread(_directory_writable, runtime_settings.CALC_DATA_DIR),
+            asyncio.to_thread(_directory_writable, runtime_settings.CALC_JOB_DIR),
+        )
+        try:
+            webdav_ok = await asyncio.to_thread(storage.check_connection)
+        except Exception:
+            webdav_ok = False
+        return HealthResponse(
+            status="ok" if data_ok and jobs_ok and webdav_ok else "degraded",
+            data_writable=data_ok,
+            jobs_writable=jobs_ok,
+            webdav=webdav_ok,
+        )
+
+    @app.get(f"{prefix}/projects", response_model=list[ProjectResponse])
+    async def list_projects() -> list[ProjectResponse]:
+        try:
+            return [
+                _project_response(item)
+                for item in await asyncio.to_thread(projects.list)
+            ]
+        except Exception:
+            raise HTTPException(
+                status_code=500, detail="Project configuration is unavailable"
+            ) from None
+
+    @app.get(f"{prefix}/folders", response_model=list[RemoteDirectoryResponse])
+    async def list_folders(
+        path: Annotated[str, Query(min_length=1)] = "Proyectos",
+    ) -> list[RemoteDirectoryResponse]:
+        try:
+            canonical_path = normalize_webdav_path(path)
+            if not PurePosixPath(canonical_path).is_relative_to(
+                PurePosixPath("Proyectos")
+            ):
+                raise ValueError("Folder path must be within Proyectos")
+            entries = await asyncio.to_thread(storage.list_directory, canonical_path)
+        except ValueError as error:
+            raise HTTPException(status_code=422, detail=str(error)) from None
+        except Exception:
+            raise HTTPException(
+                status_code=502, detail="Could not list remote folders"
+            ) from None
+        return [
+            RemoteDirectoryResponse(path=entry_path, name=entry_path.rsplit("/", 1)[-1])
+            for entry_path, entry_type in entries
+            if entry_type == "directory"
+        ]
+
+    @app.post(
+        f"{prefix}/projects",
+        response_model=ProjectResponse,
+        status_code=status.HTTP_201_CREATED,
+    )
+    async def create_project(payload: ProjectCreate) -> ProjectResponse:
+        try:
+            project = payload.model_dump(exclude_none=True)
+            project["fecha_creacion"] = datetime.now(timezone.utc).isoformat()
+            created = await asyncio.to_thread(projects.create, project)
+            return _project_response(created)
+        except ValueError as error:
+            raise HTTPException(status_code=422, detail=str(error)) from None
+        except Exception:
+            raise HTTPException(
+                status_code=500, detail="Could not create project"
+            ) from None
+
+    @app.get(f"{prefix}/projects/{{project_id}}", response_model=ProjectResponse)
+    async def get_project(project_id: UUID4Path) -> ProjectResponse:
+        project = await _get_project(projects, project_id)
+        return _project_response(project)
+
+    @app.patch(f"{prefix}/projects/{{project_id}}", response_model=ProjectResponse)
+    async def patch_project(
+        project_id: UUID4Path, payload: ProjectPatch
+    ) -> ProjectResponse:
+        canonical_id = _uuid4_or_422(project_id)
+        changes = payload.model_dump(exclude_unset=True, exclude_none=False)
+        if not changes:
+            raise HTTPException(
+                status_code=422, detail="Patch body must contain at least one field"
+            )
+        try:
+            updated = await asyncio.to_thread(projects.update, canonical_id, changes)
+        except ValueError as error:
+            raise HTTPException(status_code=422, detail=str(error)) from None
+        except Exception:
+            raise HTTPException(
+                status_code=500, detail="Could not update project"
+            ) from None
+        if updated is None:
+            raise HTTPException(status_code=404, detail="Project not found")
+        return _project_response(updated)
+
+    @app.delete(
+        f"{prefix}/projects/{{project_id}}", status_code=status.HTTP_204_NO_CONTENT
+    )
+    async def delete_project(project_id: UUID4Path) -> Response:
+        canonical_id = _uuid4_or_422(project_id)
+        try:
+            deleted = await asyncio.to_thread(projects.delete, canonical_id)
+        except Exception:
+            raise HTTPException(
+                status_code=500, detail="Could not delete project"
+            ) from None
+        if not deleted:
+            raise HTTPException(status_code=404, detail="Project not found")
+        return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+    @app.get(
+        f"{prefix}/projects/{{project_id}}/versions",
+        response_model=list[VersionResponse],
+    )
+    async def list_versions(project_id: UUID4Path) -> list[VersionResponse]:
+        project = await _get_project(projects, project_id)
+        try:
+            return await asyncio.to_thread(
+                _remote_versions, storage, project, runtime_settings.CALC_JOB_DIR
+            )
+        except ValueError as error:
+            raise HTTPException(status_code=422, detail=str(error)) from None
+        except Exception:
+            raise HTTPException(
+                status_code=502, detail="Could not list remote project versions"
+            ) from None
+
+    @app.post(
+        f"{prefix}/projects/{{project_id}}/init",
+        response_model=JobAccepted,
+        status_code=status.HTTP_202_ACCEPTED,
+    )
+    async def initialize(
+        project_id: UUID4Path, payload: InitRequest | None = None
+    ) -> JobAccepted:
+        return await _launch(
+            projects,
+            jobs,
+            remote,
+            job_worker,
+            project_id,
+            "init",
+            prefix=prefix,
+            options=(payload or InitRequest()).model_dump(),
+        )
+
+    @app.post(
+        f"{prefix}/projects/{{project_id}}/calculate",
+        response_model=JobAccepted,
+        status_code=status.HTTP_202_ACCEPTED,
+    )
+    async def calculate(
+        project_id: UUID4Path, _: EmptyActionRequest | None = None
+    ) -> JobAccepted:
+        return await _launch(
+            projects, jobs, remote, job_worker, project_id, "calculate", prefix=prefix
+        )
+
+    @app.post(
+        f"{prefix}/projects/{{project_id}}/versions/{{version}}/du",
+        response_model=JobAccepted,
+        status_code=status.HTTP_202_ACCEPTED,
+    )
+    async def du(
+        project_id: UUID4Path,
+        version: NumericVersionPath,
+        payload: DuRequest | None = None,
+    ) -> JobAccepted:
+        return await _launch(
+            projects,
+            jobs,
+            remote,
+            job_worker,
+            project_id,
+            "du",
+            prefix=prefix,
+            version=_version_or_422(version),
+            options=(payload or DuRequest()).model_dump(exclude_none=True),
+        )
+
+    @app.post(
+        f"{prefix}/projects/{{project_id}}/versions/{{version}}/print-pdf",
+        response_model=JobAccepted,
+        status_code=status.HTTP_202_ACCEPTED,
+    )
+    async def print_pdf(
+        project_id: UUID4Path,
+        version: NumericVersionPath,
+        _: EmptyActionRequest | None = None,
+    ) -> JobAccepted:
+        return await _launch(
+            projects,
+            jobs,
+            remote,
+            job_worker,
+            project_id,
+            "print-pdf",
+            prefix=prefix,
+            version=_version_or_422(version),
+        )
+
+    @app.post(
+        f"{prefix}/projects/{{project_id}}/versions/{{version}}/finalize",
+        response_model=JobAccepted,
+        status_code=status.HTTP_202_ACCEPTED,
+    )
+    async def finalize(
+        project_id: UUID4Path,
+        version: NumericVersionPath,
+        _: EmptyActionRequest | None = None,
+    ) -> JobAccepted:
+        return await _launch(
+            projects,
+            jobs,
+            remote,
+            job_worker,
+            project_id,
+            "finalize",
+            prefix=prefix,
+            version=_version_or_422(version),
+        )
+
+    @app.get(f"{prefix}/jobs/{{job_id}}", response_model=JobResponse)
+    async def get_job(job_id: UUID4Path) -> JobResponse:
+        manifest = await _get_job(jobs, job_id)
+        directory = await asyncio.to_thread(jobs.job_directory, manifest.id)
+        return await asyncio.to_thread(
+            _job_response, manifest, directory, runtime_settings
+        )
+
+    @app.get(f"{prefix}/jobs/{{job_id}}/logs", response_model=JobLogsResponse)
+    async def job_logs(job_id: UUID4Path) -> JobLogsResponse:
+        manifest = await _get_job(jobs, job_id)
+        directory = await asyncio.to_thread(jobs.job_directory, manifest.id)
+        return await asyncio.to_thread(_job_logs_response, directory, runtime_settings)
+
+    @app.get(
+        f"{prefix}/jobs/{{job_id}}/download",
+        response_class=FileResponse,
+        responses={200: {"content": {"application/zip": {}}}},
+    )
+    async def download(job_id: UUID4Path) -> FileResponse:
+        manifest = await _get_job(jobs, job_id)
+        artifact = await asyncio.to_thread(jobs.job_directory, manifest.id)
+        artifact = artifact / "result.zip"
+        if not manifest.artifact_ready:
+            raise HTTPException(status_code=409, detail="Job artifact is not ready")
+        if not await asyncio.to_thread(_is_regular_file, artifact):
+            raise HTTPException(status_code=409, detail="Job artifact is not ready")
+        return FileResponse(
+            artifact, filename=f"calc-{manifest.id}.zip", media_type="application/zip"
+        )
+
+    return app
+
+
+async def _launch(
+    projects: ProjectStore,
+    jobs: JobStore,
+    remote: RemoteOperations,
+    worker: JobWorker,
+    project_id: str,
+    operation: str,
+    *,
+    prefix: str,
+    version: str | None = None,
+    options: Mapping[str, Any] | None = None,
+) -> JobAccepted:
+    if operation not in _ACTIONS:
+        raise HTTPException(status_code=500, detail="Unsupported action")
+    project = await _get_project(projects, project_id)
+    try:
+        remote_path = normalize_webdav_path(str(project["path"]))
+        manifest = await asyncio.to_thread(
+            jobs.create,
+            operation=operation,
+            project_id=str(project["id"]),
+            remote_path=remote_path,
+            requested_version=version,
+        )
+    except ValueError as error:
+        raise HTTPException(status_code=422, detail=str(error)) from None
+    except Exception:
+        raise HTTPException(status_code=500, detail="Could not create job") from None
+    try:
+        remote.register(manifest.id, project, options=options)
+        await worker.enqueue(manifest)
+    except Exception:
+        try:
+            await asyncio.to_thread(
+                jobs.transition, manifest.id, JobStatus.FAILED, error="enqueue_failed"
+            )
+        except Exception:
+            pass
+        raise HTTPException(
+            status_code=503, detail="Job worker is unavailable"
+        ) from None
+    return JobAccepted(
+        job_id=uuid.UUID(manifest.id),
+        status_url=f"{prefix}/jobs/{manifest.id}",
+        download_url=f"{prefix}/jobs/{manifest.id}/download",
+    )
+
+
+async def _get_project(store: ProjectStore, project_id: str) -> dict[str, Any]:
+    canonical_id = _uuid4_or_422(project_id)
+    try:
+        project = await asyncio.to_thread(store.get, canonical_id)
+    except Exception:
+        raise HTTPException(
+            status_code=500, detail="Project configuration is unavailable"
+        ) from None
+    if project is None:
+        raise HTTPException(status_code=404, detail="Project not found")
+    return project
+
+
+async def _get_job(store: JobStore, job_id: str) -> JobManifest:
+    canonical_id = _uuid4_or_422(job_id)
+    try:
+        manifest = await asyncio.to_thread(store.get, canonical_id)
+    except Exception:
+        raise HTTPException(
+            status_code=500, detail="Job state is unavailable"
+        ) from None
+    if manifest is None:
+        raise HTTPException(status_code=404, detail="Job not found")
+    return manifest
+
+
+def _uuid4_or_422(value: str) -> str:
+    try:
+        parsed = uuid.UUID(value)
+    except ValueError:
+        raise HTTPException(
+            status_code=422, detail="Identifier must be a UUID4"
+        ) from None
+    if parsed.version != 4 or str(parsed) != value:
+        raise HTTPException(
+            status_code=422, detail="Identifier must be a canonical UUID4"
+        )
+    return value
+
+
+def _version_or_422(value: str) -> str:
+    if not value.isascii() or not value.isdecimal():
+        raise HTTPException(status_code=422, detail="Version must be numeric")
+    return value
+
+
+def _project_response(project: Mapping[str, Any]) -> ProjectResponse:
+    try:
+        return ProjectResponse.model_validate(project)
+    except Exception:
+        raise HTTPException(
+            status_code=500, detail="Stored project has an invalid schema"
+        ) from None
+
+
+def _job_response(
+    manifest: JobManifest, directory: Path, settings: Settings
+) -> JobResponse:
+    document = manifest.to_dict()
+    document.pop("revision", None)
+    document.pop("calculation_started", None)
+    if document["error"] is not None:
+        document["error"] = _bounded_manifest_error(
+            _safe_log(document["error"], settings)
+        )
+    return JobResponse(
+        **document,
+        stdout_tail=_safe_log(_read_log_tail(directory / "stdout.log"), settings),
+        stderr_tail=_safe_log(_read_log_tail(directory / "stderr.log"), settings),
+    )
+
+
+def _job_logs_response(directory: Path, settings: Settings) -> JobLogsResponse:
+    return JobLogsResponse(
+        stdout=_safe_log(_read_log(directory / "stdout.log"), settings),
+        stderr=_safe_log(_read_log(directory / "stderr.log"), settings),
+    )
+
+
+def _is_regular_file(path: Path) -> bool:
+    try:
+        return stat.S_ISREG(path.lstat().st_mode)
+    except FileNotFoundError:
+        return False
+
+
+def _remote_versions(
+    storage: Any, project: Mapping[str, Any], job_root: Path
+) -> list[VersionResponse]:
+    remote_project = normalize_webdav_path(str(project["path"]))
+    remote_results = f"{remote_project}/RESULTADOS"
+    if not storage.exists(remote_results):
+        return []
+
+    job_root.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="versions-", dir=job_root) as temporary:
+        temporary_root = Path(temporary)
+        response: list[VersionResponse] = []
+        numeric_versions = sorted(
+            (
+                (remote_version, remote_version.rsplit("/", 1)[-1])
+                for remote_version, entry_type in storage.list_directory(remote_results)
+                if entry_type == "directory"
+                and (version := remote_version.rsplit("/", 1)[-1]).isascii()
+                and version.isdecimal()
+            ),
+            key=lambda item: (
+                len(item[1].lstrip("0") or "0"),
+                item[1].lstrip("0") or "0",
+            ),
+        )
+        for remote_version, version in numeric_versions:
+            state: Any = {}
+            remote_version_json = f"{remote_version}/version.json"
+            entries = storage.list_directory(remote_version)
+            if (remote_version_json, "file") in entries:
+                local_version_json = temporary_root / "version.json"
+                storage.download_file(remote_version_json, local_version_json)
+                try:
+                    state = json.loads(local_version_json.read_text(encoding="utf-8"))
+                except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+                    state = {}
+
+            raw_estado = state.get("estado") if isinstance(state, dict) else None
+            estado: Literal["calculando", "finalizada"] | None
+            if raw_estado == "calculando":
+                estado = "calculando"
+            elif raw_estado == "finalizada":
+                estado = "finalizada"
+            else:
+                estado = None
+            response.append(VersionResponse(version=version, estado=estado))
+        return response
+
+
+def _directory_writable(directory: Path) -> bool:
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            dir=directory, prefix=".health-", delete=True
+        ) as output:
+            output.write(b"ok")
+            output.flush()
+            os.fsync(output.fileno())
+        return True
+    except OSError:
+        return False
+
+
+def _read_log(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except FileNotFoundError:
+        return ""
+    except OSError:
+        return ""
+
+
+def _read_log_tail(path: Path) -> str:
+    try:
+        with path.open("rb") as source:
+            source.seek(0, os.SEEK_END)
+            size = source.tell()
+            source.seek(max(0, size - _LOG_TAIL_BYTES))
+            return source.read().decode("utf-8", errors="replace")
+    except FileNotFoundError:
+        return ""
+    except OSError:
+        return ""
+
+
+def _safe_log(value: str, settings: Settings) -> str:
+    return redact_text(value, settings)
+
+
+def _bounded_manifest_error(value: str) -> str:
+    encoded = value.encode("utf-8")
+    if len(encoded) <= _MANIFEST_ERROR_BYTES:
+        return value
+    return encoded[:_MANIFEST_ERROR_BYTES].decode("utf-8", errors="ignore") + "…"
+
+
+app = create_app()