Use /public prefix for unauthenticated clients

Author: lukasbindreiter

CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.50.1] - 2026-03-31
+## [0.50.1] - 2026-04-01
 
 ### Added
 

tilebox-datasets/tests/test_aio.py

@@ -1,9 +1,28 @@
+import os
 from unittest.mock import MagicMock, patch
 
+import pytest
+
 from tilebox.datasets.aio import Client
+from tilebox.datasets.client import _TILEBOX_API_URL, _TILEBOX_DEV_API_URL
 
 
 @patch("tilebox.datasets.aio.client.open_channel")
 def test_tilebox_client_init_opens_channel(open_channel_mock: MagicMock) -> None:
     Client(url="some-url", token="some-token")  # noqa: S106
-    open_channel_mock.assert_called_once_with("some-url", "some-token")
+    open_channel_mock.assert_called_once_with("some-url", "some-token", rpc_method_prefix=None)
+
+
+@pytest.mark.parametrize("url", [_TILEBOX_API_URL, _TILEBOX_DEV_API_URL, f"{_TILEBOX_API_URL}/"])
+@patch.dict(os.environ, {}, clear=True)
+@patch("tilebox.datasets.aio.client.open_channel")
+def test_tilebox_client_init_uses_public_rpc_prefix_for_tilebox_urls(open_channel_mock: MagicMock, url: str) -> None:
+    Client(url=url, token=None)
+    open_channel_mock.assert_called_once_with(url.removesuffix("/"), None, rpc_method_prefix="/public")
+
+
+@patch.dict(os.environ, {}, clear=True)
+@patch("tilebox.datasets.aio.client.open_channel")
+def test_tilebox_client_init_skips_public_rpc_prefix_for_custom_urls(open_channel_mock: MagicMock) -> None:
+    Client(url="some-url", token=None)
+    open_channel_mock.assert_called_once_with("some-url", None, rpc_method_prefix=None)

tilebox-datasets/tests/test_client.py

@@ -1,7 +1,7 @@
 import os
 from datetime import datetime, timezone
 from pathlib import Path
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 import xarray as xr
@@ -10,10 +10,26 @@
 from _tilebox.grpc.error import NotFoundError
 from _tilebox.grpc.replay import open_recording_channel, open_replay_channel
 from tilebox.datasets import Client, DatasetClient
+from tilebox.datasets.client import _TILEBOX_API_URL, _TILEBOX_DEV_API_URL
 from tilebox.datasets.data.datapoint import QueryResultPage
 from tilebox.datasets.query.time_interval import us_to_datetime
 
 
+@pytest.mark.parametrize("url", [_TILEBOX_API_URL, _TILEBOX_DEV_API_URL, f"{_TILEBOX_API_URL}/"])
+@patch.dict(os.environ, {}, clear=True)
+@patch("tilebox.datasets.sync.client.open_channel")
+def test_tilebox_client_init_uses_public_rpc_prefix_for_tilebox_urls(open_channel_mock: MagicMock, url: str) -> None:
+    Client(url=url, token=None)
+    open_channel_mock.assert_called_once_with(url.removesuffix("/"), None, rpc_method_prefix="/public")
+
+
+@patch.dict(os.environ, {}, clear=True)
+@patch("tilebox.datasets.sync.client.open_channel")
+def test_tilebox_client_init_skips_public_rpc_prefix_for_custom_urls(open_channel_mock: MagicMock) -> None:
+    Client(url="some-url", token=None)
+    open_channel_mock.assert_called_once_with("some-url", None, rpc_method_prefix=None)
+
+
 def replay_client(replay_file: str, assert_request_matches: bool = True) -> Client:
     replay = Path(__file__).parent / "testdata" / "recordings" / replay_file
     replay_channel = open_replay_channel(replay, assert_request_matches)

tilebox-datasets/tilebox/datasets/aio/client.py

@@ -6,8 +6,9 @@
 from _tilebox.grpc.aio.channel import open_channel
 from _tilebox.grpc.aio.error import with_pythonic_errors
 from _tilebox.grpc.error import NotFoundError
+from _tilebox.grpc.public import _PUBLIC_RPC_METHOD_PREFIX
 from tilebox.datasets.aio.dataset import DatasetClient
-from tilebox.datasets.client import _TILEBOX_API_KEY_ENV_VAR, _TILEBOX_API_URL
+from tilebox.datasets.client import _TILEBOX_API_KEY_ENV_VAR, _TILEBOX_API_URL, _TILEBOX_DEV_API_URL
 from tilebox.datasets.client import Client as BaseClient
 from tilebox.datasets.data.datasets import DatasetKind, FieldDict
 from tilebox.datasets.datasets.v1.collections_pb2_grpc import CollectionServiceStub
