harness-toolbox 0.2.2__tar.gz

harness_toolbox-0.2.2/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+*.whl
+*.tar.gz
+
+# Go
+/sdks/go/bin/
+
+# TypeScript
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+sdks/python/.venv/
+
+# DevOps plugin
+.devops/
+
+# Runtime artifacts (agent tier)
+runtime/
+runs/
+
+# devloop
+.devloop/
+.worktrees/

harness_toolbox-0.2.2/Makefile

@@ -0,0 +1,16 @@
+.PHONY: test lint fix build
+
+CHECK_PATHS ?= $(if $(filter %.py,$(LINT_FILES)),$(filter %.py,$(LINT_FILES)),harness_toolbox)
+
+test:
+	uv run --project .. pytest -v harness_toolbox/tests $(TEST_FILES)
+
+lint:
+	uv run --project .. ruff check $(CHECK_PATHS)
+
+fix:
+	uv run --project .. ruff check --fix $(CHECK_PATHS)
+	uv run --project .. ruff format $(CHECK_PATHS)
+
+build:
+	uv build --out-dir ../../../dist

harness_toolbox-0.2.2/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: harness-toolbox
+Version: 0.2.2
+Summary: Async infrastructure clients and execution-scoped resource sharing
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: harness-common<0.4,>=0.3.1
+Provides-Extra: kube
+Requires-Dist: kubernetes-asyncio<37,>=36.1; extra == 'kube'
+Provides-Extra: mysql
+Requires-Dist: asyncmy<1,>=0.2.9; extra == 'mysql'
+Requires-Dist: sqlalchemy[asyncio]<3,>=2.0; extra == 'mysql'
+Provides-Extra: opensearch
+Requires-Dist: httpx<1,>=0.27; extra == 'opensearch'

harness_toolbox-0.2.2/README.md

@@ -0,0 +1,58 @@
+# Harness Toolbox for Python
+
+Async infrastructure clients for test runners, diagnostic commands, and operational Skills.
+The same execution can create test Pods, inspect their state, run commands, query databases,
+and collect logs without rebuilding clients for each nested operation.
+
+Install only the protocols you use:
+
+```sh
+pip install 'harness-toolbox[kube,opensearch,mysql]'
+```
+
+`harness-common` owns `Client`, `DataSource`, `ClientProvider` and `ClientManager`;
+toolbox re-exports these names. `Client` owns initialization and disposal. A `DataSource` identifies its configuration;
+`ClientManager` shares it across concurrent or nested work and cleans up at root exit.
+`ConnectionSource` and `Transport` separate caller-owned configuration from the path used to reach it.
+
+```python
+import asyncio
+from harness_toolbox import ClientManager
+from harness_toolbox.kube import KubernetesDataSource, Options, PodSpec
+
+async def main():
+    source = KubernetesDataSource(
+        options=Options(namespace="quality", request_timeout_s=15, connection_pool_maxsize=4),
+        kubeconfig="/path/to/kubeconfig",
+    )
+    async with ClientManager() as clients:
+        kube = await clients.get(source)
+        pod = await kube.create_pod(PodSpec("toolbox-demo", "busybox:1.37",
+                                              command=("sleep", "300")))
+        try:
+            await kube.wait_ready(pod.ref(), timeout_s=60, interval_s=1)
+            result = await kube.execute(pod.ref(), ["echo", "hello"])
+            print(result.stdout.decode(), result.exit_code)
+        finally:
+            await kube.delete_pod(pod.ref())
+            await kube.wait_deleted(pod.ref(), timeout_s=60, interval_s=1)
+
+asyncio.run(main())
+```
+
+Existing workloads can be observed with `kube.list_service_pods(name)` or
+`kube.list_deployment_pods(name)`. Both use the resource's label selector, return stable Pod
+observations, and leave readiness/sample selection to the caller. Missing resources raise
+`ResourceNotFoundError`; permission and network errors remain failures. Selectorless resources
+cannot be used to enumerate all Pods accidentally.
+
+The caller chooses cluster, namespace, credentials, SQL, indexes, collection windows, and authorization.
+The package does not read product-specific environment variables or registries. Kubernetes control uses
+`kubernetes-asyncio`; exec, port-forward and log streams require `kubectl` on the host and use the same
+kubeconfig/context. Pod Python access additionally requires Python and the protocol driver in the target Pod.
+
+See [lifecycle and connection examples](docs/lifecycle.md) for shared clients, database routes, TLS,
+log budgets, and cancellation behavior.
+
+`list_workload_pods` resolves Deployment, StatefulSet, DaemonSet or an explicit Pod.
+Kubernetes Service endpoints retain their separate `list_service_pods` operation.

