media-optimization-engine 1.4.0__py3-none-any.whl

media_engine/system_views.py

@@ -0,0 +1,102 @@
+import json
+from importlib import resources
+from pathlib import Path
+
+from django.conf import settings
+from django.http import HttpResponse, JsonResponse
+from django.views.decorators.http import require_GET
+
+from .control_plane import control_plane_status
+from .health import build_health_report
+from .node import get_node_identity
+from .runtime_config import effective_profiles
+
+
+def _version():
+    return getattr(settings, 'MEDIA_ENGINE_VERSION', '1.4.0')
+
+
+@require_GET
+def well_known(request):
+    identity = get_node_identity()
+    return JsonResponse({
+        'service': 'Media Optimization Engine',
+        'version': _version(),
+        'api_version': 'v1',
+        'node': identity.as_dict(),
+        'autonomy': {
+            'runtime_requires_control_plane': False,
+            'last_known_good_config': True,
+            'panorama_multires': True,
+            'panorama_cubemap': True,
+            'viewer_adapters': ['generic', 'pannellum', 'marzipano', 'threejs', 'flutter'],
+            'local_processing': True,
+            'local_storage_supported': True,
+            'object_storage_supported': True,
+        },
+        'discovery': {
+            'base_api': '/api/v1/',
+            'capabilities': '/api/v1/system/capabilities/',
+            'health': '/api/v1/system/health/',
+            'openapi': '/api/v1/system/openapi.yaml',
+            'version': '/api/v1/system/version/',
+        },
+        'authentication': {
+            'type': 'bearer_api_key',
+            'header': 'Authorization: Bearer <key>',
+            'required': bool(getattr(settings, 'MEDIA_ENGINE_REQUIRE_API_KEY', False)),
+        },
+    })
+
+
+@require_GET
+def capabilities(request):
+    return JsonResponse({
+        'service': 'Media Optimization Engine',
+        'version': _version(),
+        'node': get_node_identity().as_dict(),
+        'formats': ['avif', 'webp', 'jpeg'],
+        'profiles': effective_profiles(),
+        'features': {
+            'content_addressed_storage': True,
+            'deduplication': bool(getattr(settings, 'MEDIA_ENGINE_DEDUPLICATE', True)),
+            'async_generation': True,
+            'smart_quality_budget': True,
+            'focal_point': True,
+            'automatic_focal_point': bool(getattr(settings, 'MEDIA_ENGINE_AUTO_FOCAL', False)),
+            'blurhash': True,
+            'dominant_color': True,
+            'cdn_ready': True,
+            's3_r2_minio_ready': True,
+            'offline_from_control_plane': True,
+            'last_known_good_config': True,
+            'panorama_multires': True,
+            'panorama_cubemap': True,
+            'viewer_adapters': ['generic', 'pannellum', 'marzipano', 'threejs', 'flutter'],
+        },
+        'control_plane': control_plane_status(),
+    })
+
+
+@require_GET
+def version(request):
+    return JsonResponse({
+        'service': 'Media Optimization Engine',
+        'version': _version(),
+        'pipeline_version': getattr(settings, 'MEDIA_ENGINE_PIPELINE_VERSION', 1),
+        'node': get_node_identity().as_dict(),
+    })
+
+
+@require_GET
+def health(request):
+    deep = request.GET.get('deep', '').lower() in {'1', 'true', 'yes'}
+    report = build_health_report(deep=deep)
+    status = 503 if report['state'] == 'unhealthy' else 200
+    return JsonResponse(report, status=status)
+
+
+@require_GET
+def openapi_yaml(request):
+    spec = resources.files('media_engine').joinpath('spec/openapi.yaml').read_text(encoding='utf-8')
+    return HttpResponse(spec, content_type='application/yaml; charset=utf-8')

media_engine/tasks.py

