tinet-agent-cli 0.1.0.dev36__py3-none-any.whl

taco/core/developer_center_client.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+
+from taco.core.errors import TacoError
+from taco.core.http_headers import with_cli_user_agent
+from taco.core.openapi_signer import OpenApiSigner
+
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+_TIME_ERROR_CODES = frozenset(
+    {"SignaturesExpired", "SignatureExpired", "RequestTimeTooSkewed"}
+)
+
+
+class DeveloperCenterClient:
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        access_key_id: str,
+        access_key_secret: str,
+        http_client: httpx.Client | None = None,
+        timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+        now_provider: Callable[[], datetime] | None = None,
+    ) -> None:
+        self.signer = OpenApiSigner(
+            endpoint=endpoint,
+            access_key_id=access_key_id,
+            access_key_secret=access_key_secret,
+        )
+        self.endpoint = self.signer.endpoint
+        self._owns_http_client = http_client is None
+        self.http_client = http_client or httpx.Client(timeout=timeout_seconds)
+        self._now_provider = now_provider or (lambda: datetime.now(UTC))
+
+    def close(self) -> None:
+        if self._owns_http_client:
+            self.http_client.close()
+
+    def __enter__(self) -> DeveloperCenterClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def cli_auth(self) -> dict[str, Any]:
+        path = "/agent/v1/cli-auth"
+        payload = self.request_json("POST", path)
+        if not isinstance(payload, dict) or not isinstance(
+            payload.get("result"), dict
+        ):
+            raise _invalid_response_error(path, _request_id(payload))
+        result = payload["result"]
+        access_token = result.get("access_token")
+        if not isinstance(access_token, str) or not access_token.strip():
+            raise _invalid_response_error(path, _request_id(payload))
+        return result
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        json_body: Any = None,
+    ) -> Any:
+        signed = self.signer.sign(
+            method,
+            path,
+            query,
+            now=self._now_provider(),
+        )
+        try:
+            response = self.http_client.request(
+                method,
+                f"{self.endpoint}{path}",
+                params=signed.params,
+                json=json_body,
+                headers=with_cli_user_agent(),
+            )
+        except httpx.TimeoutException:
+            raise TacoError(
+                code="OPENAPI_TIMEOUT",
+                message="开发者中心请求超时。",
+                exit_code=4,
+                path=path,
+                hint="请检查网络连接后重试。",
+            ) from None
+        except httpx.HTTPError:
+            raise TacoError(
+                code="OPENAPI_CONNECTION_FAILED",
+                message="无法连接开发者中心。",
+                exit_code=4,
+                path=path,
+                hint="请检查网络、代理、证书和 endpoint。",
+            ) from None
+
+        if response.status_code >= 400:
+            raise _request_error(response, path)
+        try:
+            return response.json()
+        except ValueError:
+            raise _invalid_response_error(path) from None
+
+
+def _request_error(response: httpx.Response, path: str) -> TacoError:
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+    remote_code, request_id = _safe_error_fields(payload)
+    hint = "请检查 AccessKey 权限、IP 白名单和请求参数。"
+    if remote_code in _TIME_ERROR_CODES:
+        hint = "请检查本机 UTC 时间并启用 NTP 时间同步后重试。"
+    return TacoError(
+        code="OPENAPI_REQUEST_FAILED",
+        message=f"开发者中心请求失败，HTTP 状态码 {response.status_code}。",
+        exit_code=4,
+        status=response.status_code,
+        hint=hint,
+        remote_code=remote_code,
+        request_id=request_id,
+        path=path,
+    )
+
+
+def _safe_error_fields(payload: Any) -> tuple[str | None, str | None]:
+    if not isinstance(payload, dict):
+        return None, None
+    request_id = _request_id(payload)
+    detail = payload.get("error")
+    if not isinstance(detail, dict):
+        detail = payload
+    remote_code = detail.get("code")
+    if not isinstance(remote_code, str) or not remote_code.strip():
+        remote_code = None
+    return remote_code, request_id
+
+
+def _request_id(payload: Any) -> str | None:
+    if not isinstance(payload, dict):
+        return None
+    request_id = payload.get("requestId")
+    if isinstance(request_id, str) and request_id.strip():
+        return request_id
+    return None
+
+
+def _invalid_response_error(
+    path: str,
+    request_id: str | None = None,
+) -> TacoError:
+    return TacoError(
+        code="OPENAPI_RESPONSE_INVALID",
+        message="开发者中心成功响应不是合法的 JSON 业务对象。",
+        exit_code=4,
+        hint="请根据 requestId 检查网关和服务端响应。",
+        request_id=request_id,
+        path=path,
+    )

