Backend API Reference¶

async def check_rate_limit(
    user_action_limiter: UserActionLimiterProtocol,
    limiter_key: str,
    log_extra: Mapping[str, object],
    action: str = "action",
) -> None:
    """Checks if the action is allowed by the rate limiter.
    Raises HTTP 429 if not allowed.
    """
    allowed: bool = await user_action_limiter.is_allowed(limiter_key)
    if not allowed:
        http_error(
            429,
            f"Too many {action} attempts. Please try again later.",
            logger.warning,
            cast("ExtraLogInfo", log_extra),
        )

def common_auth_deps(feature: str) -> tuple[object, object, object]:
    """Returns a tuple of common dependencies for auth endpoints."""
    from fastapi import Depends as FastAPIDepends

    return (
        FastAPIDepends(get_request_id),
        FastAPIDepends(require_feature(feature)),
        FastAPIDepends(require_api_key),
    )

def rate_limit(action: str, key_func: Callable[[Request], str] | None = None) -> object:
    """Returns a dependency for rate limiting."""

    async def dependency(
        request: Request,
        user_action_limiter: UserActionLimiterProtocol = Depends(
            get_user_action_limiter,
        ),
    ) -> None:
        key: str
        if key_func is not None:
            key = key_func(request)
        else:
            user: User | None = getattr(request.state, "user", None)
            client_host: str = (
                request.client.host if request.client is not None else "unknown"
            )
            user_id_or_host: str = str(getattr(user, "id", client_host))
            key = f"{action}:{user_id_or_host}"
        allowed: bool = await user_action_limiter.is_allowed(key)
        if not allowed:
            http_error(
                429,
                f"Too many {action} attempts. Please try again later.",
                logger.warning,
                cast("ExtraLogInfo", {"limiter_key": key}),
            )

    return Depends(dependency)

@router.post(
    "/register",
    response_model=AuthResponse,
    status_code=status.HTTP_201_CREATED,
    summary=REGISTER_SUMMARY,
    description=REGISTER_DESCRIPTION,
    dependencies=[
        Depends(get_request_id),
        Depends(require_feature("auth:register")),
        Depends(require_api_key),
    ],
)
async def register(
    data: UserRegisterRequest = Body(
        ...,
        examples=[
            {
                "summary": "A typical registration",
                "value": {
                    "email": "user@example.com",
                    "password": "strongpassword123",
                    "name": "Jane Doe",
                },
            },
        ],
    ),
    session: AsyncSession = Depends(get_db),
    user_service: UserService = Depends(get_user_service),
    user_action_limiter: UserActionLimiterProtocol = Depends(get_user_action_limiter),
) -> AuthResponse:
    """Registers a new user account and returns a JWT access token.

    Raises:
        UserAlreadyExistsError: If the user already exists.
        InvalidDataError: If registration data is invalid.
        Exception: For unexpected errors.

    """
    await check_rate_limit(
        user_action_limiter,
        f"register:{data.email}",
        {"email": data.email},
        action="registration",
    )
    logger.info(
        f"User registration attempt: {data.email}, name: {getattr(data, 'name', None)}",
    )
    logger.debug(f"Registration payload: {data}")
    try:
        user: User = await user_service.register_user(session, data.model_dump())
        access_token: str
        refresh_token: str
        access_token, refresh_token = await user_service.authenticate_user(
            session,
            data.email,
            data.password,
        )
        logger.info(f"User registered successfully: {user.email}")
        return AuthResponse(access_token=access_token, refresh_token=refresh_token)
    except UserAlreadyExistsError as e:
        http_error(
            400,
            "User with this email already exists.",
            logger.warning,
            cast("ExtraLogInfo", {"email": data.email}),
            e,
        )
    except ValidationError as e:
        http_error(
            400,
            "Invalid registration data.",
            logger.warning,
            cast("ExtraLogInfo", {"email": data.email}),
            e,
        )
    except InvalidDataError as e:
        http_error(
            400,
            "Invalid registration data.",
            logger.warning,
            cast("ExtraLogInfo", {"email": data.email}),
            e,
        )
    except Exception as e:
        # Add detailed error logging
        import traceback

        logger.error(f"DETAILED ERROR in registration: {type(e).__name__}: {e}")
        logger.error(f"TRACEBACK: {traceback.format_exc()}")
        http_error(
            500,
            "An unexpected error occurred. Please try again later.",
            logger.error,
            cast("ExtraLogInfo", {"email": data.email, "error": str(e)}),
            e,
        )
    raise AssertionError("Unreachable")