@@ -0,0 +1,44 @@
+from celery import shared_task
+from django.conf import settings
+from django.core.files.storage import default_storage
+from django.utils import timezone
+from datetime import timedelta
+from .models import MediaAsset, MediaVariant
+from .services import generate_all_variants
+
+
+@shared_task(bind=True, autoretry_for=(Exception,), retry_backoff=True, retry_kwargs={'max_retries': 3})
+def generate_asset_variants(self, asset_id, profile='default', force=False):
+    asset = MediaAsset.objects.get(pk=asset_id)
+    generate_all_variants(asset, profile_name=profile, force=force)
+    return str(asset.id)
+
+
+@shared_task
+def cleanup_orphan_derivatives_task(days=30):
+    threshold = timezone.now() - timedelta(days=days)
+    current_version = getattr(settings, 'MEDIA_ENGINE_PIPELINE_VERSION', 1)
+    qs = MediaVariant.objects.filter(processor_version__lt=current_version, updated_at__lt=threshold)
+    removed = 0
+    for variant in qs.iterator():
+        if variant.file and default_storage.exists(variant.file.name):
+            default_storage.delete(variant.file.name)
+        variant.delete()
+        removed += 1
+    return removed
+
+
+@shared_task
+def worker_heartbeat_task():
+    import time
+    from django.core.cache import cache
+    from .health import HEARTBEAT_KEY
+    stamp = time.time()
+    cache.set(HEARTBEAT_KEY, stamp, timeout=300)
+    return stamp
+
+
+@shared_task
+def sync_control_plane_config_task():
+    from .control_plane import sync_from_control_plane
+    return sync_from_control_plane(force=False)

media_engine/templatetags/responsive_media.py

