Improve the thumbnail service to support compression and WEBP

api/catalog/api/docs/audio_docs.py

@@ -5,6 +5,7 @@
     MediaSearch,
     MediaStats,
     fields_to_md,
+    refer_sample,
 )
 from catalog.api.examples import (
     audio_complain_201_example,
@@ -31,6 +32,7 @@
     InputErrorSerializer,
     NotFoundErrorSerializer,
 )
+from catalog.api.serializers.media_serializers import MediaThumbnailRequestSerializer
 from catalog.api.serializers.provider_serializers import ProviderSerializer
 from drf_yasg import openapi
 
@@ -206,3 +208,17 @@ class AudioComplain(MediaComplain):
         "responses": responses,
         "code_examples": code_examples,
     }
+
+
+class AudioThumbnail:
+    desc = f"""
+thumbnail is an API endpoint to retrieve the scaled down and compressed thumbnail
+of the artwork of an audio track or its audio set.
+
+{refer_sample}"""
+
+    swagger_setup = {
+        "operation_id": "audio_thumbnail",
+        "operation_description": desc,
+        "query_serializer": MediaThumbnailRequestSerializer,
+    }

api/catalog/api/docs/image_docs.py

@@ -37,6 +37,7 @@
     OembedRequestSerializer,
     OembedSerializer,
 )
+from catalog.api.serializers.media_serializers import MediaThumbnailRequestSerializer
 from catalog.api.serializers.provider_serializers import ProviderSerializer
 from drf_yasg import openapi
 
@@ -240,3 +241,17 @@ class ImageOembed:
         "responses": responses,
         "code_examples": code_examples,
     }
+
+
+class ImageThumbnail:
+    desc = f"""
+thumbnail is an API endpoint to retrieve the scaled down and compressed thumbnail
+of an image.
+
+{refer_sample}"""
+
+    swagger_setup = {
+        "operation_id": "image_thumbnail",
+        "operation_description": desc,
+        "query_serializer": MediaThumbnailRequestSerializer,
+    }

api/catalog/api/serializers/media_serializers.py

@@ -420,3 +420,30 @@ class MediaSearchSerializer(serializers.Serializer):
     page = serializers.IntegerField(
         help_text="The current page number returned in the response."
     )
+
+
+class MediaThumbnailRequestSerializer(serializers.Serializer):
+    """
+    This serializer parses and validates thumbnail query string parameters.
+    """
+
+    full_size = serializers.BooleanField(
+        source="is_full_size",
+        allow_null=True,
+        required=False,
+        default=False,
+        help_text="whether to render the actual image and not a thumbnail version",
+    )
+    compressed = serializers.BooleanField(
+        source="is_compressed",
+        allow_null=True,
+        default=None,
+        required=False,
+        help_text="whether to compress the output image to reduce file size,"
+        "defaults to opposite of `full_size`",
+    )
+
+    def validate(self, data):
+        if data.get("is_compressed") is None:
+            data["is_compressed"] = not data["is_full_size"]
+        return data

api/catalog/api/views/audio_views.py

@@ -6,6 +6,7 @@
     AudioRelated,
     AudioSearch,
     AudioStats,
+    AudioThumbnail,
 )
 from catalog.api.models import Audio
 from catalog.api.serializers.audio_serializers import (
@@ -14,6 +15,7 @@
     AudioSerializer,
     AudioWaveformSerializer,
 )
+from catalog.api.serializers.media_serializers import MediaThumbnailRequestSerializer
 from catalog.api.utils.exceptions import get_api_exception
 from catalog.api.utils.throttle import OneThousandPerMinute
 from catalog.api.views.media_views import MediaViewSet
@@ -31,7 +33,7 @@
 @method_decorator(swagger_auto_schema(**AudioDetail.swagger_setup), "retrieve")
 @method_decorator(swagger_auto_schema(**AudioRelated.swagger_setup), "related")
 @method_decorator(swagger_auto_schema(**AudioComplain.swagger_setup), "report")
