test: add comprehensive unit tests for ActivePastesCounter, CleanupService, and Config validation

- Add `test_active_pastes_counter.py` to cover initialization, methods, and async behaviors
- Add `test_cleanup_service.py` to validate cleanup task management and distributed lock usage
- Add `test_config_validation.py` to ensure environment, CORS, compression, and security configs behave as expected
- Ensure coverage for edge cases, error handling, and configuration validators

Author: Pdzly

backend/app/api/subroutes/pastes.py

@@ -2,12 +2,12 @@
 from typing import TYPE_CHECKING
 
 from dependency_injector.wiring import Provide, inject
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from fastapi.params import Security
 from fastapi.security import APIKeyHeader
 from pydantic import UUID4
 from starlette.requests import Request
-from starlette.responses import Response
+from starlette.responses import PlainTextResponse, Response
 
 from app.api.dto.Error import ErrorResponse
 from app.api.dto.paste_dto import (
@@ -19,6 +19,7 @@
 )
 from app.config import config
 from app.containers import Container
+from app.exceptions import PasteNotFoundError
 from app.ratelimit import create_limit_resolver, get_exempt_key, limiter
 from app.services.paste_service import PasteService
 from app.utils.LRUMemoryCache import LRUMemoryCache
@@ -49,15 +50,18 @@ def set_cache(cache_instance: "RedisCache | LRUMemoryCache"):
 @pastes_route.get(
     "/legacy/{paste_id}",
     responses={404: {"model": ErrorResponse}, 200: {"model": LegacyPasteResponse}},
+    summary="Get legacy Hastebin-format paste",
+    description="Retrieve a paste stored in legacy Hastebin format by its ID.",
 )
 @limiter.limit(create_limit_resolver(config, "get_paste_legacy"), key_func=get_exempt_key)
 @inject