harness_toolbox-0.2.2/docs/lifecycle.md

@@ -0,0 +1,198 @@
+# Execution-scoped infrastructure
+
+## Ownership and identity
+
+One root operation owns a `ClientManager`. Nested commands receive a `ClientProvider`, reuse its
+clients, and join their work before the root exits. A cancelled waiter does not cancel shared
+initialization. Root disposal stops pending initialization, drains it, and disposes ready clients
+in reverse dependency order. A failed initialization is cleaned before retry; failed cleanup keeps
+that identity failed and is reported again at finalize. Disposal does not delete remote workloads.
+
+The manager is local to one Python execution and event loop. It cannot share live connections across
+separately launched scripts. Synchronous CLIs call `asyncio.run` at their outer boundary; domain
+operations remain async and receive the provider explicitly.
+
+A DataSource key must cover everything that changes reuse: target, protocol, credentials, configuration,
+and capacity. ConnectionSource accepts a caller-supplied stable key because environment resolution is
+external. Use `data_source_key` to hash those inputs. Do not key only by a friendly service name when
+multiple clusters or credentials can coexist. Configuration and credentials remain fixed for a root
+execution; key new configurations separately.
+
+## Database and HTTP paths
+
+```python
+from dataclasses import asdict
+from harness_toolbox import ClientManager, data_source_key
+from harness_toolbox.mysql import MySQLDataSource, MySQLTarget
+from harness_toolbox.transport import ConnectionSource, DirectTransport
+
+async def query(clients, settings):
+    target = MySQLTarget(**settings)
+    async def resolve():
+        return target
+    source = MySQLDataSource(ConnectionSource(
+        data_source_key("db-config", asdict(target)), resolve, (DirectTransport(),)
+    ))
+    database = await clients.get(source)
+    return await database.query("SELECT id FROM message WHERE id = %(id)s", {"id": "example"})
+```
+
+MySQL uses SQLAlchemy with asyncmy for direct and forwarded access. It selects a route while establishing
+a connection, before user SQL. Authentication errors may advance to another declared address, but
+do not retry the same address through another transport. Statement failures never cause replay. PodPythonTransport sends explicit connection settings and query parameters over stdin and uses
+PyMySQL in the Pod; it shares the resolved route/client, but opens a remote DB connection per exec.
+Statements use DBAPI `%(name)s` parameters on both paths. Queries are bounded by concurrency, timeout,
+and row limit. A statement timeout does not prove the server rolled back; callers decide transaction
+and retry semantics.
+
+With `params=None`, SQL is passed literally, so `DATE_FORMAT(ts, '%Y-%m-%d')` needs no escaping.
+Supplying a parameter mapping, including `{}`, enables DBAPI interpolation: bind values with
+`%(name)s` and write literal percent signs as `%%`. Do not interpolate values in the caller.
+
+`QueryResult.rows` and `mappings()` preserve native Python values on both paths, including
+`Decimal`, `datetime`, `date`, `time`, `timedelta` and `bytes`. The Pod wire format preserves
+types and precision for parameters and results; it does not require toolbox installed in the Pod.
+Consumers choose their own JSON presentation rather than relying on transport-specific string conversion.
+For row-returning statements, `affected_rows` is `-1` (not a record count); use `len(result.rows)`.
+Empty results retain their columns. Non-row statements retain the driver's affected-row count.
+
+OpenSearchDataSource uses an HTTP pool and bounded response decoding. TLS verification is enabled;
+private CAs use `ca_file`, and an intentional insecure environment must explicitly set
+`insecure_skip_verify`. Forwarded connections preserve the original TLS server name. `scroll` yields
+pages; use `contextlib.aclosing` when stopping early so the cursor is cleared before the client closes.
+Consumers own index names, queries, and output files.
+
+### Failures and connection evidence
+
+Catch `ToolboxError` for translated access failures, or a protocol/operation subclass:
+`MySQLError → MySQLConnectionError / MySQLQueryError` and
+`OpenSearchError → OpenSearchConnectionError / OpenSearchRequestError`.
+
+Every toolbox exception has three fields: `kind` is a stable `ErrorKind`, `code` is the optional
+native DB/HTTP error code, and `message` is a safe contextual explanation, also returned by
+`str(error)`. Interpret codes in the context of the protocol class, never by parsing messages.
+Protocol adapters translate native failures once and preserve the original exception with
+`raise ... from error`; already-translated exceptions propagate unchanged.
+
+```python
+from harness_toolbox import ToolboxError, ErrorKind
+
+try:
+    database = await clients.get(source)
+    result = await database.query("SELECT 1")
+except ToolboxError as error:
+    if error.kind == ErrorKind.AUTHENTICATION_FAILED:
+        handle_authentication_failure(error.message)
+    report({"kind": error.kind, "code": error.code, "message": error.message})
+else:
+    report({"connection": database.diagnostics, "rows": len(result.rows)})
+```
+
+Consumers choose report fields and serialization. Exception messages exclude native driver text,
+SQL/parameters, credentials and URL paths/query strings. Native causes and full tracebacks are
+debugging material, **not** safe report output. Pod Python carries only safe error categories and
+numeric MySQL codes; the host reconstructs the same public exception hierarchy without fabricating
+an in-process driver cause.
+
+`client.diagnostics` is independent connection evidence: protocol, resolved target, ordered
+attempts and selected transport (`direct`, `port-forward` or `pod-python`). Snapshots are detached.
+A target without a selected transport does not prove connection success. MySQL targets also expose
+`target.diagnostics` before connecting. When initialization fails before a caller obtains the
+client, the exception message still identifies the target and failed action; exceptions do not
+carry the connection snapshot.
+
+Arguments/programming errors and cancellation are not translated. Connection configuration
+resolution belongs to the caller and its failures propagate unchanged. Result limits and invalid
+remote responses are operational failures. Successful empty queries are not errors. Classification
+does not authorize retries: only connection probes can use configured fallback routes; statements
+and user requests are never automatically replayed.
+
+## Kubernetes and logs
+
+KubernetesDataSource owns namespace, API capacity, exec capacity and timeouts. KubernetesClient offers
+Pod create/get/list/delete, readiness/replacement/deletion waits, Event collection, exec, and
+port-forward. Exec returns stdout, stderr and exit code separately. Nonzero process exit is a result;
+connection failure, timeout, and output limit violations are exceptions. Created Pods are explicit
+consumer-owned workloads, so tests use `try/finally` to delete their own physical Pod instance.
+
+Delete uses a server-side UID precondition. Kubernetes does not support that condition for exec or
+logs; the client checks identity before and after access and rejects a changed instance. This detects
+replacement but cannot guarantee an atomic exec against a UID. Port-forward subprocesses belong to the
+Kubernetes client and close at finalize.
+
+PodLogDataSource depends on KubernetesDataSource through the same provider. It owns one capture pool,
+one total byte budget and a temporary directory. Physical Pod UID, container, restart count, previous
+selection, and absolute timezone-aware `[since, until)` window identify a capture. Concurrent consumers
+join the same capture; different trace IDs filter its file locally. Truncation is explicit in
+PodLogCapture; timeout, transport failure or identity change do not publish a reusable capture.
+Capture paths are borrowed and cease to exist after root disposal: copy evidence before root exit.
+
+The capacities on a shared source apply to every user of that source. Use one configured log source
+for all child commands rather than creating sources with conflicting limits. Defaults are bounded;
+products should choose limits appropriate to their clusters.
+
+## Common runtime identities
+
+A logical Service declares its `workloads`; deployment configuration supplies the mapping. Workloads
+are stable references, while Pod snapshots and UIDs are obtained during execution. The mapping can
+change without changing the logical Service identity. Kubernetes Service endpoints are separate
+from workload controllers and Pods.
+
+```python
+from harness_common import KubernetesWorkload
+from harness_toolbox.environment import kubernetes_source
+from harness_toolbox.kube import Options
+
+async def observe(clients, service):
+    pods = []
+    for workload in service.workloads:
+        if not isinstance(workload, KubernetesWorkload):
+            raise TypeError("This observer requires Kubernetes workloads")
+        source = kubernetes_source(service.environment, Options(workload.namespace, 15, 4))
+        kube = await clients.get(source)
+        pods.extend(await kube.list_workload_pods(workload.kind, workload.name))
+    return pods
+```
+
+Workload operations are one toolbox capability, alongside database, OpenSearch, process and transport
+operations. Those capabilities do not require Service or Workload objects. ServiceDataSource can
+associate logical context with independently configured sources without changing source keys.
+
+PodPythonTransport accepts an explicit `container` for multi-container Pods. It is part of the
+transport identity so clients using different containers cannot share a route. Credentials and
+query parameters continue to travel over stdin.
+
+## Environment-scoped address selection
+
+Generic client ownership and service associations live in `harness_common`; toolbox
+re-exports the original lifecycle names. `harness_toolbox.environment.kubernetes_source`
+is the Kubernetes-specific factory. The independent packages depend in one direction:
+`quality-harness` → `harness-toolbox` → `harness-common`.
+
+```python
+from harness_common import KubernetesEnvironment
+from harness_toolbox.address import AddressPolicy
+
+addresses = AddressPolicy(
+    environment=KubernetesEnvironment("smoke", "/configs/smoke", "smoke-context"),
+    namespace="runtime",
+    fallback_hosts=("mysql-replica.storage.svc",),
+    timeout_s=10,
+    connection_pool_maxsize=8,
+)
+# Pass addresses=addresses to ConnectionSource for MySQL or OpenSearch.
+```
+
+Resolution is lazy and shares Kubernetes clients through the root ClientProvider.
+A Service lookup uses this environment's kubeconfig/context (empty kubeconfig means
+in-cluster identity, never ambient local kubeconfig). A confirmed Service never falls
+back to local short-name DNS. Cross-namespace names use `service.namespace.svc`;
+ordinary domains retain DNS semantics. ClusterIP, ready headless addresses, external
+DNS addresses and explicit alternatives are attempted sequentially and deduplicated.
+
+Only initialization can switch addresses: authentication/database failures advance to
+the next address, network failures may also advance to the next transport for the same
+address. Queries are never replayed. The first successful client is reused; failed
+attempt resources are closed. HTTPS keeps the configured SNI and HTTP Host even when
+connecting by IP. Diagnostics distinguish configured target, candidate origin, mapped
+endpoint and selected transport, without credentials or query data.