-@method_decorator(swagger_auto_schema(auto_schema=None), "thumbnail")
+@method_decorator(swagger_auto_schema(**AudioThumbnail.swagger_setup), "thumbnail")
 @method_decorator(swagger_auto_schema(auto_schema=None), "waveform")
 class AudioViewSet(MediaViewSet):
     """
@@ -51,6 +53,7 @@ class AudioViewSet(MediaViewSet):
         detail=True,
         url_path="thumb",
         url_name="thumb",
+        serializer_class=MediaThumbnailRequestSerializer,
         throttle_classes=[OneThousandPerMinute],
     )
     def thumbnail(self, request, *_, **__):
@@ -64,11 +67,7 @@ def thumbnail(self, request, *_, **__):
         if not image_url:
             raise get_api_exception("Could not find artwork.", 404)
 
-        is_full_size = request.query_params.get("full_size", False)
-        if is_full_size:
-            return self._get_proxied_image(image_url, None)
-        else:
-            return self._get_proxied_image(image_url)
+        return super().thumbnail(image_url, request)
 
     @action(
         detail=True,

api/catalog/api/views/image_views.py

@@ -10,6 +10,7 @@
     ImageRelated,
     ImageSearch,
     ImageStats,
+    ImageThumbnail,
 )
 from catalog.api.models import Image
 from catalog.api.serializers.image_serializers import (
@@ -20,6 +21,7 @@
     OembedSerializer,
     WatermarkRequestSerializer,
 )
+from catalog.api.serializers.media_serializers import MediaThumbnailRequestSerializer
 from catalog.api.utils.exceptions import get_api_exception
 from catalog.api.utils.throttle import OneThousandPerMinute
 from catalog.api.utils.watermark import watermark
@@ -42,7 +44,7 @@
 @method_decorator(swagger_auto_schema(**ImageRelated.swagger_setup), "related")
 @method_decorator(swagger_auto_schema(**ImageComplain.swagger_setup), "report")
 @method_decorator(swagger_auto_schema(**ImageOembed.swagger_setup), "oembed")
-@method_decorator(swagger_auto_schema(auto_schema=None), "thumbnail")
+@method_decorator(swagger_auto_schema(**ImageThumbnail.swagger_setup), "thumbnail")
 @method_decorator(swagger_auto_schema(auto_schema=None), "watermark")
 class ImageViewSet(MediaViewSet):
     """
@@ -91,6 +93,7 @@ def oembed(self, request, *_, **__):
         detail=True,
         url_path="thumb",
         url_name="thumb",
+        serializer_class=MediaThumbnailRequestSerializer,
         throttle_classes=[OneThousandPerMinute],
     )
     def thumbnail(self, request, *_, **__):
@@ -100,11 +103,7 @@ def thumbnail(self, request, *_, **__):
         if not image_url:
             raise get_api_exception("Could not find image.", 404)
 
-        is_full_size = request.query_params.get("full_size", False)
-        if is_full_size:
-            return self._get_proxied_image(image_url, None)
-        else:
-            return self._get_proxied_image(image_url)
+        return super().thumbnail(image_url, request)
 
     @action(detail=True, url_path="watermark", url_name="watermark")
     def watermark(self, request, *_, **__):

api/catalog/api/views/media_views.py

@@ -1,5 +1,9 @@
+import json
+import logging as log
+from typing import List
 from urllib.error import HTTPError
-from urllib.request import urlopen
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
 
 from catalog.api.controllers import search_controller
 from catalog.api.models import ContentProvider
@@ -124,6 +128,16 @@ def report(self, request, *_, **__):
         serializer = self.get_serializer(report)
         return Response(data=serializer.data, status=status.HTTP_201_CREATED)
 
+    def thumbnail(self, image_url, request, *_, **__):
+        serializer = self.get_serializer(data=request.query_params)
+        if not serializer.is_valid():
+            raise get_api_exception("Invalid input.", 400)
+        return self._get_proxied_image(
+            image_url,
+            accept_header=request.headers.get("Accept", "image/*"),
+            **serializer.validated_data,
+        )
+
     # Helper functions
 
     @staticmethod
@@ -143,24 +157,69 @@ def _get_user_ip(request):
         return ip
 
     @staticmethod
-    def _get_proxied_image(image_url, width=settings.THUMBNAIL_WIDTH_PX):
-        if width is None:  # full size
-            proxy_upstream = f"{settings.THUMBNAIL_PROXY_URL}/{image_url}"
-        else:
-            proxy_upstream = (
-                f"{settings.THUMBNAIL_PROXY_URL}/"
-                f"{settings.THUMBNAIL_WIDTH_PX},fit/"
-                f"{image_url}"
-            )
+    def _thumbnail_proxy_comm(
+        path: str,
+        params: dict,
+        headers: List[
+            tuple[str, str]
+        ] = None,  # ``List`` because there is a ``list`` function
+    ):
+        proxy_url = settings.THUMBNAIL_PROXY_URL
+        query_string = urlencode(params)
+        upstream_url = f"{proxy_url}/{path}?{query_string}"
+        log.debug(f"Image proxy upstream URL: {upstream_url}")
+
         try:
-            upstream_response = urlopen(proxy_upstream)
-            status = upstream_response.status
+            req = Request(upstream_url)
+            if headers:
+                for key, val in headers:
+                    req.add_header(key, val)
+            upstream_response = urlopen(req)
+
+            res_status = upstream_response.status
             content_type = upstream_response.headers.get("Content-Type")
+            log.debug(
+                "Image proxy response "
+                f"status: {res_status}, content-type: {content_type}"
+            )
+
+            return upstream_response, res_status, content_type
         except HTTPError:
             raise get_api_exception("Failed to render thumbnail.")
 
