feat: feat(queues): add queues metrics endpoint

* feat(queues): add queues metrics endpoint

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 2194
+configured_endpoints: 2195
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cloudflare%2Fcloudflare-0ce49e6bb0d3819f135b9a567b661205fdf5df21cff157eab2b7abd7b5b50347.yml
 openapi_spec_hash: 512a5bb3a32860590c8949765605d65a
-config_hash: 5367ae3e3a9a0d6578c2756965a99e3a
+config_hash: 6f813d0ef66c7bf6daf8e0df5638e7a3

src/cloudflare/resources/queues/api.md

@@ -3,7 +3,7 @@
 Types:
 
 ```python
-from cloudflare.types.queues import Queue, QueueDeleteResponse
+from cloudflare.types.queues import Queue, QueueDeleteResponse, QueueGetMetricsResponse
 ```
 
 Methods:
@@ -14,6 +14,7 @@ Methods:
 - <code title="delete /accounts/{account_id}/queues/{queue_id}">client.queues.<a href="./src/cloudflare/resources/queues/queues.py">delete</a>(queue_id, \*, account_id) -> <a href="./src/cloudflare/types/queues/queue_delete_response.py">QueueDeleteResponse</a></code>
 - <code title="patch /accounts/{account_id}/queues/{queue_id}">client.queues.<a href="./src/cloudflare/resources/queues/queues.py">edit</a>(queue_id, \*, account_id, \*\*<a href="src/cloudflare/types/queues/queue_edit_params.py">params</a>) -> <a href="./src/cloudflare/types/queues/queue.py">Optional[Queue]</a></code>
 - <code title="get /accounts/{account_id}/queues/{queue_id}">client.queues.<a href="./src/cloudflare/resources/queues/queues.py">get</a>(queue_id, \*, account_id) -> <a href="./src/cloudflare/types/queues/queue.py">Optional[Queue]</a></code>
+- <code title="get /accounts/{account_id}/queues/{queue_id}/metrics">client.queues.<a href="./src/cloudflare/resources/queues/queues.py">get_metrics</a>(queue_id, \*, account_id) -> <a href="./src/cloudflare/types/queues/queue_get_metrics_response.py">Optional[QueueGetMetricsResponse]</a></code>
 
 ## Messages
 

src/cloudflare/resources/queues/queues.py

@@ -54,6 +54,7 @@
 from ...types.queues import queue_edit_params, queue_create_params, queue_update_params
 from ...types.queues.queue import Queue
 from ...types.queues.queue_delete_response import QueueDeleteResponse
+from ...types.queues.queue_get_metrics_response import QueueGetMetricsResponse
 
 __all__ = ["QueuesResource", "AsyncQueuesResource"]
 
@@ -364,6 +365,52 @@ def get(
             cast_to=cast(Type[Optional[Queue]], ResultWrapper[Queue]),
         )
 
+    def get_metrics(
+        self,
+        queue_id: str,
+        *,
+        account_id: str,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> Optional[QueueGetMetricsResponse]:
+        """Return best-effort metrics for a queue.
+
+        Values may be approximate due to the
+        distributed nature of queues.
+
+        Args:
+          account_id: A Resource identifier.
+
+          queue_id: A Resource identifier.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not account_id:
+            raise ValueError(f"Expected a non-empty value for `account_id` but received {account_id!r}")
+        if not queue_id:
+            raise ValueError(f"Expected a non-empty value for `queue_id` but received {queue_id!r}")
+        return self._get(
+            path_template("/accounts/{account_id}/queues/{queue_id}/metrics", account_id=account_id, queue_id=queue_id),
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                post_parser=ResultWrapper[Optional[QueueGetMetricsResponse]]._unwrapper,
+            ),
+            cast_to=cast(Type[Optional[QueueGetMetricsResponse]], ResultWrapper[QueueGetMetricsResponse]),
+        )
+
 
 class AsyncQueuesResource(AsyncAPIResource):
     @cached_property
@@ -671,6 +718,52 @@ async def get(
             cast_to=cast(Type[Optional[Queue]], ResultWrapper[Queue]),
         )
 
+    async def get_metrics(
+        self,
+        queue_id: str,
+        *,
+        account_id: str,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> Optional[QueueGetMetricsResponse]:
+        """Return best-effort metrics for a queue.
+
+        Values may be approximate due to the
+        distributed nature of queues.
+
+        Args:
+          account_id: A Resource identifier.
+
+          queue_id: A Resource identifier.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not account_id:
+            raise ValueError(f"Expected a non-empty value for `account_id` but received {account_id!r}")
+        if not queue_id:
+            raise ValueError(f"Expected a non-empty value for `queue_id` but received {queue_id!r}")
+        return await self._get(
+            path_template("/accounts/{account_id}/queues/{queue_id}/metrics", account_id=account_id, queue_id=queue_id),
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                post_parser=ResultWrapper[Optional[QueueGetMetricsResponse]]._unwrapper,
+            ),
+            cast_to=cast(Type[Optional[QueueGetMetricsResponse]], ResultWrapper[QueueGetMetricsResponse]),
+        )
+
 
 class QueuesResourceWithRawResponse:
     def __init__(self, queues: QueuesResource) -> None:
