"""Safe HTTP-over-Unix-socket client for the Codex route controller. The client intentionally has no support for authorization headers, arbitrary URLs, or arbitrary controller paths. Upstream credentials belong to the controller and the model gateway; this AstrBot plugin only sends route identifiers and actor identifiers. """ from __future__ import annotations import json import os import re import stat from dataclasses import dataclass from typing import Any from urllib.parse import quote import aiohttp SOCKET_PATH = "/run/codex-route/control.sock" _HTTP_ORIGIN = "http://localhost" _MAX_RESPONSE_BYTES = 1024 * 1024 _MAX_SAFE_TEXT = 600 _URL_RE = re.compile(r"(?i)\bhttps?://[^\s<>'\"]+") _BEARER_RE = re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+") _KEY_VALUE_RE = re.compile( r"(?i)\b(?:api[_-]?key|authorization|token|secret|password)\b" r"\s*[:=]\s*[^\s,;]+" ) _OPENAI_KEY_RE = re.compile(r"(?i)\bsk-[A-Za-z0-9_-]{8,}") _JWT_RE = re.compile( r"\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\b" ) _CONTROL_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]") _ROUTE_FIELDS = { "route_id", "id", "name", "display_name", "active", "is_active", "enabled", "deleted", "healthy", "health", "status", "model", "cost_multiplier", "multiplier", "revision", "updated_at", "last_test_at", "latency_ms", } _STATUS_FIELDS = { "active_route_id", "active_route", "route_id", "revision", "state", "status", "healthy", "health", "busy_tasks", "active_tasks", "pending_route", "can_switch", "changed_at", "updated_at", "last_test_at", "latency_ms", } _HISTORY_FIELDS = { "revision", "action", "route_id", "from_route", "to_route", "actor", "created_at", "updated_at", "timestamp", "result", "success", "status", "message", } _OPERATION_FIELDS = { "route_id", "display_name", "active_route_id", "previous_route_id", "revision", "rolled_back_to", "healthy", "health", "success", "status", "model", "latency_ms", "responses_ok", "streaming_ok", "sse_ok", "tool_call_ok", "tool_result_ok", "checks", } _CHECK_FIELDS = { "auth", "model", "responses", "streaming", "sse", "tool_call", "tool_result", "canary", } def sanitize_text(value: object, *, max_length: int = _MAX_SAFE_TEXT) -> str: """Return controller text with common credential and endpoint forms removed.""" text = _CONTROL_RE.sub("", str(value or "")) text = _BEARER_RE.sub("[REDACTED_CREDENTIAL]", text) text = _KEY_VALUE_RE.sub("[REDACTED_CREDENTIAL]", text) text = _OPENAI_KEY_RE.sub("[REDACTED_CREDENTIAL]", text) text = _JWT_RE.sub("[REDACTED_CREDENTIAL]", text) text = _URL_RE.sub("[REDACTED_URL]", text) text = text.strip() if len(text) > max_length: return text[: max_length - 1] + "…" return text class GatewayError(RuntimeError): """An error that is already safe to present to an AstrBot administrator.""" def __init__( self, safe_message: str, *, status: int | None = None, code: str | None = None, ) -> None: super().__init__(safe_message) self.safe_message = sanitize_text(safe_message) or "路由控制器请求失败" self.status = status self.code = sanitize_text(code, max_length=80) if code else None @dataclass(slots=True, frozen=True) class ControllerResponse: """Sanitized response returned to the plugin UI layer.""" message: str data: dict[str, Any] class GatewayClient: """Whitelisted route-controller client over a fixed Unix socket.""" def __init__( self, *, request_timeout_seconds: int = 15, test_timeout_seconds: int = 180, ) -> None: self.request_timeout_seconds = max(2, min(int(request_timeout_seconds), 120)) self.test_timeout_seconds = max( self.request_timeout_seconds, min(int(test_timeout_seconds), 600), ) self._session: aiohttp.ClientSession | None = None async def open(self) -> None: if self._session and not self._session.closed: return connector = aiohttp.UnixConnector(path=SOCKET_PATH) timeout = aiohttp.ClientTimeout(total=self.request_timeout_seconds) self._session = aiohttp.ClientSession( connector=connector, timeout=timeout, headers={ "Accept": "application/json", "User-Agent": "astrbot-route-gateway/0.1", }, raise_for_status=False, ) async def close(self) -> None: if self._session and not self._session.closed: await self._session.close() self._session = None async def list_routes(self) -> ControllerResponse: payload, message = await self._request("GET", "/v1/routes") source = self._payload_data(payload) if isinstance(source, list): raw_routes = source elif isinstance(source, dict): raw_routes = source.get("routes", []) else: raw_routes = [] routes = [ self._whitelist_dict(item, _ROUTE_FIELDS) for item in raw_routes if isinstance(item, dict) ] data: dict[str, Any] = {"routes": routes} if isinstance(source, dict) and isinstance(source.get("revision"), int): data["revision"] = source["revision"] return ControllerResponse(message=message, data=data) async def status(self) -> ControllerResponse: payload, message = await self._request("GET", "/v1/status") source = self._payload_data(payload) data = self._whitelist_dict(source, _STATUS_FIELDS) return ControllerResponse(message=message, data=data) async def use_route( self, route_id: str, *, actor: str, force: bool = False, ) -> ControllerResponse: return await self._operation( "POST", "/v1/routes/use", json_body={"route_id": route_id, "actor": actor, "force": bool(force)}, timeout_seconds=self.test_timeout_seconds, ) async def test_route(self, route_id: str, *, actor: str) -> ControllerResponse: return await self._operation( "POST", "/v1/routes/test", json_body={"route_id": route_id, "actor": actor, "force": False}, timeout_seconds=self.test_timeout_seconds, ) async def history(self, *, limit: int = 10) -> ControllerResponse: payload, message = await self._request( "GET", "/v1/history", params={"limit": str(max(1, min(int(limit), 100)))}, ) source = self._payload_data(payload) if isinstance(source, list): raw_history = source elif isinstance(source, dict): raw_history = source.get("history", source.get("items", [])) else: raw_history = [] items = [] for item in raw_history: if not isinstance(item, dict): continue clean = self._whitelist_dict(item, _HISTORY_FIELDS) if "message" in clean: clean["message"] = sanitize_text(clean["message"]) items.append(clean) return ControllerResponse(message=message, data={"history": items}) async def list_secrets(self) -> ControllerResponse: """SECRET_REFERENCE_API: reference names and usage counts — never values.""" payload, message = await self._request("GET", "/v1/secrets") source = self._payload_data(payload) raw = source.get("secrets", []) if isinstance(source, dict) else [] secrets = [ { "secret_ref": str(item.get("secret_ref") or ""), "used_by_routes": int(item.get("used_by_routes") or 0), } for item in raw if isinstance(item, dict) and item.get("secret_ref") ] return ControllerResponse(message=message, data={"secrets": secrets}) async def import_secret(self, secret_ref: str, value: str, *, actor: str) -> ControllerResponse: """Write-only: the value goes to the controller and can never be read back.""" payload, message = await self._request( "POST", "/v1/secrets", json_body={"secret_ref": secret_ref, "value": value, "actor": actor}, ) source = self._payload_data(payload) data = {"secret_ref": secret_ref} if isinstance(source, dict) and isinstance(source.get("replaced"), bool): data["replaced"] = source["replaced"] return ControllerResponse(message=message, data=data) async def delete_secret(self, secret_ref: str, *, actor: str) -> ControllerResponse: payload, message = await self._request( "POST", "/v1/secrets/delete", json_body={"secret_ref": secret_ref, "actor": actor}, ) del payload return ControllerResponse(message=message, data={"secret_ref": secret_ref}) async def rollback( self, *, actor: str, revision: int | None = None, force: bool = False, ) -> ControllerResponse: body: dict[str, Any] = {"actor": actor, "force": bool(force)} if revision is not None: body["revision"] = int(revision) return await self._operation( "POST", "/v1/rollback", json_body=body, timeout_seconds=self.test_timeout_seconds, ) async def create_route( self, *, route_id: str, display_name: str, secret_ref: str, base_url: str, model: str, actor: str, force: bool = False, ) -> ControllerResponse: return await self._operation( "POST", "/v1/routes", json_body={ "route_id": route_id, "display_name": display_name, "secret_ref": secret_ref, "base_url": base_url, "model": model, "actor": actor, "force": bool(force), }, ) async def copy_route( self, *, source_route_id: str, new_route_id: str, display_name: str, actor: str, force: bool = False, ) -> ControllerResponse: return await self._operation( "POST", "/v1/routes/copy", json_body={ "source_id": source_route_id, "new_id": new_route_id, "display_name": display_name, "actor": actor, "force": bool(force), }, ) async def rename_route( self, *, route_id: str, display_name: str, actor: str, force: bool = False, ) -> ControllerResponse: return await self._operation( "POST", "/v1/routes/rename", json_body={ "route_id": route_id, "display_name": display_name, "actor": actor, "force": bool(force), }, ) async def delete_route( self, *, route_id: str, actor: str, confirm: bool, force: bool = False, ) -> ControllerResponse: path = f"/v1/routes/{quote(route_id, safe='')}" return await self._operation( "DELETE", path, json_body={ "confirm": bool(confirm), "actor": actor, "force": bool(force), }, ) async def _operation( self, method: str, path: str, *, json_body: dict[str, Any], timeout_seconds: int | None = None, ) -> ControllerResponse: payload, message = await self._request( method, path, json_body=json_body, timeout_seconds=timeout_seconds, ) source = self._payload_data(payload) data = self._whitelist_dict(source, _OPERATION_FIELDS) checks = data.get("checks") if isinstance(checks, dict): data["checks"] = self._whitelist_dict(checks, _CHECK_FIELDS) else: data.pop("checks", None) return ControllerResponse(message=message, data=data) async def _request( self, method: str, path: str, *, json_body: dict[str, Any] | None = None, params: dict[str, str] | None = None, timeout_seconds: int | None = None, ) -> tuple[Any, str]: if not path.startswith("/") or "://" in path or ".." in path: raise GatewayError("插件拒绝了无效的控制器路径") self._check_socket() await self.open() assert self._session is not None timeout = None if timeout_seconds is not None: timeout = aiohttp.ClientTimeout(total=max(2, min(timeout_seconds, 600))) try: async with self._session.request( method, _HTTP_ORIGIN + path, json=json_body, params=params, timeout=timeout, ) as response: body = await response.content.read(_MAX_RESPONSE_BYTES + 1) if len(body) > _MAX_RESPONSE_BYTES: raise GatewayError("路由控制器响应过大,已拒绝处理") payload = self._decode_json(body) message = self._response_message(payload) if response.status < 200 or response.status >= 300: raise GatewayError( message or self._status_message(response.status), status=response.status, code=self._response_code(payload), ) if isinstance(payload, dict): if payload.get("ok") is False or str(payload.get("status", "")).lower() in { "error", "failed", "failure", }: raise GatewayError( message or "路由控制器拒绝了请求", status=response.status, code=self._response_code(payload), ) return payload, message except GatewayError: raise except (aiohttp.ClientError, TimeoutError, ConnectionError, OSError): # Drop pooled Unix-socket connections so the next request can recover # cleanly after a controller restart or socket inode replacement. await self.close() raise GatewayError("无法连接路由控制器,请检查控制器服务和 Socket 权限") from None @staticmethod def _check_socket() -> None: try: socket_stat = os.stat(SOCKET_PATH) except FileNotFoundError: raise GatewayError("路由控制器尚未启动") from None except OSError: raise GatewayError("无法访问路由控制器 Socket") from None if not stat.S_ISSOCK(socket_stat.st_mode): raise GatewayError("路由控制器路径不是 Unix Socket,已拒绝连接") @staticmethod def _decode_json(body: bytes) -> Any: if not body: return {} try: return json.loads(body.decode("utf-8")) except (UnicodeDecodeError, json.JSONDecodeError): raise GatewayError("路由控制器返回了无效 JSON") from None @staticmethod def _payload_data(payload: Any) -> Any: if isinstance(payload, dict) and "data" in payload: return payload.get("data") return payload @staticmethod def _response_message(payload: Any) -> str: if not isinstance(payload, dict): return "" return sanitize_text(payload.get("message", "")) @staticmethod def _response_code(payload: Any) -> str | None: if not isinstance(payload, dict): return None code = payload.get("code") or payload.get("error_code") or payload.get("error") return sanitize_text(code, max_length=80) if code else None @staticmethod def _status_message(status_code: int) -> str: if status_code == 400: return "路由控制器拒绝了无效请求" if status_code == 404: return "指定线路或控制接口不存在" if status_code == 409: return "当前状态不允许执行该路由操作" if status_code == 422: return "路由参数校验失败" if status_code == 429: return "路由控制器正忙,请稍后重试" if status_code >= 500: return "路由控制器内部错误" return f"路由控制器请求失败(HTTP {status_code})" @classmethod def _whitelist_dict(cls, value: Any, fields: set[str]) -> dict[str, Any]: if not isinstance(value, dict): return {} result: dict[str, Any] = {} for key in fields: if key not in value: continue item = value[key] if isinstance(item, (str, int, float, bool)) or item is None: result[key] = sanitize_text(item) if isinstance(item, str) else item elif key == "checks" and isinstance(item, dict): result[key] = item return result