Merge pull request #1424 from genematx/fix-asset-size

Strengthen back-compatibility

Author: genematx

CHANGELOG.md

@@ -7,6 +7,16 @@ Write the date in place of the "Unreleased" in the case a new version is release
 
 ### Fixed
 
+- Strengthen the server-side backcompatibility. Strip the newly added `Asset.size` field
+  from metadata responses when the request comes from a `python-tiled` client older than
+  v0.2.13, whose `Asset` dataclass has no `size` field and would otherwise crash
+  in `DataSource.from_json` with an unexpected keyword argument.
+
+
+## v0.2.13 (2026-07-08)
+
+### Fixed
+
 - Expand the functionality of HDF5Adapter to handle `object`-dtyped data:
   variable-length strings are coerced to fixed-length bytes, non-string object
   dtypes (e.g. vlen arrays) fall back to an empty placeholder that preserves

tests/test_asset_access.py

@@ -125,3 +125,39 @@ def test_do_not_expose_raw_assets(tmpdir):
         client.write_array([1, 2, 3], key="x")
         with fail_with_status_code(HTTP_403_FORBIDDEN):
             client["x"].raw_export(tmpdir / "exported")
+
+
+@pytest.mark.parametrize(
+    "user_agent, expect_size_key",
+    [
+        # New client understands ``size``; server includes it.
+        ("python-tiled/0.2.13", True),
+        # Old client (pre-``size`` field) would crash on unknown kwarg; server strips it.
+        ("python-tiled/0.2.12", False),
+    ],
+)
+def test_asset_size_stripped_for_old_python_clients(
+    client, user_agent, expect_size_key
+):
+    """The server strips ``size`` from assets when talking to python-tiled clients
+    older than 0.2.13, because their ``Asset`` dataclass has no ``size`` field
+    and ``DataSource.from_json`` unpacks kwargs directly, which would raise
+    ``Asset.__init__() got an unexpected keyword argument 'size'``.
+    """
+    client.write_array([1, 2, 3], key="x")
+
+    # GET path: /metadata/... with include_data_sources
+    response = client.context.http_client.get(
+        "/api/v1/metadata/x",
+        params={"include_data_sources": "true"},
+        headers={"user-agent": user_agent},
+    )
+    response.raise_for_status()
+    data_sources = response.json()["data"]["attributes"]["data_sources"]
+    assert data_sources, "expected at least one data_source"
+    for ds in data_sources:
+        for asset in ds["assets"]:
+            assert ("size" in asset) is expect_size_key, (
+                f"user-agent={user_agent!r}: expected size key "
+                f"present={expect_size_key}, got asset={asset!r}"
+            )

tiled/server/_backcompat.py

@@ -0,0 +1,70 @@
+"""Server-side back-compatibility helpers.
+
+Utilities for adapting outgoing responses (and interpreting incoming requests)
+so that older ``python-tiled`` clients keep working when the server evolves.
+"""
+
+from typing import Optional
+
+import packaging.version
+from fastapi import Request
+
+# Fields added to `tiled.structures.data_source.Asset` after a given version.
+# Older python-tiled clients unpack asset dicts as dataclass kwargs and crash
+# on unknown fields, so we strip these fields from responses to clients older
+# than the version listed here.
+ASSET_FIELDS_ADDED_IN = {
+    "size": packaging.version.parse("0.2.13"),
+}
+
+
+def raw_python_tiled_client_version(request: Request) -> Optional[str]:
+    """Return the raw ``<version>`` from a ``python-tiled/<version>`` User-Agent, or None.
+
+    Returns None when the User-Agent header is absent or does not identify a
+    Python Tiled client (i.e. it is some other client that we do not need to
+    special-case for backward compatibility).
+    """
+    user_agent = request.headers.get("user-agent", "")
+    if not user_agent.startswith("python-tiled/"):
+        return None
+    _, _, raw_version = user_agent.partition("/")
+    return raw_version
+
+
+def parse_python_tiled_client_version(
+    request: Request,
+) -> Optional[packaging.version.Version]:
+    """Return the parsed version from a ``python-tiled/<version>`` User-Agent, or None.
+
+    Returns None when the User-Agent is missing, is not a Python Tiled client,
+    or reports a version that cannot be parsed. Callers that need to
+    distinguish "not a Python Tiled client" from "unparseable version" should
+    use ``raw_python_tiled_client_version`` and parse the string themselves.
+    """
+    raw_version = raw_python_tiled_client_version(request)
+    if raw_version is None:
+        return None
+    try:
+        return packaging.version.parse(raw_version)
+    except Exception:
+        return None
+
+
+def strip_asset_fields_for_client(
+    data_sources: list, client_version: Optional[packaging.version.Version]
+) -> None:
+    """Remove asset fields that the given python-tiled client cannot accept.
+
+    Mutates the assets inside ``data_sources`` in place. A ``client_version`` of
+    None means the request did not come from python-tiled, so we leave the
+    payload untouched.
+    """
+    if client_version is None:
+        return
+    for field, added_in in ASSET_FIELDS_ADDED_IN.items():
+        if client_version >= added_in:
+            continue
+        for ds in data_sources:
+            for asset in ds.get("assets", []) or []:
+                asset.pop(field, None)

