rathflow-cli 0.1.0__py3-none-any.whl

rathflow_cli/http.py

@@ -0,0 +1,294 @@
+"""HTTP 层：JWT 登录/续期 + 错误信封 + 流式解码。
+
+契约依据：
+  - contracts/docs/error-envelope.md（错误信封与 HTTP 状态映射）
+  - contracts/docs/streaming.md §三（读取端最小实现要求，逐条落实）
+  - gateway/internal/gateway/cookiepost.go：「响应体 token 原样保留（SDK/CLI 走 Bearer）」
+    → CLI 只读响应体，**不碰 cookie**；也因此天然豁免 CSRF 门。
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Iterator
+
+import httpx
+
+from . import endpoints
+from .errors import ApiError, UsageError, from_response
+
+# 普通调用：读超时给足（上游 gateway 默认 10s，orchestrator 30s）
+_TIMEOUT = httpx.Timeout(connect=10.0, read=120.0, write=30.0, pool=10.0)
+# 流式：读超时关闭（沙箱命令可能长时间无输出仍存活）
+_STREAM_TIMEOUT = httpx.Timeout(connect=10.0, read=None, write=30.0, pool=10.0)
+
+# 到期前多久就主动刷新（秒）
+_REFRESH_MARGIN = 60
+
+
+class Client:
+    """一次进程内的 API 客户端（令牌变更经 persist 回调落盘）。"""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        project: str | None = None,
+        access_token: str | None = None,
+        refresh_token: str | None = None,
+        expires_at: float = 0.0,
+        persist=None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.project = project or None
+        self.access_token = access_token or None
+        self.refresh_token = refresh_token or None
+        self.expires_at = float(expires_at or 0)
+        self._persist = persist
+        # 客户端级超时取流式那份（read=None：沙箱里跑长命令时中途没输出也该活着）；
+        # 普通调用在 _open 里逐次传 _TIMEOUT 盖掉它。
+        self._http = httpx.Client(follow_redirects=False, timeout=_STREAM_TIMEOUT)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # ---------------------------------------------------------------- 令牌
+
+    def _absorb_tokens(self, payload: dict) -> None:
+        """从 LoginResponse 吸收令牌。protojson 把 int64 编成 JSON 字符串。"""
+        access = payload.get("accessToken") or payload.get("access_token")
+        refresh = payload.get("refreshToken") or payload.get("refresh_token")
+        if access:
+            self.access_token = access
+        if refresh:
+            self.refresh_token = refresh
+        ttl = payload.get("expiresInSeconds", payload.get("expires_in_seconds"))
+        try:
+            seconds = int(ttl) if ttl is not None else 0
+        except (TypeError, ValueError):
+            seconds = 0
+        if seconds > 0:
+            self.expires_at = time.time() + seconds - _REFRESH_MARGIN
+        elif access:
+            self.expires_at = time.time() + 15 * 60 - _REFRESH_MARGIN
+        if self._persist:
+            self._persist(self)
+
+    def login(self, email: str, password: str) -> dict:
+        payload = self._call_raw(
+            "POST",
+            endpoints.render_path("auth.Login", {}),
+            body={"email": email, "password": password},
+            allow_retry=False,
+        )
+        self._absorb_tokens(payload)
+        return payload
+
+    def logout(self) -> None:
+        if self.access_token:
+            try:
+                self._call_raw("POST", endpoints.render_path("auth.Logout", {}), body={})
+            except ApiError:
+                pass  # 幂等：服务端不可达也清本地
+        self.access_token = None
+        self.refresh_token = None
+        self.expires_at = 0.0
+        if self._persist:
+            self._persist(self)
+
+    def refresh(self) -> bool:
+        """用 refresh token 换新令牌。成功返回 True。refresh 会轮换 → 必须存回。"""
+        if not self.refresh_token:
+            return False
+        try:
+            payload = self._call_raw(
+                "POST",
+                endpoints.render_path("auth.Refresh", {}),
+                body={"refreshToken": self.refresh_token},
+                allow_retry=False,
+            )
+        except ApiError:
+            return False
+        self._absorb_tokens(payload)
+        return True
+
+    def ensure_token(self) -> None:
+        """无令牌 → 报未登录；临期且有 refresh → 先刷新。"""
+        if not self.access_token:
+            raise UsageError("未登录：先跑 `rathflow auth login`")
+        if self.refresh_token and self.expires_at and time.time() >= self.expires_at:
+            self.refresh()
+
+    # ---------------------------------------------------------------- 请求
+
+    def _headers(self) -> dict:
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": "rathflow-cli/0.1.0",
+        }
+        if self.access_token:
+            headers["Authorization"] = f"Bearer {self.access_token}"
+        if self.project:
+            # 作用域解析：路径 {project_id} 优先，其次本头（gateway/internal/resolve）
+            headers["X-RathFlow-Project"] = self.project
+        return headers
+
+    def _send(self, method: str, path: str, *, params=None, body=None, streaming: bool = False):
+        """带令牌发请求；401 → 刷新一次并重放。streaming 时响应未读体（调用方 close）。"""
+        self.ensure_token()
+        url = self.base_url + path
+        headers = self._headers()
+        for attempt in (0, 1):
+            try:
+                if streaming:
+                    req = self._http.build_request(
+                        method, url, headers=headers, params=params, json=body
+                    )
+                    resp = self._http.send(req, stream=True)
+                else:
+                    resp = self._http.request(
+                        method, url, headers=headers, params=params, json=body, timeout=_TIMEOUT
+                    )
+            except httpx.HTTPError as exc:
+                raise ApiError(0, "UNAVAILABLE", f"无法连接 {self.base_url}：{exc}") from None
+            if resp.status_code == 401 and attempt == 0 and self.refresh():
+                resp.close()
+                continue
+            return resp
+        return resp  # pragma: no cover — 循环必返回
+
+    def _send_unauthed(self, method: str, path: str, *, params=None, body=None):
+        """免登录端点：不发令牌、不做 401 重放（否则登录/注册会自我递归）。"""
+        try:
+            return self._http.request(
+                method,
+                self.base_url + path,
+                headers=self._headers(),
+                params=params,
+                json=body,
+                timeout=_TIMEOUT,
+            )
+        except httpx.HTTPError as exc:
+            raise ApiError(0, "UNAVAILABLE", f"无法连接 {self.base_url}：{exc}") from None
+
+    def _call_raw(
+        self, method: str, path: str, *, params=None, body=None, allow_retry: bool = True
+    ) -> dict:
+        """非流式调用：返回解码后的 JSON（空体 → {}）。"""
+        if allow_retry:
+            resp = self._send(method, path, params=params, body=body)
+        else:
+            resp = self._send_unauthed(method, path, params=params, body=body)
+        try:
+            raw = resp.read()
+            payload = _decode(raw) if raw else {}
+            if resp.status_code >= 400:
+                raise from_response(resp.status_code, payload)
+            return payload
+        finally:
+            resp.close()
+
+    def call(
+        self,
+        key: str | None = None,
+        *,
+        method: str | None = None,
+        path: str | None = None,
+        body: dict | None = None,
+        query: dict | None = None,
+        path_params: dict | None = None,
+        auth: bool = True,
+    ) -> dict:
+        """按端点 key（或显式 method/path）调用一次，返回响应 JSON。
+
+        auth=False 用于免登录端点（register / 公开读），不要求也不刷新令牌。
+        """
+        method, path = _resolve(key, method, path, path_params)
+        return self._call_raw(
+            method, path, params=_clean(query), body=body, allow_retry=auth
+        )
+
+    def stream(
+        self,
+        key: str | None = None,
+        *,
+        method: str | None = None,
+        path: str | None = None,
+        body: dict | None = None,
+        query: dict | None = None,
+        path_params: dict | None = None,
+    ) -> Iterator[dict]:
+        """流式调用：逐帧产出 `result` payload。
+
+        读取端纪律（streaming.md §三）：按行切帧；只认 result/error 两键；
+        未知键拒绝该帧；error 帧即流终结并按信封报错。
+        """
+        method, path = _resolve(key, method, path, path_params)
+        resp = self._send(method, path, params=_clean(query), body=body, streaming=True)
+        # 流式只认 GET/POST（其余方法本就不出流）；此处不额外校验，交给服务端
+        try:
+            if resp.status_code >= 400:
+                payload = _decode(resp.read())
+                raise from_response(resp.status_code, payload)
+            for line in resp.iter_lines():
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    frame = json.loads(line)
+                except json.JSONDecodeError:
+                    raise ApiError(
+                        resp.status_code, "UNKNOWN", "流中断：收到非 JSON 帧"
+                    ) from None
+                if not isinstance(frame, dict):
+                    raise ApiError(resp.status_code, "UNKNOWN", "流中断：帧不是对象")
+                if set(frame) == {"result"}:
+                    yield frame["result"]
+                elif set(frame) == {"error"}:
+                    raise from_response(resp.status_code, frame)
+                else:
+                    raise ApiError(
+                        resp.status_code,
+                        "UNKNOWN",
+                        f"流帧含未知键 {sorted(frame)}（前后端契约漂移，拒绝该帧）",
+                    )
+        finally:
+            resp.close()
+
+
+def _resolve(key, method, path, path_params) -> tuple[str, str]:
+    if key:
+        params = dict(path_params or {})
+        return endpoints.method_of(key), endpoints.render_path(key, params)
+    if not (method and path):
+        raise UsageError("需要端点 key，或显式 --method/--path")
+    return method.upper(), path
+
+
+def _clean(query: dict | None) -> dict | None:
+    """去掉 None 值；int64 类查询参数转字符串（protojson 惯例）。"""
+    if not query:
+        return None
+    out = {}
+    for k, v in query.items():
+        if v is None:
+            continue
+        out[k] = str(v).lower() if isinstance(v, bool) else v
+    return out or None
+
+
+def _decode(raw: bytes) -> dict:
+    if not raw:
+        return {}
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {"data": data}

rathflow_cli/output.py

@@ -0,0 +1,95 @@
+"""输出渲染：默认人类可读，`--json` 原样透传（脚本消费的唯一稳定形态）。
+
+`--json` **不重新编码**：protojson 已把 int64 编成字符串、Timestamp 编成 RFC3339、
+bytes 编成 base64；重新编码会失真，故直接 json.dumps 透传。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+_MAX_CELL = 48
+
+
+def _get(obj, dotted: str):
+    cur = obj
+    for part in dotted.split("."):
+        if isinstance(cur, dict):
+            cur = cur.get(part)
+        else:
+            return None
+        if cur is None:
+            return None
+    return cur
+
+
+def _cell(value) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (dict, list)):
+        text = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    else:
+        text = str(value)
+    text = text.replace("\n", " ")
+    if len(text) > _MAX_CELL:
+        text = text[: _MAX_CELL - 1] + "…"
+    return text
+
+
+def emit_json(payload) -> None:
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+
+
+def emit_object(obj: dict, *, json_out: bool) -> None:
+    if json_out:
+        emit_json(obj)
+        return
+    if not isinstance(obj, dict):
+        print(obj)
+        return
+    width = max((len(k) for k in obj), default=0)
+    for key, value in obj.items():
+        if value is None or value == "" or value == [] or value == {}:
+            continue
+        print(f"{key.ljust(width)}  {_cell(value)}")
+
+
+def emit_table(rows, columns, *, json_out: bool) -> None:
+    """rows = 对象列表；columns = [(表头, 点分路径)]。"""
+    if json_out:
+        emit_json(rows)
+        return
+    rows = list(rows or [])
+    if not rows:
+        print("(空)")
+        return
+    headers = [h for h, _ in columns]
+    body = [[_cell(_get(r, path)) for _, path in columns] for r in rows]
+    widths = [
+        max(len(headers[i]), max((len(row[i]) for row in body), default=0))
+        for i in range(len(headers))
+    ]
+    print("  ".join(headers[i].ljust(widths[i]) for i in range(len(headers))))
+    for row in body:
+        print("  ".join(row[i].ljust(widths[i]) for i in range(len(headers))))
+
+
+def emit_items(payload, *, items_key: str, columns, json_out: bool) -> None:
+    """分页响应：取 items_key 列表渲染；JSON 模式透传整包（保留 nextPageToken）。"""
+    if json_out:
+        emit_json(payload)
+        return
+    emit_table((payload or {}).get(items_key) or [], columns, json_out=False)
+    token = (payload or {}).get("nextPageToken")
+    if token:
+        print(f"\n(还有下一页：--page-token {token})")
+
+
+def write_bytes(data: bytes, *, to_stderr: bool = False) -> None:
+    stream = sys.stderr.buffer if to_stderr else sys.stdout.buffer
+    stream.write(data)
+    stream.flush()