@router.post(
    "/login",
    response_model=AuthResponse,
    summary=LOGIN_SUMMARY,
    description=LOGIN_DESCRIPTION,
    dependencies=[
        Depends(get_request_id),
        Depends(require_feature("auth:login")),
        Depends(require_api_key),
    ],
)
async def login(
    data: UserLoginRequest,
    session: AsyncSession = Depends(get_db),
    user_service: UserService = Depends(get_user_service),
    user_action_limiter: UserActionLimiterProtocol = Depends(get_user_action_limiter),
) -> AuthResponse:
    """Authenticates a user and returns a JWT access token.

    Raises:
        UserNotFoundError: If user is not found.
        ValidationError: If credentials are invalid.
        Exception: For unexpected errors.

    """
    await check_rate_limit(
        user_action_limiter,
        f"login:{data.email}",
        {"email": data.email},
        action="login",
    )
    logger.info(f"User login attempt: {data.email}")
    try:
        access_token: str
        refresh_token: str
        access_token, refresh_token = await user_service.authenticate_user(
            session,
            data.email,
            data.password,
        )
        logger.info(f"User authenticated successfully: {data.email}")
        return AuthResponse(access_token=access_token, refresh_token=refresh_token)
    except UserNotFoundError as e:
        logger.warning(f"Login failed: {data.email}")
        http_error(
            401,
            "Invalid credentials",
            logger.warning,
            cast("ExtraLogInfo", {"email": data.email}),
            e,
        )
    except ValidationError as e:
        logger.warning(f"Login failed: {data.email}")
        http_error(
            401,
            "Invalid credentials",
            logger.warning,
            cast("ExtraLogInfo", {"email": data.email}),
            e,
        )
    except Exception as e:
        logger.error(f"Login failed: {data.email}")
        http_error(
            401,
            "An unexpected error occurred. Please try again later.",
            logger.error,
            cast("ExtraLogInfo", {"email": data.email, "error": str(e)}),
            e,
        )
    raise AssertionError("Unreachable")

@router.post(
    "/logout",
    response_model=MessageResponse,
    summary=LOGOUT_SUMMARY,
    description=LOGOUT_DESCRIPTION,
    dependencies=[
        Depends(get_request_id),
        Depends(require_feature("auth:logout")),
        Depends(require_api_key),
    ],
)
async def logout(
    request: Request,
    current_user: User = Depends(get_current_user),
    session: AsyncSession = Depends(get_db),
    user_service: UserService = Depends(get_user_service),
    blacklist_token: Callable[[AsyncSession, str, datetime], Awaitable[None]] = Depends(
        get_blacklist_token,
    ),
) -> MessageResponse:
    """Logs out the current user and blacklists the access token.

    Raises:
        Exception: If token is invalid or expired.

    """
    logger.info("logout_attempt", extra={"user_id": current_user.id})
    auth_header: str | None = request.headers.get("authorization") if request else None
    if auth_header is not None and auth_header.lower().startswith("bearer "):
        token: str = auth_header.split(" ", 1)[1]
        try:
            settings = get_settings()
            if not settings.jwt_secret_key:
                raise ValueError("JWT secret key is not configured.")
            payload: Mapping[str, object] = jwt.decode(
                token,
                str(settings.jwt_secret_key),
                algorithms=[settings.jwt_algorithm],
            )
            jti: str = cast("str", payload.get("jti") or token)
            exp: int | None = cast("int | None", payload.get("exp"))
            if exp is not None:
                expires_at: datetime = datetime.fromtimestamp(exp, tz=UTC)
                await blacklist_token(session, jti, expires_at)
                logger.info(
                    "logout_token_blacklisted",
                    extra={"user_id": current_user.id},
                )
        except Exception as e:
            logger.error(
                "logout_token_blacklist_error",
                extra={
                    "error": str(e),
                    "error_type": type(e).__name__,
                    "user_id": current_user.id,
                    "token_length": len(token) if token else 0,
                },
            )
            http_error(
                401,
                "Invalid or expired token.",
                logger.warning,
                cast("ExtraLogInfo", {"error": str(e)}),
            )
    await user_service.logout_user(session, current_user.id)
    logger.info("logout_success", extra={"user_id": current_user.id})
    return MessageResponse(message="Logged out successfully.")