@@ -0,0 +1,262 @@
+from django import template
+from django.contrib.contenttypes.models import ContentType
+from django.utils.html import escape
+from django.utils.safestring import mark_safe
+
+from media_engine.manifest import build_manifest
+from media_engine.models import MediaBinding
+
+register = template.Library()
+
+
+def _srcset(items):
+    return ', '.join(f"{escape(item['url'])} {item['width']}w" for item in items)
+
+
+def _attrs(**values):
+    parts = []
+    for name, value in values.items():
+        if value in (None, ''):
+            continue
+        html_name = 'class' if name == 'css_class' else name.rstrip('_').replace('_', '-')
+        parts.append(f'{html_name}="{escape(value)}"')
+    return (' ' + ' '.join(parts)) if parts else ''
+
+
+def _merge_style(dominant_color, style):
+    parts = []
+    if dominant_color:
+        parts.append(f'background:{dominant_color}')
+    if style:
+        parts.append(str(style).strip().rstrip(';'))
+    return ';'.join(part for part in parts if part)
+
+
+def _binding_for(instance, field_name):
+    if instance is None or not getattr(instance, 'pk', None):
+        return None
+    content_type = ContentType.objects.get_for_model(instance, for_concrete_model=False)
+    return (
+        MediaBinding.objects.filter(
+            content_type=content_type,
+            object_id=str(instance.pk),
+            field_name=field_name,
+        )
+        .select_related('asset')
+        .first()
+    )
+
+
+def _field_url(instance, field_name):
+    field_file = getattr(instance, field_name, None) if instance is not None else None
+    if not field_file:
+        return ''
+    try:
+        return field_file.url
+    except (AttributeError, ValueError):
+        return ''
+
+
+def _fallback_img(
+    url,
+    *,
+    alt='',
+    css_class='',
+    width='',
+    height='',
+    loading='lazy',
+    decoding='async',
+    fetchpriority='auto',
+    style='',
+    element_id='',
+):
+    if not url:
+        return ''
+    attrs = _attrs(
+        src=url,
+        alt=alt,
+        css_class=css_class,
+        width=width,
+        height=height,
+        loading=loading,
+        decoding=decoding,
+        fetchpriority=fetchpriority,
+        style=style,
+        id=element_id,
+    )
+    return mark_safe(f'<img{attrs}>')
+
+
+def _pick_variant(manifest, preferred_width=960, preferred_format='webp'):
+    variants = manifest.get('variants', {})
+    try:
+        target_width = max(1, int(preferred_width))
+    except (TypeError, ValueError):
+        target_width = 960
+
+    formats = []
+    for fmt in (preferred_format, 'webp', 'avif'):
+        if fmt and fmt not in formats:
+            formats.append(fmt)
+
+    for fmt in formats:
+        candidates = list(variants.get(fmt) or [])
+        if not candidates:
+            continue
+        candidates.sort(key=lambda item: int(item.get('width') or 0))
+        for item in candidates:
+            if int(item.get('width') or 0) >= target_width:
+                return item
+        return candidates[-1]
+
+    return manifest.get('fallback') or None
+
+
+@register.simple_tag
+def responsive_image(
+    asset,
+    profile='default',
+    role='content',
+    alt='',
+    css_class='',
+    sizes='100vw',
+    picture_class='',
+    picture_style='',
+    width='',
+    height='',
+    loading='',
+    decoding='async',
+    fetchpriority='',
+    style='',
+    element_id='',
+    adaptive=False,
+):
+    """Render responsive sources while keeping presentation attributes on the img."""
+    manifest = build_manifest(asset, profile=profile)
+    variants = manifest.get('variants', {})
+    fallback = manifest.get('fallback')
+    if not fallback:
+        original = manifest.get('original_url')
+        if not original:
+            return ''
+        fallback = {'url': original, 'width': manifest['width'], 'height': manifest['height']}
+
+    eager = role == 'hero'
+    resolved_loading = loading or ('eager' if eager else 'lazy')
+    priority = fetchpriority or ('high' if eager else 'auto')
+
+    source_parts = []
+    if variants.get('avif'):
+        source_parts.append(
+            f'<source type="image/avif" srcset="{_srcset(variants["avif"])}" sizes="{escape(sizes)}">'
+        )
+    if variants.get('webp'):
+        source_parts.append(
+            f'<source type="image/webp" srcset="{_srcset(variants["webp"])}" sizes="{escape(sizes)}">'
+        )
+
+    resolved_width = width or fallback.get('width') or manifest['width']
+    resolved_height = height or fallback.get('height') or manifest['height']
+    merged_style = _merge_style(manifest.get('dominant_color'), style)
+
+    img_attrs = _attrs(
+        src=fallback['url'],
+        alt=alt,
+        css_class=css_class,
+        width=str(resolved_width),
+        height=str(resolved_height),
+        loading=resolved_loading,
+        decoding=decoding or 'async',
+        fetchpriority=priority,
+        style=merged_style,
+        id=element_id,
+    )
+    picture_attrs = _attrs(
+        css_class=picture_class,
+        style=picture_style,
+        data_moe_adaptive='1' if adaptive else '',
+    )
+    return mark_safe(
+        f'<picture{picture_attrs}>' + ''.join(source_parts) + f'<img{img_attrs}></picture>'
+    )
+
+
+@register.simple_tag
+def media_image(
+    instance,
+    field_name,
+    profile='',
+    role='',
+    alt='',
+    css_class='',
+    sizes='100vw',
+    picture_class='',
+    picture_style='',
+    width='',
+    height='',
+    loading='',
+    decoding='async',
+    fetchpriority='',
+    style='',
+    element_id='',
+    adaptive=False,
+):
+    """Render a model ImageField or FileField through its MediaBinding."""
+    binding = _binding_for(instance, field_name)
+    resolved_role = role or (binding.role if binding else 'content')
+    if binding:
+        return responsive_image(
+            binding.asset,
+            profile=profile or binding.profile,
+            role=resolved_role,
+            alt=alt,
+            css_class=css_class,
+            sizes=sizes,
+            picture_class=picture_class,
+            picture_style=picture_style,
+            width=width,
+            height=height,
+            loading=loading,
+            decoding=decoding,
+            fetchpriority=fetchpriority,
+            style=style,
+            element_id=element_id,
+            adaptive=adaptive,
+        )
+
+    return _fallback_img(
+        _field_url(instance, field_name),
+        alt=alt,
+        css_class=css_class,
+        width=width,
+        height=height,
+        loading=loading or ('eager' if resolved_role == 'hero' else 'lazy'),
+        decoding=decoding or 'async',
+        fetchpriority=fetchpriority or ('high' if resolved_role == 'hero' else 'auto'),
+        style=style,
+        element_id=element_id,
+    )
+
+
+@register.simple_tag
+def media_url(
+    instance,
+    field_name,
+    preferred_width=960,
+    preferred_format='webp',
+    profile='',
+):
+    """Return one optimized derivative URL for CSS, metadata, email, or APIs."""
+    binding = _binding_for(instance, field_name)
+    if not binding:
+        return _field_url(instance, field_name)
+
+    manifest = build_manifest(binding.asset, profile=profile or binding.profile)
+    variant = _pick_variant(
+        manifest,
+        preferred_width=preferred_width,
+        preferred_format=preferred_format,
+    )
+    if variant and variant.get('url'):
+        return variant['url']
+    return manifest.get('original_url') or _field_url(instance, field_name)