taco/core/errors.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class TacoError(Exception):
+    code: str
+    message: str
+    exit_code: int = 1
+    status: int | None = None
+    hint: str | None = None
+    remote_code: str | None = None
+    app_id: str | None = None
+    request_id: str | None = None
+    path: str | None = None
+
+    def __post_init__(self) -> None:
+        Exception.__init__(self, self.message)

taco/core/file_lock.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from filelock import FileLock, Timeout
+
+from taco.core.errors import TacoError
+
+
+DEFAULT_LOCK_TIMEOUT_SECONDS = 10.0
+LOCK_POLL_INTERVAL_SECONDS = 0.05
+
+
+class InterProcessFileLock:
+    """Cross-platform advisory file lock with bounded waiting."""
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        timeout_seconds: float = DEFAULT_LOCK_TIMEOUT_SECONDS,
+    ) -> None:
+        self.path = path
+        self.timeout_seconds = max(0.0, timeout_seconds)
+        self._lock = FileLock(
+            path,
+            timeout=self.timeout_seconds,
+            mode=0o600,
+        )
+        self._acquired = False
+
+    def acquire(self) -> None:
+        if self._acquired:
+            return
+        try:
+            self._lock.acquire(
+                timeout=self.timeout_seconds,
+                poll_interval=LOCK_POLL_INTERVAL_SECONDS,
+            )
+            self._acquired = True
+            try:
+                self.path.chmod(0o600)
+            except OSError:
+                pass
+        except Timeout:
+            raise TacoError(
+                code="CONFIG_FILE_BUSY",
+                message="TACO 配置文件正被其他进程修改。",
+                exit_code=2,
+                hint="请稍后重试。",
+                path=str(self.path),
+            ) from None
+        except OSError as error:
+            raise _lock_file_error(self.path) from error
+
+    def release(self) -> None:
+        if not self._acquired:
+            return
+        self._acquired = False
+        try:
+            self._lock.release()
+        except OSError as error:
+            raise _lock_file_error(self.path) from error
+
+    def __enter__(self) -> InterProcessFileLock:
+        self.acquire()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.release()
+
+
+def _lock_file_error(path: Path) -> TacoError:
+    return TacoError(
+        code="CONFIG_FILE_WRITE_FAILED",
+        message="无法创建或锁定 TACO 配置锁文件。",
+        exit_code=2,
+        hint=f"请检查目录权限和文件类型：{path.parent}",
+        path=str(path),
+    )