@router.post(
    "/refresh-token",
    response_model=AuthResponse,
    summary=REFRESH_SUMMARY,
    description=REFRESH_DESCRIPTION,
    dependencies=[
        Depends(get_request_id),
        Depends(require_feature("auth:refresh_token")),
        Depends(require_api_key),
    ],
)
async def refresh_token(
    body: Mapping[str, object] = Body(...),
    session: AsyncSession = Depends(get_db),
    async_refresh_access_token: Callable[[AsyncSession, str], Awaitable[str]] = Depends(
        get_async_refresh_access_token,
    ),
) -> AuthResponse:
    """Accepts either {"token": ...} or {"refresh_token": ...} for compatibility with tests.

    Raises:
        RefreshTokenRateLimitError: If too many attempts.
        RefreshTokenBlacklistedError: If token is blacklisted.
        RefreshTokenError: If token is invalid.
        ValueError: If token is missing or invalid.

    """
    token_val: object | None = body.get("token") or body.get("refresh_token")
    if not isinstance(token_val, str):
        http_error(422, "Missing refresh token.", logger.warning, {})
    token: str = token_val if isinstance(token_val, str) else ""
    try:
        new_token: str = await async_refresh_access_token(session, token)
        logger.info("refresh_success", extra={"token": token})
        return AuthResponse(access_token=new_token, refresh_token=token)
    except RefreshTokenRateLimitError:
        http_error(
            429,
            "Too many token refresh attempts. Please try again later.",
            logger.warning,
            cast("ExtraLogInfo", {"token": token}),
        )
    except RefreshTokenBlacklistedError:
        http_error(
            401,
            "Invalid or expired refresh token.",
            logger.warning,
            cast("ExtraLogInfo", {"token": token}),
        )
    except RefreshTokenError:
        http_error(
            401,
            "Invalid or expired refresh token.",
            logger.warning,
            cast("ExtraLogInfo", {"token": token}),
        )
    except ValueError as e:
        http_error(
            401,
            "Invalid or expired refresh token.",
            logger.warning,
            cast("ExtraLogInfo", {"token": token, "error": str(e)}),
            e,
        )
    except Exception as e:
        http_error(
            401,
            "Invalid or expired refresh token.",
            logger.warning,
            cast("ExtraLogInfo", {"token": token, "error": str(e)}),
            e,
        )
    raise AssertionError("Unreachable")

@router.post(
    "/request-password-reset",
    response_model=MessageResponse,
    summary=PWRESET_REQUEST_SUMMARY,
    description=PWRESET_REQUEST_DESCRIPTION,
    dependencies=[
        Depends(get_request_id),
        Depends(require_feature("auth:request_password_reset")),
        Depends(require_api_key),
    ],
)
async def request_password_reset(
    data: PasswordResetRequest,
    session: AsyncSession = Depends(get_db),
    user_service: UserService = Depends(get_user_service),
    user_action_limiter: UserActionLimiterProtocol = Depends(get_user_action_limiter),
    validate_email: Callable[[str], bool] = Depends(get_validate_email),
) -> MessageResponse:
    """Initiates a password reset flow.

    Raises:
        Exception: For unexpected errors.

    """
    await check_rate_limit(
        user_action_limiter,
        f"pwreset:{data.email}",
        {"email": data.email},
        action="pwreset",
    )
    logger.info(f"Password reset requested: {data.email}")
    try:
        user_service.get_password_reset_token(data.email)
        logger.info("pwreset_link_generated", extra={"email": data.email})
        return MessageResponse(message="Password reset link sent.")
    except Exception as e:
        logger.warning(
            f"Password reset request failed: {data.email}",
            extra={"error": str(e)},
        )
        return MessageResponse(message="Password reset link sent.")

@router.post(
    "/reset-password",
    response_model=MessageResponse,
    summary=PWRESET_SUMMARY,
    description=PWRESET_DESCRIPTION,
    dependencies=[
        Depends(get_request_id),
        Depends(require_feature("auth:reset_password")),
        Depends(require_api_key),
    ],
)
async def reset_password(
    data: PasswordResetConfirmRequest = Body(...),
    session: AsyncSession = Depends(get_db),
    user_service: UserService = Depends(get_user_service),
    get_password_validation_error: Callable[[str], str | None] = Depends(
        get_password_validation_error,
    ),
) -> MessageResponse:
    """Completes the password reset flow using a valid reset token.

    Raises:
        ValidationError: If password is invalid.
        Exception: For unexpected errors.

    """
    pw_error: str | None = get_password_validation_error(data.new_password)
    if pw_error is not None:
        http_error(
            400,
            pw_error,
            logger.warning,
            cast("ExtraLogInfo", {"token_prefix": data.token[:8]}),
        )
    logger.info(f"Password reset confirm attempt: {data.token[:8]}")
    try:
        await user_service.reset_password(session, data.token, data.new_password)
        logger.info(f"Password reset successful: {data.token[:8]}")
        return MessageResponse(message="Password has been reset.")
    except ValidationError as e:
        http_error(
            400,
            str(e),
            logger.warning,
            cast("ExtraLogInfo", {"token_prefix": data.token[:8], "error": str(e)}),
            e,
        )
    except Exception as e:
        http_error(
            400,
            "An error occurred while resetting the password. Please try again later.",
            logger.error,
            cast("ExtraLogInfo", {"token_prefix": data.token[:8], "error": str(e)}),
            e,
        )
    raise AssertionError("Unreachable")

