cheso-cli 0.2.0__py3-none-any.whl

cheso_cli/__init__.py

@@ -0,0 +1,12 @@
+"""Cheso 命令行工具。"""
+
+from cheso_cli.config import VERSION as __version__
+
+__all__ = ["__version__", "main"]
+
+
+def main(argv: list[str] | None = None) -> None:
+    """命令行脚本入口（``cheso`` / ``cheso-cli``）。"""
+    from cheso_cli.cli import main as _main
+
+    _main(argv)

cheso_cli/__main__.py

@@ -0,0 +1,5 @@
+"""模块启动入口：``python -m cheso_cli``。"""
+
+from cheso_cli.cli import main
+
+main()

cheso_cli/auth.py

@@ -0,0 +1,128 @@
+"""决定命令使用哪个令牌，并在需要时刷新已保存的 OAuth 访问令牌。
+
+优先级：``--token`` > ``CHESO_API_TOKEN`` > ``cheso login`` 保存的凭据。
+
+刷新令牌每次使用后都会轮换；服务器再次收到已使用的刷新令牌时，会撤销整个授权。
+Agent 经常同时运行多个 ``cheso`` 命令，因此刷新操作始终持有凭据文件锁，并在拿到锁后重新读取文件。
+如果其他进程已经完成刷新，就使用其新访问令牌，避免用已经失效的刷新令牌再次刷新。
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable, Mapping
+
+import httpx
+
+from cheso_cli.client import StaticToken, TokenSource
+from cheso_cli.config import DEFAULT_SITE, ENV_TOKEN, SITES, Settings
+from cheso_cli.credentials import CredentialStore, SiteCredentials
+from cheso_cli.errors import LoginRequired
+from cheso_cli.oauth import ERROR_INVALID_CLIENT, ERROR_INVALID_GRANT, OAuthClient, OAuthProtocolError
+
+# 访问令牌将在以下秒数内过期时提前刷新。
+REFRESH_SKEW_SECONDS = 60.0
+
+TOKEN_SOURCE_FLAG = "--token"
+TOKEN_SOURCE_ENV = ENV_TOKEN
+TOKEN_SOURCE_LOGIN = "login"
+
+
+def login_hint(settings: Settings) -> str:
+    """当前站点的登录命令，例如 ``cheso login --site cn``。"""
+    for name, url in SITES.items():
+        if settings.base_url == url:
+            return "cheso login" if name == DEFAULT_SITE else f"cheso login --site {name}"
+    return f"cheso login --base-url {settings.base_url}"
+
+
+class OAuthSession(TokenSource):
+    """从凭据文件读取访问令牌，需要时在文件锁内刷新。"""
+
+    def __init__(
+        self,
+        settings: Settings,
+        store: CredentialStore,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        now: Callable[[], float] = time.time,
+    ) -> None:
+        self.settings = settings
+        self.store = store
+        self._transport = transport
+        self._now = now
+        self.refresh_count = 0
+
+    def _fresh(self, creds: SiteCredentials) -> bool:
+        return bool(creds.access_token) and creds.expires_at - self._now() > REFRESH_SKEW_SECONDS
+
+    def token(self) -> str:
+        creds = self.store.get(self.settings.base_url)
+        if not creds.logged_in:
+            raise self._login_required("Not logged in")
+        if self._fresh(creds):
+            return creds.access_token
+        return self._refresh(rejected=None)
+
+    def refresh_after_unauthorized(self, rejected: str) -> str | None:
+        return self._refresh(rejected=rejected)
+
+    def _refresh(self, *, rejected: str | None) -> str:
+        """在锁内刷新。``rejected`` 是服务器刚以 401 拒绝的访问令牌，没有时为空。"""
+        base = self.settings.base_url
+        with self.store.locked():
+            creds = self.store.get(base)
+            if not creds.logged_in:
+                raise self._login_required("Not logged in")
+            # 等待锁期间，其他进程可能已经刷新了令牌。
+            if self._fresh(creds) and creds.access_token != rejected:
+                return creds.access_token
+            if not creds.refresh_token or not creds.client_id:
+                creds.clear_tokens()
+                self.store.put(base, creds)
+                raise self._login_required("The login has expired")
+            with OAuthClient(self.settings, transport=self._transport, now=self._now) as oauth:
+                endpoint = creds.token_endpoint or oauth.metadata().token_endpoint
+                try:
+                    tokens = oauth.refresh(endpoint, client_id=creds.client_id, refresh_token=creds.refresh_token)
+                except OAuthProtocolError as e:
+                    if e.error not in (ERROR_INVALID_GRANT, ERROR_INVALID_CLIENT):
+                        raise
+                    creds.clear_tokens()
+                    if e.error == ERROR_INVALID_CLIENT:
+                        creds.client_id = ""
+                    self.store.put(base, creds)
+                    raise self._login_required("The login has expired or was revoked") from e
+            self.refresh_count += 1
+            creds.access_token = tokens.access_token
+            creds.refresh_token = tokens.refresh_token or creds.refresh_token
+            creds.expires_at = tokens.expires_at
+            creds.token_endpoint = endpoint
+            self.store.put(base, creds)
+            return creds.access_token
+
+    def _login_required(self, what: str) -> LoginRequired:
+        return LoginRequired(f"{what} for {self.settings.base_url}. Run `{login_hint(self.settings)}`.")
+
+
+def resolve_token_source(
+    settings: Settings,
+    store: CredentialStore,
+    *,
+    token_flag: str | None,
+    env: Mapping[str, str] | None = None,
+    transport: httpx.BaseTransport | None = None,
+    now: Callable[[], float] = time.time,
+) -> tuple[TokenSource, str]:
+    """返回令牌来源及其名称（``--token``、``CHESO_API_TOKEN`` 或 ``login``）。"""
+    env = os.environ if env is None else env
+    if token_flag:
+        return StaticToken(token_flag), TOKEN_SOURCE_FLAG
+    env_token = env.get(ENV_TOKEN, "").strip()
+    if env_token:
+        return StaticToken(env_token), TOKEN_SOURCE_ENV
+    creds = store.get(settings.base_url)
+    if not creds.logged_in:
+        raise LoginRequired(f"Not logged in to {settings.base_url}. Run `{login_hint(settings)}` (or set {ENV_TOKEN}).")
+    return OAuthSession(settings, store, transport=transport, now=now), TOKEN_SOURCE_LOGIN