fix: coerce null stats in Apify request queue metadata (#974)

Opening a request queue crashed when the Apify API omitted `stats`
(sending an explicit `null`): `model_dump(by_alias=True)` preserved
`stats: None`, and the non-optional `stats` field on
`ApifyRequestQueueMetadata` rejected it. The `default_factory` only
fires when the key is absent, not when it is present-but-null.

This adds a `BeforeValidator` that coerces `None` to a default
`RequestQueueStats`, mirroring the defensive `metadata.stats or
RequestQueueStats()` already used in `get_metadata()`, so every
validation path is protected.

Author: vdusek

src/apify/storage_clients/_apify/_models.py

@@ -3,7 +3,7 @@
 from datetime import datetime, timedelta
 from typing import TYPE_CHECKING, Annotated
 
-from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, BaseModel, BeforeValidator, ConfigDict, Field
 from pydantic.alias_generators import to_camel
 
 from apify_client._models import RequestQueueStats
@@ -105,5 +105,13 @@ class CachedRequest(BaseModel):
 class ApifyRequestQueueMetadata(RequestQueueMetadata):
     model_config = ConfigDict(alias_generator=to_camel)
 
-    stats: Annotated[RequestQueueStats, Field(default_factory=RequestQueueStats)]
-    """Additional statistics about the request queue."""
+    stats: Annotated[
+        RequestQueueStats,
+        BeforeValidator(lambda value: RequestQueueStats() if value is None else value),
+        Field(default_factory=RequestQueueStats),
+    ]
+    """Additional statistics about the request queue.
+
+    The API may omit the stats (sending an explicit `null`), so a `None` value is coerced to a default
+    `RequestQueueStats` rather than failing validation.
+    """

tests/unit/storage_clients/test_apify_request_queue_client.py

@@ -5,9 +5,10 @@
 
 import pytest
 
-from apify_client._models import RequestQueueHead
+from apify_client._models import RequestQueueHead, RequestQueueStats
 from crawlee.storage_clients.models import RequestQueueMetadata
 
+from apify.storage_clients._apify._models import ApifyRequestQueueMetadata
 from apify.storage_clients._apify._request_queue_single_client import ApifyRequestQueueSingleClient
 from apify.storage_clients._apify._utils import unique_key_to_request_id
 
@@ -46,6 +47,32 @@ def test_unique_key_to_request_id_consistency() -> None:
     assert request_id_1 == request_id_2, 'The same unique key should generate consistent request IDs.'
 
 
+@pytest.mark.parametrize(
+    ('stats', 'expected_read_count'),
+    [(None, None), ({'readCount': 5}, 5)],
+    ids=['none_coerced_to_default', 'populated_passed_through'],
+)
+def test_metadata_stats_validation(stats: dict | None, expected_read_count: int | None) -> None:
+    """A `stats: None` payload (as `open()` produces via `model_dump`) defaults; a populated one passes through."""
+    now = datetime.now(tz=UTC)
+    metadata = ApifyRequestQueueMetadata.model_validate(
+        {
+            'id': 'test-rq-id',
+            'name': None,
+            'accessedAt': now,
+            'createdAt': now,
+            'modifiedAt': now,
+            'hadMultipleClients': False,
+            'handledRequestCount': 0,
+            'pendingRequestCount': 0,
+            'totalRequestCount': 0,
+            'stats': stats,
+        }
+    )
+    assert isinstance(metadata.stats, RequestQueueStats)
+    assert metadata.stats.read_count == expected_read_count
+
+
 @pytest.mark.parametrize(
     ('unique_key', 'expected_request_id'),
     [