@@ -694,6 +787,9 @@ def __init__(self, queues: QueuesResource) -> None:
         self.get = to_raw_response_wrapper(
             queues.get,
         )
+        self.get_metrics = to_raw_response_wrapper(
+            queues.get_metrics,
+        )
 
     @cached_property
     def messages(self) -> MessagesResourceWithRawResponse:
@@ -734,6 +830,9 @@ def __init__(self, queues: AsyncQueuesResource) -> None:
         self.get = async_to_raw_response_wrapper(
             queues.get,
         )
+        self.get_metrics = async_to_raw_response_wrapper(
+            queues.get_metrics,
+        )
 
     @cached_property
     def messages(self) -> AsyncMessagesResourceWithRawResponse:
@@ -774,6 +873,9 @@ def __init__(self, queues: QueuesResource) -> None:
         self.get = to_streamed_response_wrapper(
             queues.get,
         )
+        self.get_metrics = to_streamed_response_wrapper(
+            queues.get_metrics,
+        )
 
     @cached_property
     def messages(self) -> MessagesResourceWithStreamingResponse:
@@ -814,6 +916,9 @@ def __init__(self, queues: AsyncQueuesResource) -> None:
         self.get = async_to_streamed_response_wrapper(
             queues.get,
         )
+        self.get_metrics = async_to_streamed_response_wrapper(
+            queues.get_metrics,
+        )
 
     @cached_property
     def messages(self) -> AsyncMessagesResourceWithStreamingResponse:

src/cloudflare/types/queues/__init__.py

@@ -23,6 +23,7 @@
 from .subscription_list_params import SubscriptionListParams as SubscriptionListParams
 from .subscription_get_response import SubscriptionGetResponse as SubscriptionGetResponse
 from .message_bulk_push_response import MessageBulkPushResponse as MessageBulkPushResponse
+from .queue_get_metrics_response import QueueGetMetricsResponse as QueueGetMetricsResponse
 from .subscription_create_params import SubscriptionCreateParams as SubscriptionCreateParams
 from .subscription_list_response import SubscriptionListResponse as SubscriptionListResponse
 from .subscription_update_params import SubscriptionUpdateParams as SubscriptionUpdateParams

src/cloudflare/types/queues/queue_get_metrics_response.py

@@ -0,0 +1,25 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from ..._models import BaseModel
+
+__all__ = ["QueueGetMetricsResponse"]
+
+
+class QueueGetMetricsResponse(BaseModel):
+    """Best-effort metrics for the queue.
+
+    Values may be approximate due to the distributed nature of queues.
+    """
+
+    backlog_bytes: float
+    """The size in bytes of unacknowledged messages in the queue."""
+
+    backlog_count: float
+    """The number of unacknowledged messages in the queue."""
+
+    oldest_message_timestamp_ms: float
+    """Unix timestamp in milliseconds of the oldest unacknowledged message in the
+    queue.
+
+    Returns 0 if unknown.
+    """

tests/api_resources/test_queues.py

