Add Node reference implementation parity testing in CI

Author: kvz

.github/workflows/ci.yml

@@ -8,17 +8,23 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ['3.9', '3.10', '3.11', '3.12']
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install tsx
+        run: npm install -g tsx
 
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
           architecture: x64
-          cache: "pip"
+          cache: 'pip'
 
       - name: Install Poetry manager
         run: pip install --upgrade poetry
@@ -29,3 +35,5 @@ jobs:
       - name: Test with pytest
         run: |
           poetry run pytest --cov=transloadit tests
+        env:
+          TEST_NODE_PARITY: 1

tests/test_client.py

@@ -1,5 +1,10 @@
 import unittest
 from unittest import mock
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
 
 import requests_mock
 from six.moves import urllib
@@ -8,9 +13,43 @@
 from transloadit.client import Transloadit
 
 
+def get_expected_url(params):
+    """Get expected URL from Node.js reference implementation."""
+    if os.getenv('TEST_NODE_PARITY') != '1':
+        return None
+
+    # Check for tsx before trying to use it
+    tsx_path = subprocess.run(['which', 'tsx'], capture_output=True)
+    if tsx_path.returncode != 0:
+        raise RuntimeError('tsx command not found. Please install it with: npm install -g tsx')
+
+    script_path = Path(__file__).parent / 'node-smartcdn-sig.ts'
+    json_input = json.dumps(params)
+
+    result = subprocess.run(
+        ['tsx', str(script_path)],
+        input=json_input,
+        capture_output=True,
+        text=True
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(f'Node script failed: {result.stderr}')
+
+    return result.stdout.strip()
+
+
 class ClientTest(unittest.TestCase):
     def setUp(self):
         self.transloadit = Transloadit("key", "secret")
+        # Use fixed timestamp for all Smart CDN tests
+        self.expire_at_ms = 1732550672867
+
+    def assert_parity_with_node(self, url, params, message=''):
+        """Assert that our URL matches the Node.js reference implementation."""
+        expected_url = get_expected_url(params)
+        if expected_url is not None:
+            self.assertEqual(expected_url, url, message or 'URL should match Node.js reference implementation')
 
     @requests_mock.Mocker()
     def test_get_assembly(self, mock):
@@ -97,22 +136,130 @@ def test_get_bill(self, mock):
         self.assertEqual(response.data["ok"], "BILL_FOUND")
 
     def test_get_signed_smart_cdn_url(self):
-        client = Transloadit("foo_key", "foo_secret")
+        """Test Smart CDN URL signing with various scenarios."""
+        client = Transloadit("test-key", "test-secret")
+
+        # Test basic URL generation
+        params = {
+            'workspace': 'workspace',
+            'template': 'template',
+            'input': 'file.jpg',
+            'auth_key': 'test-key',
+            'auth_secret': 'test-secret',
+            'expire_at_ms': self.expire_at_ms
+        }
+
+        with mock.patch('time.time', return_value=self.expire_at_ms/1000 - 3600):
+            url = client.get_signed_smart_cdn_url(
+                params['workspace'],
+                params['template'],
+                params['input'],
+                {},
+                3600 * 1000  # 1 hour
+            )
+
+        expected_url = 'https://workspace.tlcdn.com/template/file.jpg?auth_key=test-key&exp=1732550672867&sig=sha256%3Ad994b8a737db1c43d6e04a07018dc33e8e28b23b27854bd6383d828a212cfffb'
+        self.assertEqual(url, expected_url, 'Basic URL should match expected')
+        self.assert_parity_with_node(url, params)
+
+        # Test with different input field
+        params['input'] = 'input.jpg'
+        with mock.patch('time.time', return_value=self.expire_at_ms/1000 - 3600):
+            url = client.get_signed_smart_cdn_url(
+                params['workspace'],
+                params['template'],
+                params['input'],
+                {},
+                3600 * 1000
+            )
+
+        expected_url = 'https://workspace.tlcdn.com/template/input.jpg?auth_key=test-key&exp=1732550672867&sig=sha256%3A75991f02828d194792c9c99f8fea65761bcc4c62dbb287a84f642033128297c0'
+        self.assertEqual(url, expected_url, 'URL with different input should match expected')
+        self.assert_parity_with_node(url, params)
 
-        # Freeze time to 2024-05-01T00:00:00.000Z for consistent signatures
-        with mock.patch('time.time', return_value=1714521600):
+        # Test with additional parameters
+        params['input'] = 'file.jpg'
+        params['url_params'] = {'width': 100}
+        with mock.patch('time.time', return_value=self.expire_at_ms/1000 - 3600):
             url = client.get_signed_smart_cdn_url(
-                workspace="foo_workspace",
-                template="foo_template",
-                input="foo/input",
-                url_params={
-                    "foo": "bar",
-                    "aaa": [42, 21]  # Should be sorted before `foo`
-                }
+                params['workspace'],
+                params['template'],
+                params['input'],
+                params['url_params'],
+                3600 * 1000
             )
 
-        expected_url = (
-            "https://foo_workspace.tlcdn.com/foo_template/foo%2Finput?aaa=42&aaa=21&auth_key=foo_key&exp=1714525200000&foo=bar&sig=sha256%3A9a8df3bb28eea621b46ec808a250b7903b2546be7e66c048956d4f30b8da7519"
+        expected_url = 'https://workspace.tlcdn.com/template/file.jpg?auth_key=test-key&exp=1732550672867&width=100&sig=sha256%3Ae5271d8fb6482d9351ebe4285b6fc75539c4d311ff125c4d76d690ad71c258ef'
+        self.assertEqual(url, expected_url, 'URL with additional params should match expected')
+        self.assert_parity_with_node(url, params)
+
+        # Test with empty parameter string
+        params['url_params'] = {'width': '', 'height': '200'}
+        with mock.patch('time.time', return_value=self.expire_at_ms/1000 - 3600):
+            url = client.get_signed_smart_cdn_url(
+                params['workspace'],
+                params['template'],
+                params['input'],
+                params['url_params'],
+                3600 * 1000
+            )
+
+        expected_url = 'https://workspace.tlcdn.com/template/file.jpg?auth_key=test-key&exp=1732550672867&height=200&width=&sig=sha256%3A1a26733c859f070bc3d83eb3174650d7a0155642e44a5ac448a43bc728bc0f85'
+        self.assertEqual(url, expected_url, 'URL with empty param should match expected')
+        self.assert_parity_with_node(url, params)
+
+        # Test with null parameter (should be excluded)
+        params['url_params'] = {'width': None, 'height': '200'}
+        with mock.patch('time.time', return_value=self.expire_at_ms/1000 - 3600):
+            url = client.get_signed_smart_cdn_url(
+                params['workspace'],
+                params['template'],
+                params['input'],
+                params['url_params'],
+                3600 * 1000
+            )
+
+        expected_url = 'https://workspace.tlcdn.com/template/file.jpg?auth_key=test-key&exp=1732550672867&height=200&sig=sha256%3Adb740ebdfad6e766ebf6516ed5ff6543174709f8916a254f8d069c1701cef517'
+        self.assertEqual(url, expected_url, 'URL with null param should match expected')
+        self.assert_parity_with_node(url, params)
+
+        # Test with only empty parameter
+        params['url_params'] = {'width': ''}
+        with mock.patch('time.time', return_value=self.expire_at_ms/1000 - 3600):
+            url = client.get_signed_smart_cdn_url(
+                params['workspace'],
+                params['template'],
+                params['input'],
+                params['url_params'],
+                3600 * 1000
+            )
+
+        expected_url = 'https://workspace.tlcdn.com/template/file.jpg?auth_key=test-key&exp=1732550672867&width=&sig=sha256%3A840426f9ac72dde02fd080f09b2304d659fdd41e630b1036927ec1336c312e9d'
+        self.assertEqual(url, expected_url, 'URL with only empty param should match expected')
+        self.assert_parity_with_node(url, params)
+
+        # Test default expiry (should be about 1 hour from now)
+        params['url_params'] = {}
+        del params['expire_at_ms']
+        now = time.time()
+        url = client.get_signed_smart_cdn_url(
+            params['workspace'],
+            params['template'],
+            params['input']
         )
-        
-        self.assertEqual(url, expected_url)
+
+        import re
+        match = re.search(r'exp=(\d+)', url)
+        self.assertIsNotNone(match, 'URL should contain expiry timestamp')
+
+        expiry = int(match.group(1))
+        now_ms = int(now * 1000)
+        one_hour = 60 * 60 * 1000
+
+        self.assertGreater(expiry, now_ms, 'Expiry should be in the future')
+        self.assertLess(expiry, now_ms + one_hour + 5000, 'Expiry should be about 1 hour from now')
+        self.assertGreater(expiry, now_ms + one_hour - 5000, 'Expiry should be about 1 hour from now')
+
+        # For parity test, set the exact expiry time to match Node.js
+        params['expire_at_ms'] = expiry
+        self.assert_parity_with_node(url, params)

transloadit/client.py

@@ -172,13 +172,13 @@ def get_bill(self, month: int, year: int):
         Return an instance of <transloadit.response.Response>
         """
         return self.request.get(f"/bill/{year}-{month:02d}")
-    
+
     def get_signed_smart_cdn_url(
         self,
         workspace: str,
         template: str,
         input: str,
-        url_params: Optional[dict[str, Union[str, int, float, bool, List[Union[str, int, float, bool]]]]] = None,
+        url_params: Optional[dict[str, Union[str, int, float, bool, List[Union[str, int, float, bool]], None]]] = None,
         expires_in: Optional[int] = 60 * 60 * 1000 # 1 hour
     ) -> str:
         """
@@ -189,14 +189,14 @@ def get_signed_smart_cdn_url(
             - workspace (str): Workspace slug
             - template (str): Template slug or template ID
             - input (str): Input value that is provided as ${fields.input} in the template
-            - url_params (Optional[dict]): Additional parameters for the URL query string. Values can be strings, numbers, booleans or arrays thereof.
+            - url_params (Optional[dict]): Additional parameters for the URL query string. Values can be strings, numbers, booleans, arrays thereof, or None.
             - expires_in (Optional[int]): Expiration time of signature in milliseconds. Defaults to 1 hour.
 
         :Returns:
             str: The signed Smart CDN URL
 
         :Raises:
-            ValueError: If url_params contains values that are not strings, numbers, booleans or arrays
+            ValueError: If url_params contains values that are not strings, numbers, booleans, arrays, or None
         """
         workspace_slug = quote_plus(workspace)
         template_slug = quote_plus(template)
@@ -205,12 +205,14 @@ def get_signed_smart_cdn_url(
         params = []
         if url_params:
             for k, v in url_params.items():
-                if isinstance(v, (str, int, float, bool)):
+                if v is None:
+                    continue  # Skip None values
+                elif isinstance(v, (str, int, float, bool)):
                     params.append((k, str(v)))
                 elif isinstance(v, (list, tuple)):
                     params.append((k, [str(vv) for vv in v]))
                 else:
-                    raise ValueError(f"URL parameter values must be strings, numbers, booleans or arrays. Got {type(v)} for {k}")
+                    raise ValueError(f"URL parameter values must be strings, numbers, booleans, arrays, or None. Got {type(v)} for {k}")
 
         params.append(("auth_key", self.auth_key))
         params.append(("exp", str(int(time.time() * 1000) + expires_in)))
@@ -221,7 +223,7 @@ def get_signed_smart_cdn_url(
 
         string_to_sign = f"{workspace_slug}/{template_slug}/{input_field}?{query_string}"
         algorithm = "sha256"
-        
+
         signature = algorithm + ":" + hmac.new(
             self.auth_secret.encode("utf-8"),
             string_to_sign.encode("utf-8"),