media_engine/tests/test_distributed_node.py

@@ -0,0 +1,72 @@
+import json
+import tempfile
+from pathlib import Path
+
+from django.core.cache import cache
+from django.test import SimpleTestCase, override_settings
+from rest_framework.test import APIRequestFactory
+
+from media_engine.auth import MediaEngineApiKeyPermission
+from media_engine.control_plane import CONFIG_CACHE_KEY, validate_remote_config
+from media_engine.node import get_node_identity
+from media_engine.runtime_config import effective_profiles
+
+
+class DistributedNodeTests(SimpleTestCase):
+    @override_settings(
+        MEDIA_ENGINE_NODE_ID='node-a',
+        MEDIA_ENGINE_PROJECT_SLUG='project-a',
+        MEDIA_ENGINE_TENANT_SLUG='tenant-a',
+        MEDIA_ENGINE_DEPLOYMENT_ID='prod-1',
+    )
+    def test_node_identity_is_local(self):
+        identity = get_node_identity()
+        self.assertEqual(identity.node_id, 'node-a')
+        self.assertEqual(identity.project_slug, 'project-a')
+        self.assertEqual(identity.tenant_slug, 'tenant-a')
+
+    @override_settings(MEDIA_ENGINE_REQUIRE_API_KEY=True, MEDIA_ENGINE_API_KEYS='secret-a,secret-b')
+    def test_api_key_permission(self):
+        factory = APIRequestFactory()
+        permission = MediaEngineApiKeyPermission()
+        good = factory.get('/api/v1/images/', HTTP_AUTHORIZATION='Bearer secret-b')
+        bad = factory.get('/api/v1/images/', HTTP_AUTHORIZATION='Bearer wrong')
+        self.assertTrue(permission.has_permission(good, None))
+        self.assertFalse(permission.has_permission(bad, None))
+
+    def test_control_plane_rejects_secret_settings(self):
+        validated = validate_remote_config({
+            'version': 2,
+            'profiles': {'hero': {'quality': {'avif': 55}}},
+            'feature_flags': {'auto_focal': True, 'shell_command': True},
+            'AWS_SECRET_ACCESS_KEY': 'must-not-pass',
+            'REDIS_URL': 'must-not-pass',
+        })
+        self.assertNotIn('AWS_SECRET_ACCESS_KEY', validated)
+        self.assertNotIn('REDIS_URL', validated)
+        self.assertNotIn('shell_command', validated['feature_flags'])
+        self.assertTrue(validated['feature_flags']['auto_focal'])
+
+    def test_last_known_good_profile_override_is_local_file(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            Path(tmp, 'current.json').write_text(json.dumps({
+                'version': 3,
+                'profiles': {'hero': {'quality': {'avif': 41}}},
+                'feature_flags': {},
+            }))
+            cache.delete(CONFIG_CACHE_KEY)
+            with override_settings(
+                MEDIA_ENGINE_CONFIG_DIR=tmp,
+                MEDIA_ENGINE_PROFILES={
+                    'hero': {
+                        'widths': [640, 1280],
+                        'formats': ['avif', 'webp'],
+                        'quality': {'avif': 58, 'webp': 78},
+                    }
+                },
+            ):
+                profiles = effective_profiles()
+                self.assertEqual(profiles['hero']['quality']['avif'], 41)
+                self.assertEqual(profiles['hero']['quality']['webp'], 78)
+                self.assertEqual(profiles['hero']['widths'], [640, 1280])
+            cache.delete(CONFIG_CACHE_KEY)

media_engine/tests/test_image_ops.py

@@ -0,0 +1,14 @@
+from django.test import SimpleTestCase
+from PIL import Image
+from media_engine.image_ops import resized, dominant_color
+
+
+class ImageOpsTests(SimpleTestCase):
+    def test_resize_preserves_aspect_ratio(self):
+        image = Image.new('RGB', (1000, 500), 'red')
+        out = resized(image, 500)
+        self.assertEqual(out.size, (500, 250))
+
+    def test_dominant_color(self):
+        image = Image.new('RGB', (10, 10), (255, 0, 0))
+        self.assertEqual(dominant_color(image), '#ff0000')

media_engine/tests/test_panorama.py

@@ -0,0 +1,31 @@
+from django.test import SimpleTestCase
+from PIL import Image
+
+from media_engine.processors.panorama.detect import detect_equirectangular
+from media_engine.processors.panorama.tiles import pyramid_widths, build_plan
+from media_engine.processors.panorama.cubemap import equirectangular_to_cubemap
+
+
+class PanoramaMathTests(SimpleTestCase):
+    def test_detects_typical_equirectangular_ratio(self):
+        result = detect_equirectangular(8192, 4096)
+        self.assertTrue(result.is_panorama)
+        self.assertEqual(result.projection, 'equirectangular')
+
+    def test_rejects_normal_landscape(self):
+        result = detect_equirectangular(1600, 900)
+        self.assertFalse(result.is_panorama)
+
+    def test_pyramid_widths(self):
+        self.assertEqual(pyramid_widths(8192, 1024), [1024, 2048, 4096, 8192])
+
+    def test_tile_plan(self):
+        plan = build_plan(2048, 512, 1)
+        self.assertEqual((plan.cols, plan.rows), (4, 2))
+        self.assertEqual((plan.width, plan.height), (2048, 1024))
+
+    def test_cubemap_has_six_faces(self):
+        image = Image.new('RGB', (512, 256), (120, 80, 40))
+        faces = equirectangular_to_cubemap(image, 64)
+        self.assertEqual(set(faces), {'front', 'back', 'left', 'right', 'top', 'bottom'})
+        self.assertTrue(all(face.size == (64, 64) for face in faces.values()))

media_engine/tests/test_paths.py

@@ -0,0 +1,9 @@
+from django.test import SimpleTestCase
+from media_engine.storage_paths import original_storage_name, derivative_storage_name
+
+
+class StoragePathTests(SimpleTestCase):
+    def test_paths_are_content_addressed(self):
+        sha = 'ab' * 32
+        self.assertIn('/ab/ab/', original_storage_name(sha, 'jpg'))
+        self.assertIn('/v1/hero/640.avif', derivative_storage_name(sha, 1, 'hero', 640, 'avif'))

media_engine/tests/test_profiles.py

@@ -0,0 +1,8 @@
+from django.test import SimpleTestCase, override_settings
+from media_engine.profiles import requested_widths
+
+
+class ProfileTests(SimpleTestCase):
+    def test_does_not_upscale(self):
+        profile = {'widths': [320, 640, 1280]}
+        self.assertEqual(requested_widths(profile, 800), [320, 640])