harness_toolbox-0.2.2/harness_toolbox/AGENTS.md

@@ -0,0 +1,40 @@
+# Python 平台工具箱
+
+## 项目定位与边界
+
+独立分发包 `harness-toolbox` 提供异步基础设施客户端。测试环境操作与诊断采集共享机制；
+环境台账、凭据来源、业务查询、动作授权和结果判定由消费方拥有；环境内的网络地址解析由 toolbox 拥有。
+
+## 代码地图与核心模块
+
+```text
+harness_toolbox/
+├── client.py       # common 生命周期类型的兼容导出
+├── environment.py  # KubernetesEnvironment → KubernetesDataSource
+├── address.py      # IP/DNS/环境内 Service 地址候选与解析失败
+├── errors.py       # ToolboxError 契约与协议子类；适配器负责转换原生异常
+├── diagnostics.py  # 客户端连接路径快照，与异常独立
+├── transport.py    # 连接解析、直连、port-forward、Pod Python 路径
+├── process.py      # 有界子进程 I/O、退出结果与取消清理
+├── kube/           # Pod 增删、状态等待、Event、exec 与隧道
+├── opensearch.py   # HTTP 池、有界响应与 scroll
+├── mysql.py        # SQLAlchemy async 池与 Pod Python 查询
+├── pod_log.py      # 按物理实例/窗口共享采集，依赖 Kubernetes 客户端
+└── tests/          # 协议 stub 和本机 HTTP/进程测试
+```
+
+## 关键约定
+
+- 根调用方通过 `async with ClientManager()` 管理执行期，子调用方只接收 ClientProvider。
+- DataSource 创建不做外部 I/O；initialize 完成依赖获取后才发布成功，dispose 必须幂等。
+- Service 名称必须用对应 Environment 的 kubeconfig/context 解析，不回退本机短名 DNS；仅初始化阶段切换地址，业务请求不重放。
+- 同 key 的配置、凭据和容量必须一致；失败资源清理完成才允许重试。禁止日志输出凭据和查询内容。
+- 协议依赖仅通过 extras 引入；通用生命周期归 harness-common，只使用标准库。Skill 必须显式安装所用协议 extra。
+- Pod 删除通过 UID precondition 保证实例身份；exec/log API 没有原子 UID 条件，只能前后核验。
+- ClientManager 释放连接、临时采集文件和子进程，不隐式删除消费方创建的远端 Pod。
+
+## References
+
+- [使用指南](../README.md)
+- [生命周期与访问边界](../docs/lifecycle.md)
+- [跨语言工具箱](../../../../../docs/toolbox.md)