rathflow_cli/selftest.py

@@ -0,0 +1,120 @@
+"""轻量自检（不联服务端）：``python -m rathflow_cli.selftest``
+
+查两件事，都是「装得上但会打错 URL」的那类毛病：
+
+1. **命令实现里不写 URL 字面量** —— 所有请求必须走 ``endpoints.py`` 的端点 key；
+2. **端点表与生成物一致** —— 生成物 ``endpoints.ts`` 由上游 proto 生成，本包的
+   ``endpoints.py`` 手工同步；两者漂移就会打错 URL。生成物在本仓库中不存在
+   （它是上游 monorepo 的产物），此时这一项跳过，可用环境变量
+   ``RATHFLOW_ENDPOINTS_TS`` 指向它来启用比对。
+"""
+
+from __future__ import annotations
+
+import re
+import os
+import sys
+from pathlib import Path
+
+from . import endpoints
+
+_COMMANDS = Path(__file__).resolve().parent / "commands"
+
+
+def _find_generated() -> Path | None:
+    """定位上游生成的 endpoints.ts；找不到就返回 None（跳过比对）。"""
+    override = os.environ.get("RATHFLOW_ENDPOINTS_TS")
+    if override:
+        candidate = Path(override)
+        return candidate if candidate.exists() else None
+    for base in Path(__file__).resolve().parents:
+        candidate = base / "web" / "lib" / "api" / "generated" / "endpoints.ts"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+_GENERATED = _find_generated()
+
+_ROW = re.compile(
+    r'\{ key: "(?P<key>[^"]+)", method: "(?P<method>\w+)", path: "(?P<path>[^"]+)",'
+    r" pathParams: \[(?P<pp>[^\]]*)\], multiParams: \[(?P<mp>[^\]]*)\],"
+    r".*?stream: (?P<stream>true|false),"
+)
+_URL_LITERAL = re.compile(r'"(?:/api/|/admin/api/)')
+
+
+def main() -> int:
+    generated_problems, compared = _check_generated()
+    problems = generated_problems + _check_no_url_literals()
+    if problems:
+        print(f"自检未通过（{len(problems)} 项）：", file=sys.stderr)
+        for line in problems:
+            print(f"  - {line}", file=sys.stderr)
+        return 1
+    total = len(endpoints.ENDPOINTS)
+    if compared:
+        print(f"自检通过：端点表与生成物一致（{total} 个端点）")
+    else:
+        print(f"自检通过：命令层无 URL 字面量（{total} 个端点；未找到生成物，跳过端点表比对）")
+    return 0
+
+
+def _check_generated() -> tuple[list[str], bool]:
+    """比对端点表与上游生成物；返回 (问题列表, 是否真的比对了)。"""
+    if _GENERATED is None or not _GENERATED.exists():
+        return [], False
+    rows = {}
+    for line in _GENERATED.read_text(encoding="utf-8").splitlines():
+        m = _ROW.search(line)
+        if not m:
+            continue
+        rows[m["key"]] = {
+            "method": m["method"],
+            "path": m["path"],
+            "multi": _names(m["mp"]),
+            "stream": m["stream"] == "true",
+        }
+
+    problems = []
+    missing = sorted(rows.keys() - endpoints.ENDPOINTS.keys())
+    extra = sorted(endpoints.ENDPOINTS.keys() - rows.keys())
+    if missing:
+        problems.append(f"endpoints.py 缺 {len(missing)} 个端点：{missing[:5]}…")
+    if extra:
+        problems.append(f"endpoints.py 多出 {len(extra)} 个端点：{extra[:5]}…")
+
+    for key in sorted(rows.keys() & endpoints.ENDPOINTS.keys()):
+        want, got = rows[key], endpoints.ENDPOINTS[key]
+        if (got[1], got[0]) != (want["path"], want["method"]):
+            problems.append(f"{key}: 路径/方法不一致 {got} vs {want['path']}/{want['method']}")
+        have_multi = set(endpoints.MULTI_PARAMS.get(key, frozenset()))
+        if have_multi != want["multi"]:
+            problems.append(f"{key}: multiParams 不一致 {sorted(have_multi)} vs {sorted(want['multi'])}")
+        if endpoints.is_streaming(key) != want["stream"]:
+            problems.append(f"{key}: stream 标记不一致 {endpoints.is_streaming(key)} vs {want['stream']}")
+
+    # 模板参数与 MULTI_PARAMS 声明必须对得上（多段参数一定出现在模板里）
+    for key in endpoints.ENDPOINTS:
+        declared = set(endpoints.MULTI_PARAMS.get(key, frozenset()))
+        unknown = declared - set(endpoints.path_params(key))
+        if unknown:
+            problems.append(f"{key}: MULTI_PARAMS 声明了模板里没有的参数 {sorted(unknown)}")
+    return problems, True
+
+
+def _check_no_url_literals() -> list[str]:
+    problems = []
+    for path in sorted(_COMMANDS.glob("*.py")):
+        for no, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+            if _URL_LITERAL.search(line) and not line.lstrip().startswith("#"):
+                problems.append(f"{path.name}:{no} 出现 URL 字面量（该走端点 key）")
+    return problems
+
+
+def _names(raw: str) -> set[str]:
+    return set(re.findall(r'"([^"]+)"', raw))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rathflow_cli/state.py