tiled/server/app.py

@@ -58,6 +58,7 @@
 from ..type_aliases import AppTask, TaskMap
 from ..utils import SHARE_TILED_PATH, Conflicts, UnsupportedQueryType
 from ..validation_registration import ValidationRegistry, default_validation_registry
+from ._backcompat import raw_python_tiled_client_version
 from .authentication import move_api_key
 from .compression import CompressionMiddleware
 from .protocols import ExternalAuthenticator, InternalAuthenticator
@@ -807,9 +808,8 @@ async def double_submit_cookie_csrf_protection(
     async def client_compatibility_check(
         request: Request, call_next: RequestResponseEndpoint
     ):
-        user_agent = request.headers.get("user-agent", "")
-        if user_agent.startswith("python-tiled/"):
-            agent, _, raw_version = user_agent.partition("/")
+        raw_version = raw_python_tiled_client_version(request)
+        if raw_version is not None:
             try:
                 parsed_version = packaging.version.parse(raw_version)
             except Exception as caught_exception:

tiled/server/router.py

@@ -56,6 +56,10 @@
 from ..utils import BrokenLink, ensure_awaitable, patch_mimetypes, path_from_uri
 from ..validation_registration import ValidationError, ValidationRegistry
 from . import schemas
+from ._backcompat import (
+    parse_python_tiled_client_version,
+    strip_asset_fields_for_client,
+)
 from .authentication import (
     authenticate_websocket_first_message,
     check_scopes,
@@ -201,20 +205,16 @@ async def about(
             "required": not settings.allow_anonymous_access,
         }
         provider_specs = []
-        user_agent = request.headers.get("user-agent", "")
         # The name of the "internal" mode used to be "password".
         # This ensures back-compat with older Python clients.
         internal_mode_name = "internal"
         MINIMUM_INTERNAL_PYTHON_CLIENT_VERSION = packaging.version.parse("0.1.0b17")
-        if user_agent.startswith("python-tiled/"):
-            agent, _, raw_version = user_agent.partition("/")
-            try:
-                parsed_version = packaging.version.parse(raw_version)
-            except Exception:
-                pass
-            else:
-                if parsed_version < MINIMUM_INTERNAL_PYTHON_CLIENT_VERSION:
-                    internal_mode_name = "password"
+        client_version = parse_python_tiled_client_version(request)
+        if (
+            client_version is not None
+            and client_version < MINIMUM_INTERNAL_PYTHON_CLIENT_VERSION
+        ):
+            internal_mode_name = "password"
         for provider, authenticator in authenticators.items():
             if isinstance(authenticator, InternalAuthenticator):
                 spec = {
@@ -1912,10 +1912,14 @@ async def _create_node(
         links = links_for_node(
             structure_family, structure, get_base_url(request), path + f"/{node.key}"
         )
+        data_sources_dump = [ds.model_dump() for ds in node.data_sources]
+        strip_asset_fields_for_client(
+            data_sources_dump, parse_python_tiled_client_version(request)
+        )
         response_data = {
             "id": node.key,
             "links": links,
-            "data_sources": [ds.model_dump() for ds in node.data_sources],
+            "data_sources": data_sources_dump,
         }
         if metadata_modified:
             response_data["metadata"] = metadata
@@ -2808,25 +2812,29 @@ async def metrics(request: Request, _=Security(check_scopes, scopes=["metrics"])
 
 
 def _model_dump_backcompat(request: Request, response: schemas.Response) -> dict:
-    """Backwards compatibility for clients older than v0.2.4
+    """Adjust the outgoing response payload to match older client expectations.
+
+    - Clients older than v0.2.4 crash on `properties` in data sources.
+      Issue: https://github.com/bluesky/tiled/issues/1300
+    - Clients older than v0.2.13 crash on `size` in assets, because their
+      `tiled.structures.data_source.Asset` dataclass has no `size` field and
+      `DataSource.from_json` unpacks kwargs directly.
 
-    Older clients expect "data_sources" in the response to not include "properties".
     To be removed in a future major release.
-    Issue: https://github.com/bluesky/tiled/issues/1300
     """
     response_dict = response.model_dump()
-    user_agent = request.headers.get("user-agent", "")
-    if user_agent.startswith("python-tiled/"):
-        agent, _, raw_version = user_agent.partition("/")
-        try:
-            parsed_version = packaging.version.parse(raw_version)
-            if parsed_version < packaging.version.parse("0.2.4"):
-                for ds in response_dict["data"]["attributes"]["data_sources"]:
-                    ds.pop("properties", None)
-
-                return response_dict
-
-        except Exception:
-            pass
-
+    client_version = parse_python_tiled_client_version(request)
+    if client_version is None:
+        return response_dict
+    data = response_dict.get("data") or []
+    resources = data if isinstance(data, list) else [data]
+    all_data_sources = [
+        ds
+        for resource in resources
+        for ds in (resource.get("attributes", {}) or {}).get("data_sources") or []
+    ]
+    if client_version < packaging.version.parse("0.2.4"):
+        for ds in all_data_sources:
+            ds.pop("properties", None)
+    strip_asset_fields_for_client(all_data_sources, client_version)
     return response_dict