dataapp-resource-proxy 0.1.0__py3-none-any.whl

dataapp_resource_proxy/client.py

@@ -0,0 +1,1813 @@
+"""Resource Proxy client with local and platform-provided transports."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import hashlib
+import inspect
+import json as jsonlib
+import logging
+import math as mathlib
+import os
+import re
+import uuid
+from collections.abc import Mapping
+from datetime import datetime
+from time import perf_counter
+from typing import Any, Literal, Protocol
+
+import httpx
+
+from ._local_config import (
+    load_local_config,
+    load_project_config,
+    resolve_config_environment,
+)
+from .errors import ResourceProxyError
+from .handles import (
+    BrowserResource,
+    CaptchaPluginGrant,
+    CaptchaTask,
+    ProxyResource,
+    _datetime,
+    _optional_text,
+    _required_text,
+)
+
+logger = logging.getLogger(__name__)
+_CAPTCHA_TASKS = "/v1/captcha/tasks"
+_CAPTCHA_TASK_ID = re.compile(r"^cap_[a-f0-9]{32}$")
+_CAPTCHA_POLL_SECONDS = 3
+_MODEL_CHAT_COMPLETIONS = "/v1/model-proxy/chat/completions"
+# The server permits up to 600 seconds and the TLS gateway allows another five.
+_MODEL_READ_TIMEOUT_SECONDS = 605
+_MIN_CAPTCHA_IMAGE_BASE64_CHARS = 136
+_MAX_CAPTCHA_IMAGE_BASE64_CHARS = 66_668
+_RESOURCE_PATH = re.compile(r"^(/v1/(?:ip-proxy/leases|aws-proxy/browser-sessions))/[^/]+")
+_ACCESS_PROFILES = {
+    "bazhuayu_pre": ("bazhuayu_pre", None),
+    "bazhuayu_overseas_pre": ("bazhuayu_pre", "overseas"),
+    "bazhuayu": ("bazhuayu", None),
+    "bazhuayu_overseas": ("bazhuayu", "overseas"),
+    "octoparse_pre": ("octoparse_pre", None),
+    "octoparse": ("octoparse", None),
+}
+_VERIFIED_PRE_NODE_URLS = {
+    "bazhuayu_pre": {
+        "domestic": "https://pre-resource-proxy.bazhuayu.com:443",
+        "overseas": "https://pre-resource-proxy-overseas.bazhuayu.com:443",
+    },
+    "octoparse_pre": {
+        "domestic": "https://pre-resource-proxy.bazhuayu.com:443",
+        "overseas": "https://pre-resource-proxy-overseas.bazhuayu.com:443",
+    },
+}
+_API_KEYS_URLS = {
+    "bazhuayu_pre": "https://pre.bazhuayu.com/console/account-center/api-keys",
+    "bazhuayu": "https://www.bazhuayu.com/console/account-center/api-keys",
+    "octoparse_pre": "https://pre.octoparse.com/console/account-center/api-keys",
+    "octoparse": "https://www.octoparse.com/console/account-center/api-keys",
+}
+_BILLING_ROUTE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+_EXECUTION_ID = re.compile(r"^[A-Za-z0-9_-]{1,96}$")
+_SAFE_ERROR_CODE = re.compile(r"^[a-z][a-z0-9-]{0,79}$")
+_DEFAULT_REGIONAL_READ_TIMEOUT_SECONDS = 10.0
+_MAX_REGIONAL_READ_TIMEOUT_SECONDS = 30.0
+_CATALOG_CACHE_SECONDS = 30.0
+_CATALOG_CACHE_MAX_ENTRIES = 64
+_CAPTCHA_BILLING_TYPE = re.compile(r"^[a-z][a-z0-9_]{0,63}$")
+
+# These are navigation hints for common crawler use cases. They are deliberately
+# small and never substitute for the Resource Proxy's authoritative catalog.
+_POPULAR_PROXY_COUNTRY_HINTS = (
+    {"code": "CN", "name": "China"},
+    {"code": "US", "name": "United States"},
+    {"code": "GB", "name": "United Kingdom"},
+    {"code": "JP", "name": "Japan"},
+    {"code": "SG", "name": "Singapore"},
+)
+
+
+def _captcha_directory(value: Mapping[str, Any]) -> dict[str, Any]:
+    """Validate and defensively apply Billing's effective CAPTCHA allow-list."""
+    pricing_version = value.get("pricing_version")
+    raw_available = value.get("available_billing_types")
+    raw_types = value.get("types")
+    if (
+        not isinstance(value.get("version"), str)
+        or not value["version"].strip()
+        or not isinstance(pricing_version, str)
+        or not pricing_version.strip()
+        or not isinstance(raw_available, list)
+        or any(
+            not isinstance(item, str) or not _CAPTCHA_BILLING_TYPE.fullmatch(item)
+            for item in raw_available
+        )
+        or len(set(raw_available)) != len(raw_available)
+        or not isinstance(raw_types, list)
+    ):
+        raise ResourceProxyError("resource service returned an invalid CAPTCHA directory")
+
+    available = set(raw_available)
+    filtered_types: list[dict[str, Any]] = []
+    for raw_entry in raw_types:
+        if (
+            not isinstance(raw_entry, dict)
+            or not isinstance(raw_entry.get("id"), str)
+            or not isinstance(raw_entry.get("variants"), list)
+        ):
+            raise ResourceProxyError("resource service returned an invalid CAPTCHA directory")
+        entry = copy.deepcopy(raw_entry)
+        variants: list[dict[str, Any]] = []
+        for variant in entry["variants"]:
+            if not isinstance(variant, dict):
+                raise ResourceProxyError(
+                    "resource service returned an invalid CAPTCHA directory"
+                )
+            billing_type = variant.get("billing_type")
+            overrides = variant.get("billing_type_overrides", [])
+            if (
+                not isinstance(billing_type, str)
+                or not _CAPTCHA_BILLING_TYPE.fullmatch(billing_type)
+                or not isinstance(overrides, list)
+                or any(
+                    not isinstance(override, dict)
+                    or not isinstance(override.get("billing_type"), str)
+                    or not _CAPTCHA_BILLING_TYPE.fullmatch(override["billing_type"])
+                    or not isinstance(override.get("parameter"), str)
+                    or "equals" not in override
+                    for override in overrides
+                )
+            ):
+                raise ResourceProxyError(
+                    "resource service returned an invalid CAPTCHA directory"
+                )
+            if billing_type not in available:
+                continue
+            unavailable = [
+                item for item in overrides if item["billing_type"] not in available
+            ]
+            safe: dict[str, Any] = copy.deepcopy(variant)
+            supported = True
+            for override in unavailable:
+                parameter = override.get("parameter")
+                equals = override.get("equals")
+                properties = safe.get("properties")
+                required = safe.get("required", [])
+                one_of_required = safe.get("one_of_required", [])
+                if (
+                    not isinstance(parameter, str)
+                    or not isinstance(properties, dict)
+                    or parameter not in properties
+                    or not isinstance(required, list)
+                    or parameter in required
+                    or not isinstance(one_of_required, list)
+                    or any(
+                        not isinstance(group, list) or parameter in group
+                        for group in one_of_required
+                    )
+                    or not isinstance(properties[parameter], dict)
+                ):
+                    supported = False
+                    break
+                spec = properties[parameter]
+                enum = spec.get("enum")
+                if isinstance(enum, list):
+                    allowed_values = [item for item in enum if item != equals]
+                    if not allowed_values:
+                        supported = False
+                        break
+                    spec["enum"] = allowed_values
+                elif spec.get("type") == "boolean" and isinstance(equals, bool):
+                    spec["enum"] = [not equals]
+                elif any(
+                    item.get("parameter") == parameter
+                    and item["billing_type"] in available
+                    for item in overrides
+                ):
+                    supported = False
+                    break
+                else:
+                    properties.pop(parameter)
+                    if isinstance(safe.get("example"), dict):
+                        safe["example"].pop(parameter, None)
+            if not supported:
+                continue
+            safe["billing_type_overrides"] = [
+                item for item in overrides if item["billing_type"] in available
+            ]
+            if not safe["billing_type_overrides"]:
+                safe.pop("billing_type_overrides")
+            variants.append(safe)
+        if not variants:
+            continue
+        entry["variants"] = variants
+        default_variant = entry.get("default_variant")
+        if default_variant is not None and not any(
+            default_variant in {variant.get("id"), variant.get("variant_id")}
+            for variant in variants
+        ):
+            entry.pop("default_variant", None)
+        filtered_types.append(entry)
+
+    result = copy.deepcopy(dict(value))
+    result["types"] = filtered_types
+    return result
+
+
+class ResourceTransport(Protocol):
+    """Authenticated transport used by platform and local clients."""
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Mapping[str, Any]: ...
+
+    async def close(self) -> None: ...
+
+
+class _HttpTransport:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        timeout: float = 30,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._transport = transport
+        self._timeout = timeout
+        self._http = self._new_client()
+
+    def _new_client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            base_url=self._base_url, transport=self._transport, timeout=self._timeout
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Mapping[str, Any]:
+        request_headers = {"Authorization": f"Bearer {self._api_key}"}
+        request_headers.update(headers or {})
+        timeout = self._http.timeout
+        if path == _MODEL_CHAT_COMPLETIONS:
+            timeout = httpx.Timeout(self._timeout, read=_MODEL_READ_TIMEOUT_SECONDS)
+        if self._http.is_closed:
+            # Receipt reads can outlive the execution and its HTTP connection pool.
+            async with self._new_client() as client:
+                response = await client.request(
+                    method, path, json=json, headers=request_headers, timeout=timeout,
+                )
+        else:
+            response = await self._http.request(
+                method, path, json=json, headers=request_headers, timeout=timeout,
+            )
+        return _decode_response(response)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+
+class _ExecutionTransport:
+    def __init__(self, transport: ResourceTransport, token: str) -> None:
+        self._transport = transport
+        self._token = token
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Mapping[str, Any]:
+        request_headers = {"Authorization": f"Bearer {self._token}"}
+        request_headers.update(headers or {})
+        return await self._transport.request(
+            method, path, json=json, headers=request_headers
+        )
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+
+class ResourceProxy:
+    """Own managed resources within one local or platform execution."""
+
+    def __init__(
+        self,
+        transport: ResourceTransport,
+        *,
+        owns_transport: bool = False,
+        requires_execution_token: bool = False,
+        heartbeat_interval: float = 30,
+        app_id: str | None = None,
+        app_version: str | None = None,
+        environment: str | None = None,
+        network: str = "domestic",
+        regional_mode: bool = False,
+        regional_read_timeout: float = _DEFAULT_REGIONAL_READ_TIMEOUT_SECONDS,
+    ) -> None:
+        if heartbeat_interval <= 0:
+            raise ValueError("heartbeat_interval must be positive")
+        self._regional_read_timeout = _validate_regional_read_timeout(
+            regional_read_timeout
+        )
+        self._transport = transport
+        self._owns_transport = owns_transport
+        self._requires_execution_token = requires_execution_token
+        self._heartbeat_interval = heartbeat_interval
+        self._app_id = app_id
+        self._app_version = app_version
+        self._environment = environment
+        self._network = network
+        self._regional_mode = regional_mode
+        self._billing_route_id: str | None = None
+        self._regional_clients: dict[str, ResourceProxy] = {}
+        self.execution_id: str | None = None
+        self.expires_at: datetime | None = None
+        self._resources: dict[int, Any] = {}
+        self._heartbeat_task: asyncio.Task[None] | None = None
+        self._operation_lock = asyncio.Lock()
+        self._start_lock = asyncio.Lock()
+        self._closed = False
+        self._local_transport: _HttpTransport | None = None
+        self._managed_billing_enabled = False
+        self._managed_billing_warned = False
+        self._catalog_cache: dict[tuple[Any, ...], tuple[float, dict[str, Any]]] = {}
+        self._captcha_task_networks: dict[str, str] = {}
+
+    def __repr__(self) -> str:
+        networks = tuple([self._network, *self._regional_clients])
+        return (
+            f"ResourceProxy(execution_id={self.execution_id!r}, "
+            f"environment={self._environment!r}, networks={networks!r})"
+        )
+
+    @classmethod
+    def from_env(
+        cls,
+        environ: Mapping[str, str] | None = None,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        heartbeat_interval: float = 30,
+        regional_read_timeout: float | None = None,
+    ) -> ResourceProxy:
+        supplied = os.environ if environ is None else environ
+        project = load_project_config(supplied)
+        environment = resolve_config_environment(supplied, project)
+        has_process_key = bool(
+            supplied.get("DATAAPP_API_KEY") or supplied.get("DATAOS_API_KEY")
+        )
+        stored = (
+            {}
+            if has_process_key
+            else load_local_config(supplied, environment=environment)
+        )
+        env = {**stored, **supplied}
+        if supplied.get("DATAOS_API_KEY") and not supplied.get("DATAAPP_API_KEY"):
+            # An explicit process value outranks the per-user file even when it
+            # uses the compatibility name.
+            env["DATAAPP_API_KEY"] = supplied["DATAOS_API_KEY"]
+            env.pop("DATAOS_API_KEY", None)
+        configured_read_timeout = _configured_regional_read_timeout(
+            env, regional_read_timeout
+        )
+        legacy_url = env.get("DATAOS_RESOURCE_PROXY_URL") or None
+        domestic_url = env.get("DATAOS_RESOURCE_PROXY_DOMESTIC_URL") or None
+        overseas_url = env.get("DATAOS_RESOURCE_PROXY_OVERSEAS_URL") or None
+        new_environment = env.get("DATAAPP_ENVIRONMENT") or None
+        old_environment = env.get("DATAOS_ENVIRONMENT") or None
+        if new_environment and old_environment and new_environment != old_environment:
+            raise ResourceProxyError(
+                "DATAAPP_ENVIRONMENT conflicts with deprecated DATAOS_ENVIRONMENT",
+                code="configuration-error",
+            )
+        access_profile = new_environment or old_environment
+        if access_profile is not None and access_profile not in _ACCESS_PROFILES:
+            raise ResourceProxyError(
+                "DATAAPP_ENVIRONMENT must be bazhuayu_pre, bazhuayu_overseas_pre, "
+                "bazhuayu, bazhuayu_overseas, octoparse_pre, or octoparse",
+                code="configuration-error",
+            )
+        profile_environment, preferred_network = (
+            _ACCESS_PROFILES[access_profile]
+            if access_profile is not None
+            else (None, None)
+        )
+        if profile_environment is not None and profile_environment != environment:
+            raise ResourceProxyError(
+                "DATAAPP_ENVIRONMENT conflicts with the downloaded project environment",
+                code="configuration-error",
+            )
+        new_api_key = env.get("DATAAPP_API_KEY")
+        old_api_key = env.get("DATAOS_API_KEY")
+        if new_api_key and old_api_key and new_api_key.strip() != old_api_key.strip():
+            raise ResourceProxyError(
+                "DATAAPP_API_KEY conflicts with deprecated DATAOS_API_KEY",
+                code="configuration-error",
+            )
+        api_key = new_api_key or old_api_key
+        if project is not None:
+            expected_domestic = project.domestic_url.rstrip("/")
+            expected_overseas = project.overseas_url.rstrip("/")
+            if legacy_url and legacy_url.rstrip("/") != expected_domestic:
+                raise ResourceProxyError(
+                    "DATAOS_RESOURCE_PROXY_URL conflicts with the downloaded project environment",
+                    code="configuration-error",
+                )
+            if domestic_url and domestic_url.rstrip("/") != expected_domestic:
+                raise ResourceProxyError(
+                    "DATAOS_RESOURCE_PROXY_DOMESTIC_URL conflicts with the downloaded "
+                    "project environment",
+                    code="configuration-error",
+                )
+            if overseas_url and overseas_url.rstrip("/") != expected_overseas:
+                raise ResourceProxyError(
+                    "DATAOS_RESOURCE_PROXY_OVERSEAS_URL conflicts with the downloaded "
+                    "project environment",
+                    code="configuration-error",
+                )
+            domestic_url = project.domestic_url
+            overseas_url = project.overseas_url
+        if not legacy_url and not domestic_url and not overseas_url:
+            verified = _VERIFIED_PRE_NODE_URLS.get(environment or "")
+            if verified is not None:
+                if preferred_network == "overseas":
+                    overseas_url = verified["overseas"]
+                else:
+                    domestic_url = verified["domestic"]
+                    overseas_url = verified["overseas"]
+            elif environment in {"bazhuayu", "octoparse"}:
+                raise ResourceProxyError(
+                    "production local debug requires an explicit Resource Proxy URL",
+                    code="configuration-error",
+                )
+        if (
+            legacy_url
+            and domestic_url
+            and legacy_url.rstrip("/") != domestic_url.rstrip("/")
+        ):
+            raise ResourceProxyError(
+                "DATAOS_RESOURCE_PROXY_URL conflicts with DATAOS_RESOURCE_PROXY_DOMESTIC_URL",
+                code="configuration-error",
+            )
+        regional = bool(domestic_url or overseas_url)
+        base_url = domestic_url or legacy_url
+        base_network = preferred_network or "domestic"
+        if domestic_url is not None:
+            base_network = "domestic"
+        if base_url is None and overseas_url is not None:
+            base_url = overseas_url
+            base_network = "overseas"
+        if not api_key or not api_key.strip():
+            api_keys_url = (
+                project.api_keys_url
+                if project is not None
+                else _API_KEYS_URLS.get(environment or "")
+            )
+            account_center = (
+                f" Get a Key from {api_keys_url}." if api_keys_url is not None else ""
+            )
+            raise ResourceProxyError(
+                "DATAAPP_API_KEY is required for local managed resources. Managed IP "
+                "traffic and CAPTCHA solves accrue resource costs. After confirming use, "
+                "run `python -m dataapp_resource_proxy configure`; it securely prompts for "
+                f"the Key and stores it outside the project.{account_center} "
+                "Platform Runs use injected run identity and do not need this Key.",
+                code="configuration-error",
+            )
+        if not base_url:
+            raise ResourceProxyError(
+                "a Resource Proxy URL is required; use a downloaded project with "
+                ".dataapp-sdk.json or set an explicit environment and URL. "
+                "No pre environment is selected implicitly.",
+                code="configuration-error",
+            )
+        local_transport = _HttpTransport(base_url, api_key, transport=transport)
+        client = cls(
+            local_transport,
+            owns_transport=True,
+            requires_execution_token=True,
+            heartbeat_interval=heartbeat_interval,
+            app_id=env.get("DATAOS_APP_ID") or None,
+            app_version=env.get("DATAOS_APP_VERSION") or None,
+            environment=environment,
+            network=base_network,
+            regional_mode=regional,
+            regional_read_timeout=configured_read_timeout,
+        )
+        client._local_transport = local_transport
+        if overseas_url and base_network != "overseas":
+            overseas_transport = _HttpTransport(overseas_url, api_key, transport=transport)
+            overseas = cls(
+                overseas_transport,
+                owns_transport=True,
+                requires_execution_token=True,
+                heartbeat_interval=heartbeat_interval,
+                app_id=env.get("DATAOS_APP_ID") or None,
+                app_version=env.get("DATAOS_APP_VERSION") or None,
+                environment=environment,
+                network="overseas",
+                regional_read_timeout=configured_read_timeout,
+            )
+            overseas._local_transport = overseas_transport
+            client._regional_clients["overseas"] = overseas
+        return client
+
+    async def __aenter__(self) -> ResourceProxy:
+        try:
+            # Regional clients create only the execution needed by the first
+            # operation. Explicit start() starts this client's configured node.
+            return self if self._regional_mode else await self.start()
+        except BaseException as error:
+            if self._owns_transport:
+                try:
+                    await self._transport.close()
+                    self._closed = True
+                except BaseException:
+                    error.add_note("resource transport cleanup also failed")
+            raise
+
+    @property
+    def environment(self) -> str | None:
+        """Account and Billing environment bound by the resource service."""
+        return self._environment
+
+    @property
+    def billing_route_id(self) -> str | None:
+        """Server-owned Billing route identifier for the current execution."""
+        return self._billing_route_id
+
+    @property
+    def network(self) -> str:
+        """Resource node network used by this execution."""
+        return self._network
+
+    @property
+    def regional_read_timeout(self) -> float:
+        """Validated per-node deadline for regional receipt and usage reads."""
+        return self._regional_read_timeout
+
+    async def start(self) -> ResourceProxy:
+        """Create the execution lazily and start its heartbeat."""
+        async with self._start_lock:
+            if self._closed:
+                raise RuntimeError("resource client is closed")
+            if self.execution_id is None:
+                value = await self._request(
+                    "POST",
+                    "/v1/executions",
+                    json={
+                        **({"app_id": self._app_id} if self._app_id is not None else {}),
+                        **(
+                            {"app_version": self._app_version}
+                            if self._app_version is not None
+                            else {}
+                        ),
+                        **(
+                            {"environment": self._environment}
+                            if self._environment is not None
+                            else {}
+                        ),
+                    },
+                    authenticated=False,
+                )
+                execution_id = _required_text(value, "execution_id")
+                expires_at = _datetime(value.get("expires_at"))
+                token = value.get("token")
+                if token is None and self._requires_execution_token:
+                    raise ValueError("resource service returned no execution token")
+                if token is not None and (not isinstance(token, str) or not token):
+                    raise ValueError("resource service returned invalid token")
+                execution_transport = (
+                    _ExecutionTransport(self._transport, token)
+                    if isinstance(token, str)
+                    else None
+                )
+                returned_environment = value.get("environment")
+                returned_route = value.get("billing_route_id")
+                try:
+                    if not _EXECUTION_ID.fullmatch(execution_id):
+                        raise ResourceProxyError(
+                            "resource service returned an invalid execution ID",
+                            code="invalid-response",
+                        )
+                    if self._environment is not None:
+                        if returned_environment != self._environment:
+                            raise ResourceProxyError(
+                                "resource service returned the wrong environment",
+                                code="invalid-response",
+                            )
+                        if (
+                            not isinstance(returned_route, str)
+                            or not _BILLING_ROUTE_ID.fullmatch(returned_route)
+                        ):
+                            raise ResourceProxyError(
+                                "resource service returned an invalid billing route",
+                                code="invalid-response",
+                            )
+                except (ResourceProxyError, ValueError):
+                    if execution_transport is not None and _EXECUTION_ID.fullmatch(execution_id):
+                        await self._revoke_rejected_execution(execution_transport)
+                    raise
+                if self._environment is not None:
+                    assert isinstance(returned_route, str)
+                    self._billing_route_id = returned_route
+                if execution_transport is not None:
+                    self._transport = execution_transport
+                self.execution_id = execution_id
+                self.expires_at = expires_at
+                self._managed_billing_enabled = (
+                    self._local_transport is not None
+                    and value.get("managed_billing_enabled") is True
+                )
+                self._heartbeat_task = asyncio.create_task(
+                    self._heartbeat_loop(), name="resource-proxy-heartbeat"
+                )
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        try:
+            await self.close()
+        except BaseException:
+            if exc is None:
+                raise
+            exc.add_note("managed resource cleanup also failed")
+
+    async def proxy(
+        self,
+        *,
+        country: str | None = None,
+        state: str | None = None,
+        city: str | None = None,
+        expire_time: str | None = None,
+        exit_policy: str = "renewable",
+        network_preference: str | None = None,
+        target_hint: str | None = None,
+        line_tier: str = "standard",
+        proxy_group: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ProxyResource:
+        _validate_network_preference(network_preference)
+        _validate_target_hint(target_hint)
+        _validate_line_tier(line_tier)
+        _validate_proxy_group(proxy_group)
+        if proxy_group is not None and line_tier != "standard":
+            raise ValueError("proxy_group cannot be combined with a non-default line_tier")
+        group_network = _network_for_proxy_group(proxy_group)
+        if (
+            group_network is not None
+            and network_preference not in {None, "auto", group_network}
+        ):
+            raise ValueError("proxy_group conflicts with network_preference")
+        selected_network = group_network or network_preference
+        selected = self._client_for_network(selected_network)
+        if selected is not self:
+            return await selected.proxy(
+                country=country,
+                state=state,
+                city=city,
+                expire_time=expire_time,
+                exit_policy=exit_policy,
+                network_preference=selected_network,
+                target_hint=target_hint,
+                line_tier=line_tier,
+                proxy_group=proxy_group,
+                idempotency_key=idempotency_key,
+            )
+        async with self._operation_lock:
+            await self.start()
+            body = {
+                "country": country,
+                "state": state,
+                "city": city,
+                "expire_time": expire_time,
+                "exit_policy": exit_policy,
+                "network_preference": (
+                    None if selected_network == "auto" else selected_network
+                ),
+                "target_hint": target_hint,
+                "line_tier": line_tier if line_tier != "standard" else None,
+                "proxy_group": proxy_group,
+            }
+            self._warn_managed_billing()
+            value = await self._request(
+                "POST",
+                "/v1/ip-proxy/leases",
+                json={key: item for key, item in body.items() if item is not None},
+                headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())},
+            )
+            lease_id = _required_text(value, "lease_id")
+            if any(
+                isinstance(existing, ProxyResource) and existing.lease_id == lease_id
+                for existing in self._resources.values()
+            ):
+                raise ResourceProxyError(
+                    "proxy lease already has a live handle",
+                    code="duplicate-proxy-handle",
+                )
+            handle = ProxyResource(
+                client=self,
+                lease_id=lease_id,
+                proxy_url=_required_text(value, "proxy_url"),
+                expires_at=_datetime(value.get("expires_at")),
+                credential_generation=(
+                    int(value["credential_generation"])
+                    if value.get("credential_generation") is not None
+                    else None
+                ),
+                network=_optional_text(value.get("network")),
+                node_id=_optional_text(value.get("node_id")),
+                line_tier=_optional_text(value.get("line_tier")),
+                proxy_group=_optional_text(value.get("proxy_group")),
+                supplier_code=_optional_text(value.get("supplier_code")),
+                supplier_route_id=_optional_text(value.get("supplier_route_id")),
+                supplier_account_ref=_optional_text(value.get("supplier_account_ref")),
+                line_policy_version=_optional_text(value.get("line_policy_version")),
+            )
+            self._resources[id(handle)] = handle
+            return handle
+
+    @staticmethod
+    def proxy_location_hints() -> dict[str, Any]:
+        """Return non-authoritative popular country hints for a selection UI or AI agent.
+
+        Call :meth:`proxy_locations` before presenting a location as currently
+        supported. Hints are not inventory and intentionally contain no cities.
+        """
+
+        return {
+            "level": "country",
+            "items": copy.deepcopy(list(_POPULAR_PROXY_COUNTRY_HINTS)),
+            "authoritative": False,
+            "coverage_only": True,
+        }
+
+    async def proxy_groups(
+        self,
+        *,
+        network_preference: str | None = None,
+        refresh: bool = False,
+    ) -> dict[str, Any]:
+        """Return product groups exposed by the selected Resource Proxy node.
+
+        The result describes configured coverage, not live proxy inventory.
+        ``refresh=True`` bypasses the SDK's short-lived response cache.
+        """
+
+        _validate_network_preference(network_preference)
+        selected = self._client_for_network(network_preference)
+        if selected is not self:
+            return await selected.proxy_groups(
+                network_preference=network_preference, refresh=refresh
+            )
+        network = self._network if network_preference in {None, "auto"} else network_preference
+        body = {"network_preference": network}
+        return await self._catalog_query(
+            "/v1/ip-proxy/groups/query",
+            body,
+            cache_key=("groups", network),
+            refresh=refresh,
+        )
+
+    async def proxy_locations(
+        self,
+        *,
+        proxy_group: str = "auto",
+        country: str | None = None,
+        state: str | None = None,
+        expire_time: str | None = None,
+        network_preference: str | None = None,
+        offset: int = 0,
+        limit: int = 200,
+        refresh: bool = False,
+    ) -> dict[str, Any]:
+        """Query the authoritative location catalog for one proxy product group.
+
+        Catalog membership means that at least one configured route covers the
+        location. A later lease request can still fail when a supplier has no
+        temporary inventory.
+        """
+
+        _validate_proxy_group(proxy_group)
+        _validate_network_preference(network_preference)
+        if state is not None and country is None:
+            raise ValueError("state requires country")
+        normalized_country = _normalize_country(country)
+        normalized_state = _optional_catalog_code(state, "state")
+        if expire_time is not None and (
+            not isinstance(expire_time, str) or not 1 <= len(expire_time) <= 24
+        ):
+            raise ValueError("expire_time must contain 1-24 characters")
+        if (
+            isinstance(offset, bool)
+            or not isinstance(offset, int)
+            or not 0 <= offset <= 1_000_000
+        ):
+            raise ValueError("offset must be between 0 and 1000000")
+        if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 200:
+            raise ValueError("limit must be between 1 and 200")
+        group_network = _network_for_proxy_group(proxy_group)
+        if (
+            group_network is not None
+            and network_preference not in {None, "auto", group_network}
+        ):
+            raise ValueError("proxy_group conflicts with network_preference")
+        selected_network = group_network or network_preference
+        selected = self._client_for_network(selected_network)
+        if selected is not self:
+            return await selected.proxy_locations(
+                proxy_group=proxy_group,
+                country=normalized_country,
+                state=normalized_state,
+                expire_time=expire_time,
+                network_preference=selected_network,
+                offset=offset,
+                limit=limit,
+                refresh=refresh,
+            )
+        network = self._network if selected_network in {None, "auto"} else selected_network
+        body = {
+            "proxy_group": proxy_group,
+            "network_preference": network,
+            "country": normalized_country,
+            "state": normalized_state,
+            "expire_time": expire_time,
+            "offset": offset,
+            "limit": limit,
+        }
+        clean_body = {key: value for key, value in body.items() if value is not None}
+        return await self._catalog_query(
+            "/v1/ip-proxy/locations/query",
+            clean_body,
+            cache_key=(
+                "locations", network, proxy_group, normalized_country, normalized_state,
+                expire_time, offset, limit,
+            ),
+            refresh=refresh,
+        )
+
+    async def _catalog_query(
+        self,
+        path: str,
+        body: Mapping[str, Any],
+        *,
+        cache_key: tuple[Any, ...],
+        refresh: bool,
+    ) -> dict[str, Any]:
+        now = perf_counter()
+        cached = self._catalog_cache.get(cache_key)
+        if not refresh and cached is not None and now - cached[0] <= _CATALOG_CACHE_SECONDS:
+            return copy.deepcopy(cached[1])
+        async with self._operation_lock:
+            now = perf_counter()
+            cached = self._catalog_cache.get(cache_key)
+            if not refresh and cached is not None and now - cached[0] <= _CATALOG_CACHE_SECONDS:
+                return copy.deepcopy(cached[1])
+            await self.start()
+            value = await self._request("POST", path, json=body)
+            if path == "/v1/captcha/types/query":
+                value = _captcha_directory(value)
+            else:
+                _validate_catalog_response(value, locations=path.endswith("/locations/query"))
+            if len(self._catalog_cache) >= _CATALOG_CACHE_MAX_ENTRIES:
+                oldest = min(self._catalog_cache, key=lambda key: self._catalog_cache[key][0])
+                self._catalog_cache.pop(oldest, None)
+            stored = copy.deepcopy(value)
+            self._catalog_cache[cache_key] = (perf_counter(), stored)
+            return copy.deepcopy(stored)
+
+    async def browser(
+        self,
+        *,
+        region: str | None = None,
+        browser_identifier: str | None = None,
+        session_timeout: int = 900,
+        viewport: tuple[int, int] | None = None,
+        slot_id: str | None = None,
+        network_preference: str | None = None,
+        target_hint: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> BrowserResource:
+        _validate_network_preference(network_preference)
+        _validate_target_hint(target_hint)
+        selected = self._client_for_network(network_preference)
+        if selected is not self:
+            return await selected.browser(
+                region=region,
+                browser_identifier=browser_identifier,
+                session_timeout=session_timeout,
+                viewport=viewport,
+                slot_id=slot_id,
+                network_preference=network_preference,
+                target_hint=target_hint,
+                idempotency_key=idempotency_key,
+            )
+        async with self._operation_lock:
+            await self.start()
+            create_key = idempotency_key or str(uuid.uuid4())
+            body: dict[str, Any] = {"session_timeout_seconds": session_timeout}
+            body["slot_id"] = slot_id or (
+                "slot_" + hashlib.sha256(create_key.encode()).hexdigest()[:32]
+            )
+            if region is not None:
+                body["region"] = region
+            if browser_identifier is not None:
+                body["browser_identifier"] = browser_identifier
+            if viewport is not None:
+                body["viewport"] = {"width": viewport[0], "height": viewport[1]}
+            if network_preference not in {None, "auto"}:
+                body["network_preference"] = network_preference
+            if target_hint is not None:
+                body["target_hint"] = target_hint
+            value = await self._request(
+                "POST",
+                "/v1/aws-proxy/browser-sessions",
+                json=body,
+                headers={"Idempotency-Key": create_key},
+            )
+            resource_id = _required_text(value, "resource_id")
+            if any(
+                isinstance(existing, BrowserResource)
+                and existing.resource_id == resource_id
+                for existing in self._resources.values()
+            ):
+                raise ResourceProxyError(
+                    "browser session already has a live handle",
+                    code="duplicate-browser-handle",
+                )
+            status = str(value.get("status") or "ACTIVE")
+            if status.upper() not in {"ACTIVE", "READY"}:
+                raise ResourceProxyError(
+                    "browser session is not active", code="browser-unavailable"
+                )
+            handle = BrowserResource(
+                client=self,
+                resource_id=resource_id,
+                status=status,
+                session_deadline=_datetime(
+                    value.get("session_deadline") or value.get("expires_at")
+                ),
+                network=_optional_text(value.get("network")),
+                node_id=_optional_text(value.get("node_id")),
+            )
+            self._resources[id(handle)] = handle
+            return handle
+
+    async def captcha_types(
+        self, *, type: str | None = None, network_preference: str | None = "overseas",
+        refresh: bool = False,
+    ) -> dict[str, Any]:
+        """Query supported task parameters without starting or charging a solver.
+
+        The directory contains only variants whose Billing classifications have
+        effective supplier-cost quotes at ``pricing_version``. Use the returned
+        parameters for ``solve_captcha``. Results are briefly cached guidance;
+        Resource Proxy rechecks availability when a task is submitted.
+        """
+        _validate_network_preference(network_preference)
+        selected = self._client_for_network(network_preference)
+        if selected is not self:
+            return await selected.captcha_types(
+                type=type, network_preference=network_preference, refresh=refresh,
+            )
+        body = {"type": type} if type is not None else {}
+        return await self._catalog_query(
+            "/v1/captcha/types/query", body,
+            cache_key=("captcha_types", type, self._network), refresh=refresh,
+        )
+
+    async def create_captcha_task(
+        self,
+        *,
+        type: str,
+        parameters: dict[str, Any] | None = None,
+        task_variant: str | None = None,
+        website_url: str | None = None,
+        website_key: str | None = None,
+        action: str | None = None,
+        data: str | None = None,
+        page_data: str | None = None,
+        user_agent: str | None = None,
+        api_js_url: str | None = None,
+        data_s: str | None = None,
+        enterprise_s: str | None = None,
+        image_body: str | None = None,
+        case_sensitive: bool | None = None,
+        numeric: Literal[0, 1] | None = None,
+        math: bool | None = None,
+        recognizing_threshold: int | None = None,
+        capmonster_module: str | None = None,
+        idempotency_key: str | None = None,
+        network_preference: str | None = "overseas",
+    ) -> CaptchaTask:
+        """Submit one managed CAPTCHA using the platform's solver credentials.
+
+        Query :meth:`captcha_types` for generic ``type``, ``task_variant`` and
+        vendor ``parameters``. Generic fields cannot be mixed with convenience
+        fields. Structured answers are returned as ``CaptchaTask.data``; the
+        developer applies them to the matching current browser challenge.
+        ``capmonster_module`` selects an ImageToText recognizer, not a detector.
+        """
+        _validate_network_preference(network_preference)
+        selected = self._client_for_network(network_preference)
+        if selected is not self:
+            task = await selected.create_captcha_task(
+                type=type,
+                parameters=parameters,
+                task_variant=task_variant,
+                website_url=website_url,
+                website_key=website_key,
+                action=action,
+                data=data,
+                page_data=page_data,
+                user_agent=user_agent,
+                api_js_url=api_js_url,
+                data_s=data_s,
+                enterprise_s=enterprise_s,
+                image_body=image_body,
+                case_sensitive=case_sensitive,
+                numeric=numeric,
+                math=math,
+                recognizing_threshold=recognizing_threshold,
+                capmonster_module=capmonster_module,
+                idempotency_key=idempotency_key,
+                network_preference=network_preference,
+            )
+            self._captcha_task_networks[task.task_id] = selected.network
+            return task
+        if capmonster_module is not None:
+            if type != "image_to_text":
+                raise ValueError("captcha module is only valid for image_to_text")
+            if not isinstance(capmonster_module, str) or not capmonster_module.isprintable():
+                raise ValueError("captcha module must contain printable characters only")
+            capmonster_module = capmonster_module.strip()
+            if not 1 <= len(capmonster_module) <= 128:
+                raise ValueError("captcha module must contain 1-128 characters")
+        if image_body is not None and not (
+            _MIN_CAPTCHA_IMAGE_BASE64_CHARS
+            <= len(image_body)
+            <= _MAX_CAPTCHA_IMAGE_BASE64_CHARS
+        ):
+            raise ValueError("captcha image Base64 length is outside the supported range")
+        body = {
+            "type": type,
+            "parameters": parameters,
+            "task_variant": task_variant,
+            "website_url": website_url,
+            "website_key": website_key,
+            "action": action,
+            "data": data,
+            "page_data": page_data,
+            "user_agent": user_agent,
+            "api_js_url": api_js_url,
+            "data_s": data_s,
+            "enterprise_s": enterprise_s,
+            "image_body": image_body,
+            "case_sensitive": case_sensitive,
+            "numeric": numeric,
+            "math": math,
+            "recognizing_threshold": recognizing_threshold,
+            "capmonster_module": capmonster_module,
+        }
+        if not isinstance(type, str) or not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]{0,63}", type):
+            raise ValueError("invalid CAPTCHA task type")
+        if parameters is not None:
+            if not isinstance(parameters, dict):
+                raise ValueError("CAPTCHA parameters must be an object")
+            if any(value is not None for key, value in body.items()
+                   if key not in {"type", "parameters", "task_variant"}):
+                raise ValueError("generic parameters cannot be mixed with convenience fields")
+            try:
+                encoded = jsonlib.dumps(parameters, ensure_ascii=False, allow_nan=False).encode()
+            except (ValueError, TypeError, RecursionError):
+                raise ValueError("CAPTCHA parameters must be finite JSON values") from None
+            if len(encoded) > 262_144:
+                raise ValueError("CAPTCHA parameters exceed the 256 KiB limit")
+        elif task_variant is not None:
+            raise ValueError("task_variant requires generic parameters")
+        async with self._operation_lock:
+            await self.start()
+            self._warn_managed_billing()
+            value = await self._request(
+                "POST", _CAPTCHA_TASKS,
+                json={key: item for key, item in body.items() if item is not None},
+                headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())},
+            )
+        task = _captcha_task(value)
+        self._captcha_task_networks[task.task_id] = self._network
+        return task
+
+    async def get_captcha_task(
+        self, task_id: str, *, network_preference: str | None = None
+    ) -> CaptchaTask:
+        """Read or poll a task owned by the current execution."""
+        _validate_network_preference(network_preference)
+        if not _CAPTCHA_TASK_ID.fullmatch(task_id):
+            raise ValueError("invalid captcha task identifier")
+        owner = self._captcha_task_networks.get(task_id)
+        if owner is not None and network_preference not in {None, "auto", owner}:
+            raise ValueError(
+                f"captcha task belongs to the {owner} Resource Proxy node"
+            )
+        selected_network = owner or network_preference or "overseas"
+        selected = self._client_for_network(selected_network)
+        if selected is not self:
+            task = await selected.get_captcha_task(
+                task_id, network_preference=selected_network
+            )
+            return task
+        async with self._operation_lock:
+            await self.start()
+            value = await self._request("GET", f"{_CAPTCHA_TASKS}/{task_id}")
+        task = _captcha_task(value, expected_id=task_id)
+        return task
+
+    async def solve_captcha(
+        self,
+        *,
+        type: str,
+        parameters: dict[str, Any] | None = None,
+        task_variant: str | None = None,
+        website_url: str | None = None,
+        website_key: str | None = None,
+        action: str | None = None,
+        data: str | None = None,
+        page_data: str | None = None,
+        user_agent: str | None = None,
+        api_js_url: str | None = None,
+        data_s: str | None = None,
+        enterprise_s: str | None = None,
+        image_body: str | None = None,
+        case_sensitive: bool | None = None,
+        numeric: Literal[0, 1] | None = None,
+        math: bool | None = None,
+        recognizing_threshold: int | None = None,
+        capmonster_module: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float = 120,
+        network_preference: str | None = "overseas",
+    ) -> CaptchaTask:
+        """Wait for one solver result. The caller verifies it in the browser.
+
+        Optional ``capmonster_module`` selects recognition only for image tasks.
+        """
+        _validate_network_preference(network_preference)
+        selected = self._client_for_network(network_preference)
+        if selected is not self:
+            return await selected.solve_captcha(
+                type=type,
+                parameters=parameters,
+                task_variant=task_variant,
+                website_url=website_url,
+                website_key=website_key,
+                action=action,
+                data=data,
+                page_data=page_data,
+                user_agent=user_agent,
+                api_js_url=api_js_url,
+                data_s=data_s,
+                enterprise_s=enterprise_s,
+                image_body=image_body,
+                case_sensitive=case_sensitive,
+                numeric=numeric,
+                math=math,
+                recognizing_threshold=recognizing_threshold,
+                capmonster_module=capmonster_module,
+                idempotency_key=idempotency_key,
+                timeout=timeout,
+                network_preference=network_preference,
+            )
+        if not mathlib.isfinite(timeout) or timeout <= 0:
+            raise ValueError("captcha timeout must be finite and positive")
+        try:
+            async with asyncio.timeout(timeout):
+                task = await self.create_captcha_task(
+                    type=type, parameters=parameters, task_variant=task_variant,
+                    website_url=website_url, website_key=website_key,
+                    action=action, data=data, page_data=page_data, user_agent=user_agent,
+                    api_js_url=api_js_url, data_s=data_s, enterprise_s=enterprise_s,
+                    image_body=image_body, case_sensitive=case_sensitive, numeric=numeric,
+                    math=math, recognizing_threshold=recognizing_threshold,
+                    capmonster_module=capmonster_module,
+                    idempotency_key=idempotency_key,
+                    network_preference=network_preference,
+                )
+                while task.status == "processing":
+                    await asyncio.sleep(_CAPTCHA_POLL_SECONDS)
+                    task = await self.get_captcha_task(task.task_id)
+        except TimeoutError:
+            raise ResourceProxyError(
+                "captcha task exceeded its wait deadline", code="captcha-timeout",
+            ) from None
+        if task.status == "failed":
+            raise ResourceProxyError(
+                "captcha task failed", code=task.error_code or "captcha-failed",
+            )
+        return task
+
+    async def captcha_plugin_grant(
+        self, *, allowed_types: list[str], allowed_hosts: list[str] | None = None,
+        ttl_seconds: int = 300,
+    ) -> CaptchaPluginGrant:
+        """Issue a narrow grant; original extensions need the managed adapter patch."""
+        async with self._operation_lock:
+            await self.start()
+            self._warn_managed_billing()
+            value = await self._request(
+                "POST", "/v1/captcha/plugin-grants", json={
+                    "allowed_types": allowed_types,
+                    "allowed_hosts": allowed_hosts or [],
+                    "ttl_seconds": ttl_seconds,
+                },
+            )
+        expires_at = _datetime(value.get("expires_at"))
+        if expires_at is None:
+            raise ResourceProxyError("resource service returned an invalid plugin grant")
+        if value.get("protocol_version") != 1:
+            raise ResourceProxyError("resource service returned an unsupported plugin protocol")
+        return CaptchaPluginGrant(
+            api_url=_required_text(value, "api_url"),
+            client_key=_required_text(value, "client_key"),
+            expires_at=expires_at,
+            node_id=_required_text(value, "node_id"),
+            network=_required_text(value, "network"),
+            protocol_version=1,
+        )
+
+    async def chat_completion(
+        self, payload: Mapping[str, Any], *, idempotency_key: str | None = None,
+    ) -> Mapping[str, Any]:
+        """Send one non-streaming model request from a local or platform execution."""
+        if payload.get("stream", False) is not False:
+            raise ValueError("chat_completion requires a non-streaming request")
+        async with self._operation_lock:
+            await self.start()
+            self._warn_managed_billing()
+            return await self._request(
+                "POST", _MODEL_CHAT_COMPLETIONS, json=dict(payload),
+                headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())},
+                enveloped=False,
+            )
+
+    async def resource_charge(self) -> Mapping[str, Any] | None:
+        """Read this local execution's charge receipt, including after close.
+
+        Monetary amounts retain the server's decimal strings. A server or
+        execution without managed billing returns None.
+        """
+        async with self._operation_lock:
+            if self._local_transport is None:
+                raise RuntimeError("resource_charge is available for local resource executions")
+            if self.execution_id is None:
+                raise RuntimeError("start a local resource execution before reading its charge")
+            if not self._managed_billing_enabled:
+                return None
+            if not re.fullmatch(r"[A-Za-z0-9_-]+", self.execution_id):
+                raise ResourceProxyError("resource service returned an invalid execution ID")
+            return await self._request(
+                "GET", f"/v1/executions/{self.execution_id}/resource-charge",
+                authenticated=False, transport=self._local_transport,
+            )
+
+    async def resource_charges(self) -> tuple[Mapping[str, Any], ...]:
+        """Read charge receipts for every regional execution that was started."""
+        clients = (self, *self._regional_clients.values())
+
+        async def read(client: ResourceProxy) -> Mapping[str, Any]:
+            error_code: str | None = None
+            error_type: str | None = None
+            started = perf_counter()
+            try:
+                async with asyncio.timeout(client._regional_read_timeout):
+                    receipt = await client.resource_charge()
+            except asyncio.CancelledError:
+                raise
+            except TimeoutError as error:
+                receipt = None
+                error_code = "resource-read-timeout"
+                error_type = _safe_error_type(error)
+            except Exception as error:
+                receipt = None
+                error_code = _safe_error_code(error, "receipt-unavailable")
+                error_type = _safe_error_type(error)
+            return {
+                "network": client._network,
+                "execution_id": client.execution_id,
+                "environment": client._environment,
+                "billing_route_id": client._billing_route_id,
+                "receipt": receipt,
+                "error_code": error_code,
+                "error_type": error_type,
+                "duration_ms": round((perf_counter() - started) * 1000, 2),
+                "timeout_seconds": client._regional_read_timeout,
+            }
+
+        started = tuple(client for client in clients if client.execution_id is not None)
+        return tuple(await asyncio.gather(*(read(client) for client in started)))
+
+    async def usage(self) -> Mapping[str, Any]:
+        async with self._operation_lock:
+            await self.start()
+            return await self._request("GET", "/v1/usage")
+
+    async def usages(self) -> tuple[Mapping[str, Any], ...]:
+        """Read usage separately for each regional execution that was started."""
+        clients = (self, *self._regional_clients.values())
+
+        async def read(client: ResourceProxy) -> Mapping[str, Any]:
+            error_code: str | None = None
+            error_type: str | None = None
+            started = perf_counter()
+            try:
+                async with asyncio.timeout(client._regional_read_timeout):
+                    usage: Mapping[str, Any] | None = await client.usage()
+            except asyncio.CancelledError:
+                raise
+            except TimeoutError as error:
+                usage = None
+                error_code = "resource-read-timeout"
+                error_type = _safe_error_type(error)
+            except Exception as error:
+                usage = None
+                error_code = _safe_error_code(error, "usage-unavailable")
+                error_type = _safe_error_type(error)
+            return {
+                "network": client._network,
+                "execution_id": client.execution_id,
+                "environment": client._environment,
+                "usage": usage,
+                "error_code": error_code,
+                "error_type": error_type,
+                "duration_ms": round((perf_counter() - started) * 1000, 2),
+                "timeout_seconds": client._regional_read_timeout,
+            }
+
+        started = tuple(client for client in clients if client.execution_id is not None)
+        return tuple(await asyncio.gather(*(read(client) for client in started)))
+
+    async def close(self) -> None:
+        async with self._operation_lock:
+            async with self._start_lock:
+                if self._closed:
+                    return
+                heartbeat = self._heartbeat_task
+                self._heartbeat_task = None
+                if heartbeat is not None:
+                    heartbeat.cancel()
+                    await asyncio.gather(heartbeat, return_exceptions=True)
+                first_error: BaseException | None = None
+                for regional in self._regional_clients.values():
+                    try:
+                        await regional.close()
+                    except BaseException as error:
+                        first_error = first_error or error
+                for resource in list(reversed(self._resources.values())):
+                    try:
+                        await resource.close()
+                    except BaseException as error:
+                        first_error = first_error or error
+                self._resources.clear()
+                self._catalog_cache.clear()
+                self._captcha_task_networks.clear()
+                if self.execution_id is not None:
+                    try:
+                        await self._request("DELETE", "/v1/executions/current")
+                    except ResourceProxyError as error:
+                        if error.status_code not in {401, 404}:
+                            first_error = first_error or error
+                    except BaseException as error:
+                        first_error = first_error or error
+                self._closed = True
+                if self._owns_transport:
+                    try:
+                        await self._transport.close()
+                    except BaseException as error:
+                        first_error = first_error or error
+        if first_error is not None:
+            if not isinstance(first_error, Exception):
+                raise first_error
+            raise ResourceProxyError("managed resource cleanup failed") from None
+
+    async def _heartbeat_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self._heartbeat_interval)
+            try:
+                await self._request("POST", "/v1/executions/heartbeat", json={})
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                # Server-side expiry remains the authoritative cleanup fallback.
+                continue
+
+    async def _revoke_rejected_execution(self, transport: ResourceTransport) -> None:
+        """Best-effort revoke using only the newly issued execution token."""
+        try:
+            await self._request(
+                "DELETE",
+                "/v1/executions/current",
+                authenticated=False,
+                transport=transport,
+            )
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.warning("rejected_resource_execution_cleanup_failed")
+
+    async def _renew_proxy(self, lease_id: str) -> dict[str, Any]:
+        return await self._request("POST", f"/v1/ip-proxy/leases/{lease_id}/renew", json={})
+
+    async def _get_proxy(self, lease_id: str) -> dict[str, Any]:
+        return await self._request("GET", f"/v1/ip-proxy/leases/{lease_id}")
+
+    async def _rotate_proxy(
+        self, lease_id: str, *, credential_generation: int | None
+    ) -> dict[str, Any]:
+        body = (
+            {"credential_generation": credential_generation}
+            if credential_generation is not None
+            else {}
+        )
+        return await self._request(
+            "POST",
+            f"/v1/ip-proxy/leases/{lease_id}/credentials/rotate",
+            json=body,
+            headers={"Idempotency-Key": str(uuid.uuid4())},
+        )
+
+    async def _release_proxy(self, lease_id: str) -> None:
+        try:
+            await self._request("DELETE", f"/v1/ip-proxy/leases/{lease_id}")
+        except ResourceProxyError as error:
+            if error.status_code not in {401, 404}:
+                raise
+
+    async def _browser_connection(self, resource_id: str) -> dict[str, Any]:
+        return await self._request(
+            "POST", f"/v1/aws-proxy/browser-sessions/{resource_id}/connections", json={}
+        )
+
+    async def _get_browser(self, resource_id: str) -> dict[str, Any]:
+        return await self._request("GET", f"/v1/aws-proxy/browser-sessions/{resource_id}")
+
+    async def _release_browser(self, resource_id: str) -> None:
+        try:
+            await self._request("DELETE", f"/v1/aws-proxy/browser-sessions/{resource_id}")
+        except ResourceProxyError as error:
+            if error.status_code not in {401, 404}:
+                raise
+
+    def _forget(self, resource: Any) -> None:
+        self._resources.pop(id(resource), None)
+
+    def _warn_managed_billing(self) -> None:
+        if self._managed_billing_enabled and not self._managed_billing_warned:
+            self._managed_billing_warned = True
+            logger.warning(
+                "Managed IP traffic, CAPTCHA solves, and model requests during local debug "
+                "accrue developer resource costs. These costs will be deducted from developer "
+                "earnings at settlement; remaining earnings will be paid out after deduction. "
+                "Use resource_charge() to check usage, prices, and the amount to be deducted. "
+                "Pod cost is shown in cloud debug."
+            )
+
+    def _client_for_network(self, network_preference: str | None) -> ResourceProxy:
+        if not self._regional_mode:
+            return self
+        if network_preference in {None, "auto", "domestic"}:
+            if self._network == "domestic":
+                return self
+            raise ResourceProxyError(
+                "the domestic Resource Proxy node is not configured",
+                code="configuration-error",
+            )
+        if self._network == "overseas":
+            return self
+        client = self._regional_clients.get("overseas")
+        if client is None:
+            raise ResourceProxyError(
+                "the overseas Resource Proxy node is not configured",
+                code="configuration-error",
+            )
+        return client
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        authenticated: bool = True,
+        transport: ResourceTransport | None = None,
+        enveloped: bool = True,
+    ) -> dict[str, Any]:
+        if authenticated:
+            self._require_open_execution()
+        request_id = uuid.uuid4().hex
+        request_headers = {**(headers or {}), "X-Request-ID": request_id}
+        started = perf_counter()
+        outcome = "error"
+        try:
+            selected_transport = self._transport if transport is None else transport
+            value = selected_transport.request(method, path, json=json, headers=request_headers)
+            payload = await value if inspect.isawaitable(value) else value
+            data = payload.get("data") if enveloped and isinstance(payload, Mapping) else payload
+            if not isinstance(data, Mapping):
+                raise ResourceProxyError("resource service returned an invalid response")
+            outcome = "ok"
+            return dict(data)
+        except asyncio.CancelledError:
+            outcome = "cancelled"
+            raise
+        except ResourceProxyError:
+            raise
+        except Exception as error:
+            raise ResourceProxyError(
+                f"resource service request failed ({type(error).__name__})",
+                code="transport-error",
+            ) from None
+        finally:
+            route = (
+                "/v1/executions/{id}/resource-charge" if path.endswith("/resource-charge")
+                else _RESOURCE_PATH.sub(r"\1/{id}", path)
+            )
+            logger.debug(
+                "resource_request method=%s route=%s request_id=%s outcome=%s duration_ms=%.2f",
+                method, route, request_id, outcome, (perf_counter() - started) * 1000,
+            )
+
+    def _require_open_execution(self) -> None:
+        if self._closed:
+            raise RuntimeError("resource client is closed")
+        if self.execution_id is None:
+            raise RuntimeError("use ResourceProxy inside an async context")
+
+
+def _captcha_task(value: dict[str, Any], *, expected_id: str | None = None) -> CaptchaTask:
+    task_id = value.get("task_id")
+    status = value.get("status")
+    solution = value.get("solution")
+    token = solution.get("token") if isinstance(solution, dict) else None
+    text = solution.get("text") if isinstance(solution, dict) else None
+    structured = solution.get("data") if isinstance(solution, dict) else None
+    ready_solution = (
+        status != "ready"
+        or (isinstance(structured, dict) and bool(structured))
+        or (
+            isinstance(token, str)
+            and bool(token)
+            and text is None
+        )
+        or (
+            isinstance(text, str)
+            and bool(text)
+            and token is None
+        )
+    )
+    if (
+        not isinstance(task_id, str)
+        or not _CAPTCHA_TASK_ID.fullmatch(task_id)
+        or (expected_id is not None and expected_id != task_id)
+        or status not in ("processing", "ready", "failed")
+        or not ready_solution
+    ):
+        raise ResourceProxyError("resource service returned an invalid captcha task")
+    return CaptchaTask(
+        task_id=task_id,
+        status=status,
+        token=token if status == "ready" else None,
+        text=text if status == "ready" else None,
+        user_agent=_optional_text(solution.get("user_agent"))
+        if status == "ready" and isinstance(solution, dict) else None,
+        error_code=_optional_text(value.get("error_code")) if status == "failed" else None,
+        node_id=_optional_text(value.get("node_id")),
+        network=_optional_text(value.get("network")),
+        data=(copy.deepcopy(structured)
+              if status == "ready" and isinstance(structured, dict) else None),
+    )
+
+
+def _decode_response(response: httpx.Response) -> Mapping[str, Any]:
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+    if response.status_code >= 400:
+        error = payload.get("error") if isinstance(payload, dict) else None
+        code = error.get("code") if isinstance(error, dict) else "resource-service-error"
+        message = error.get("message") if isinstance(error, dict) else None
+        raise ResourceProxyError(
+            str(message or f"resource service returned HTTP {response.status_code}"),
+            code=str(code),
+            status_code=response.status_code,
+        )
+    if not isinstance(payload, Mapping):
+        raise ResourceProxyError("resource service returned an invalid response")
+    return payload
+
+
+def _validate_network_preference(value: str | None) -> None:
+    if value is not None and (
+        not isinstance(value, str) or value not in {"auto", "domestic", "overseas"}
+    ):
+        raise ValueError("network_preference must be auto, domestic or overseas")
+
+
+def _normalize_country(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or re.fullmatch(r"[A-Za-z]{2}", value) is None:
+        raise ValueError("country must be an ISO alpha-2 code")
+    return value.upper()
+
+
+def _optional_catalog_code(value: str | None, name: str) -> str | None:
+    if value is None:
+        return None
+    if (
+        not isinstance(value, str)
+        or not 1 <= len(value) <= 64
+        or any(ord(char) < 32 for char in value)
+    ):
+        raise ValueError(f"{name} must contain 1-64 printable characters")
+    return value
+
+
+def _validate_catalog_response(value: Mapping[str, Any], *, locations: bool) -> None:
+    if value.get("network") not in {"domestic", "overseas"}:
+        raise ResourceProxyError(
+            "resource service returned an invalid proxy catalog",
+            code="invalid-response",
+        )
+    if value.get("coverage_only") is not True:
+        raise ResourceProxyError(
+            "resource service returned an invalid proxy catalog",
+            code="invalid-response",
+        )
+    key = "items" if locations else "groups"
+    rows = value.get(key)
+    if not isinstance(rows, list) or any(not isinstance(row, Mapping) for row in rows):
+        raise ResourceProxyError(
+            "resource service returned an invalid proxy catalog",
+            code="invalid-response",
+        )
+    if locations:
+        if value.get("level") not in {"country", "state", "city"}:
+            raise ResourceProxyError(
+                "resource service returned an invalid proxy catalog",
+                code="invalid-response",
+            )
+        for row in rows:
+            if not isinstance(row.get("code"), str) or not row["code"]:
+                raise ResourceProxyError(
+                    "resource service returned an invalid proxy catalog",
+                    code="invalid-response",
+                )
+            _validate_location_availability(row)
+    else:
+        for row in rows:
+            complete = row.get("duration_catalog_complete")
+            if complete is not None and not isinstance(complete, bool):
+                raise ResourceProxyError(
+                    "resource service returned an invalid proxy catalog",
+                    code="invalid-response",
+                )
+
+
+def _validate_location_availability(row: Mapping[str, Any]) -> None:
+    availability = row.get("availability")
+    if availability is not None and availability not in {
+        "unknown", "temporarily_unavailable",
+    }:
+        raise ResourceProxyError(
+            "resource service returned an invalid proxy catalog",
+            code="invalid-response",
+        )
+    eligible = row.get("eligible_routes")
+    cooling = row.get("cooling_routes")
+    for value in (eligible, cooling):
+        if value is not None and (
+            isinstance(value, bool) or not isinstance(value, int) or value < 0
+        ):
+            raise ResourceProxyError(
+                "resource service returned an invalid proxy catalog",
+                code="invalid-response",
+            )
+    if isinstance(eligible, int) and isinstance(cooling, int) and cooling > eligible:
+        raise ResourceProxyError(
+            "resource service returned an invalid proxy catalog",
+            code="invalid-response",
+        )
+    retry_at = row.get("earliest_retry_at")
+    if retry_at is not None:
+        if not isinstance(retry_at, str):
+            raise ResourceProxyError(
+                "resource service returned an invalid proxy catalog",
+                code="invalid-response",
+            )
+        try:
+            parsed = datetime.fromisoformat(retry_at.replace("Z", "+00:00"))
+        except ValueError:
+            parsed = None
+        if parsed is None or parsed.tzinfo is None:
+            raise ResourceProxyError(
+                "resource service returned an invalid proxy catalog",
+                code="invalid-response",
+            )
+
+
+def _safe_error_code(error: Exception, fallback: str) -> str:
+    code = error.code if isinstance(error, ResourceProxyError) else fallback
+    return code if isinstance(code, str) and _SAFE_ERROR_CODE.fullmatch(code) else fallback
+
+
+def _safe_error_type(error: Exception) -> str:
+    name = type(error).__name__
+    return name if re.fullmatch(r"[A-Za-z][A-Za-z0-9_]{0,79}", name) else "Exception"
+
+
+def _validate_regional_read_timeout(value: float) -> float:
+    try:
+        normalized = float(value)
+    except (OverflowError, TypeError, ValueError):
+        normalized = mathlib.nan
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or (
+        not mathlib.isfinite(normalized)
+        or normalized <= 0
+        or normalized > _MAX_REGIONAL_READ_TIMEOUT_SECONDS
+    ):
+        raise ValueError(
+            "regional_read_timeout must be finite, positive, and at most 30 seconds"
+        )
+    return normalized
+
+
+def _configured_regional_read_timeout(
+    env: Mapping[str, str], override: float | None
+) -> float:
+    try:
+        if override is not None:
+            return _validate_regional_read_timeout(override)
+        raw = env.get("DATAOS_RESOURCE_READ_TIMEOUT_SECONDS")
+        if raw is None:
+            return _DEFAULT_REGIONAL_READ_TIMEOUT_SECONDS
+        return _validate_regional_read_timeout(float(raw))
+    except (TypeError, ValueError):
+        raise ResourceProxyError(
+            "resource read timeout must be a finite number greater than 0 and at most 30 seconds",
+            code="configuration-error",
+        ) from None
+
+
+def _validate_line_tier(value: str) -> None:
+    if not isinstance(value, str) or value not in {"standard", "enhanced"}:
+        raise ValueError("line_tier must be standard or enhanced")
+
+
+_PROXY_GROUPS = frozenset({
+    "auto",
+    "domestic_basic",
+    "overseas_basic",
+    "overseas_enhanced",
+})
+
+
+def _validate_proxy_group(value: str | None) -> None:
+    if value is not None and (not isinstance(value, str) or value not in _PROXY_GROUPS):
+        raise ValueError(
+            "proxy_group must be auto, domestic_basic, overseas_basic, "
+            "or overseas_enhanced"
+        )
+
+
+def _network_for_proxy_group(value: str | None) -> str | None:
+    if value == "domestic_basic":
+        return "domestic"
+    if value in {"overseas_basic", "overseas_enhanced"}:
+        return "overseas"
+    return None
+
+
+def _validate_target_hint(value: str | None) -> None:
+    if value is None:
+        return
+    if not isinstance(value, str) or len(value) > 253 or not re.fullmatch(
+        r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?"
+        r"(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*",
+        value,
+    ):
+        raise ValueError("target_hint must contain a host name only")