basic-python-project 0.0.0__py3-none-any.whl

meinewaldki_citizen_rest_service/keycloak_clients.py

@@ -0,0 +1,55 @@
+"""Keycloak clients for user and admin operations."""
+
+from keycloak import KeycloakOpenID, KeycloakOpenIDConnection, KeycloakAdmin
+
+from meinewaldki_citizen_rest_service.constants import (
+    CLIENT_NAME,
+    GUEST_ADMIN_PASSWORD,
+    GUEST_ADMIN_REALM_NAME,
+    GUEST_ADMIN_USERNAME,
+    GUEST_USER_REALM_NAME,
+    KEYCLOAK_CERT_PATH,
+    KEYCLOAK_SERVER_URL,
+    REGISTERED_ADMIN_PASSWORD,
+    REGISTERED_ADMIN_REALM_NAME,
+    REGISTERED_ADMIN_USERNAME,
+    REGISTERED_USER_REALM_NAME,
+)
+
+_keycloak_verify: bool | str = KEYCLOAK_CERT_PATH if KEYCLOAK_CERT_PATH else True
+
+guest_user_client = KeycloakOpenID(
+    server_url=KEYCLOAK_SERVER_URL,
+    client_id=CLIENT_NAME,
+    realm_name=GUEST_USER_REALM_NAME,
+    verify=_keycloak_verify,
+)
+
+guest_user_admin_connection = KeycloakOpenIDConnection(
+    server_url=KEYCLOAK_SERVER_URL,
+    username=GUEST_ADMIN_USERNAME,
+    password=GUEST_ADMIN_PASSWORD,
+    realm_name=GUEST_USER_REALM_NAME,
+    user_realm_name=GUEST_ADMIN_REALM_NAME,
+    verify=_keycloak_verify,
+)
+
+guest_user_admin = KeycloakAdmin(connection=guest_user_admin_connection)
+
+registered_user_client = KeycloakOpenID(
+    server_url=KEYCLOAK_SERVER_URL,
+    client_id=CLIENT_NAME,
+    realm_name=REGISTERED_USER_REALM_NAME,
+    verify=_keycloak_verify,
+)
+
+registered_user_admin_connection = KeycloakOpenIDConnection(
+    server_url=KEYCLOAK_SERVER_URL,
+    username=REGISTERED_ADMIN_USERNAME,
+    password=REGISTERED_ADMIN_PASSWORD,
+    realm_name=REGISTERED_USER_REALM_NAME,
+    user_realm_name=REGISTERED_ADMIN_REALM_NAME,
+    verify=_keycloak_verify,
+)
+
+registered_user_admin = KeycloakAdmin(connection=registered_user_admin_connection)

meinewaldki_citizen_rest_service/main.py

