feat: add dataset.create_items_public_url and key_value_store.create_keys_public_url (#453)

When storage resources (Datasets or Key-Value Stores) are set to
Restricted, accessing or sharing their data externally becomes difficult
due to limited permissions. This PR introduces functionality to generate
signed URLs that allow controlled external access to these resources
without adding token to the request.

This PR introduces methods to generate signed URLs for Dataset items and
Key-Value Store records:
1. **Datasets**
`dataset(:datasetId).create_items_public_url(options,
expires_in_millis)`
→ Returns a signed URL like:
`/v2/datasets/:datasetId/items?signature=xxx`

2. Key-Value Stores
`key_value_store(:storeId).create_keys_public_url(options,
expires_in_millis)`
→ Returns a signed URL like:
`/v2/key-value-stores/:storeId/keys?signature=xxx`

🕒 Expiration:
The `expires_in_millis` parameter defines how long the signature is
valid.
- If provided, the URL will expire after the specified time.
- If omitted, the URL will never expire.


Note 1: The signature is included only if the token has WRITE access to
the storage. Otherwise, an unsigned URL is returned.

P.S. We're not yet exposing `urlSigningSecretKey` for datasets, it will
be released after [PR](apify/apify-core#22173)
is merged.

[More context
here](https://www.notion.so/apify/Signed-Dataset-Items-KV-store-record-URLs-224f39950a2280158a6bd82bc2e2ebb5?source=copy_link)

Same PR in JS apify/apify-client-js#720

Author: danpoletaev

src/apify_client/clients/resource_clients/dataset.py

@@ -4,9 +4,16 @@
 import warnings
 from contextlib import asynccontextmanager, contextmanager
 from typing import TYPE_CHECKING, Any
+from urllib.parse import urlencode, urlparse, urlunparse
+
+from apify_shared.utils import create_storage_content_signature
 
 from apify_client._types import ListPage
-from apify_client._utils import catch_not_found_or_throw, filter_out_none_values_recursively, pluck_data
+from apify_client._utils import (
+    catch_not_found_or_throw,
+    filter_out_none_values_recursively,
+    pluck_data,
+)
 from apify_client.clients.base import ResourceClient, ResourceClientAsync
 from apify_client.errors import ApifyApiError
 
@@ -558,6 +565,67 @@ def get_statistics(self) -> dict | None:
 
         return None
 
+    def create_items_public_url(
+        self,
+        *,
+        offset: int | None = None,
+        limit: int | None = None,
+        clean: bool | None = None,
+        desc: bool | None = None,
+        fields: list[str] | None = None,
+        omit: list[str] | None = None,
+        unwind: list[str] | None = None,
+        skip_empty: bool | None = None,
+        skip_hidden: bool | None = None,
+        flatten: list[str] | None = None,
+        view: str | None = None,
+        expires_in_secs: int | None = None,
+    ) -> str:
+        """Generate a URL that can be used to access dataset items.
+
+        If the client has permission to access the dataset's URL signing key,
+        the URL will include a signature to verify its authenticity.
+
+        You can optionally control how long the signed URL should be valid using the `expires_in_secs` option.
+        This value sets the expiration duration in seconds from the time the URL is generated.
+        If not provided, the URL will not expire.
+
+        Any other options (like `limit` or `offset`) will be included as query parameters in the URL.
+
+        Returns:
+            The public dataset items URL.
+        """
+        dataset = self.get()
+
+        request_params = self._params(
+            offset=offset,
+            limit=limit,
+            desc=desc,
+            clean=clean,
+            fields=fields,
+            omit=omit,
+            unwind=unwind,
+            skipEmpty=skip_empty,
+            skipHidden=skip_hidden,
+            flatten=flatten,
+            view=view,
+        )
+
+        if dataset and 'urlSigningSecretKey' in dataset:
+            signature = create_storage_content_signature(
+                resource_id=dataset['id'],
+                url_signing_secret_key=dataset['urlSigningSecretKey'],
+                expires_in_millis=expires_in_secs * 1000 if expires_in_secs is not None else None,
+            )
+            request_params['signature'] = signature
+
+        items_public_url = urlparse(self._url('items'))
+        filtered_params = {k: v for k, v in request_params.items() if v is not None}
+        if filtered_params:
+            items_public_url = items_public_url._replace(query=urlencode(filtered_params))
+
+        return urlunparse(items_public_url)
+
 
 class DatasetClientAsync(ResourceClientAsync):
     """Async sub-client for manipulating a single dataset."""
@@ -1003,3 +1071,64 @@ async def get_statistics(self) -> dict | None:
             catch_not_found_or_throw(exc)
 
         return None
+
+    async def create_items_public_url(
+        self,
+        *,
+        offset: int | None = None,
+        limit: int | None = None,
+        clean: bool | None = None,
+        desc: bool | None = None,
+        fields: list[str] | None = None,
+        omit: list[str] | None = None,
+        unwind: list[str] | None = None,
+        skip_empty: bool | None = None,
+        skip_hidden: bool | None = None,
+        flatten: list[str] | None = None,
+        view: str | None = None,
+        expires_in_secs: int | None = None,
+    ) -> str:
+        """Generate a URL that can be used to access dataset items.
+
+        If the client has permission to access the dataset's URL signing key,
+        the URL will include a signature to verify its authenticity.
+
+        You can optionally control how long the signed URL should be valid using the `expires_in_secs` option.
+        This value sets the expiration duration in seconds from the time the URL is generated.
+        If not provided, the URL will not expire.
+
+        Any other options (like `limit` or `offset`) will be included as query parameters in the URL.
+
+        Returns:
+            The public dataset items URL.
+        """
+        dataset = await self.get()
+
+        request_params = self._params(
+            offset=offset,
+            limit=limit,
+            desc=desc,
+            clean=clean,
+            fields=fields,
+            omit=omit,
+            unwind=unwind,
+            skipEmpty=skip_empty,
+            skipHidden=skip_hidden,
+            flatten=flatten,
+            view=view,
+        )
+
+        if dataset and 'urlSigningSecretKey' in dataset:
+            signature = create_storage_content_signature(
+                resource_id=dataset['id'],
+                url_signing_secret_key=dataset['urlSigningSecretKey'],
+                expires_in_millis=expires_in_secs * 1000 if expires_in_secs is not None else None,
+            )
+            request_params['signature'] = signature
+
+        items_public_url = urlparse(self._url('items'))
+        filtered_params = {k: v for k, v in request_params.items() if v is not None}
+        if filtered_params:
+            items_public_url = items_public_url._replace(query=urlencode(filtered_params))
+
+        return urlunparse(items_public_url)

src/apify_client/clients/resource_clients/key_value_store.py

@@ -4,6 +4,9 @@
 from contextlib import asynccontextmanager, contextmanager
 from http import HTTPStatus
 from typing import TYPE_CHECKING, Any
+from urllib.parse import urlencode, urlparse, urlunparse
+
+from apify_shared.utils import create_storage_content_signature
 
 from apify_client._utils import (
     catch_not_found_or_throw,
@@ -264,6 +267,54 @@ def delete_record(self, key: str) -> None:
             timeout_secs=_SMALL_TIMEOUT,
         )
 
+    def create_keys_public_url(
+        self,
+        *,
+        limit: int | None = None,
+        exclusive_start_key: str | None = None,
+        collection: str | None = None,
+        prefix: str | None = None,
+        expires_in_secs: int | None = None,
+    ) -> str:
+        """Generate a URL that can be used to access key-value store keys.
+
+        If the client has permission to access the key-value store's URL signing key,
+        the URL will include a signature to verify its authenticity.
+
+        You can optionally control how long the signed URL should be valid using the `expires_in_secs` option.
+        This value sets the expiration duration in seconds from the time the URL is generated.
+        If not provided, the URL will not expire.
+
+        Any other options (like `limit` or `prefix`) will be included as query parameters in the URL.
+
+        Returns:
+            The public key-value store keys URL.
+        """
+        store = self.get()
+
+        request_params = self._params(
+            limit=limit,
+            exclusive_start_key=exclusive_start_key,
+            collection=collection,
+            prefix=prefix,
+        )
+
+        if store and 'urlSigningSecretKey' in store:
+            signature = create_storage_content_signature(
+                resource_id=store['id'],
+                url_signing_secret_key=store['urlSigningSecretKey'],
+                expires_in_millis=expires_in_secs * 1000 if expires_in_secs is not None else None,
+            )
+            request_params['signature'] = signature
+
+        keys_public_url = urlparse(self._url('keys'))
+
+        filtered_params = {k: v for k, v in request_params.items() if v is not None}
+        if filtered_params:
+            keys_public_url = keys_public_url._replace(query=urlencode(filtered_params))
+
+        return urlunparse(keys_public_url)
+
 
 class KeyValueStoreClientAsync(ResourceClientAsync):
     """Async sub-client for manipulating a single key-value store."""
@@ -503,3 +554,52 @@ async def delete_record(self, key: str) -> None:
             params=self._params(),
             timeout_secs=_SMALL_TIMEOUT,
         )
+
+    async def create_keys_public_url(
+        self,
+        *,
+        limit: int | None = None,
+        exclusive_start_key: str | None = None,
+        collection: str | None = None,
+        prefix: str | None = None,
+        expires_in_secs: int | None = None,
+    ) -> str:
+        """Generate a URL that can be used to access key-value store keys.
+
+        If the client has permission to access the key-value store's URL signing key,
+        the URL will include a signature to verify its authenticity.
+
+        You can optionally control how long the signed URL should be valid using the `expires_in_secs` option.
+        This value sets the expiration duration in seconds from the time the URL is generated.
+        If not provided, the URL will not expire.
+
+        Any other options (like `limit` or `prefix`) will be included as query parameters in the URL.
+
+        Returns:
+            The public key-value store keys URL.
+        """
+        store = await self.get()
+
+        keys_public_url = urlparse(self._url('keys'))
+
+        request_params = self._params(
+            limit=limit,
+            exclusive_start_key=exclusive_start_key,
+            collection=collection,
+            prefix=prefix,
+        )
+
+        if store and 'urlSigningSecretKey' in store:
+            signature = create_storage_content_signature(
+                resource_id=store['id'],
+                url_signing_secret_key=store['urlSigningSecretKey'],
+                expires_in_millis=expires_in_secs * 1000 if expires_in_secs is not None else None,
+            )
+            request_params['signature'] = signature
+
+        keys_public_url = urlparse(self._url('keys'))
+        filtered_params = {k: v for k, v in request_params.items() if v is not None}
+        if filtered_params:
+            keys_public_url = keys_public_url._replace(query=urlencode(filtered_params))
+
+        return urlunparse(keys_public_url)

tests/integration/integration_test_utils.py

@@ -0,0 +1,10 @@
+import secrets
+import string
+
+
+def random_string(length: int = 10) -> str:
+    return ''.join(secrets.choice(string.ascii_letters) for _ in range(length))
+
+
+def random_resource_name(resource: str) -> str:
+    return f'python-client-test-{resource}-{random_string(5)}'

tests/integration/test_dataset.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import impit
+
+from integration.integration_test_utils import random_resource_name
+
+if TYPE_CHECKING:
+    from apify_client import ApifyClient, ApifyClientAsync
+
+
+class TestDatasetSync:
+    def test_dataset_should_create_public_items_expiring_url_with_params(self, apify_client: ApifyClient) -> None:
+        created_dataset = apify_client.datasets().get_or_create(name=random_resource_name('dataset'))
+
+        dataset = apify_client.dataset(created_dataset['id'])
+        items_public_url = dataset.create_items_public_url(
+            expires_in_secs=2000,
+            limit=10,
+            offset=0,
+        )
+
+        assert 'signature=' in items_public_url
+        assert 'limit=10' in items_public_url
+        assert 'offset=0' in items_public_url
+
+        impit_client = impit.Client()
+        response = impit_client.get(items_public_url, timeout=5)
+        assert response.status_code == 200
+
+        dataset.delete()
+        assert apify_client.dataset(created_dataset['id']).get() is None
+
+    def test_dataset_should_create_public_items_non_expiring_url(self, apify_client: ApifyClient) -> None:
+        created_dataset = apify_client.datasets().get_or_create(name=random_resource_name('dataset'))
+
+        dataset = apify_client.dataset(created_dataset['id'])
+        items_public_url = dataset.create_items_public_url()
+
+        assert 'signature=' in items_public_url
+
+        impit_client = impit.Client()
+        response = impit_client.get(items_public_url, timeout=5)
+        assert response.status_code == 200
+
+        dataset.delete()
+        assert apify_client.dataset(created_dataset['id']).get() is None
+
+
+class TestDatasetAsync:
+    async def test_dataset_should_create_public_items_expiring_url_with_params(
+        self, apify_client_async: ApifyClientAsync
+    ) -> None:
+        created_dataset = await apify_client_async.datasets().get_or_create(name=random_resource_name('dataset'))
+
+        dataset = apify_client_async.dataset(created_dataset['id'])
+        items_public_url = await dataset.create_items_public_url(
+            expires_in_secs=2000,
+            limit=10,
+            offset=0,
+        )
+
+        assert 'signature=' in items_public_url
+        assert 'limit=10' in items_public_url
+        assert 'offset=0' in items_public_url
+
+        impit_async_client = impit.AsyncClient()
+        response = await impit_async_client.get(items_public_url, timeout=5)
+        assert response.status_code == 200
+
+        await dataset.delete()
+        assert await apify_client_async.dataset(created_dataset['id']).get() is None
+
+    async def test_dataset_should_create_public_items_non_expiring_url(
+        self, apify_client_async: ApifyClientAsync
+    ) -> None:
+        created_dataset = await apify_client_async.datasets().get_or_create(name=random_resource_name('dataset'))
+
+        dataset = apify_client_async.dataset(created_dataset['id'])
+        items_public_url = await dataset.create_items_public_url()
+
+        assert 'signature=' in items_public_url
+
+        impit_async_client = impit.AsyncClient()
+        response = await impit_async_client.get(items_public_url, timeout=5)
+        assert response.status_code == 200
+
+        await dataset.delete()
+        assert await apify_client_async.dataset(created_dataset['id']).get() is None