Harden sync assembly retries and generated docs

Author: kvz

CHANGELOG.md

@@ -1,8 +1,8 @@
 ### 2.0.0 / 2026-05-20 ###
-* @TODO before merging: expand the SDK surface so this release supports all Transloadit API endpoints, and update these release notes with the final endpoint coverage.
 * **Breaking Change**: Raised the supported Python runtime floor from 3.9+ to 3.12+ so the SDK no longer has to retain vulnerable locked dependency versions for EOL Python 3.9 or depend on tooling lines that are already dropping older runtime support.
+* Expanded low-level API endpoint coverage for Assemblies, Assembly Notifications, Templates, Template Credentials, Priority Job Slots, and Billing, with sync and async methods generated from the API2 endpoint contract.
 * Added explicit asyncio support with `AsyncTransloadit`, async request/assembly/template helpers, and `asyncio.sleep`-based polling. Resumable uploads stay on the existing TUS client, but run through `asyncio.to_thread()` so the event loop remains responsive instead of pretending the sync uploader is natively async.
-* Hardened upload and response edge cases: invalid service URLs and empty template IDs now fail fast, external absolute API URLs are no longer signed, sync TUS uploads now handle nameless streams and submit rate limits before uploading, async form fields match sync boolean serialization, async TUS cancellation waits for worker cleanup, async polling rate-limit retries reset after successful polls, async rate-limit backoff honors server `retryIn`, Smart CDN signing rejects invalid workspace slugs/reserved query keys, and sync non-JSON responses fall back to response text.
+* Hardened upload and response edge cases: invalid service URLs and empty template IDs now fail fast, external absolute API URLs are no longer signed, sync TUS uploads now handle nameless streams and submit rate limits before uploading, sync non-resumable retries rewind seekable files and reject non-seekable retry streams, sync/async polling rate-limit retries reset after successful polls and cap repeated rate limits, async form fields match sync boolean serialization, async TUS cancellation waits for worker cleanup, async rate-limit backoff honors server `retryIn`, Smart CDN signing rejects invalid workspace slugs/reserved query keys, and sync non-JSON responses fall back to response text.
 * Hardened sync and async request handling by preserving custom `auth` constraints, quoting path IDs, and keeping explicit/custom service URLs compatible with local, CI, and [Transloadit Gateway](https://github.com/transloadit/gateway) deployments.
 * Fixed sync and async template creation to send the current API `template` payload shape.
 * Raised the runtime HTTP stack to patched versions by requiring `requests` 2.33+ and adding an explicit `urllib3` 2.7+ floor.

tests/test_api_url.py

@@ -0,0 +1,14 @@
+import unittest
+
+from transloadit.api_url import should_sign_api_url
+
+
+class ApiUrlTest(unittest.TestCase):
+    def test_should_sign_same_service_url_with_different_host_casing(self):
+        self.assertTrue(
+            should_sign_api_url(
+                "https://API2.transloadit.com/assemblies/abc",
+                "https://api2.transloadit.com",
+            )
+        )
+

tests/test_assembly.py

@@ -130,3 +130,208 @@ def test_save_resumable_retries_rate_limit_before_tus_upload(self):
             "https://api2.example/assemblies/abc",
         )
         uploader.upload.assert_called_once()