+    @staticmethod
+    def _get_proxied_image(
+        image_url: str,
+        accept_header: str = "image/*",
+        is_full_size: bool = False,
+        is_compressed: bool = True,
+    ):
+        info_res, *_ = MediaViewSet._thumbnail_proxy_comm("info", {"url": image_url})
+        info = json.loads(info_res.read())
+
+        params = {
+            "url": image_url,
+            "width": info["width"] if is_full_size else settings.THUMBNAIL_WIDTH_PX,
+        }
+
+        if is_compressed:
+            params |= {
+                "quality": settings.THUMBNAIL_JPG_QUALITY,
+                "compression": settings.THUMBNAIL_PNG_COMPRESSION,
+            }
+        else:
+            params |= {
+                "quality": 100,
+                "compression": 0,
+            }
+
+        if "webp" in accept_header:
+            params["type"] = "auto"  # Use ``Accept`` header to determine output type.
+
+        img_res, res_status, content_type = MediaViewSet._thumbnail_proxy_comm(
+            "resize", params, [("Accept", accept_header)]
+        )
         response = HttpResponse(
-            upstream_response.read(), status=status, content_type=content_type
+            img_res.read(), status=res_status, content_type=content_type
         )
-
         return response

api/catalog/settings.py

@@ -183,7 +183,9 @@
 # Produce CC-hosted thumbnails dynamically through a proxy.
 THUMBNAIL_PROXY_URL = config("THUMBNAIL_PROXY_URL", default="http://localhost:8222")
 
-THUMBNAIL_WIDTH_PX = 600
+THUMBNAIL_WIDTH_PX = config("THUMBNAIL_WIDTH_PX", cast=int, default=600)
+THUMBNAIL_JPG_QUALITY = config("THUMBNAIL_JPG_QUALITY", cast=int, default=80)
+THUMBNAIL_PNG_COMPRESSION = config("THUMBNAIL_PNG_COMPRESSION", cast=int, default=6)
 
 AUTHENTICATION_BACKENDS = (
     "oauth2_provider.backends.OAuth2Backend",

api/docs/guides/quickstart.md

@@ -79,7 +79,7 @@ The command `just up` spawns the following services:
   - API application database
 - [Elasticsearch](https://www.elastic.co/elasticsearch/)
 - [Redis](https://redis.io/)
-- [imageproxy](https://github.com/willnorris/imageproxy)
+- [imaginary](https://github.com/h2non/imaginary)
 - [NGINX](http://nginx.org)
 - **web** (`api/`)
 - **ingestion_server** and **indexer_worker** (`ingestion_server/`)

api/env.docker

@@ -6,7 +6,7 @@ DJANGO_DEBUG_ENABLED="True"
 
 REDIS_HOST="cache"
 
-THUMBNAIL_PROXY_URL="http://thumbs:8222"
+THUMBNAIL_PROXY_URL="http://thumbnails:8222"
 
 DJANGO_DATABASE_HOST="db"
 

api/env.template

@@ -15,7 +15,11 @@ DJANGO_DEBUG_ENABLED="True"
 #REDIS_PORT="6379"
 #REDIS_PASSWORD=""
 
-#THUMBNAIL_PROXY_URL="http://thumbs:8222"
+#THUMBNAIL_PROXY_URL="http://thumbnails:8222"
+
+#THUMBNAIL_WIDTH_PX="600"
+#THUMBNAIL_JPG_QUALITY="80"
+#THUMBNAIL_PNG_COMPRESSION="6"
 
 #DJANGO_DATABASE_HOST="db"
 #DJANGO_DATABASE_PORT="5432"

api/test/audio_integration_test.py

@@ -17,6 +17,8 @@
     search_special_chars,
     stats,
     thumb,
+    thumb_compression,
+    thumb_webp,
 )
 
 import pytest
@@ -73,5 +75,13 @@ def test_audio_thumb(audio_fixture):
     thumb(audio_fixture)
 
 
+def test_audio_thumb_compression(audio_fixture):
+    thumb_compression(audio_fixture)
+
+
+def test_audio_thumb_webp(audio_fixture):
+    thumb_webp(audio_fixture)
+
+
 def test_audio_report(audio_fixture):
     report("audio", audio_fixture)

api/test/image_integration_test.py

@@ -17,6 +17,8 @@
     search_special_chars,
     stats,
     thumb,
+    thumb_compression,
+    thumb_webp,
 )
 from urllib.parse import urlencode
 
@@ -72,6 +74,14 @@ def test_image_thumb(image_fixture):
     thumb(image_fixture)
 
 
+def test_image_thumb_compression(image_fixture):
+    thumb_compression(image_fixture)
+
+
+def test_image_thumb_webp(image_fixture):
+    thumb_webp(image_fixture)
+
+
 def test_audio_report(image_fixture):
     report("images", image_fixture)