harness-toolbox 0.2.2__py3-none-any.whl

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/__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/_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/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/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

harness_toolbox/diagnostics.py

@@ -0,0 +1,73 @@
+"""Connection evidence is client state, separate from the exception contract."""
+
+from copy import deepcopy
+from dataclasses import asdict
+
+from harness_toolbox.errors import ToolboxError
+from harness_toolbox.transport import Endpoint
+
+
+def _transport_name(transport: object) -> str:
+    from harness_toolbox.transport import DirectTransport, PodPythonTransport, PortForwardTransport
+
+    for kind, name in (
+        (PodPythonTransport, "pod-python"),
+        (PortForwardTransport, "port-forward"),
+        (DirectTransport, "direct"),
+    ):
+        if isinstance(transport, kind):
+            return name
+    return type(transport).__name__
+
+
+class _AccessRecorder:
+    """Client-owned state; callers receive detached snapshots."""
+
+    def __init__(self, protocol: str) -> None:
+        self.protocol = protocol
+        self.target: dict | None = None
+        self.attempts: list[dict] = []
+        self.selected_transport: str | None = None
+        self.selected_endpoint: dict | None = None
+
+    def snapshot(self) -> dict:
+        return deepcopy(
+            {
+                "protocol": self.protocol,
+                "target": self.target,
+                "selected_transport": self.selected_transport,
+                "selected_endpoint": self.selected_endpoint,
+                "attempts": self.attempts,
+            }
+        )
+
+    def failed(
+        self,
+        transport: str,
+        error: ToolboxError,
+        endpoint: Endpoint | None = None,
+        source: str = "configured",
+    ) -> None:
+        self.attempts.append(
+            {
+                "transport": transport,
+                "endpoint": asdict(endpoint) if endpoint else None,
+                "source": source,
+                "status": "error",
+                "error": {"kind": error.kind, "code": error.code, "message": error.message},
+            }
+        )
+
+    def connected(
+        self, transport: str, endpoint: Endpoint | None = None, source: str = "configured"
+    ) -> None:
+        self.selected_endpoint = asdict(endpoint) if endpoint else None
+        self.attempts.append(
+            {
+                "transport": transport,
+                "endpoint": self.selected_endpoint,
+                "source": source,
+                "status": "ok",
+            }
+        )
+        self.selected_transport = transport

harness_toolbox/environment.py

@@ -0,0 +1,31 @@
+"""Associate logical runtime identities with independently configured data sources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from harness_common.environment import KubernetesEnvironment
+
+if TYPE_CHECKING:
+    from harness_toolbox.kube import KubernetesDataSource, Options
+
+
+def kubernetes_source(environment: KubernetesEnvironment, options: Options) -> KubernetesDataSource:
+    """Adapt environment access facts, with explicit namespace and capacity limits.
+
+    Logical environment names do not replace physical connection identity.
+    """
+    from harness_toolbox.kube import KubernetesDataSource
+
+    if environment.host is not None:
+        environment.host.validate()
+        if environment.host.transport == "ssh":
+            raise ValueError(
+                "KubernetesDataSource requires local cluster access; run the client on "
+                "Environment.host via host.command"
+            )
+    return KubernetesDataSource(
+        options,
+        kubeconfig=environment.kubeconfig or None,
+        context_name=environment.context,
+    )

harness_toolbox/errors.py

@@ -0,0 +1,56 @@
+"""Public failure contract; protocol adapters own native exception translation."""
+
+from enum import StrEnum
+
+
+class ErrorKind(StrEnum):
+    CONNECTION_FAILED = "connection_failed"
+    CONNECTION_LOST = "connection_lost"
+    TLS_VERIFICATION_FAILED = "tls_verification_failed"
+    AUTHENTICATION_FAILED = "authentication_failed"
+    PERMISSION_DENIED = "permission_denied"
+    RESOURCE_NOT_FOUND = "resource_not_found"
+    TIMEOUT = "timeout"
+    LIMIT_EXCEEDED = "limit_exceeded"
+    INVALID_RESPONSE = "invalid_response"
+    OPERATION_FAILED = "operation_failed"
+
+
+class ToolboxError(Exception):
+    """A safe message, stable kind and optional protocol-native code.
+
+    why: Consumers catch toolbox types rather than depending on driver exceptions.
+    Messages must omit credentials and query payloads; native exceptions belong in
+    ``__cause__`` for debugging, not in user-facing reports. Serialization and retry
+    decisions belong to callers, not to this exception contract.
+    """
+
+    def __init__(self, message: str, *, kind: ErrorKind, code: int | str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.kind = kind
+        self.code = code
+
+
+class MySQLError(ToolboxError):
+    """MySQL access failed."""
+
+
+class MySQLConnectionError(MySQLError):
+    """Connection acquisition or probing failed, before user SQL execution."""
+
+
+class MySQLQueryError(MySQLError):
+    """Query execution or result collection failed; side effects may have occurred."""
+
+
+class OpenSearchError(ToolboxError):
+    """OpenSearch access failed."""
+
+
+class OpenSearchConnectionError(OpenSearchError):
+    """Connection acquisition or probing failed, before the user request."""
+
+
+class OpenSearchRequestError(OpenSearchError):
+    """Request execution or response collection failed."""

harness_toolbox/host.py

@@ -0,0 +1,44 @@
+"""Host observations shared by quality runners and project-owned fixtures."""
+
+import platform
+import shlex
+from collections.abc import Sequence
+from datetime import UTC, datetime
+
+from harness_common.environment import EnvironmentFacts
+from harness_common.host import Host
+
+
+def command(host: Host | None, argv: Sequence[str]) -> list[str]:
+    """Build local/SSH argv for process.execute's bounded I/O and timeout.
+
+    Remote commands use the host's filesystem, including kubeconfig paths.
+    Resource teardown remains the calling fixture's responsibility.
+    """
+    if not argv or not argv[0]:
+        raise ValueError("host command requires a program")
+    if host is not None:
+        host.validate()
+        if host.transport == "ssh":
+            return [
+                "ssh",
+                "-o",
+                "BatchMode=yes",
+                "-o",
+                "ConnectTimeout=10",
+                host.address,
+                shlex.join(argv),
+            ]
+    return list(argv)
+
+
+def observe_local() -> EnvironmentFacts:
+    """Observe this process's host; never use these values for a remote target."""
+    os_name = platform.system().lower()
+    arch = {"x86_64": "amd64", "aarch64": "arm64"}.get(platform.machine(), platform.machine())
+    values = {"os": os_name, "arch": arch, "kernel_version": platform.release()}
+    if os_name == "linux":
+        distribution = platform.freedesktop_os_release()
+        values["distribution"] = distribution.get("ID", "")
+        values["distribution_version"] = distribution.get("VERSION_ID", "")
+    return EnvironmentFacts("local:uname,os-release", datetime.now(UTC).isoformat(), values)

harness_toolbox/kube/__init__.py

@@ -0,0 +1,11 @@
+"""Namespace-scoped Kubernetes control and observation."""
+
+from harness_toolbox.kube.client import KubernetesClient as KubernetesClient
+from harness_toolbox.kube.client import KubernetesDataSource as KubernetesDataSource
+from harness_toolbox.kube.model import Event as Event
+from harness_toolbox.kube.model import Options as Options
+from harness_toolbox.kube.model import Pod as Pod
+from harness_toolbox.kube.model import PodRef as PodRef
+from harness_toolbox.kube.model import PodSpec as PodSpec
+from harness_toolbox.kube.model import ResourceNotFoundError as ResourceNotFoundError
+from harness_toolbox.process import ExecResult as ExecResult