@router.get(
    "/me",
    response_model=UserProfile,
    summary=ME_SUMMARY,
    description=ME_DESCRIPTION,
    dependencies=[
        Depends(get_request_id),
        Depends(require_feature("auth:me")),
        Depends(require_api_key),
    ],
)
async def get_me(
    current_user: User = Depends(get_current_user),
) -> UserProfile:
    """Returns the profile information of the currently authenticated user."""
    logger.info("Get current user info", extra={"user_id": current_user.id})
    user_dict: dict[str, object] = {
        "id": current_user.id,
        "email": current_user.email,
        "name": current_user.name,
        "bio": current_user.bio,
        "avatar_url": current_user.avatar_url,
        "created_at": (
            current_user.created_at.isoformat() if current_user.created_at else None
        ),
        "updated_at": (
            current_user.updated_at.isoformat() if current_user.updated_at else None
        ),
    }
    return UserProfile.model_validate(user_dict)

def ensure_nonempty_filename(file: UploadFile = FastAPIFile(...)) -> UploadFile:
    """
    Ensures the uploaded file has a non-empty filename.
    Raises:
        HTTPException: If the filename is empty.
    """
    if not file.filename:
        http_error(
            400,
            "Invalid file.",
            logger.warning,
            cast(ExtraLogInfo, {"filename": str(file.filename)}),
        )
    return file

async def root_test() -> Mapping[str, str]:
    logging.warning("UPLOADS ROOT-TEST CALLED")
    return _root_test_response()

async def test_alive() -> Mapping[str, str]:
    logging.warning("UPLOADS TEST-ALIVE CALLED")
    return _test_alive_response()

async def export_alive() -> Mapping[str, str]:
    logging.warning("UPLOADS EXPORT-ALIVE CALLED")
    return _export_alive_response()

@router.get(
    "/export-test",
    summary="Test endpoint for export router",
    description="""
    **Export Router Test**

    Returns 200 if the uploads export router is active. Requires authentication.

    **Returns:**
    - JSON status
    - Current user ID (if authenticated)
    """,
    tags=["File"],
    responses={
        200: {
            "description": "Export router test successful",
            "content": {
                "application/json": {
                    "examples": {
                        "default": {"value": {"status": "uploads export test"}}
                    }
                }
            },
        }
    },
)
async def export_test(
    current_user: User | None = Depends(get_current_user),
) -> Mapping[str, str]:
    logging.warning(
        f"UPLOADS EXPORT-TEST CALLED with user_id={current_user.id if current_user else 'None'}"
    )
    return {"status": "uploads export test"}

