feat: hybrid Nextcloud I/O with multi-tenant support

Migrate cloud storage from pure WebDAV to hybrid model:
- Reads: direct filesystem from NC volume mount (fast, no network overhead)
- Writes: still via WebDAV (keeps Nextcloud metadata in sync)
- Multi-tenant: tenants.json config with per-tenant NC instances
- Fallback: WebDAV reads when volume mount unavailable

New modules:
- server/tenant_config.py: multi-tenant config loader
- server/volume_reader.py: direct volume mount filesystem reader
- server/routers/cloud.py: refactored cloud API router (was inline in main.py)
- config/tenants.json: 3BM tenant configuration

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jochem25

config/tenants.json

@@ -0,0 +1,12 @@
+{
+  "tenants": {
+    "3bm": {
+      "name": "3BM Cooperatie",
+      "nextcloud_url": "http://nc-3bm:80",
+      "nextcloud_domain": "cloud-3bm.open-aec.com",
+      "service_user": "openaec-service",
+      "service_pass_env": "NC_SERVICE_PASS_3BM",
+      "group_folder_id": 1
+    }
+  }
+}

docker-compose.yml

@@ -24,17 +24,20 @@ services:
       - CORS_ORIGINS=*
       - DATABASE_URL=postgresql+asyncpg://bimvalidator:${POSTGRES_PASSWORD:-changeme}@db:5432/bimvalidator
       - PROJECT_FILES_DIR=/data/projects
-      # Nextcloud cloud storage (opt-in — leave empty to disable)
-      - NEXTCLOUD_URL=
-      - NEXTCLOUD_SERVICE_USER=
-      - NEXTCLOUD_SERVICE_PASS=
+      # Multi-tenant cloud storage (Nextcloud hybrid I/O)
+      - TENANTS_CONFIG=/etc/openaec/tenants.json
+      - NC_SERVICE_PASS_3BM=${NC_SERVICE_PASS_3BM:-}
     volumes:
       # Persist uploaded files across restarts
       - bim-uploads:/tmp/ifc_uploads
       - bim-processed:/tmp/ifc_processed
       - bim-jobs:/tmp/ids_validation_jobs
       # Persistent project file storage
       - bim-projects:/data/projects
+      # Tenant config
+      - ./config/tenants.json:/etc/openaec/tenants.json:ro
+      # Nextcloud data volume (read-only, direct filesystem access)
+      - tenant-3bm_nc-3bm-data:/nc-data-3bm:ro
     networks:
       - default
       - openaec_platform
@@ -49,6 +52,8 @@ volumes:
   bim-processed:
   bim-jobs:
   bim-projects:
+  tenant-3bm_nc-3bm-data:
+    external: true
 
 networks:
   openaec_platform:

server/main.py

@@ -40,6 +40,7 @@
     ValidationStatus,
 )
 from server.project_manager import ProjectManager
+from server.routers.cloud import router as cloud_router
 from server.routers.projects import router as projects_router
 from ifc_validator.standards.resolver import get_bundled_ids
 
@@ -79,6 +80,7 @@ def format(self, record: logging.LogRecord) -> str:
 
 # Include persistent project router (PostgreSQL-backed)
 app.include_router(projects_router)
+app.include_router(cloud_router)
 
 
 @app.on_event("startup")
@@ -89,8 +91,10 @@ async def startup():
 
 @app.on_event("shutdown")
 async def shutdown():
-    """Clean up database connections on shutdown."""
+    """Clean up database connections and HTTP clients on shutdown."""
     await close_db()
+    from server.nextcloud_client import close_all_clients
+    await close_all_clients()
 
 
 # Configure CORS for browser access
@@ -1040,200 +1044,6 @@ async def get_element_properties(model_id: str, global_id: str):
     return props
 
 
