feat: add opt-in resumable scheme to the upload_url endpoint

- accept a `resumable` flag (defaults off)
- GCS: skip when the stored md5 matches the checksum, else return a server-initiated resumable session URI
- non-GCS backends fall back to single-PUT
- reject non-resumable uploads over 500 MB
- make `size` an IntegerField, dropping the redundant float casts

Part of learningequality#5975.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzUP3UYP4cLyouvssXyekj

Author: rtibbles

contentcuration/contentcuration/tests/viewsets/test_file.py

@@ -1,4 +1,5 @@
 import uuid
+from unittest import mock
 
 from django.urls import reverse
 from le_utils.constants import content_kinds
@@ -12,6 +13,8 @@
 from contentcuration.tests.viewsets.base import generate_delete_event
 from contentcuration.tests.viewsets.base import generate_update_event
 from contentcuration.tests.viewsets.base import SyncTestMixin
+from contentcuration.viewsets.file import FileUploadURLSerializer
+from contentcuration.viewsets.file import MAX_NON_RESUMABLE_UPLOAD_SIZE
 from contentcuration.viewsets.sync.constants import CONTENTNODE
 from contentcuration.viewsets.sync.constants import FILE
 
@@ -546,6 +549,9 @@ def test_mismatched_preset_upload(self):
 
     def test_insufficient_storage(self):
         self.file["size"] = 100000000000000