@router.get(
    "/export",
    summary="Export files as CSV",
    description="""
    **Export Operation**

    Exports the list of uploaded files as a CSV file.

    **Steps:**
    1. Authenticated user requests export.
    2. Server filters and sorts files as requested.
    3. Returns a CSV with filename and URL columns.

    **Notes:**
    - Supports filtering by creation date and filename.
    - Rate limiting and authentication required.
    """,
    responses={
        200: {
            "description": "Files exported as CSV",
            "content": {
                "text/csv": {
                    "examples": {
                        "default": {
                            "value": "filename,url\ndocument.pdf,/uploads/document.pdf"
                        }
                    }
                }
            },
        },
        401: {
            "description": "Unauthorized. Missing or invalid authentication.",
            "content": {
                "application/json": {"example": {"detail": "Not authenticated."}}
            },
        },
        403: {
            "description": "Forbidden. Not enough permissions.",
            "content": {
                "application/json": {"example": {"detail": "Not enough permissions."}}
            },
        },
        422: {
            "description": "Unprocessable Entity. Invalid input.",
            "content": {"application/json": {"example": {"detail": "Invalid input."}}},
        },
        429: {
            "description": "Too many requests.",
            "content": {
                "application/json": {"example": {"detail": "Rate limit exceeded."}}
            },
        },
        500: {
            "description": "Internal server error.",
            "content": {
                "application/json": {"example": {"detail": "Unexpected error."}}
            },
        },
        503: {
            "description": "Service unavailable.",
            "content": {
                "application/json": {
                    "example": {"detail": "Service temporarily unavailable."}
                }
            },
        },
    },
    openapi_extra={
        "x-codeSamples": [
            {
                "lang": "curl",
                "label": "cURL",
                "source": "curl -H 'Authorization: Bearer <token>' 'https://api.reviewpoint.org/api/v1/uploads/export'",
            },
            {
                "lang": "Python",
                "label": "Python (requests)",
                "source": "import requests\nurl = 'https://api.reviewpoint.org/api/v1/uploads/export'\nheaders = {'Authorization': 'Bearer <token>'}\nresponse = requests.get(url, headers=headers)\nprint(response.content.decode())",
            },
            {
                "lang": "JavaScript",
                "label": "JavaScript (fetch)",
                "source": "fetch('https://api.reviewpoint.org/api/v1/uploads/export', {\n  headers: { 'Authorization': 'Bearer <token>' }\n})\n  .then(res => res.text())\n  .then(console.log);",
            },
            {
                "lang": "Go",
                "label": "Go (net/http)",
                "source": 'package main\nimport (\n  "net/http"\n)\nfunc main() {\n  req, _ := http.NewRequest("GET", "https://api.reviewpoint.org/api/v1/uploads/export", nil)\n  req.Header.Set("Authorization", "Bearer <token>")\n  http.DefaultClient.Do(req)\n}',
            },
            {
                "lang": "Java",
                "label": "Java (OkHttp)",
                "source": 'OkHttpClient client = new OkHttpClient();\nRequest request = new Request.Builder()\n  .url("https://api.reviewpoint.org/api/v1/uploads/export")\n  .get()\n  .addHeader("Authorization", "Bearer <token>")\n  .build();\nResponse response = client.newCall(request).execute();',
            },
            {
                "lang": "PHP",
                "label": "PHP (cURL)",
                "source": "$ch = curl_init('https://api.reviewpoint.org/api/v1/uploads/export');\ncurl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <token>']);\n$response = curl_exec($ch);\ncurl_close($ch);",
            },
            {
                "lang": "Ruby",
                "label": "Ruby (Net::HTTP)",
                "source": "require 'net/http'\nuri = URI('https://api.reviewpoint.org/api/v1/uploads/export')\nreq = Net::HTTP::Get.new(uri)\nreq['Authorization'] = 'Bearer <token>'\nres = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }\nputs res.body",
            },
            {
                "lang": "HTTPie",
                "label": "HTTPie",
                "source": "http GET https://api.reviewpoint.org/api/v1/uploads/export Authorization:'Bearer <token>'",
            },
            {
                "lang": "PowerShell",
                "label": "PowerShell",
                "source": "$headers = @{Authorization='Bearer <token>'}\nInvoke-RestMethod -Uri 'https://api.reviewpoint.org/api/v1/uploads/export' -Headers $headers -Method Get",
            },
        ]
    },
)
async def export_files_csv(
    session: AsyncSession = Depends(get_async_session),
    current_user: User = Depends(get_current_user),
    params: object = Depends(pagination_params),
    q: str | None = Query(None, description="Search by filename (partial match)"),
    sort: Literal["created_at", "filename"] = Query(
        "created_at", description="Sort by field: created_at, filename"
    ),
    order: Literal["desc", "asc"] = Query(
        "desc", description="Sort order: asc or desc"
    ),
    fields: str | None = Query(
        None,
        description="Comma-separated list of fields to include in response (e.g. filename,url)",
    ),
    created_before: str | None = Query(
        None,
        description="Filter files created before this datetime (ISO 8601, e.g. 2024-01-01T00:00:00Z)",
    ),
    created_after: str | None = Query(
        None,
        description="Filter files created after this datetime (ISO 8601, e.g. 2024-01-01T00:00:00Z)",
    ),
    request_id: str = Depends(get_request_id),
    feature_flag_ok: bool = Depends(require_feature("uploads:export")),
    api_key_ok: None = Depends(require_api_key),
) -> StreamingResponse:
    """
    Export the list of uploaded files as a CSV file.
    Raises:
        HTTPException: If date parsing fails.
    """
    logging.info(
        f"UPLOADS EXPORT CALLED with user_id={getattr(current_user, 'id', None)}"
    )

    def _generate_csv(files: Sequence[DBFile], columns: Sequence[str]) -> Iterator[str]:
        output: StringIO = StringIO()
        writer = csv.writer(output)
        writer.writerow(columns)
        for f in files:
            row: list[str] = []
            if "filename" in columns:
                row.append(f.filename)
            if "url" in columns:
                row.append(f"/uploads/{f.filename}")
            writer.writerow(row)
        yield output.getvalue()

    created_after_dt: datetime | None
    created_before_dt: datetime | None
    try:
        created_after_dt = (
            parse_flexible_datetime(created_after) if created_after else None
        )
    except ValueError as e:
        logger.error(f"Invalid created_after: {e}")
        http_error(
            422,
            str(e),
            logger.error,
            cast(ExtraLogInfo, {"created_after": created_after or ""}),
            e,
        )
    try:
        created_before_dt = (
            parse_flexible_datetime(created_before) if created_before else None
        )
    except ValueError as e:
        logger.error(f"Invalid created_before: {e}")
        http_error(
            422,
            str(e),
            logger.error,
            cast(ExtraLogInfo, {"created_before": created_before or ""}),
            e,
        )
    files: Sequence[DBFile]
    _total: int
    files, _total = await repo_list_files(
        session,
        current_user.id,
        offset=getattr(params, "offset", 0),
        limit=getattr(params, "limit", 10000),  # Large limit for export
        q=q,
        sort=sort,
        order=order,
        created_after=created_after_dt,
        created_before=created_before_dt,
    )
    columns: list[str] = ["filename", "url"]
    if fields:
        requested: list[str] = [
            f.strip() for f in fields.split(",") if f.strip() in columns
        ]
        if requested:
            columns = requested
    return StreamingResponse(
        _generate_csv(files, columns),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=uploads_export.csv"},
    )