@@ -0,0 +1,129 @@
+"""进程内状态：合并「flag > 环境变量 > profile > 默认」并承载惰性 Client。"""
+
+from __future__ import annotations
+
+from . import config
+from .http import Client
+
+
+class State:
+    def __init__(
+        self,
+        *,
+        profile_name: str | None = None,
+        base_url: str | None = None,
+        project: str | None = None,
+        json_out: bool = False,
+        quiet: bool = False,
+    ):
+        self.data = config.load()
+        self.json_out = json_out
+        self.quiet = quiet
+        self._client: Client | None = None
+        self._flags = {"base_url": base_url, "project": project}
+        self.apply(profile_name=profile_name)
+        self.token_override = _env(config.ENV_TOKEN)
+
+    def apply(
+        self,
+        *,
+        profile_name: str | None = None,
+        base_url: str | None = None,
+        project: str | None = None,
+        json_out: bool = False,
+        quiet: bool = False,
+    ) -> None:
+        """合并一级选项。根回调先跑；子应用回调再跑一次（命令后写的选项）。
+
+        子应用层的显式选项优先；「优先级」仍是 flag > env > profile > 默认。
+        """
+        if profile_name:
+            self.data["current"] = profile_name
+        if base_url:
+            self._flags["base_url"] = base_url
+        if project:
+            self._flags["project"] = project
+        self.json_out = self.json_out or json_out
+        self.quiet = self.quiet or quiet
+
+        prof = self.profile
+        self.base_url = (
+            self._flags.get("base_url")
+            or _env(config.ENV_BASE_URL)
+            or prof.get("base_url")
+            or config.DEFAULT_BASE_URL
+        )
+        self.project = self._flags.get("project") or _env(config.ENV_PROJECT) or prof.get("project")
+
+    @property
+    def profile_name(self) -> str:
+        return self.data["current"]
+
+    @property
+    def profile(self) -> dict:
+        return config.profile(self.data, self.profile_name)
+
+    def client(self) -> Client:
+        if self._client is None:
+            prof = self.profile
+            if self.token_override:
+                # CI 场景：直接用环境变量令牌，不落盘、不刷新
+                self._client = Client(
+                    self.base_url, project=self.project, access_token=self.token_override
+                )
+            else:
+                self._client = Client(
+                    self.base_url,
+                    project=self.project,
+                    access_token=prof.get("access_token"),
+                    refresh_token=prof.get("refresh_token"),
+                    expires_at=prof.get("expires_at", 0),
+                    persist=self._persist,
+                )
+        return self._client
+
+    def _persist(self, client: Client) -> None:
+        """令牌变更落盘（refresh 会轮换 refresh token，必须存回）。"""
+        prof = self.profile
+        prof["access_token"] = client.access_token
+        prof["refresh_token"] = client.refresh_token
+        prof["expires_at"] = client.expires_at
+        config.save(self.data)
+
+    def remember_identity(self, login_payload: dict) -> None:
+        """记下登录响应里的身份信息（whoami 的数据源）。"""
+        prof = self.profile
+        prof["user"] = {
+            "user_id": login_payload.get("userId"),
+            "org_id": login_payload.get("orgId"),
+            "is_platform_admin": bool(login_payload.get("isPlatformAdmin")),
+        }
+        if login_payload.get("defaultProjectId") and not prof.get("project"):
+            prof["project"] = login_payload["defaultProjectId"]
+        self.data["profiles"][self.profile_name] = prof
+        config.save(self.data)
+
+
+def _env(name: str) -> str | None:
+    import os
+
+    return os.environ.get(name) or None
+
+
+# 当前进程的 State：根回调在派发子命令前写入，命令实现用 current() 取。
+# 用模块级单例而非 click 的 ctx 链：typer 0.16 起自带的 click 已不再是独立包，
+# 取「当前 Context」需要私有路径，跨版本不可靠。CLI 是单次进程，单例足够。
+_CURRENT: State | None = None
+
+
+def install(state: State) -> None:
+    """根回调调用（每个进程一次）。"""
+    global _CURRENT
+    _CURRENT = state
+
+
+def current() -> State:
+    """取当前命令的 State（由根回调注入）。"""
+    if _CURRENT is None:
+        raise RuntimeError("State 未初始化（内部错误）")
+    return _CURRENT