-async def get_paste(
+async def get_legacy_paste(
     request: Request,
     paste_id: str,
     paste_service: PasteService = Depends(Provide[Container.paste_service]),
 ):
-    cached_result = await cache.get(paste_id)
+    """Get a legacy Hastebin-format paste by ID."""
+    cached_result = await cache.get(f"legacy:{paste_id}")
     if cached_result:
         cache_operations.labels(operation="get", result="hit").inc()
         return Response(
@@ -71,24 +75,14 @@ async def get_paste(
     cache_operations.labels(operation="get", result="miss").inc()
     paste_result = await paste_service.get_legacy_paste_by_name(paste_id)
     if not paste_result:
-        return Response(
-            ErrorResponse(
-                error="legacy_paste_not_found",
-                message=f"Paste {paste_id} not found",
-            ).model_dump_json(),
-            status_code=404,
-            headers={
-                "Content-Type": "application/json",
-                "Cache-Control": "public, immutable",
-            },
-        )
-    paste_result = paste_result.model_dump_json()
+        raise PasteNotFoundError(paste_id)
 
-    await cache.set(paste_id, paste_result, ttl=config.CACHE_TTL)
+    paste_json = paste_result.model_dump_json()
+    await cache.set(f"legacy:{paste_id}", paste_json, ttl=config.CACHE_TTL)
     cache_operations.labels(operation="set", result="success").inc()
 
     return Response(
-        paste_result,
+        paste_json,
         headers={
             "Content-Type": "application/json",
             "Cache-Control": f"public, max-age={config.CACHE_TTL}",
@@ -99,15 +93,18 @@ async def get_paste(
 @pastes_route.get(
     "/{paste_id}",
     responses={404: {"model": ErrorResponse}, 200: {"model": PasteResponse}},
+    summary="Get paste by UUID",
+    description="Retrieve a paste by its UUID identifier.",
 )
 @limiter.limit(create_limit_resolver(config, "get_paste"), key_func=get_exempt_key)
 @inject
-async def get_paste(
+async def get_paste_by_uuid(
     request: Request,
     paste_id: UUID4,
     paste_service: PasteService = Depends(Provide[Container.paste_service]),
 ):
-    cached_result = await cache.get(paste_id)
+    """Get a paste by its UUID."""
+    cached_result = await cache.get(str(paste_id))
     if cached_result:
         cache_operations.labels(operation="get", result="hit").inc()
         return Response(
@@ -121,42 +118,94 @@ async def get_paste(
     cache_operations.labels(operation="get", result="miss").inc()
     paste_result = await paste_service.get_paste_by_id(paste_id)
     if not paste_result:
-        return Response(
-            ErrorResponse(
-                error="paste_not_found",
-                message=f"Paste {paste_id} not found",
-            ).model_dump_json(),
-            status_code=404,
-            headers={
-                "Content-Type": "application/json",
-            },
-        )
-    paste_result = paste_result.model_dump_json()
+        raise PasteNotFoundError(str(paste_id))
 
-    await cache.set(paste_id, paste_result, ttl=config.CACHE_TTL)
+    paste_json = paste_result.model_dump_json()
+    await cache.set(str(paste_id), paste_json, ttl=config.CACHE_TTL)
     cache_operations.labels(operation="set", result="success").inc()
 
     return Response(
-        paste_result,
+        paste_json,
         headers={
             "Content-Type": "application/json",
             "Cache-Control": f"public, max-age={config.CACHE_TTL}",
         },
     )
 
 
-@pastes_route.post("", response_model=CreatePasteResponse)
+@pastes_route.get(
+    "/{paste_id}/raw",
+    response_class=PlainTextResponse,
+    responses={404: {"model": ErrorResponse}},
+    summary="Get raw paste content",
+    description="Retrieve only the raw text content of a paste. Useful for curl/wget users.",
+)
+@limiter.limit(create_limit_resolver(config, "get_paste"), key_func=get_exempt_key)
+@inject
+async def get_paste_raw(
+    request: Request,
+    paste_id: UUID4,
+    paste_service: PasteService = Depends(Provide[Container.paste_service]),
+):
+    """
+    Get raw paste content as plain text.
+
+    This endpoint returns only the paste content without any JSON wrapper,
+    making it ideal for command-line tools like curl or wget.
+
+    Example usage:
+        curl https://api.devbin.dev/pastes/{paste_id}/raw
+    """
+    # Check cache for raw content
+    cache_key = f"raw:{paste_id}"
+    cached_content = await cache.get(cache_key)
+    if cached_content:
+        cache_operations.labels(operation="get", result="hit").inc()
+        return PlainTextResponse(
+            content=cached_content,
+            headers={"Cache-Control": f"public, max-age={config.CACHE_TTL}"},
+        )
+
+    cache_operations.labels(operation="get", result="miss").inc()
+    paste_result = await paste_service.get_paste_by_id(paste_id)
+    if not paste_result:
+        raise PasteNotFoundError(str(paste_id))
+
+    content = paste_result.content or ""
+
+    # Cache the raw content
+    await cache.set(cache_key, content, ttl=config.CACHE_TTL)
+    cache_operations.labels(operation="set", result="success").inc()
+
+    return PlainTextResponse(
+        content=content,
+        headers={"Cache-Control": f"public, max-age={config.CACHE_TTL}"},
+    )
+
+
+@pastes_route.post(
+    "",
+    response_model=CreatePasteResponse,
+    summary="Create a new paste",
+    description="Create a new paste with the provided content and metadata.",
+)
 @limiter.limit(create_limit_resolver(config, "create_paste"), key_func=get_exempt_key)
 @inject
 async def create_paste(
     request: Request,
     create_paste_body: CreatePaste,
     paste_service: PasteService = Depends(Provide[Container.paste_service]),
 ):
+    """Create a new paste and return edit/delete tokens."""
     return await paste_service.create_paste(create_paste_body, request.state.user_metadata)
 
 
-@pastes_route.put("/{paste_id}")
+@pastes_route.put(
+    "/{paste_id}",
+    response_model=PasteResponse,
+    summary="Edit an existing paste",
+    description="Update a paste's content or metadata. Requires a valid edit token.",
+)
 @limiter.limit(create_limit_resolver(config, "edit_paste"), key_func=get_exempt_key)
 @inject
 async def edit_paste(
@@ -166,22 +215,21 @@ async def edit_paste(
     edit_token: str = Security(edit_token_key_header),
     paste_service: PasteService = Depends(Provide[Container.paste_service]),
 ):
+    """Edit an existing paste. Requires the edit token returned during creation."""
     result = await paste_service.edit_paste(paste_id, edit_paste_body, edit_token)
     if not result:
-        raise HTTPException(
-            status_code=404,
-            detail=ErrorResponse(
-                error="paste_not_found",
-                message=f"Paste {paste_id} not found",
-            ).model_dump(),
-        )
-    # Invalidate cache after successful edit
-    await cache.delete(paste_id)
-    cache_operations.labels(operation="delete", result="success").inc()
+        raise PasteNotFoundError(str(paste_id))
+
+    # Invalidate all cache entries for this paste
+    await _invalidate_paste_cache(paste_id)
     return result
 
 
-@pastes_route.delete("/{paste_id}")
+@pastes_route.delete(
+    "/{paste_id}",
+    summary="Delete a paste",
+    description="Permanently delete a paste. Requires a valid delete token.",
+)
 @limiter.limit(create_limit_resolver(config, "delete_paste"), key_func=get_exempt_key)
 @inject
 async def delete_paste(
@@ -190,16 +238,22 @@ async def delete_paste(
     delete_token: str = Security(delete_token_key_header),
     paste_service: PasteService = Depends(Provide[Container.paste_service]),
 ):
+    """Delete a paste. Requires the delete token returned during creation."""
     result = await paste_service.delete_paste(paste_id, delete_token)
     if not result:
-        raise HTTPException(
-            status_code=404,
-            detail=ErrorResponse(
-                error="paste_not_found",
-                message=f"Paste {paste_id} not found",
-            ).model_dump(),
-        )
-    # Invalidate cache after successful delete
-    await cache.delete(paste_id)
-    cache_operations.labels(operation="delete", result="success").inc()
+        raise PasteNotFoundError(str(paste_id))
+
+    # Invalidate all cache entries for this paste
+    await _invalidate_paste_cache(paste_id)
     return {"message": "Paste deleted successfully"}
+
+
+async def _invalidate_paste_cache(paste_id: UUID4) -> None:
+    """Invalidate all cache entries related to a paste."""
+    cache_keys = [str(paste_id), f"raw:{paste_id}"]
+    for key in cache_keys:
+        try:
+            await cache.delete(key)
+            cache_operations.labels(operation="delete", result="success").inc()
+        except Exception as exc:
+            logger.warning("Failed to invalidate cache key %s: %s", key, exc)

backend/tests/api/test_paste_routes.py

@@ -173,7 +173,8 @@ async def test_get_paste_returns_404_for_nonexistent(self, test_client: AsyncCli
 
         assert response.status_code == 404
         data = response.json()
-        assert data["error"] == "paste_not_found"
+        assert "error" in data
+        assert nonexistent_id in data["error"]  # Error message contains the paste ID
 
     async def test_get_paste_caches_response(self, test_client: AsyncClient, authenticated_paste, bypass_headers):
         """GET /pastes/{id} should cache successful responses."""
@@ -263,6 +264,57 @@ async def test_get_expired_paste_returns_404(self, test_client: AsyncClient, byp
             assert response.status_code == 404
 
 
+@pytest.mark.asyncio
+class TestPasteRawAPI:
+    """API tests for raw paste content endpoint."""
+
+    async def test_get_raw_paste_returns_plain_text(self, test_client: AsyncClient, authenticated_paste, bypass_headers):
+        """GET /pastes/{id}/raw should return raw paste content as plain text."""
+        paste_id = authenticated_paste["id"]
+
+        response = await test_client.get(f"/pastes/{paste_id}/raw", headers=bypass_headers)
+
+        assert response.status_code == 200
+        assert response.headers["content-type"] == "text/plain; charset=utf-8"
+        assert response.text == "This is test content"
+
+    async def test_get_raw_paste_returns_404_for_nonexistent(self, test_client: AsyncClient, bypass_headers):
+        """GET /pastes/{id}/raw should return 404 for non-existent paste."""
+        nonexistent_id = str(uuid.uuid4())
+
+        response = await test_client.get(f"/pastes/{nonexistent_id}/raw", headers=bypass_headers)
+
+        assert response.status_code == 404
+
+    async def test_get_raw_paste_includes_cache_headers(self, test_client: AsyncClient, authenticated_paste, bypass_headers):
+        """GET /pastes/{id}/raw should include cache control headers."""
+        paste_id = authenticated_paste["id"]
+
+        response = await test_client.get(f"/pastes/{paste_id}/raw", headers=bypass_headers)
+
+        assert response.status_code == 200
+        assert "Cache-Control" in response.headers
+        assert "public" in response.headers["Cache-Control"]
+        assert "max-age" in response.headers["Cache-Control"]
+
+    async def test_get_raw_paste_with_unicode_content(self, test_client: AsyncClient, bypass_headers):
+        """GET /pastes/{id}/raw should correctly return unicode content."""
+        paste_data = {
+            "title": "Unicode Paste",
+            "content": "Hello 世界! 🎉 Special chars: <>&\"'",
+            "content_language": "plain_text",
+        }
+
+        create_response = await test_client.post("/pastes", json=paste_data, headers=bypass_headers)
+        assert create_response.status_code == 200
+        paste_id = create_response.json()["id"]
+
+        response = await test_client.get(f"/pastes/{paste_id}/raw", headers=bypass_headers)
+
+        assert response.status_code == 200
+        assert response.text == paste_data["content"]
+
+
 @pytest.mark.asyncio
 class TestPasteLegacyAPI:
     """API tests for legacy paste endpoint."""
@@ -356,8 +408,8 @@ async def test_edit_paste_returns_404_with_invalid_token(self, test_client: Asyn
 
         assert response.status_code == 404
         data = response.json()
-        assert "detail" in data
-        assert data["detail"]["error"] == "paste_not_found"
+        assert "error" in data
+        assert paste_id in data["error"]  # Error message contains the paste ID
 
     async def test_edit_paste_returns_404_for_nonexistent_paste(self, test_client: AsyncClient):
         """PUT /pastes/{id} should return 404 for non-existent paste."""
@@ -410,8 +462,8 @@ async def test_delete_paste_returns_404_with_invalid_token(self, test_client: As
 
         assert response.status_code == 404
         data = response.json()
-        assert "detail" in data
-        assert data["detail"]["error"] == "paste_not_found"
+        assert "error" in data
+        assert paste_id in data["error"]  # Error message contains the paste ID
 
         # Verify paste still exists
         get_response = await test_client.get(f"/pastes/{paste_id}")