@router.post(
    "",
    summary="Upload a file",
    description="""
    **Secure File Upload**

    Uploads files with comprehensive validation, virus scanning, and metadata generation.

    **Process:**
    1. **File Validation**: Checks file type, size, and content
    2. **Security Scan**: Virus scanning and malware detection
    3. **Metadata Generation**: Extracts file information and generates checksums
    4. **Storage**: Secure storage with access controls
    5. **Response**: Returns file metadata and access URLs

    **Supported File Types:**
    - **Documents**: PDF, DOC, DOCX, TXT, RTF
    - **Images**: JPEG, PNG, GIF, SVG, WEBP
    - **Data**: CSV, XLS, XLSX, JSON, XML
    - **Archives**: ZIP, TAR, GZ (with content scanning)

    **File Constraints:**
    - **Maximum Size**: 100MB per file
    - **Rate Limiting**: 5 uploads per minute per user
    - **Naming**: Automatic sanitization and duplicate handling

    **Security Features:**
    - Virus and malware scanning
    - Content type validation (not just extension)
    - File size limits and timeout protection
    - Automatic quarantine of suspicious files
    - Access logging and audit trail

    **Response Format:**
    ```json
    {
      "id": 123,
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "size": 2048576,
      "md5_hash": "d41d8cd98f00b204e9800998ecf8427e",
      "upload_url": "/api/v1/uploads/123",
      "download_url": "/api/v1/uploads/123/download",
      "created_at": "2024-01-16T09:15:00Z"
    }
    ```

    **Usage Examples:**

    *cURL:*
    ```bash
    curl -X POST "https://api.reviewpoint.org/api/v1/uploads" \\
      -H "Authorization: Bearer YOUR_JWT_TOKEN" \\
      -F "file=@document.pdf" \\
      -F "description=Research paper draft"
    ```

    *Python:*
    ```python
    import requests
    files = {"file": ("doc.pdf", open("doc.pdf", "rb"))}
    headers = {"Authorization": "Bearer YOUR_JWT_TOKEN"}
    response = requests.post(
        "https://api.reviewpoint.org/api/v1/uploads",
        files=files,
        headers=headers
    )
    ```

    **Error Handling:**
    - `400`: Invalid file type or corrupt file
    - `401`: Authentication required
    - `413`: File too large (>100MB)
    - `415`: Unsupported file type
    - `429`: Upload rate limit exceeded
    - `422`: Validation errors (missing file, etc.)
    """,
    response_model=FileUploadResponse,
    status_code=status.HTTP_201_CREATED,
    responses={
        201: {
            "description": "File uploaded successfully",
            "content": {
                "application/json": {
                    "example": {
                        "filename": "document.pdf",
                        "url": "/uploads/document.pdf",
                    }
                }
            },
        },
        400: {
            "description": "Invalid file",
            "content": {
                "application/json": {"example": {"detail": "File type not allowed."}}
            },
        },
        401: {
            "description": "Unauthorized. Missing or invalid authentication.",
            "content": {
                "application/json": {"example": {"detail": "Not authenticated."}}
            },
        },
        413: {
            "description": "File too large.",
            "content": {
                "application/json": {"example": {"detail": "File size exceeds limit."}}
            },
        },
        415: {
            "description": "Unsupported Media Type.",
            "content": {
                "application/json": {"example": {"detail": "Unsupported file type."}}
            },
        },
        422: {
            "description": "Unprocessable Entity. Invalid input.",
            "content": {"application/json": {"example": {"detail": "Invalid input."}}},
        },
        429: {
            "description": "Too many requests.",
            "content": {
                "application/json": {"example": {"detail": "Rate limit exceeded."}}
            },
        },
        500: {
            "description": "Internal server error.",
            "content": {
                "application/json": {"example": {"detail": "Unexpected error."}}
            },
        },
        503: {
            "description": "Service unavailable.",
            "content": {
                "application/json": {
                    "example": {"detail": "Service temporarily unavailable."}
                }
            },
        },
    },
    openapi_extra={
        "requestBody": {
            "content": {
                "multipart/form-data": {
                    "example": {"file": "(binary file, e.g. document.pdf)"}
                }
            }
        },
        "x-codeSamples": [
            {
                "lang": "curl",
                "label": "cURL",
                "source": "curl -X POST 'https://api.reviewpoint.org/api/v1/uploads' \\\n  -H 'Authorization: Bearer <token>' \\\n  -F 'file=@document.pdf'",
            },
            {
                "lang": "Python",
                "label": "Python (requests)",
                "source": "import requests\nurl = 'https://api.reviewpoint.org/api/v1/uploads'\nheaders = {'Authorization': 'Bearer <token>'}\nfiles = {'file': open('document.pdf', 'rb')}\nresponse = requests.post(url, headers=headers, files=files)\nprint(response.json())",
            },
            {
                "lang": "JavaScript",
                "label": "JavaScript (fetch)",
                "source": "const form = new FormData();\nform.append('file', fileInput.files[0]);\nfetch('https://api.reviewpoint.org/api/v1/uploads', {\n  method: 'POST',\n  headers: { 'Authorization': 'Bearer <token>' },\n  body: form\n})\n  .then(res => res.json())\n  .then(console.log);",
            },
            {
                "lang": "Go",
                "label": "Go (net/http)",
                "source": 'package main\nimport (\n  "bytes"\n  "mime/multipart"\n  "net/http"\n  "os"\n)\nfunc main() {\n  file, _ := os.Open("document.pdf")\n  defer file.Close()\n  body := &bytes.Buffer{}\n  writer := multipart.NewWriter(body)\n  part, _ := writer.CreateFormFile("file", "document.pdf")\n  io.Copy(part, file)\n  writer.Close()\n  req, _ := http.NewRequest("POST", "https://api.reviewpoint.org/api/v1/uploads", body)\n  req.Header.Set("Authorization", "Bearer <token>")\n  req.Header.Set("Content-Type", writer.FormDataContentType())\n  http.DefaultClient.Do(req)\n}',
            },
            {
                "lang": "Java",
                "label": "Java (OkHttp)",
                "source": 'OkHttpClient client = new OkHttpClient();\nMediaType mediaType = MediaType.parse("application/pdf");\nFile file = new File("document.pdf");\nRequestBody fileBody = RequestBody.create(mediaType, file);\nMultipartBody requestBody = new MultipartBody.Builder()\n  .setType(MultipartBody.FORM)\n  .addFormDataPart("file", file.getName(), fileBody)\n  .build();\nRequest request = new Request.Builder()\n  .url("https://api.reviewpoint.org/api/v1/uploads")\n  .post(requestBody)\n  .addHeader("Authorization", "Bearer <token>")\n  .build();\nResponse response = client.newCall(request).execute();',
            },
            {
                "lang": "PHP",
                "label": "PHP (cURL)",
                "source": "$ch = curl_init('https://api.reviewpoint.org/api/v1/uploads');\ncurl_setopt($ch, CURLOPT_POST, 1);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, ['file' => new CURLFile('document.pdf')]);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <token>']);\n$response = curl_exec($ch);\ncurl_close($ch);",
            },
            {
                "lang": "Ruby",
                "label": "Ruby (Net::HTTP)",
                "source": "require 'net/http'\nrequire 'uri'\nrequire 'json'\nuri = URI('https://api.reviewpoint.org/api/v1/uploads')\nrequest = Net::HTTP::Post.new(uri)\nrequest['Authorization'] = 'Bearer <token>'\nform_data = [['file', File.open('document.pdf')]]\nrequest.set_form form_data, 'multipart/form-data'\nresponse = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|\n  http.request(request)\nend\nputs response.body",
            },
            {
                "lang": "HTTPie",
                "label": "HTTPie",
                "source": "http -f POST https://api.reviewpoint.org/api/v1/uploads Authorization:'Bearer <token>' file@document.pdf",
            },
            {
                "lang": "PowerShell",
                "label": "PowerShell",
                "source": "$file = Get-Item .\\document.pdf\n$Form = @{file = $file}\nInvoke-RestMethod -Uri 'https://api.reviewpoint.org/api/v1/uploads' -Method Post -Form $Form -Headers @{Authorization='Bearer <token>'}",
            },
        ],
    },
)
async def upload_file(
    file: UploadFile = FastAPIFile(
        ..., description="The file to upload. Must be a valid file type."
    ),
    session: AsyncSession = Depends(get_async_session),
    current_user: User = Depends(get_current_user),
    request_id: str = Depends(get_request_id),
    feature_flag_ok: bool = Depends(require_feature("uploads:upload")),
    api_key_ok: None = Depends(require_api_key),
) -> FileUploadResponse:
    """
    Uploads a file and returns its filename and URL.
    Raises:
        HTTPException: If file is invalid or upload fails.
    """

    # Enforce a maximum upload size (e.g., 5MB)
    MAX_UPLOAD_SIZE = 5 * 1024 * 1024  # 5MB
    file.file.seek(0, 2)  # Seek to end
    file_size = file.file.tell()
    file.file.seek(0)
    if file_size > MAX_UPLOAD_SIZE:
        http_error(
            413,
            f"File size exceeds limit of {MAX_UPLOAD_SIZE // (1024*1024)}MB.",
            logger.warning,
            cast(ExtraLogInfo, {"filename": str(file.filename), "size": file_size}),
        )

    if not file.filename:
        http_error(
            400,
            "Invalid file.",
            logger.warning,
            cast(ExtraLogInfo, {"filename": str(file.filename)}),
        )

    filename_str: str = file.filename if file.filename is not None else ""
    if not is_safe_filename(filename_str):
        http_error(
            400,
            "Invalid filename. Path traversal attempts are not allowed.",
            logger.warning,
            cast(ExtraLogInfo, {"filename": filename_str}),
        )

    safe_filename: str = sanitize_filename(filename_str)
    original_filename: str = filename_str
    file.filename = safe_filename

    if original_filename != safe_filename:
        logging.warning(
            f"Filename sanitized from '{original_filename}' to '{safe_filename}'"
        )

    max_retries: Final[int] = 3
    last_exception: Exception | None = None

    for attempt in range(max_retries):
        try:
            # Create a new session for each attempt to avoid SQLAlchemy IllegalStateChangeError
            async with session.begin_nested():
                db_file: DBFile = await create_file(
                    session,
                    file.filename,
                    file.content_type or "application/octet-stream",
                    user_id=current_user.id,
                    size=file_size,
                )

            await session.commit()
            return FileUploadResponse(
                filename=db_file.filename, url=f"/uploads/{db_file.filename}"
            )
        except Exception as e:
            last_exception = e
            try:
                await session.rollback()
            except Exception as rollback_error:
                logging.error(f"Error during session rollback: {rollback_error}")
            error_str: str = str(e).lower()

            if attempt < max_retries - 1 and (
                "database is locked" in error_str
                or "unique constraint failed" in error_str
                or "illegal state change" in error_str
            ):
                wait_time: float = 0.1 * (2**attempt)
                await asyncio.sleep(wait_time)
                continue

            if "unique constraint failed" in error_str:
                http_error(
                    409,
                    "File with same name already exists or concurrent upload conflict",
                    logger.warning,
                    cast(
                        ExtraLogInfo,
                        {
                            "filename": (
                                file.filename if file.filename is not None else ""
                            )
                        },
                    ),
                    e,
                )

            logging.error(f"Failed to upload file on attempt {attempt+1}: {str(e)}")

    if last_exception:
        if "illegal state change" in str(last_exception).lower():
            http_error(
                500,
                "Database concurrency conflict. Please try again.",
                logger.error,
                cast(
                    ExtraLogInfo,
                    {"filename": file.filename if file.filename is not None else ""},
                ),
                last_exception,
            )
        http_error(
            500,
            f"Failed to upload file: {str(last_exception)}",
            logger.error,
            cast(
                ExtraLogInfo,
                {"filename": file.filename if file.filename is not None else ""},
            ),
            last_exception,
        )
    http_error(
        500,
        "Failed to upload file after multiple retries",
        logger.error,
        cast(
            ExtraLogInfo,
            {"filename": file.filename if file.filename is not None else ""},
        ),
    )

    # Defensive: static type checkers require a return, but this is unreachable
    raise RuntimeError(
        "Unreachable: all code paths in upload_file should raise or return"
    )