+        self.file[
+            "resumable"
+        ] = True  # resumable bypasses the >500MB guard so this still exercises the quota (412) path
 
         self.client.force_authenticate(user=self.user)
         response = self.client.post(
@@ -590,6 +596,26 @@ def test_duration_zero(self):
 
         self.assertEqual(response.status_code, 400)
 
+    def test_fractional_size_rejected(self):
+        s = FileUploadURLSerializer(data={**self.file, "size": 1000.5})
+        assert not s.is_valid()
+        assert "size" in s.errors
+
+    def test_large_non_resumable_rejected(self):
+        self.file["size"] = MAX_NON_RESUMABLE_UPLOAD_SIZE + 1
+        self.client.force_authenticate(user=self.user)
+        resp = self.client.post(reverse("file-upload-url"), self.file, format="json")
+        assert resp.status_code == 400
+
+    def test_large_resumable_allowed(self):
+        self.user.disk_space = 10 * 1024 * 1024 * 1024
+        self.user.save()
+        self.file["size"] = MAX_NON_RESUMABLE_UPLOAD_SIZE + 1
+        self.file["resumable"] = True
+        self.client.force_authenticate(user=self.user)
+        resp = self.client.post(reverse("file-upload-url"), self.file, format="json")
+        assert resp.status_code == 200
+
 
 class ContentIDTestCase(SyncTestMixin, StudioAPITestCase):
     def setUp(self):
@@ -763,3 +789,60 @@ def test_content_id__thumbnails_dont_update_content_id(self):
         self.assertEqual(
             copied_node_content_id_before_upload, copied_node_content_id_after_upload
         )
+
+
+class ResumableUploadURLTestCase(StudioAPITestCase):
+    def setUp(self):
+        super(ResumableUploadURLTestCase, self).setUp()
+        self.user = testdata.user()
+        # Give user enough quota to handle resumable uploads
+        self.user.disk_space = 10 * 1024 * 1024 * 1024
+        self.user.save()
+        self.file = {
+            "size": 1000,
+            "checksum": uuid.uuid4().hex,
+            "name": "le_studio",
+            "file_format": file_formats.MP3,
+            "preset": format_presets.AUDIO,
+            "duration": 10.123,
+            "resumable": True,
+        }
+
+    @mock.patch("contentcuration.viewsets.file.default_storage")
+    def test_resumable_returns_session_when_not_stored(self, mock_storage):
+        mock_storage.get_stored_object_md5.return_value = None
+        mock_storage.create_resumable_upload_session.return_value = (
+            "https://session.url"
+        )
+        self.client.force_authenticate(user=self.user)
+        resp = self.client.post(reverse("file-upload-url"), self.file, format="json")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["resumable"] is True
+        assert data["uploadURL"] == "https://session.url"
+        assert data["alreadyUploaded"] is False
+        assert "file" in data
+        assert data["file"]["id"]
+        mock_storage.create_resumable_upload_session.assert_called_once()
+
+    @mock.patch("contentcuration.viewsets.file.default_storage")
+    def test_resumable_skips_when_already_stored(self, mock_storage):
+        mock_storage.get_stored_object_md5.return_value = self.file["checksum"]
+        self.client.force_authenticate(user=self.user)
+        resp = self.client.post(reverse("file-upload-url"), self.file, format="json")
+        data = resp.json()
+        assert data["resumable"] is True and data["alreadyUploaded"] is True
+        assert data["uploadURL"] is None
+        assert "file" in data
+        assert data["file"]["id"]
+        mock_storage.create_resumable_upload_session.assert_not_called()
+
+    def test_resumable_falls_back_to_single_put_on_s3(self):
+        # default_storage is S3 in the test env → no resumable support
+        self.client.force_authenticate(user=self.user)
+        resp = self.client.post(reverse("file-upload-url"), self.file, format="json")
+        data = resp.json()
+        assert data["resumable"] is False
+        assert "uploadURL" in data
+        assert "file" in data
+        assert data["file"]["id"]

contentcuration/contentcuration/utils/files.py

@@ -1,4 +1,5 @@
 import base64
+import codecs
 import copy
 import mimetypes
 import os

contentcuration/contentcuration/viewsets/file.py

@@ -1,7 +1,7 @@
-import codecs
 import math
 
 from django.core.exceptions import PermissionDenied
+from django.core.files.storage import default_storage
 from django.http import HttpResponseBadRequest
 from le_utils.constants import file_formats
 from le_utils.constants import format_presets
@@ -34,6 +34,8 @@
 
 PRESET_LOOKUP = {p.id: p for p in format_presets.PRESETLIST}
 
+MAX_NON_RESUMABLE_UPLOAD_SIZE = 500 * 1024 * 1024
+
 
 class StrictFloatField(serializers.FloatField):
     def to_internal_value(self, data):
@@ -48,7 +50,7 @@ class FileUploadURLSerializer(serializers.Serializer):
     """
     Serializer to validate inputs for the upload_url endpoint.
     Required:
-      - size: a float value
+      - size: an integer value (bytes)
       - checksum: a 32-digit hex string
       - name: a string (note: mapped from request.data['name'])
       - file_format: a valid file format choice from file_formats.choices
@@ -57,12 +59,13 @@ class FileUploadURLSerializer(serializers.Serializer):
       - duration: a number that will be floored to an integer and must be > 0
     """
 
-    size = serializers.FloatField(required=True)
+    size = serializers.IntegerField(required=True)
     checksum = serializers.RegexField(regex=r"^[0-9a-f]{32}$", required=True)
     name = serializers.CharField(required=True)
     file_format = serializers.ChoiceField(choices=file_formats.choices, required=True)
     preset = serializers.ChoiceField(choices=format_presets.choices, required=True)
     duration = StrictFloatField(required=False, allow_null=True)
+    resumable = serializers.BooleanField(required=False, default=False)
 
     def validate_duration(self, value):
         if value is None:
@@ -89,6 +92,10 @@ def validate(self, attrs):
             raise serializers.ValidationError(
                 f"File format {attrs['file_format']} is not an allowed format for this preset {attrs['preset']}"
             )
+        if not attrs["resumable"] and attrs["size"] > MAX_NON_RESUMABLE_UPLOAD_SIZE:
+            raise serializers.ValidationError(
+                "Files larger than 500 MB must use a resumable upload."
+            )
         return attrs
 
 
@@ -235,26 +242,37 @@ def upload_url(self, request):
         file_format = validated_data["file_format"]
         preset = validated_data["preset"]
         duration = validated_data.get("duration")
+        resumable = validated_data["resumable"]
 
         try:
-            request.user.check_space(float(size), checksum)
+            request.user.check_space(size, checksum)
         except PermissionDenied:
             return HttpResponseBadRequest(
                 reason="Not enough space. Check your storage under Settings page.",
                 status=412,
             )
 
-        might_skip = File.objects.filter(checksum=checksum).exists()
-
         filepath = generate_object_storage_name(
             checksum, filename, default_ext=file_format
         )
-        checksum_base64 = codecs.encode(
-            codecs.decode(checksum, "hex"), "base64"
-        ).decode()
-        retval = get_presigned_upload_url(
-            filepath, checksum_base64, 600, content_length=size
-        )
+        if resumable and hasattr(default_storage, "create_resumable_upload_session"):
+            # Resumable response omits mimetype/might_skip.
+            stored = default_storage.get_stored_object_md5(filepath) == checksum
+            retval = {
+                "resumable": True,
+                "uploadURL": None
+                if stored
+                else default_storage.create_resumable_upload_session(
+                    filepath, checksum, size
+                ),
+                "alreadyUploaded": stored,
+            }
+        else:
+            retval = get_presigned_upload_url(
+                filepath, checksum, 600, content_length=size
+            )
+            retval["resumable"] = False
+            retval["might_skip"] = File.objects.filter(checksum=checksum).exists()
 
         file = File(
             file_size=size,
@@ -270,8 +288,5 @@ def upload_url(self, request):
         # Avoid using our file_on_disk attribute for checks
         file.save(set_by_file_on_disk=False)
 
-        retval.update(
-            {"might_skip": might_skip, "file": self.serialize_object(id=file.id)}
-        )
-
+        retval["file"] = self.serialize_object(id=file.id)
         return Response(retval)