-# ==========================================================================
-# Cloud storage (Nextcloud) — opt-in via environment variables
-# ==========================================================================
-
-NEXTCLOUD_URL = os.environ.get("NEXTCLOUD_URL", "")
-NEXTCLOUD_SERVICE_USER = os.environ.get("NEXTCLOUD_SERVICE_USER", "")
-NEXTCLOUD_SERVICE_PASS = os.environ.get("NEXTCLOUD_SERVICE_PASS", "")
-CLOUD_ENABLED = bool(NEXTCLOUD_URL and NEXTCLOUD_SERVICE_USER and NEXTCLOUD_SERVICE_PASS)
-
-_nextcloud_client = None
-
-
-def get_nextcloud_client():
-    """Get or create the singleton NextcloudClient.
-
-    Returns the client if cloud storage is configured, otherwise raises 503.
-    """
-    global _nextcloud_client
-    if not CLOUD_ENABLED:
-        raise HTTPException(
-            status_code=503,
-            detail="Cloud storage is not configured",
-        )
-    if _nextcloud_client is None:
-        from server.nextcloud_client import NextcloudClient
-
-        _nextcloud_client = NextcloudClient(
-            base_url=NEXTCLOUD_URL,
-            username=NEXTCLOUD_SERVICE_USER,
-            password=NEXTCLOUD_SERVICE_PASS,
-        )
-    return _nextcloud_client
-
-
-@app.get("/api/cloud/status")
-async def cloud_status():
-    """Check if cloud storage is enabled and reachable."""
-    from server.models.cloud import CloudStatusResponse
-
-    if not CLOUD_ENABLED:
-        return CloudStatusResponse(enabled=False, connected=False)
-
-    client = get_nextcloud_client()
-    try:
-        connected = await client.test_connection()
-    except Exception:
-        connected = False
-
-    return CloudStatusResponse(enabled=True, connected=connected)
-
-
-@app.get("/api/cloud/projects")
-async def cloud_list_projects():
-    """List available project folders in Nextcloud."""
-    from server.models.cloud import CloudProjectItem, CloudProjectsResponse
-
-    client = get_nextcloud_client()
-    try:
-        items = await client.list_projects()
-    except Exception as exc:
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
-
-    return CloudProjectsResponse(
-        projects=[
-            CloudProjectItem(name=item.name, last_modified=item.last_modified)
-            for item in items
-        ]
-    )
-
-
-@app.get("/api/cloud/projects/{project}/files")
-async def cloud_list_files(project: str):
-    """List BCF files in a project's tool subdirectory."""
-    from server.models.cloud import CloudFileItem, CloudFilesResponse
-
-    client = get_nextcloud_client()
-    try:
-        items = await client.list_files(project)
-    except Exception as exc:
-        from server.nextcloud_client import NextcloudError
-
-        if isinstance(exc, NextcloudError) and exc.status_code:
-            raise HTTPException(
-                status_code=exc.status_code, detail=str(exc)
-            ) from exc
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
-
-    return CloudFilesResponse(
-        project=project,
-        files=[
-            CloudFileItem(
-                name=item.name,
-                size=item.content_length,
-                last_modified=item.last_modified,
-            )
-            for item in items
-        ],
-    )
-
-
-@app.get("/api/cloud/projects/{project}/files/{filename}")
-async def cloud_download_file(project: str, filename: str):
-    """Download a file from a project's tool subdirectory."""
-    client = get_nextcloud_client()
-    try:
-        content = await client.download_file(project, filename)
-    except Exception as exc:
-        from server.nextcloud_client import NextcloudError
-
-        if isinstance(exc, NextcloudError) and exc.status_code:
-            raise HTTPException(
-                status_code=exc.status_code, detail=str(exc)
-            ) from exc
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
-
-    return Response(
-        content=content,
-        media_type="application/octet-stream",
-        headers={
-            "Content-Disposition": f'attachment; filename="{filename}"',
-        },
-    )
-
-
-@app.put("/api/cloud/projects/{project}/files/{filename}")
-async def cloud_upload_file(
-    project: str,
-    filename: str,
-    file: UploadFile = File(...),
-):
-    """Upload a file to a project's tool subdirectory."""
-    from server.models.cloud import CloudUploadResponse
-
-    client = get_nextcloud_client()
-    content = await file.read()
-    try:
-        await client.upload_file(project, filename, content)
-    except Exception as exc:
-        from server.nextcloud_client import NextcloudError
-
-        if isinstance(exc, NextcloudError) and exc.status_code:
-            raise HTTPException(
-                status_code=exc.status_code, detail=str(exc)
-            ) from exc
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
-
-    return CloudUploadResponse(success=True, project=project, filename=filename)
-
-
-@app.delete("/api/cloud/projects/{project}/files/{filename}")
-async def cloud_delete_file(project: str, filename: str):
-    """Delete a file from a project's tool subdirectory."""
-    from server.models.cloud import CloudDeleteResponse
-
-    client = get_nextcloud_client()
-    try:
-        await client.delete_file(project, filename)
-    except Exception as exc:
-        from server.nextcloud_client import NextcloudError
-
-        if isinstance(exc, NextcloudError) and exc.status_code:
-            raise HTTPException(
-                status_code=exc.status_code, detail=str(exc)
-            ) from exc
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
-
-    return CloudDeleteResponse(success=True, project=project, filename=filename)
-
-
-@app.post("/api/cloud/projects/{project}/save")
-async def cloud_save_bcf(
-    project: str,
-    file: UploadFile = File(...),
-    filename: str = Form("validation.bcf"),
-):
-    """Convenience endpoint: save a BCF file to a project's cloud folder."""
-    from server.models.cloud import CloudUploadResponse
-
-    client = get_nextcloud_client()
-    content = await file.read()
-    try:
-        await client.upload_file(project, filename, content)
-    except Exception as exc:
-        from server.nextcloud_client import NextcloudError
-
-        if isinstance(exc, NextcloudError) and exc.status_code:
-            raise HTTPException(
-                status_code=exc.status_code, detail=str(exc)
-            ) from exc
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
-
-    return CloudUploadResponse(success=True, project=project, filename=filename)
-
-
 # ==========================================================================
 # Static file serving — serve built frontend in production
 # ==========================================================================