@@ -13,6 +13,7 @@
 from cloudflare.types.queues import (
     Queue,
     QueueDeleteResponse,
+    QueueGetMetricsResponse,
 )
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
@@ -321,6 +322,54 @@ def test_path_params_get(self, client: Cloudflare) -> None:
                 account_id="023e105f4ecef8ad9ca31a8372d0c353",
             )
 
+    @parametrize
+    def test_method_get_metrics(self, client: Cloudflare) -> None:
+        queue = client.queues.get_metrics(
+            queue_id="023e105f4ecef8ad9ca31a8372d0c353",
+            account_id="023e105f4ecef8ad9ca31a8372d0c353",
+        )
+        assert_matches_type(Optional[QueueGetMetricsResponse], queue, path=["response"])
+
+    @parametrize
+    def test_raw_response_get_metrics(self, client: Cloudflare) -> None:
+        response = client.queues.with_raw_response.get_metrics(
+            queue_id="023e105f4ecef8ad9ca31a8372d0c353",
+            account_id="023e105f4ecef8ad9ca31a8372d0c353",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        queue = response.parse()
+        assert_matches_type(Optional[QueueGetMetricsResponse], queue, path=["response"])
+
+    @parametrize
+    def test_streaming_response_get_metrics(self, client: Cloudflare) -> None:
+        with client.queues.with_streaming_response.get_metrics(
+            queue_id="023e105f4ecef8ad9ca31a8372d0c353",
+            account_id="023e105f4ecef8ad9ca31a8372d0c353",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            queue = response.parse()
+            assert_matches_type(Optional[QueueGetMetricsResponse], queue, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
+    @parametrize
+    def test_path_params_get_metrics(self, client: Cloudflare) -> None:
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `account_id` but received ''"):
+            client.queues.with_raw_response.get_metrics(
+                queue_id="023e105f4ecef8ad9ca31a8372d0c353",
+                account_id="",
+            )
+
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `queue_id` but received ''"):
+            client.queues.with_raw_response.get_metrics(
+                queue_id="",
+                account_id="023e105f4ecef8ad9ca31a8372d0c353",
+            )
+
 
 class TestAsyncQueues:
     parametrize = pytest.mark.parametrize(
@@ -626,3 +675,51 @@ async def test_path_params_get(self, async_client: AsyncCloudflare) -> None:
                 queue_id="",
                 account_id="023e105f4ecef8ad9ca31a8372d0c353",
             )
+
+    @parametrize
+    async def test_method_get_metrics(self, async_client: AsyncCloudflare) -> None:
+        queue = await async_client.queues.get_metrics(
+            queue_id="023e105f4ecef8ad9ca31a8372d0c353",
+            account_id="023e105f4ecef8ad9ca31a8372d0c353",
+        )
+        assert_matches_type(Optional[QueueGetMetricsResponse], queue, path=["response"])
+
+    @parametrize
+    async def test_raw_response_get_metrics(self, async_client: AsyncCloudflare) -> None:
+        response = await async_client.queues.with_raw_response.get_metrics(
+            queue_id="023e105f4ecef8ad9ca31a8372d0c353",
+            account_id="023e105f4ecef8ad9ca31a8372d0c353",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        queue = await response.parse()
+        assert_matches_type(Optional[QueueGetMetricsResponse], queue, path=["response"])
+
+    @parametrize
+    async def test_streaming_response_get_metrics(self, async_client: AsyncCloudflare) -> None:
+        async with async_client.queues.with_streaming_response.get_metrics(
+            queue_id="023e105f4ecef8ad9ca31a8372d0c353",
+            account_id="023e105f4ecef8ad9ca31a8372d0c353",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            queue = await response.parse()
+            assert_matches_type(Optional[QueueGetMetricsResponse], queue, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
+    @parametrize
+    async def test_path_params_get_metrics(self, async_client: AsyncCloudflare) -> None:
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `account_id` but received ''"):
+            await async_client.queues.with_raw_response.get_metrics(
+                queue_id="023e105f4ecef8ad9ca31a8372d0c353",
+                account_id="",
+            )
+
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `queue_id` but received ''"):
+            await async_client.queues.with_raw_response.get_metrics(
+                queue_id="",
+                account_id="023e105f4ecef8ad9ca31a8372d0c353",
+            )