@@ -0,0 +1,63 @@
+"""Main entry point for the MeineWaldKI Citizen REST API Service."""
+
+import logging
+import os
+
+import sentry_sdk
+import uvicorn
+from fastapi import FastAPI
+from sentry_sdk.integrations.fastapi import FastApiIntegration
+from sentry_sdk.integrations.starlette import StarletteIntegration
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+
+from meinewaldki_citizen_rest_service.constants import GLITCHTIP_DSN
+from meinewaldki_citizen_rest_service.routers import guest_user_access, records, users
+
+if GLITCHTIP_DSN:
+    sentry_sdk.init(
+        dsn=GLITCHTIP_DSN,
+        integrations=[
+            StarletteIntegration(),
+            FastApiIntegration(),
+        ],
+        # Capture 100 % of transactions in dev; lower this in production
+        traces_sample_rate=float(os.environ.get("SENTRY_TRACES_SAMPLE_RATE", "1.0")),
+        environment=os.environ.get("ENVIRONMENT", "development"),
+        release=os.environ.get("VERSION", "dev"),
+    )
+
+app = FastAPI(
+    title="MeineWaldKI REST API Service",
+    description="TODO",
+    root_path="/citizen-api",
+    version=os.environ.get("VERSION", "dev"),
+    middleware=[
+        Middleware(
+            CORSMiddleware,
+            allow_origins=[
+                # Unsure what flutter uses as origin
+                "http://localhost:8100",  # Unsecure http for local testing
+                "https://localhost:8100",  # Secure https for local testing
+                "http://localhost",  # Unsecure http for local testing
+                "https://localhost",  # Secure https for local testing
+                "capacitor://localhost",  # Capacitor (Ionics) apps
+            ],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+    ],
+)
+
+app.include_router(guest_user_access.router)
+app.include_router(users.router)
+app.include_router(records.router)
+
+if __name__ == "__main__":
+    logger = logging.getLogger(__name__)
+
+    HOST = "localhost"
+    PORT = 5001
+    logger.info("Swagger UI is listening at: http://%s:%s/docs", HOST, PORT)
+    uvicorn.run(app, host="0.0.0.0", port=PORT)

meinewaldki_citizen_rest_service/minio_client.py

@@ -0,0 +1,52 @@
+"""MinIO client and upload helper for image storage."""
+
+import hashlib
+import io
+
+from minio import Minio
+from PIL import Image
+
+from meinewaldki_citizen_rest_service.constants import (
+    MINIO_ACCESS_KEY,
+    MINIO_BUCKET,
+    MINIO_ENDPOINT,
+    MINIO_SECRET_KEY,
+    MINIO_SECURE,
+)
+
+_client = Minio(
+    MINIO_ENDPOINT,
+    access_key=MINIO_ACCESS_KEY,
+    secret_key=MINIO_SECRET_KEY,
+    secure=MINIO_SECURE,
+)
+
+
+def upload_image(data: bytes, content_type: str) -> str:
+    """Uploads raw image bytes to MinIO.
+
+    The object name is the SHA-256 hash of the image pixel data, giving
+    content-addressable storage and natural deduplication.
+
+    Args:
+        data: Raw image bytes.
+        content_type: MIME type of the image (e.g. ``image/jpeg``).
+
+    Returns:
+        The SHA-256 hex digest used as the object name in MinIO.
+    """
+    img = Image.open(io.BytesIO(data))
+
+    sha256 = hashlib.sha256()
+    sha256.update(img.tobytes())
+    img_hash = sha256.hexdigest()
+
+    _client.put_object(
+        MINIO_BUCKET,
+        img_hash,
+        io.BytesIO(data),
+        length=len(data),
+        content_type=content_type,
+    )
+
+    return img_hash

meinewaldki_citizen_rest_service/routers/guest_user_access.py

@@ -0,0 +1,44 @@
+"""Router for managing guest user access in the MeineWaldki Citizen REST Service."""
+
+import uuid
+
+from fastapi import APIRouter
+
+from meinewaldki_citizen_rest_service.keycloak_clients import (
+    guest_user_admin,
+    guest_user_client,
+)
+
+router = APIRouter(
+    prefix="/guest-user",
+    tags=["guest-user"],
+)
+
+
+@router.get("/create")
+async def create_guest_user():
+    """Creates a guest user in Keycloak and returns credentials.
+
+    Returns:
+        A dict with access and refresh tokens.
+    """
+    user_uuid = uuid.uuid4()
+    password_uuid = uuid.uuid4()
+    email = uuid.uuid4()
+
+    payload = {
+        "username": str(user_uuid),
+        "email": str(email) + "@" + str(email) + ".de",
+        "enabled": True,
+        "emailVerified": True,
+        "credentials": [{"value": str(password_uuid), "type": "password"}],
+    }
+
+    guest_user_admin.create_user(payload)
+
+    token = guest_user_client.token(str(user_uuid), str(password_uuid))
+
+    return {
+        "access_token": token["access_token"],
+        "refresh_token": token["refresh_token"],
+    }

meinewaldki_citizen_rest_service/routers/records.py

@@ -0,0 +1,268 @@
+"""Router for submitting forest observation records."""
+
+import asyncio
+import uuid
+from datetime import UTC, datetime
+from typing import Annotated
+
+import sentry_sdk
+from fastapi import APIRouter, Depends, HTTPException, Response, UploadFile, status
+from geoalchemy2.elements import WKTElement
+from sqlalchemy import select, update
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from meinewaldki_citizen_rest_service.constants import (
+    ALLOWED_IMAGE_MIME_TYPES,
+    WGS84_SRID,
+)
+from meinewaldki_citizen_rest_service.database.engine import get_session
+from meinewaldki_citizen_rest_service.database.models import Image, Record
+from meinewaldki_citizen_rest_service.dependencies import get_current_user_id
+from meinewaldki_citizen_rest_service.minio_client import upload_image as minio_upload
+from meinewaldki_citizen_rest_service.schemas import (
+    ImageRead,
+    ImageSyncStatus,
+    RecordCreate,
+    RecordRead,
+    RecordSyncStatus,
+)
+
+router = APIRouter(
+    prefix="/records",
+    tags=["records"],
+)
+
+
+@router.post("", status_code=status.HTTP_201_CREATED)
+async def create_record(
+    body: RecordCreate,
+    response: Response,
+    user_id: Annotated[uuid.UUID, Depends(get_current_user_id)],
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> RecordRead:
+    """Submits a forest observation record with image placeholders.
+
+    Idempotent — safe to retry after a lost response. Returns 201 on first
+    creation, 200 if the record already exists (identified by the unique
+    combination of client_record_id, user_id, and created_at).
+    The images are not uploaded yet — their sync_status signals that.
+    A separate upload endpoint will handle the binary data later.
+
+    Args:
+        body: Record data including image placeholders.
+        response: FastAPI response object for status code override.
+        user_id: Authenticated user's UUID from JWT.
+        session: Async database session.
+
+    Returns:
+        RecordRead with server-assigned IDs and image sync statuses.
+    """
+    original_location = None
+    if body.original_location is not None:
+        loc = body.original_location
+        original_location = WKTElement(f"POINT({loc.lon} {loc.lat})", srid=WGS84_SRID)
+
+    record_statement = (
+        pg_insert(Record)  # type: ignore
+        .values(
+            client_record_id=body.client_record_id,
+            created_at=body.created_at,
+            hardware_data=body.hardware_data,
+            user_id=user_id,
+            original_location=original_location,
+            uploaded_at=datetime.now(UTC),
+            is_anonymized=False,
+            sync_status=RecordSyncStatus.pending,
+        )
+        .on_conflict_do_nothing(constraint="uq_record_client_user_created")
+        .returning(Record.id)
+    )
+    result = await session.execute(record_statement)
+
+    server_record_id = result.scalar_one_or_none()
+
+    if server_record_id is None:
+        # Record already exists — fetch and return it
+        response.status_code = status.HTTP_200_OK
+        existing = await session.execute(
+            select(Record).where(
+                Record.client_record_id == body.client_record_id,  # type: ignore
+                Record.user_id == user_id,  # type: ignore
+                Record.created_at == body.created_at,  # type: ignore
+            )
+        )
+        record = existing.scalar_one()
+        imgs = await session.execute(
+            select(Image).where(Image.record_id == record.id)  # type: ignore[arg-type]
+        )
+        images = imgs.scalars().all()
+        return RecordRead(
+            id=record.id,
+            client_record_id=record.client_record_id,
+            images=[
+                ImageRead(
+                    id=img.id,
+                    client_image_id=img.client_image_id,
+                    image_orientation=img.image_orientation,
+                    sync_status=img.sync_status,
+                )
+                for img in images
+            ],
+        )
+
+    images = [
+        Image(
+            record_id=server_record_id,
+            client_image_id=img.client_image_id,
+            image_orientation=img.image_orientation,
+            exif_metadata=img.exif_metadata,
+            minio_path=None,
+            sync_status=ImageSyncStatus.pending,
+        )
+        for img in body.images
+    ]
+    session.add_all(images)
+    await session.commit()
+
+    return RecordRead(
+        id=server_record_id,
+        client_record_id=body.client_record_id,
+        images=[
+            ImageRead(
+                id=img.id,
+                client_image_id=img.client_image_id,
+                image_orientation=img.image_orientation,
+                sync_status=img.sync_status,
+            )
+            for img in images
+        ],
+    )
+
+
+@router.post(
+    "/images/{server_image_id}",
+    status_code=status.HTTP_201_CREATED,
+)
+async def upload_image(
+    server_image_id: int,
+    file: UploadFile,
+    response: Response,
+    user_id: Annotated[uuid.UUID, Depends(get_current_user_id)],
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> ImageRead:
+    """Uploads the binary image for a previously created image placeholder.
+
+    Idempotent — safe to retry after a lost response. Returns 201 on first
+    upload, 200 if the image was already uploaded.
+    The client uses the server-assigned image id returned by POST /records.
+    Ownership is verified by joining against the parent record's user_id.
+
+    Args:
+        server_image_id: Server-assigned image ID from record creation.
+        file: Uploaded image file.
+        response: FastAPI response object for status code override.
+        user_id: Authenticated user's UUID from JWT.
+        session: Async database session.
+
+    Returns:
+        ImageRead with updated sync status.
+
+    Raises:
+        HTTPException: 404 if image not found or not owned by user,
+            415 if unsupported MIME type, 422 if file cannot be read,
+            503 if MinIO is unavailable.
+    """
+    result = await session.execute(
+        select(Image)
+        .join(Record, Image.record_id == Record.id)  # type: ignore[arg-type]
+        .where(Image.id == server_image_id, Record.user_id == user_id)  # type: ignore
+    )
+    image = result.scalar_one_or_none()
+    if image is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Image not found"
+        )
+
+    if image.sync_status == ImageSyncStatus.synced:
+        response.status_code = status.HTTP_200_OK
+        return ImageRead(
+            id=image.id,
+            client_image_id=image.client_image_id,
+            image_orientation=image.image_orientation,
+            sync_status=image.sync_status,
+        )
+
+    if file.content_type not in ALLOWED_IMAGE_MIME_TYPES:
+        sentry_sdk.capture_message(
+            f"Rejected upload with disallowed MIME type: {file.content_type}",
+            level="warning",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            detail="Unsupported file type",
+        )
+
+    try:
+        data = await file.read()
+    except Exception as e:
+        sentry_sdk.capture_exception(e)
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail="Could not read uploaded file",
+        )
+
+    try:
+        minio_path = await asyncio.to_thread(
+            minio_upload,
+            data=data,
+            content_type=file.content_type,
+        )
+    except Exception as e:
+        sentry_sdk.capture_exception(e)
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Image storage is currently unavailable",
+        )
+
+    image.minio_path = minio_path
+    image.sync_status = ImageSyncStatus.synced
+    session.add(image)
+    await session.commit()
+
+    return ImageRead(
+        id=image.id,
+        client_image_id=image.client_image_id,
+        image_orientation=image.image_orientation,
+        sync_status=image.sync_status,
+    )
+
+
+@router.delete("/{server_record_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_record(
+    server_record_id: int,
+    user_id: Annotated[uuid.UUID, Depends(get_current_user_id)],
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> None:
+    """Anonymizes a record owned by the authenticated user.
+
+    Sets is_anonymized to True, which fires the DB-side trigger that
+    anonymizes all associated images and logs the action to the audit table.
+    Idempotent — if the record is already anonymized or not found, 204 is
+    returned without error.
+
+    Args:
+        server_record_id: Server-assigned record ID.
+        user_id: Authenticated user's UUID from JWT.
+        session: Async database session.
+    """
+    await session.execute(
+        update(Record)
+        .where(
+            Record.id == server_record_id,  # type: ignore[arg-type]
+            Record.user_id == user_id,  # type: ignore[arg-type]
+            Record.is_anonymized.is_(False),  # type: ignore[attr-defined]
+        )
+        .values(is_anonymized=True)
+    )
+    await session.commit()

meinewaldki_citizen_rest_service/routers/users.py

@@ -0,0 +1,92 @@
+"""Router for user provisioning."""
+
+import asyncio
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Response, status
+from sqlalchemy import update
+from sqlalchemy.dialects.postgresql import insert
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from meinewaldki_citizen_rest_service.database.engine import get_session
+from meinewaldki_citizen_rest_service.database.models import User
+from meinewaldki_citizen_rest_service.dependencies import (
+    TokenData,
+    get_current_keycloak_admin,
+    get_current_token_data,
+    get_current_user_id,
+)
+from keycloak import KeycloakAdmin
+from keycloak.exceptions import KeycloakDeleteError
+
+from meinewaldki_citizen_rest_service.schemas import UserStatus
+
+router = APIRouter(
+    prefix="/users",
+    tags=["users"],
+)
+
+
+@router.post("/me", status_code=status.HTTP_201_CREATED)
+async def provision_user(
+    response: Response,
+    token_data: Annotated[TokenData, Depends(get_current_token_data)],
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> None:
+    """Provisions the authenticated user into core.users.
+
+    Safe to call multiple times. Returns 201 if the user was created, 200 if
+    they already existed — allowing the client to distinguish a first-time
+    registration from a retry after a lost response.
+
+    Args:
+        response: FastAPI response object for status code override.
+        token_data: Decoded JWT token data with user ID, type, and email.
+        session: Async database session.
+    """
+    statement = (
+        insert(User)  # type: ignore
+        .values(
+            id=token_data.user_id, status=token_data.user_type, email=token_data.email
+        )
+        .on_conflict_do_nothing(index_elements=["id"])
+        .returning(User.id)
+    )
+    result = await session.execute(statement)
+    await session.commit()
+
+    if result.scalar_one_or_none() is None:
+        response.status_code = status.HTTP_200_OK
+
+
+@router.delete("/me", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(
+    user_id: Annotated[uuid.UUID, Depends(get_current_user_id)],
+    keycloak_admin: Annotated[KeycloakAdmin, Depends(get_current_keycloak_admin)],
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> None:
+    """Deletes the authenticated user.
+
+    Idempotent — safe to retry after a lost response. Sets the user's status
+    to deleted in the DB (firing the DB-side cleanup trigger), then removes
+    the user from Keycloak. A 404 from Keycloak is silently ignored so that
+    retries where the DB trigger already ran still complete cleanly.
+
+    Args:
+        user_id: Authenticated user's UUID from JWT.
+        keycloak_admin: Keycloak admin client for the user's realm.
+        session: Async database session.
+    """
+    await session.execute(
+        update(User)
+        .where(User.id == user_id, User.status != UserStatus.deleted)  # type: ignore
+        .values(status=UserStatus.deleted)
+    )
+    await session.commit()
+
+    try:
+        await asyncio.to_thread(keycloak_admin.delete_user, str(user_id))
+    except KeycloakDeleteError as e:
+        if e.response_code != 404:
+            raise

meinewaldki_citizen_rest_service/schemas/__init__.py

@@ -0,0 +1,49 @@
+"""
+Shared schemas package.
+
+Base models defined here are reused by both the SQLModel table models
+(database/models.py) and the FastAPI Pydantic request / response schemas.
+"""
+
+from .citizen_science import (
+    CitizenScienceFeatureBase,
+    CitizenScienceFeatureOptionBase,
+    CitizenScienceUserAssignmentBase,
+    CsAssignmentSource,
+    CsAssignmentType,
+    CsValueType,
+)
+from .image import (
+    ImageBase,
+    ImageOrientation,
+    ImageRead,
+    ImageSyncStatus,
+)
+from .record import (
+    LocationSchema,
+    RecordBase,
+    RecordCreate,
+    RecordRead,
+    RecordSyncStatus,
+)
+from .user import UserBase, UserStatus
+
+__all__ = [
+    "UserStatus",
+    "UserBase",
+    "RecordSyncStatus",
+    "RecordBase",
+    "LocationSchema",
+    "RecordCreate",
+    "RecordRead",
+    "ImageSyncStatus",
+    "ImageOrientation",
+    "ImageBase",
+    "ImageRead",
+    "CsValueType",
+    "CsAssignmentType",
+    "CsAssignmentSource",
+    "CitizenScienceFeatureBase",
+    "CitizenScienceFeatureOptionBase",
+    "CitizenScienceUserAssignmentBase",
+]

meinewaldki_citizen_rest_service/schemas/citizen_science.py

@@ -0,0 +1,61 @@
+"""Shared citizen science schemas.
+
+Base models defined here are reused by both the SQLModel table models
+(database/models.py) and future Pydantic request / response schemas.
+"""
+
+import enum
+from typing import Optional
+
+from sqlmodel import SQLModel
+
+
+class CsValueType(str, enum.Enum):
+    """Maps to the core.cs_value_type PostgreSQL enum."""
+
+    boolean = "boolean"
+    enum = "enum"
+    int = "int"
+    text = "text"
+
+
+class CsAssignmentType(str, enum.Enum):
+    """Maps to the core.cs_assignment_type PostgreSQL enum."""
+
+    user_chosen = "user_chosen"
+    system_assigned = "system_assigned"
+    hybrid = "hybrid"
+
+
+class CsAssignmentSource(str, enum.Enum):
+    """Maps to the core.cs_assignment_source PostgreSQL enum."""
+
+    user = "user"
+    system = "system"
+    override = "override"
+
+
+class CitizenScienceFeatureBase(SQLModel):
+    """Shared fields for CitizenScienceFeature schemas and DB model."""
+
+    name: str
+    description: Optional[str] = None
+    value_type: CsValueType
+    assignment_type: CsAssignmentType
+    track_history: bool = False
+    is_active: bool = True
+
+
+class CitizenScienceFeatureOptionBase(SQLModel):
+    """Shared fields for CitizenScienceFeatureOption schemas and DB model."""
+
+    feature_value: str
+    feature_label: str
+    is_default: bool = False
+
+
+class CitizenScienceUserAssignmentBase(SQLModel):
+    """Shared fields for CitizenScienceUserAssignment schemas and DB model."""
+
+    source: CsAssignmentSource
+    has_changed: bool = False