+
+    def test_save_non_resumable_rewinds_seekable_files_before_retry(self):
+        upload = io.BytesIO(b"payload")
+        rate_limited = Response(
+            data={
+                "error": "RATE_LIMIT_REACHED",
+                "info": {"retryIn": 0},
+            },
+            status_code=200,
+            headers={},
+        )
+        success = Response(
+            data={"ok": "ASSEMBLY_COMPLETED", "assembly_id": "abcdef45673"},
+            status_code=200,
+            headers={},
+        )
+        seen_positions = []
+        self.assembly.add_file(upload, "payload_field")
+
+        def post_side_effect(*args, **kwargs):
+            seen_positions.append(kwargs["files"]["payload_field"].tell())
+            kwargs["files"]["payload_field"].seek(0, io.SEEK_END)
+            return rate_limited if len(seen_positions) == 1 else success
+
+        with mock.patch.object(self.transloadit.request, "post", side_effect=post_side_effect):
+            with mock.patch("transloadit.assembly.sleep"):
+                assembly = self.assembly.create(resumable=False, retries=1)
+
+        self.assertEqual(assembly.data["ok"], "ASSEMBLY_COMPLETED")
+        self.assertEqual(seen_positions, [0, 0])
+
+    def test_save_non_resumable_rejects_non_seekable_file_retry(self):
+        class NonSeekableFile:
+            pass
+
+        rate_limited = Response(
+            data={
+                "error": "RATE_LIMIT_REACHED",
+                "info": {"retryIn": 0},
+            },
+            status_code=200,
+            headers={},
+        )
+        self.assembly.add_file(NonSeekableFile(), "payload_field")
+
+        with mock.patch.object(self.transloadit.request, "post", return_value=rate_limited):
+            with self.assertRaises(RuntimeError):
+                self.assembly.create(resumable=False, retries=1)
+
+    def test_save_wait_raises_on_plain_text_create_response(self):
+        plain_response = Response(
+            data="plain assembly response",
+            status_code=502,
+            headers={"X-Route": "plain"},
+        )
+
+        with mock.patch.object(self.transloadit.request, "post", return_value=plain_response):
+            with self.assertRaises(RuntimeError):
+                self.assembly.create(wait=True, resumable=False)
+
+    def test_save_returns_plain_text_success_without_wait(self):
+        plain_response = Response(
+            data="plain assembly response",
+            status_code=200,
+            headers={"X-Route": "plain"},
+        )
+
+        with mock.patch.object(self.transloadit.request, "post", return_value=plain_response):
+            response = self.assembly.create(wait=False, resumable=False)
+
+        self.assertIs(response, plain_response)
+
+    def test_save_resumable_plain_text_response_raises_before_tus_upload(self):
+        plain_response = Response(
+            data="plain assembly response",
+            status_code=200,
+            headers={"X-Route": "plain"},
+        )
+        self.assembly.add_file(io.BytesIO(b"payload"), "payload_field")
+
+        with mock.patch.object(self.transloadit.request, "post", return_value=plain_response):
+            with mock.patch("transloadit.assembly.tus.TusClient") as tus_client:
+                with self.assertRaises(RuntimeError):
+                    self.assembly.create(resumable=True)
+
+        tus_client.assert_not_called()
+
+    def test_save_wait_pins_assembly_url_across_poll_rate_limits(self):
+        initial_response = Response(
+            data={
+                "ok": "ASSEMBLY_PROCESSING",
+                "info": {"retryIn": 0},
+                "assembly_ssl_url": "https://api2.example/assemblies/abc",
+            },
+            status_code=200,
+            headers={},
+        )
+        rate_limited = Response(
+            data={
+                "error": "ASSEMBLY_STATUS_FETCHING_RATE_LIMIT_REACHED",
+                "info": {"retryIn": 0},
+            },
+            status_code=200,
+            headers={},
+        )
+        completed = Response(
+            data={
+                "ok": "ASSEMBLY_COMPLETED",
+                "assembly_ssl_url": "https://api2.example/assemblies/other",
+            },
+            status_code=200,
+            headers={},
+        )
+
+        with mock.patch.object(self.transloadit.request, "post", return_value=initial_response):
+            with mock.patch.object(
+                self.transloadit,
+                "get_assembly",
+                side_effect=[rate_limited, completed],
+            ) as get_mock:
+                with mock.patch("transloadit.assembly.sleep"):
+                    response = self.assembly.create(wait=True, resumable=False, retries=2)
+
+        self.assertIs(response, completed)
+        self.assertEqual(
+            get_mock.call_args_list,
+            [
+                mock.call(assembly_url="https://api2.example/assemblies/abc"),
+                mock.call(assembly_url="https://api2.example/assemblies/abc"),
+            ],
+        )
+
+    def test_save_wait_does_not_follow_poll_response_assembly_url(self):
+        initial_response = Response(
+            data={
+                "ok": "ASSEMBLY_PROCESSING",
+                "info": {"retryIn": 0},
+                "assembly_ssl_url": "https://api2.example/assemblies/abc",
+            },
+            status_code=200,
+            headers={},
+        )
+        redirected_processing = Response(
+            data={
+                "ok": "ASSEMBLY_PROCESSING",
+                "info": {"retryIn": 0},
+                "assembly_ssl_url": "https://example.invalid/assemblies/evil",
+            },
+            status_code=200,
+            headers={},
+        )
+        completed = Response(
+            data={"ok": "ASSEMBLY_COMPLETED", "assembly_id": "abcdef45673"},
+            status_code=200,
+            headers={},
+        )
+
+        with mock.patch.object(self.transloadit.request, "post", return_value=initial_response):
+            with mock.patch.object(
+                self.transloadit,
+                "get_assembly",
+                side_effect=[redirected_processing, completed],
+            ) as get_mock:
+                with mock.patch("transloadit.assembly.sleep"):
+                    response = self.assembly.create(wait=True, resumable=False, retries=2)
+
+        self.assertIs(response, completed)
+        self.assertEqual(
+            get_mock.call_args_list,
+            [
+                mock.call(assembly_url="https://api2.example/assemblies/abc"),
+                mock.call(assembly_url="https://api2.example/assemblies/abc"),
+            ],
+        )
+
+    def test_save_wait_caps_poll_rate_limit_retries(self):
+        initial_response = Response(
+            data={
+                "ok": "ASSEMBLY_PROCESSING",
+                "info": {"retryIn": 0},
+                "assembly_ssl_url": "https://api2.example/assemblies/abc",
+            },
+            status_code=200,
+            headers={},
+        )
+        rate_limited = Response(
+            data={
+                "error": "ASSEMBLY_STATUS_FETCHING_RATE_LIMIT_REACHED",
+                "info": {"retryIn": 0},
+            },
+            status_code=200,
+            headers={},
+        )
+
+        with mock.patch.object(self.transloadit.request, "post", return_value=initial_response):
+            with mock.patch.object(
+                self.transloadit,
+                "get_assembly",
+                return_value=rate_limited,
+            ) as get_mock:
+                with mock.patch("transloadit.assembly.sleep"):
+                    response = self.assembly.create(wait=True, resumable=False, retries=1)
+
+        self.assertIs(response, rate_limited)
+        self.assertEqual(get_mock.call_count, 2)

transloadit/api_url.py

@@ -36,11 +36,12 @@ def should_sign_api_url(url, service):
     # Only same-service URLs and Transloadit API regional hosts may receive auth params.
     if (
         parsed_url.scheme == parsed_service.scheme
-        and parsed_url.netloc == parsed_service.netloc
+        and (parsed_url.hostname or "").lower() == (parsed_service.hostname or "").lower()
+        and parsed_url.port == parsed_service.port
     ):
         return True
 
-    hostname = parsed_url.hostname or ""
+    hostname = (parsed_url.hostname or "").lower()
     return parsed_url.scheme == "https" and (
         hostname == "api2.transloadit.com"
         or (hostname.startswith("api2-") and hostname.endswith(".transloadit.com"))