harness_toolbox-0.2.2/harness_toolbox/__init__.py

@@ -0,0 +1,19 @@
+"""Infrastructure mechanisms without business or environment configuration."""
+
+from harness_toolbox.client import (
+    Client as Client,
+)
+from harness_toolbox.client import (
+    ClientManager as ClientManager,
+)
+from harness_toolbox.client import (
+    ClientProvider as ClientProvider,
+)
+from harness_toolbox.client import (
+    DataSource as DataSource,
+)
+from harness_toolbox.client import (
+    data_source_key as data_source_key,
+)
+from harness_toolbox.errors import ErrorKind as ErrorKind
+from harness_toolbox.errors import ToolboxError as ToolboxError

harness_toolbox-0.2.2/harness_toolbox/_mysql_values.py

@@ -0,0 +1,46 @@
+"""Private, stdlib-only wire codec, also shipped as source to Pod Python.
+
+Every cell is tagged so SQL text cannot be mistaken for a serialized native value.
+Keep this module independent of package imports: Pods need only Python and PyMySQL.
+"""
+
+from base64 import b64decode, b64encode
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+
+
+def encode_value(value: object) -> list[object]:
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return ["scalar", value]
+    if isinstance(value, bytes):
+        return ["bytes", b64encode(value).decode("ascii")]
+    if isinstance(value, Decimal):
+        return ["decimal", str(value)]
+    if isinstance(value, datetime):
+        return ["datetime", value.isoformat()]
+    if isinstance(value, date):
+        return ["date", value.isoformat()]
+    if isinstance(value, time):
+        return ["time", value.isoformat()]
+    if isinstance(value, timedelta):
+        return ["timedelta", [value.days, value.seconds, value.microseconds]]
+    raise TypeError(f"Unsupported MySQL value type: {type(value).__name__}")
+
+
+def decode_value(cell: list[object]) -> object:
+    kind, value = cell
+    if kind == "scalar":
+        return value
+    if kind == "bytes":
+        return b64decode(value)
+    if kind == "decimal":
+        return Decimal(value)
+    if kind == "datetime":
+        return datetime.fromisoformat(value)
+    if kind == "date":
+        return date.fromisoformat(value)
+    if kind == "time":
+        return time.fromisoformat(value)
+    if kind == "timedelta":
+        return timedelta(*value)
+    raise ValueError("Unknown MySQL wire value type")