taco/core/http_headers.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from taco import __version__
+
+
+def cli_user_agent() -> str:
+    return f"CLI/TACO/{__version__}"
+
+
+def with_cli_user_agent(
+    headers: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    merged = {
+        key: value
+        for key, value in (headers or {}).items()
+        if key.lower() != "user-agent"
+    }
+    merged["User-Agent"] = cli_user_agent()
+    return merged

taco/core/openapi_signer.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import ipaddress
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+from urllib.parse import quote, urlsplit
+
+from taco.core.errors import TacoError
+
+
+DEFAULT_EXPIRES_SECONDS = 60
+MIN_EXPIRES_SECONDS = 1
+MAX_EXPIRES_SECONDS = 86400
+RESERVED_QUERY_NAMES = frozenset(
+    {"AccessKeyId", "Expires", "Timestamp", "Signature"}
+)
+ALLOWED_METHODS = frozenset({"GET", "POST", "PUT", "DELETE", "PATCH"})
+_DOMAIN_PATTERN = re.compile(r"^[A-Za-z0-9.-]+$")
+
+
+@dataclass(frozen=True, slots=True)
+class SignedRequest:
+    params: tuple[tuple[str, str], ...] = field(repr=False)
+    signature: str = field(repr=False)
+    canonical_string: str = field(repr=False)
+
+
+class OpenApiSigner:
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        access_key_id: str,
+        access_key_secret: str,
+        expires: int = DEFAULT_EXPIRES_SECONDS,
+    ) -> None:
+        self.endpoint, self.authority = normalize_endpoint(endpoint)
+        if not access_key_id.strip() or not access_key_secret.strip():
+            raise TacoError(
+                code="OPENAPI_CREDENTIAL_REQUIRED",
+                message="AccessKeyId 和 AccessKeySecret 不能为空。",
+                exit_code=2,
+            )
+        if not MIN_EXPIRES_SECONDS <= expires <= MAX_EXPIRES_SECONDS:
+            raise TacoError(
+                code="OPENAPI_EXPIRES_INVALID",
+                message="签名有效时间必须在 1 到 86400 秒之间。",
+                exit_code=2,
+            )
+        self._access_key_id = access_key_id
+        self._access_key_secret = access_key_secret
+        self._expires = expires
+
+    def sign(
+        self,
+        method: str,
+        path: str,
+        query: Mapping[str, Any] | None = None,
+        *,
+        now: datetime | None = None,
+    ) -> SignedRequest:
+        normalized_method = method.upper()
+        if normalized_method not in ALLOWED_METHODS:
+            raise TacoError(
+                code="OPENAPI_METHOD_INVALID",
+                message="开发者中心请求方法不受支持。",
+                exit_code=2,
+                path=_safe_path(path),
+            )
+        _validate_path(path)
+        timestamp = _format_timestamp(now or datetime.now(UTC))
+        business_params = _expand_query(query or {})
+        common_params = [
+            ("AccessKeyId", self._access_key_id),
+            ("Expires", str(self._expires)),
+            ("Timestamp", timestamp),
+        ]
+        unsigned_params = tuple(sorted((*business_params, *common_params)))
+        encoded_query = "&".join(
+            f"{_encode(name)}={_encode(value)}" for name, value in unsigned_params
+        )
+        canonical_string = (
+            f"{normalized_method}{self.authority}{path}?{encoded_query}"
+        )
+        digest = hmac.new(
+            self._access_key_secret.encode("utf-8"),
+            canonical_string.encode("utf-8"),
+            hashlib.sha1,
+        ).digest()
+        signature = base64.b64encode(digest).decode("ascii")
+        return SignedRequest(
+            params=(*unsigned_params, ("Signature", signature)),
+            signature=signature,
+            canonical_string=canonical_string,
+        )
+
+
+def normalize_endpoint(endpoint: str) -> tuple[str, str]:
+    try:
+        parsed = urlsplit(endpoint)
+        port = parsed.port
+    except (TypeError, ValueError) as error:
+        raise _endpoint_error() from error
+    if (
+        parsed.scheme.lower() != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path not in ("", "/")
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise _endpoint_error()
+
+    host = parsed.hostname.lower()
+    if any(character.isspace() for character in host):
+        raise _endpoint_error()
+    try:
+        ipaddress.ip_address(host)
+        is_ipv6 = ":" in host
+    except ValueError:
+        if not _DOMAIN_PATTERN.fullmatch(host):
+            raise _endpoint_error()
+        is_ipv6 = False
+
+    authority = f"[{host}]" if is_ipv6 else host
+    if port is not None and port != 443:
+        authority = f"{authority}:{port}"
+    return f"https://{authority}", authority
+
+
+def _expand_query(query: Mapping[str, Any]) -> list[tuple[str, str]]:
+    params: list[tuple[str, str]] = []
+    for name, value in query.items():
+        if not isinstance(name, str) or not name:
+            raise TacoError(
+                code="OPENAPI_QUERY_INVALID",
+                message="开发者中心 Query 参数名必须是非空字符串。",
+                exit_code=2,
+            )
+        if name in RESERVED_QUERY_NAMES:
+            raise TacoError(
+                code="OPENAPI_QUERY_RESERVED",
+                message="业务参数不能覆盖开发者中心公共鉴权参数。",
+                exit_code=2,
+            )
+        if value is None:
+            continue
+        if isinstance(value, Sequence) and not isinstance(
+            value, (str, bytes, bytearray)
+        ):
+            for index, item in enumerate(value):
+                params.append((f"{name}[{index}]", _query_value(item)))
+        else:
+            params.append((name, _query_value(value)))
+    return params
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (str, int, float)):
+        return str(value)
+    raise TacoError(
+        code="OPENAPI_QUERY_INVALID",
+        message="开发者中心 Query 参数值类型不受支持。",
+        exit_code=2,
+    )
+
+
+def _format_timestamp(value: datetime) -> str:
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise TacoError(
+            code="OPENAPI_TIMESTAMP_INVALID",
+            message="签名时间必须包含时区。",
+            exit_code=2,
+        )
+    return value.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _validate_path(path: str) -> None:
+    parsed = urlsplit(path)
+    if (
+        not path.startswith("/")
+        or path.startswith("//")
+        or parsed.scheme
+        or parsed.netloc
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise TacoError(
+            code="OPENAPI_PATH_INVALID",
+            message="开发者中心 API path 必须是绝对路径且不能包含 Query 或 fragment。",
+            exit_code=2,
+            path=_safe_path(path),
+        )
+
+
+def _safe_path(path: object) -> str | None:
+    if not isinstance(path, str):
+        return None
+    return path.split("?", 1)[0].split("#", 1)[0]
+
+
+def _encode(value: str) -> str:
+    return quote(value, safe="-_.~", encoding="utf-8", errors="strict")
+
+
+def _endpoint_error() -> TacoError:
+    return TacoError(
+        code="OPENAPI_ENDPOINT_INVALID",
+        message="开发者中心 endpoint 必须是 HTTPS 平台根地址。",
+        exit_code=2,
+        hint="只允许 scheme、host 和可选端口，不能包含路径、用户信息、Query 或 fragment。",
+    )

taco/core/output.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+
+from taco.core.context import get_cli_context
+from taco.core.errors import TacoError
+
+
+def mask_token(token: str | None) -> str:
+    if not token:
+        return ""
+    if len(token) <= 8:
+        return "***"
+    return f"{token[:4]}...{token[-4:]}"
+
+
+def success(data: Any) -> dict[str, Any]:
+    return {"ok": True, "data": data}
+
+
+def failure(error: TacoError) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "code": error.code,
+        "message": error.message,
+        "exit_code": error.exit_code,
+    }
+    if error.status is not None:
+        payload["status"] = error.status
+    if error.hint is not None:
+        payload["hint"] = error.hint
+    if error.app_id is not None:
+        payload["app_id"] = error.app_id
+    if error.remote_code is not None:
+        payload["remote_code"] = error.remote_code
+    if error.request_id is not None:
+        payload["request_id"] = error.request_id
+    if error.path is not None:
+        payload["path"] = error.path
+    return {"ok": False, "error": payload}
+
+
+def to_json_line(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+def emit_success(
+    ctx: typer.Context,
+    data: Any,
+    *,
+    human_message: str | None = None,
+    json_default: bool = False,
+) -> None:
+    if get_cli_context(ctx).json_output or json_default or human_message is None:
+        typer.echo(to_json_line(success(data)))
+    else:
+        typer.echo(human_message)
+
+
+def exit_with_error(
+    ctx: typer.Context,
+    error: TacoError,
+    *,
+    json_default: bool = False,
+) -> None:
+    if get_cli_context(ctx).json_output or json_default:
+        typer.echo(to_json_line(failure(error)), err=True)
+    else:
+        typer.echo(f"{error.code}: {error.message}", err=True)
+    raise typer.Exit(error.exit_code)