server/nextcloud_client.py

@@ -3,7 +3,7 @@
 
 Provides async file operations (list, upload, download, delete) against
 a Nextcloud instance using WebDAV. Authentication uses Basic auth with
-a service account.
+a service account. Multi-tenant: one client instance per tenant.
 
 Usage:
     client = NextcloudClient(
@@ -12,14 +12,21 @@
         password="secret",
     )
     projects = await client.list_projects()
+
+    # Or from tenant config:
+    client = NextcloudClient.from_tenant(tenant_config)
 """
 
+from __future__ import annotations
+
 import xml.etree.ElementTree as ET
 from dataclasses import dataclass
 from urllib.parse import quote, unquote
 
 import httpx
 
+from server.tenant_config import TenantConfig
+
 DAV_NS = {"d": "DAV:"}
 TOOL_SLUG = "bim-validator"
 PROJECTS_ROOT = "Projects"
@@ -68,6 +75,15 @@ def __init__(
             timeout=timeout,
         )
 
+    @classmethod
+    def from_tenant(cls, tenant: TenantConfig) -> NextcloudClient:
+        """Create a client from a TenantConfig."""
+        return cls(
+            base_url=tenant.nextcloud_url,
+            username=tenant.service_user,
+            password=tenant.service_pass,
+        )
+
     async def close(self) -> None:
         """Close the underlying HTTP client."""
         await self._client.aclose()
@@ -344,3 +360,22 @@ def _parse_multistatus(self, xml_bytes: bytes, base_path: str) -> list[DavItem]:
             )
 
         return items
+
+
+# ── Multi-tenant client registry ───────────────────────────────
+
+_clients: dict[str, NextcloudClient] = {}
+
+
+def get_nc_client(tenant: TenantConfig) -> NextcloudClient:
+    """Get or create a NextcloudClient for the given tenant."""
+    if tenant.slug not in _clients:
+        _clients[tenant.slug] = NextcloudClient.from_tenant(tenant)
+    return _clients[tenant.slug]
+
+
+async def close_all_clients() -> None:
+    """Close all cached clients. Call on app shutdown."""
+    for client in _clients.values():
+        await client.close()
+    _clients.clear()