harness_toolbox-0.2.2/harness_toolbox/address.py

@@ -0,0 +1,170 @@
+"""Resolve access addresses within the declared environment, without probing services."""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import socket
+from collections.abc import AsyncIterator
+from dataclasses import asdict, dataclass
+
+from harness_common import Environment, KubernetesEnvironment
+
+from harness_toolbox.client import ClientProvider, data_source_key
+from harness_toolbox.errors import ErrorKind, ToolboxError
+from harness_toolbox.transport import Endpoint
+
+
+class AddressResolutionError(ToolboxError):
+    """An address could not be resolved in its declared environment."""
+
+
+@dataclass(frozen=True)
+class AddressPolicy:
+    """Environment and ordered alternatives for one logical connection target.
+
+    Short names in Kubernetes environments are Services in ``namespace``. Qualified
+    Service names use ``name.namespace.svc`` (optionally a cluster DNS suffix).
+    Two-label names are Services only when their namespace matches the explicit
+    scope. Other domains use DNS; no arbitrary domain is guessed into a Service.
+    """
+
+    environment: Environment | None = None
+    namespace: str = ""
+    fallback_hosts: tuple[str, ...] = ()
+    timeout_s: float = 10
+    connection_pool_maxsize: int = 8
+
+    @property
+    def key(self) -> str:
+        config = asdict(self)
+        # Logical aliases must not fragment clients using the same physical access.
+        config["environment"] = (
+            {"kubeconfig": self.environment.kubeconfig, "context": self.environment.context}
+            if isinstance(self.environment, KubernetesEnvironment)
+            else None
+        )
+        return data_source_key("address-policy", config)
+
+
+@dataclass(frozen=True)
+class AddressCandidate:
+    endpoint: Endpoint
+    source: str
+    error: AddressResolutionError | None = None
+
+
+def _service_name(host: str, namespace: str) -> tuple[str, str] | None:
+    parts = host.rstrip(".").split(".")
+    if len(parts) == 1:
+        if not namespace:
+            raise ValueError("Kubernetes short Service names require an explicit namespace")
+        return host, namespace
+    if len(parts) >= 3 and parts[2] == "svc":
+        return parts[0], parts[1]
+    if len(parts) == 2 and parts[1] == namespace:
+        return parts[0], namespace
+    return None
+
+
+async def _dns(host: str, port: int, timeout_s: float) -> tuple[str, ...]:
+    async with asyncio.timeout(timeout_s):
+        records = await asyncio.get_running_loop().getaddrinfo(host, port, type=socket.SOCK_STREAM)
+    # Keep resolver preference (including IPv6), but remove duplicate socket records.
+    return tuple(dict.fromkeys(record[4][0] for record in records))
+
+
+async def _hosts(
+    policy: AddressPolicy, endpoint: Endpoint, clients: ClientProvider | None
+) -> tuple[tuple[str, ...], str]:
+    try:
+        ipaddress.ip_address(endpoint.host)
+    except ValueError:
+        pass
+    else:
+        return (endpoint.host,), "ip"
+    environment = policy.environment
+    service = (
+        _service_name(endpoint.host, policy.namespace)
+        if isinstance(environment, KubernetesEnvironment)
+        else None
+    )
+    if service is None:
+        return await _dns(endpoint.host, endpoint.port, policy.timeout_s), "dns"
+    assert isinstance(environment, KubernetesEnvironment)
+    if clients is None:
+        raise ValueError("Kubernetes address resolution requires a ClientProvider")
+    from harness_toolbox.environment import kubernetes_source
+    from harness_toolbox.kube import Options
+
+    name, namespace = service
+    from aiohttp import ClientError
+    from kubernetes_asyncio.config.config_exception import ConfigException
+
+    try:
+        kube = await clients.get(
+            kubernetes_source(
+                environment,
+                Options(
+                    namespace=namespace,
+                    request_timeout_s=policy.timeout_s,
+                    connection_pool_maxsize=policy.connection_pool_maxsize,
+                ),
+            )
+        )
+        # why: local short-name DNS can resolve a healthy database in a different cluster.
+        # Service identity is authoritative; never fall back to ambient DNS for this name.
+        return await kube.service_addresses(name), "kubernetes-service"
+    except (ClientError, ConfigException) as error:
+        raise AddressResolutionError(
+            f"Cannot access Kubernetes environment {environment.name!r} for Service {name!r}",
+            kind=ErrorKind.CONNECTION_FAILED,
+        ) from error
+
+
+async def address_candidates(
+    endpoint: Endpoint, policy: AddressPolicy | None, clients: ClientProvider | None
+) -> AsyncIterator[AddressCandidate]:
+    """Yield ordered candidates; resolution failures remain visible before alternatives.
+
+    Without a policy, transports keep ownership of name resolution (e.g. a remote
+    Pod or a caller-supplied tunnel). No network work occurs while creating a source.
+    """
+    if policy is None:
+        yield AddressCandidate(endpoint, "configured")
+        return
+    if policy.timeout_s <= 0 or policy.connection_pool_maxsize < 1:
+        raise ValueError("Address resolution limits must be positive")
+    seen: set[Endpoint] = set()
+    for host in dict.fromkeys((endpoint.host, *policy.fallback_hosts)):
+        configured = Endpoint(host, endpoint.port, endpoint.servername or endpoint.host)
+        try:
+            hosts, source = await _hosts(policy, configured, clients)
+            if not hosts:
+                raise AddressResolutionError(
+                    f"No addresses for {host!r}", kind=ErrorKind.RESOURCE_NOT_FOUND
+                )
+        except (OSError, TimeoutError, ToolboxError) as error:
+            kind = (
+                error.kind
+                if isinstance(error, ToolboxError)
+                else (
+                    ErrorKind.TIMEOUT
+                    if isinstance(error, TimeoutError)
+                    else ErrorKind.CONNECTION_FAILED
+                )
+            )
+            failure = AddressResolutionError(
+                f"Resolve {host!r} in environment "
+                f"{policy.environment.name if policy.environment else 'local'!r}: {kind.value}",
+                kind=kind,
+                code=error.code if isinstance(error, ToolboxError) else None,
+            )
+            failure.__cause__ = error
+            yield AddressCandidate(configured, "resolution", failure)
+            continue
+        for address in hosts:
+            resolved = Endpoint(address, endpoint.port, configured.servername)
+            if resolved not in seen:
+                seen.add(resolved)
+                yield AddressCandidate(resolved, source)

harness_toolbox-0.2.2/harness_toolbox/client.py

@@ -0,0 +1,8 @@
+"""Compatibility imports; generic client ownership lives in harness-common."""
+
+from harness_common.client import Client as Client
+from harness_common.client import ClientManager as ClientManager
+from harness_common.client import ClientProvider as ClientProvider
+from harness_common.client import DataSource as DataSource
+from harness_common.client import ServiceDataSource as ServiceDataSource
+from harness_common.client import data_source_key as data_source_key