feat(storage): Enable full object checksum PR 1/3 : parse finalize_time and server crc32c in async object stream (#17261)

### 1. Overview of the Solution
This solution implements end-to-end full-object checksum validation in
`AsyncMultiRangeDownloader` for the asynchronous Google Cloud Storage
Python client library. As asynchronous multiplexed downloads of
non-contiguous ranges are performed concurrently over a single
bidirectional gRPC connection, this feature automatically and
incrementally calculates a rolling checksum as bytes arrive and
validates it against the server's authoritative object checksum once the
download completes.
The technical approach consists of three coordinated layers:
* **`_AsyncReadObjectStream` (Stream Ingestion)**: Safely extracts the
authoritative server checksum (`full_obj_server_crc32c`) and
finalization status (`is_finalized`) from the object metadata received
in the first data payload response of the stream.
* **`_ReadResumptionStrategy` & `_DownloadState` (Verification Logic)**:
Computes an isolated, persistent rolling checksum in the individual
`_DownloadState` object to ensure calculations do not bleed across
concurrent multiplexed ranges. Crucially, the rolling hash updates only
*after* buffer writes succeed to prevent state corruption during retry
re-connects, raising a `DataCorruption` exception on completion if a
mismatch occurs.
* **`AsyncMultiRangeDownloader` (Orchestration & Cleanup)**: Detects
candidate full-object ranges (e.g., `(0, 0)` or `(0, persisted_size)`),
propagates checksum settings to the resumption strategy, and guarantees
robust cleanup (closing the stream immediately and unregistering IDs) if
data corruption or write errors occur.
### 2. What This PR Specifically Does
This PR implements **Step 1: Stream Metadata Ingestion** of the
solution:
* Modifies `_AsyncReadObjectStream` to safely parse GCS object metadata
from the first data payload of the response.
* Populates `is_finalized`, `full_obj_server_crc32c`, and
`object_metadata` attributes in `_AsyncReadObjectStream.open()`.
* Adds an autouse pytest event loop fixture in `tests/unit/conftest.py`
to resolve compatibility issues with `pytest-asyncio` under Python
3.11+.
* Adds unit tests in `test_async_read_object_stream.py` to verify that
finalization status and server-authoritative checksums are correctly
extracted or skipped for unfinalized objects.

Author: chandra-siri

packages/google-cloud-storage/google/cloud/storage/asyncio/async_read_object_stream.py

@@ -79,6 +79,9 @@ def __init__(
 self.socket_like_rpc: Optional[AsyncBidiRpc] =None
 self._is_stream_open: bool=False
 self.persisted_size: Optional[int] =None
+self.is_finalized: bool=False
+self.full_obj_server_crc32c: Optional[int] =None
+self.object_metadata: Optional[_storage_v2.Object] =None
 
 asyncdefopen(self, metadata: Optional[List[Tuple[str, str]]] =None) ->None:
 """Opens the bidi-gRPC connection to read from the object.
@@ -132,6 +135,18 @@ async def open(self, metadata: Optional[List[Tuple[str, str]]] = None) -> None:
 self.generation_number=response.metadata.generation
 # update persisted size
 self.persisted_size=response.metadata.size
+self.object_metadata=response.metadata
+if (
+hasattr(response.metadata, "finalize_time")
+andresponse.metadata.finalize_time
+andresponse.metadata.finalize_time.second>0
+ ):
+self.is_finalized=True
+if (
+hasattr(response.metadata, "checksums")
+andresponse.metadata.checksums
+ ):
+self.full_obj_server_crc32c=response.metadata.checksums.crc32c
 
 ifresponseandresponse.read_handle:
 self.read_handle=response.read_handle

packages/google-cloud-storage/tests/unit/asyncio/test_async_read_object_stream.py

@@ -38,9 +38,11 @@ async def instantiate_read_obj_stream(mock_client, mock_cls_async_bidi_rpc, open
 socket_like_rpc.open=AsyncMock()
 
 recv_response=mock.MagicMock(spec=_storage_v2.BidiReadObjectResponse)
-recv_response.metadata=mock.MagicMock(spec=_storage_v2.Object)
+recv_response.metadata=mock.MagicMock()
 recv_response.metadata.generation=_TEST_GENERATION_NUMBER
 recv_response.metadata.size=_TEST_OBJECT_SIZE
+recv_response.metadata.finalize_time.second=30
+recv_response.metadata.checksums.crc32c=98765
 recv_response.read_handle=_TEST_READ_HANDLE
 socket_like_rpc.recv=AsyncMock(return_value=recv_response)
 
@@ -130,6 +132,8 @@ async def test_open(mock_client, mock_cls_async_bidi_rpc):
 assertread_obj_stream.generation_number==_TEST_GENERATION_NUMBER
 assertread_obj_stream.read_handle==_TEST_READ_HANDLE
 assertread_obj_stream.persisted_size==_TEST_OBJECT_SIZE
+assertread_obj_stream.is_finalizedisTrue
+assertread_obj_stream.full_obj_server_crc32c==98765
 assertread_obj_stream.is_stream_open
 
 
@@ -381,3 +385,36 @@ async def test_recv_updates_read_handle_on_refresh(
 
 awaitstream.recv()
 assertstream.read_handle==refreshed_handle
+
+
+@mock.patch("google.cloud.storage.asyncio.async_read_object_stream.AsyncBidiRpc")
+@mock.patch(
+"google.cloud.storage.asyncio.async_grpc_client.AsyncGrpcClient.grpc_client"
+)
+@pytest.mark.asyncio
+asyncdeftest_open_unfinalized_object_skips_checksum(
+mock_client, mock_cls_async_bidi_rpc
+):
+socket_like_rpc=AsyncMock()
+mock_cls_async_bidi_rpc.return_value=socket_like_rpc
+socket_like_rpc.open=AsyncMock()
+
+recv_response=mock.MagicMock(spec=_storage_v2.BidiReadObjectResponse)
+recv_response.metadata=mock.MagicMock()
+recv_response.metadata.generation=_TEST_GENERATION_NUMBER
+recv_response.metadata.size=_TEST_OBJECT_SIZE
+recv_response.metadata.finalize_time.second=0# NOT finalized!
+recv_response.metadata.checksums.crc32c=98765
+recv_response.read_handle=_TEST_READ_HANDLE
+socket_like_rpc.recv=AsyncMock(return_value=recv_response)
+
+read_obj_stream=_AsyncReadObjectStream(
+client=mock_client,
+bucket_name=_TEST_BUCKET_NAME,
+object_name=_TEST_OBJECT_NAME,
+ )
+
+awaitread_obj_stream.open()
+
+assertread_obj_stream.is_finalizedisFalse
+assertread_obj_stream.full_obj_server_crc32cisNone

packages/google-cloud-storage/tests/unit/conftest.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+importasyncio
+importpytest
+
+
+@pytest.fixture(autouse=True)
+defset_event_loop():
+try:
+asyncio.get_running_loop()
+yield
+exceptRuntimeError:
+loop=asyncio.new_event_loop()
+asyncio.set_event_loop(loop)
+try:
+yield
+finally:
+loop.close()
+asyncio.set_event_loop(None)