@router.post(
    "/bulk-delete",
    summary="Bulk delete files",
    description="""
    **Bulk File Deletion**

    Delete multiple files in a single request.

    **Features:**
    - Delete up to 100 files per request
    - Only deletes files owned by the current user
    - Returns detailed success/failure results
    - Atomic operation per file (failure of one doesn't affect others)

    **Request Body:**
    ```json
    {
      "filenames": ["file1.pdf", "file2.pdf", "file3.pdf"]
    }
    ```

    **Response:**
    ```json
    {
      "deleted": ["file1.pdf", "file2.pdf"],
      "failed": ["file3.pdf"]
    }
    ```
    """,
    response_model=BulkDeleteResponse,
    status_code=status.HTTP_200_OK,
)
async def bulk_delete_files_endpoint(
    request_data: BulkDeleteRequest,
    session: AsyncSession = Depends(get_async_session),
    current_user: User = Depends(get_current_user),
    request_id: str = Depends(get_request_id),
    feature_flag_ok: bool = Depends(require_feature("uploads:bulk_delete")),
    api_key_ok: None = Depends(require_api_key),
) -> BulkDeleteResponse:
    """
    Bulk delete files for the current user.
    """
    # Limit bulk operations to prevent abuse
    if len(request_data.filenames) > 100:
        http_error(
            400,
            "Cannot delete more than 100 files at once",
            logger.warning,
            cast(ExtraLogInfo, {"count": len(request_data.filenames)}),
        )

    if not request_data.filenames:
        return BulkDeleteResponse(deleted=[], failed=[])

    try:
        deleted, failed = await bulk_delete_files(
            session, request_data.filenames, current_user.id
        )
        await session.commit()

        logger.info(
            f"Bulk delete completed: {len(deleted)} deleted, {len(failed)} failed",
            extra={"user_id": current_user.id, "deleted": deleted, "failed": failed},
        )

        return BulkDeleteResponse(deleted=deleted, failed=failed)
    except Exception as e:
        await session.rollback()
        http_error(
            500,
            f"Bulk delete failed: {str(e)}",
            logger.error,
            cast(ExtraLogInfo, {"filenames": request_data.filenames}),
            e,
        )
        # This should never be reached due to http_error raising, but for type safety
        return BulkDeleteResponse(deleted=[], failed=request_data.filenames)