@@ -32,18 +33,25 @@ def __init__(
             warn_if_unauthenticated: Whether to warn if no API key is provided and the client is used with the default
                 Tilebox API URL. Defaults to True.
         """
+        url = url.removesuffix("/")
+
         if token is None:
             token = os.environ.get(_TILEBOX_API_KEY_ENV_VAR, None)
 
-        if token is None and url == _TILEBOX_API_URL and warn_if_unauthenticated:
+        is_tilebox_deployment = url in (_TILEBOX_API_URL, _TILEBOX_DEV_API_URL)
+        if token is None and is_tilebox_deployment and warn_if_unauthenticated:
             logger.opt(colors=True).info(
                 "<yellow>"
                 "No Tilebox API key detected. Using <bold>anonymous open data access</bold> without authentication. "
                 "For higher throughput and rate limits, sign up for a free account at https://console.tilebox.com."
                 "</yellow>"
             )
 
-        channel = open_channel(url, token)
+        channel = open_channel(
+            url,
+            token,
+            rpc_method_prefix=_PUBLIC_RPC_METHOD_PREFIX if (is_tilebox_deployment and token is None) else None,
+        )
         dataset_service_stub = with_pythonic_errors(DatasetServiceStub(channel))
         collection_service_stub = with_pythonic_errors(CollectionServiceStub(channel))
         data_access_service_stub = with_pythonic_errors(DataAccessServiceStub(channel))

tilebox-datasets/tilebox/datasets/client.py

@@ -13,6 +13,7 @@
 from tilebox.datasets.uuid import as_uuid
 
 _TILEBOX_API_URL = "https://api.tilebox.com"
+_TILEBOX_DEV_API_URL = "https://api.tilebox.dev"
 _TILEBOX_API_KEY_ENV_VAR = "TILEBOX_API_KEY"
 
 

tilebox-datasets/tilebox/datasets/sync/client.py

@@ -5,7 +5,8 @@
 
 from _tilebox.grpc.channel import open_channel
 from _tilebox.grpc.error import NotFoundError, with_pythonic_errors
-from tilebox.datasets.client import _TILEBOX_API_KEY_ENV_VAR, _TILEBOX_API_URL
+from _tilebox.grpc.public import _PUBLIC_RPC_METHOD_PREFIX
+from tilebox.datasets.client import _TILEBOX_API_KEY_ENV_VAR, _TILEBOX_API_URL, _TILEBOX_DEV_API_URL
 from tilebox.datasets.client import Client as BaseClient
 from tilebox.datasets.data.datasets import DatasetKind, FieldDict
 from tilebox.datasets.datasets.v1.collections_pb2_grpc import CollectionServiceStub
@@ -31,18 +32,25 @@ def __init__(
             warn_if_unauthenticated: Whether to warn if no API key is provided and the client is used with the default
                 Tilebox API URL. Defaults to True.
         """
+        url = url.removesuffix("/")
+
         if token is None:
             token = os.environ.get(_TILEBOX_API_KEY_ENV_VAR, None)
 
-        if token is None and url == _TILEBOX_API_URL and warn_if_unauthenticated:
+        is_tilebox_deployment = url in (_TILEBOX_API_URL, _TILEBOX_DEV_API_URL)
+        if token is None and is_tilebox_deployment and warn_if_unauthenticated:
             logger.opt(colors=True).info(
                 "<yellow>"
                 "No Tilebox API key detected. Using <bold>anonymous open data access</bold> without authentication. "
                 "For higher throughput and rate limits, sign up for a free account at https://console.tilebox.com."
                 "</yellow>"
             )
 
-        channel = open_channel(url, token)
+        channel = open_channel(
+            url,
+            token,
+            rpc_method_prefix=_PUBLIC_RPC_METHOD_PREFIX if (is_tilebox_deployment and token is None) else None,
+        )
         dataset_service_stub = with_pythonic_errors(DatasetServiceStub(channel))
         collection_service_stub = with_pythonic_errors(CollectionServiceStub(channel))
         data_access_service_stub = with_pythonic_errors(DataAccessServiceStub(channel))

tilebox-grpc/_tilebox/grpc/aio/channel.py

@@ -1,7 +1,14 @@
 from collections.abc import Callable, Sequence
 from typing import TypeVar
 
-from _tilebox.grpc.channel import CHANNEL_OPTIONS, ChannelInfo, ChannelProtocol, add_metadata, parse_channel_info
+from _tilebox.grpc.channel import (
+    CHANNEL_OPTIONS,
+    ChannelInfo,
+    ChannelProtocol,
+    add_metadata,
+    parse_channel_info,
+    update_method,
+)
 from grpc import Compression, ssl_channel_credentials
 from grpc.aio import (
     Channel,
@@ -14,13 +21,14 @@
 )
 
 
-def open_channel(url: str, auth_token: str | None = None) -> Channel:
+def open_channel(url: str, auth_token: str | None = None, rpc_method_prefix: str | None = None) -> Channel:
     """Open an async gRPC channel to the given URL.
 
     Args:
         url: The URL to open a channel to. Depending on the URL, the channel will be a secure (SSL) or insecure channel.
         auth_token: Authentication token for the channel. If set, an interceptor channel will be created which adds
             the given token as metadata to each request.
+        rpc_method_prefix: Optional prefix to prepend to each outgoing RPC method path, e.g. `/public`.
 
     Returns:
         A gRPC channel.
@@ -29,6 +37,8 @@ def open_channel(url: str, auth_token: str | None = None) -> Channel:
     interceptors: list[ClientInterceptor] = []
     if auth_token is not None:
         interceptors = [_AuthMetadataInterceptor(auth_token), *interceptors]  # add auth interceptor as the first one
+    if rpc_method_prefix is not None:
+        interceptors = [*interceptors, _RpcMethodPrefixInterceptor(rpc_method_prefix)]
 
     return _open_channel(channel_info, interceptors)
 
@@ -78,3 +88,18 @@ async def intercept_unary_unary(
         request: RequestType,
     ) -> UnaryUnaryCall:
         return await continuation(add_metadata(client_call_details, [self._auth]), request)
+
+
+class _RpcMethodPrefixInterceptor(UnaryUnaryClientInterceptor):
+    def __init__(self, prefix: str) -> None:
+        """A gRPC channel interceptor which prefixes every outgoing RPC method path."""
+        super().__init__()
+        self._prefix = prefix
+
+    async def intercept_unary_unary(
+        self,
+        continuation: Callable[[ClientCallDetails, RequestType], UnaryUnaryCall],
+        client_call_details: ClientCallDetails,
+        request: RequestType,
+    ) -> UnaryUnaryCall:
+        return await continuation(update_method(client_call_details, self._prefix), request)

tilebox-grpc/_tilebox/grpc/channel.py

@@ -61,13 +61,14 @@ class ChannelInfo:
     """The protocol to use for the channel."""
 
 
-def open_channel(url: str, auth_token: str | None = None) -> Channel:
+def open_channel(url: str, auth_token: str | None = None, rpc_method_prefix: str | None = None) -> Channel:
     """Open a sync gRPC channel to the given URL.
 
     Args:
         url: The URL to open a channel to. Depending on the URL, the channel will be a secure (SSL) or insecure channel.
         auth_token: Authentication token for the channel. If set, an interceptor channel will be created which adds
             the given token as metadata to each request.
+        rpc_method_prefix: Optional prefix to prepend to each outgoing RPC method path, e.g. `/public`.
 
     Returns:
         A sync gRPC channel.
@@ -76,6 +77,8 @@ def open_channel(url: str, auth_token: str | None = None) -> Channel:
     interceptors: list[UnaryUnaryClientInterceptor] = []
     if auth_token is not None:
         interceptors = [_AuthMetadataInterceptor(auth_token), *interceptors]  # add auth interceptor as the first one
+    if rpc_method_prefix is not None:
+        interceptors = [*interceptors, _RpcMethodPrefixInterceptor(rpc_method_prefix)]
 
     return intercept_channel(_open_channel(channel_info), *interceptors)
 
@@ -165,15 +168,63 @@ def intercept_unary_unary(
         return continuation(add_metadata(client_call_details, [self._auth]), request)
 
 
+class _RpcMethodPrefixInterceptor(UnaryUnaryClientInterceptor):
+    def __init__(self, prefix: str) -> None:
+        """A sync gRPC channel interceptor which prefixes every outgoing RPC method path."""
+        super().__init__()
+        self._prefix = prefix
+
+    def intercept_unary_unary(
+        self,
+        continuation: Callable[[ClientCallDetails, RequestType], ResponseType],
+        client_call_details: ClientCallDetails,
+        request: RequestType,
+    ) -> ResponseType:
+        return continuation(update_method(client_call_details, self._prefix), request)
+
+
 def add_metadata(
     client_call_details: ClientCallDetails, additional_metadata: list[tuple[str, str]]
 ) -> ClientCallDetails:
     metadata = [] if client_call_details.metadata is None else list(client_call_details.metadata)
     metadata.extend(additional_metadata)
+    return _replace_call_details(client_call_details, metadata=metadata)
+
+
+def update_method(client_call_details: ClientCallDetails, prefix: str) -> ClientCallDetails:
+    return _replace_call_details(client_call_details, method=prefix_rpc_method(client_call_details.method, prefix))
+
+
+def prefix_rpc_method(method: str | bytes, prefix: str) -> str | bytes:
+    normalized_prefix = prefix.strip("/")
+    if normalized_prefix == "":
+        return method
+
+    if isinstance(method, bytes):
+        prefix_bytes = f"/{normalized_prefix}".encode()
+        normalized_method = method if method.startswith(b"/") else b"/" + method
+        if normalized_method == prefix_bytes or normalized_method.startswith(prefix_bytes + b"/"):
+            return normalized_method
+        return prefix_bytes + normalized_method
+
+    prefix = f"/{normalized_prefix}"
+    normalized_method = method if method.startswith("/") else f"/{method}"
+    if normalized_method == prefix or normalized_method.startswith(f"{prefix}/"):
+        return normalized_method
+
+    return f"{prefix}{normalized_method}"
+
+
+def _replace_call_details(
+    client_call_details: ClientCallDetails,
+    *,
+    method: str | bytes | None = None,
+    metadata: list[tuple[str, str]] | None = None,
+) -> ClientCallDetails:
     return ClientCallDetails(
-        client_call_details.method,
+        client_call_details.method if method is None else method,
         client_call_details.timeout,
-        metadata,
+        client_call_details.metadata if metadata is None else metadata,
         client_call_details.credentials,
         client_call_details.wait_for_ready,
     )

tilebox-grpc/_tilebox/grpc/error.py

@@ -5,6 +5,7 @@
 from collections.abc import Callable, Coroutine
 from typing import Any, Protocol, TypeVar, cast
 
+from _tilebox.grpc.public import _PUBLIC_RPC_METHOD_PREFIX
 from grpc import RpcError, StatusCode
 from grpc.aio import AioRpcError
 
@@ -37,6 +38,10 @@ class InternalServerError(KeyError):
     """InternalServerError indicates that an unexpected error happened on the server side"""
 
 
+class InvalidRequestError(IOError):
+    """"""
+
+
 Stub = TypeVar("Stub")
 
 
@@ -61,14 +66,22 @@ def with_pythonic_errors(stub: Stub, async_funcs: bool = False) -> Stub:
     return stub
 
 
+class RPCState(Protocol):
+    @property
+    def method(self) -> str: ...
+
+
 class AnyRpcError(Protocol):
     """Protocol for gRPC errors that works for both sync and async gRPC."""
 
     def code(self) -> StatusCode: ...
     def details(self) -> str: ...
 
+    @property
+    def args(self) -> tuple[RPCState, ...]: ...
+
 
-def translate_rpc_error(err: AnyRpcError) -> BaseException:  # noqa: PLR0911, C901
+def translate_rpc_error(err: AnyRpcError) -> BaseException:  # noqa: PLR0911, PLR0912, C901
     # translate specific error codes to more pythonic errors
 
     # https://grpc.io/docs/guides/error/
@@ -100,8 +113,24 @@ def translate_rpc_error(err: AnyRpcError) -> BaseException:  # noqa: PLR0911, C9
             # Client application cancelled the request
             return KeyboardInterrupt(f"Request canceled by user: {err.details()}")
         case StatusCode.UNIMPLEMENTED:
-            # Method not found on server
-            return NotImplementedError(err.details())
+            # Method not found on server, either due to a mismatch in Client / server version
+            # or because no token was provided and the given method is not part of the /public/ prefix
+            # so let's check which one it is
+
+            if len(err.args) >= 1:
+                method = err.args[0].method
+                if method.startswith(_PUBLIC_RPC_METHOD_PREFIX):
+                    action = method.rsplit("/", maxsplit=1)[-1]
+                    return AuthenticationError(
+                        f"{action} is only available for authenticated users. Please provide a valid API Key "
+                        f"token in your Client. Create a free account at https://console.tilebox.com"
+                    )
+                return InvalidRequestError(
+                    f"Requested URL {method} not found. Update your Tilebox Python Clients to the latest version."
+                )
+
+            # if we don't know anything else about the error, just forward the details directly
+            return InvalidRequestError(err.details())
 
     # for all other errors we raise a generic internal server error
     return InternalServerError(f"Oops, something went wrong: {err.details()}")

tilebox-grpc/_tilebox/grpc/public.py

@@ -0,0 +1 @@
+_PUBLIC_RPC_METHOD_PREFIX = "/public"