agent-webview 0.1.0__py3-none-any.whl

agent_webview/cookies.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from http.cookies import Morsel
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from agent_webview.files import ensure_private_directory, write_private_json
+from agent_webview.models import CookieRecord
+
+
+def _truthy_attribute(value: Any) -> bool:
+    return bool(value) and str(value).lower() not in {"false", "0", "none"}
+
+
+def _normalize_expires(value: Any) -> str | int | float | None:
+    if not value:
+        return None
+    if isinstance(value, (int, float)):
+        return value if value > 0 else None
+    text = str(value)
+    year = re.search(r"\b(\d{4})\b", text)
+    if year and int(year.group(1)) <= 1970:
+        return None
+    try:
+        parsed = parsedate_to_datetime(text)
+    except (TypeError, ValueError, OverflowError):
+        return text
+    return text if parsed.year > 1970 else None
+
+
+def normalize_pywebview_cookies(raw_cookies: Iterable[Any]) -> list[CookieRecord]:
+    normalized: list[CookieRecord] = []
+    for container in raw_cookies:
+        if isinstance(container, Morsel):
+            items = [(container.key, container)]
+        elif hasattr(container, "items"):
+            items = list(container.items())
+        else:
+            continue
+        for name, morsel in items:
+            if isinstance(morsel, Morsel):
+                same_site = morsel["samesite"] or None
+                if same_site:
+                    same_site = same_site.title()
+                normalized.append(
+                    CookieRecord(
+                        name=str(name),
+                        value=morsel.value,
+                        domain=morsel["domain"] or None,
+                        path=morsel["path"] or "/",
+                        expires=_normalize_expires(morsel["expires"]),
+                        secure=_truthy_attribute(morsel["secure"]),
+                        http_only=_truthy_attribute(morsel["httponly"]),
+                        same_site=same_site
+                        if same_site in {"Strict", "Lax", "None"}
+                        else None,
+                    )
+                )
+            else:
+                normalized.append(CookieRecord(name=str(name), value=str(morsel)))
+    return normalized
+
+
+class SnapshotStore:
+    def __init__(self, directory: Path) -> None:
+        self.directory = ensure_private_directory(directory)
+
+    def save(
+        self,
+        *,
+        session_id: str,
+        url: str | None,
+        cookies: list[dict[str, Any]],
+        name: str | None,
+    ) -> dict[str, Any]:
+        snapshot_id = uuid4().hex
+        document = {
+            "snapshot_id": snapshot_id,
+            "name": name,
+            "session_id": session_id,
+            "url": url,
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "cookies": cookies,
+            "limitations": [
+                "通过 document.cookie 恢复，无法恢复 HttpOnly Cookie。",
+                "浏览器策略可能拒绝部分 Cookie 属性。",
+            ],
+        }
+        target = self.directory / f"{snapshot_id}.json"
+        write_private_json(target, document)
+        return document
+
+    def get(self, snapshot_id: str) -> dict[str, Any]:
+        path = self._path(snapshot_id)
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def list(self) -> list[dict[str, Any]]:
+        snapshots = []
+        for path in sorted(
+            self.directory.glob("*.json"),
+            key=lambda item: item.stat().st_mtime,
+            reverse=True,
+        ):
+            try:
+                document = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            snapshots.append(
+                {
+                    key: document.get(key)
+                    for key in ("snapshot_id", "name", "session_id", "url", "created_at")
+                }
+            )
+        return snapshots
+
+    def delete(self, snapshot_id: str) -> None:
+        self._path(snapshot_id).unlink()
+
+    def _path(self, snapshot_id: str) -> Path:
+        if not snapshot_id or any(char not in "0123456789abcdef" for char in snapshot_id):
+            raise FileNotFoundError(snapshot_id)
+        path = self.directory / f"{snapshot_id}.json"
+        if not path.is_file():
+            raise FileNotFoundError(snapshot_id)
+        return path

agent_webview/errors.py

@@ -0,0 +1,14 @@
+class BrowserNotReadyError(RuntimeError):
+    """页面尚未就绪。"""
+
+
+class BrowserCommandError(RuntimeError):
+    """页面脚本执行失败。"""
+
+    def __init__(self, message: str, details: dict | None = None) -> None:
+        super().__init__(message)
+        self.details = details or {}
+
+
+class BrowserCommandTimeoutError(TimeoutError):
+    """页面脚本执行超时。"""

agent_webview/events.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from threading import Condition
+from time import monotonic
+from typing import Any
+
+
+@dataclass(frozen=True)
+class EventPage:
+    events: list[dict[str, Any]]
+    latest_sequence: int
+    oldest_sequence: int
+    dropped_before: int | None
+
+
+class EventBuffer:
+    def __init__(self, capacity: int = 5000) -> None:
+        if capacity < 1:
+            raise ValueError("容量必须大于零")
+        self._events: deque[dict[str, Any]] = deque(maxlen=capacity)
+        self._sequence = 0
+        self._condition = Condition()
+
+    @property
+    def latest_sequence(self) -> int:
+        with self._condition:
+            return self._sequence
+
+    def append(self, kind: str, payload: Any) -> dict[str, Any]:
+        with self._condition:
+            self._sequence += 1
+            event = {
+                "sequence": self._sequence,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "kind": kind,
+                "payload": payload,
+            }
+            self._events.append(event)
+            self._condition.notify_all()
+            return event
+
+    def clear(self) -> None:
+        with self._condition:
+            self._events.clear()
+
+    def get(
+        self,
+        *,
+        after: int = 0,
+        limit: int = 200,
+        kinds: Iterable[str] | None = None,
+        timeout: float = 0,
+    ) -> EventPage:
+        accepted_kinds = set(kinds or [])
+        deadline = monotonic() + max(0, timeout)
+
+        with self._condition:
+            while True:
+                matching = [
+                    event
+                    for event in self._events
+                    if event["sequence"] > after
+                    and (not accepted_kinds or event["kind"] in accepted_kinds)
+                ]
+                if matching or timeout <= 0:
+                    break
+                remaining = deadline - monotonic()
+                if remaining <= 0:
+                    break
+                self._condition.wait(remaining)
+
+            oldest = self._events[0]["sequence"] if self._events else self._sequence + 1
+            dropped_before = oldest if after < oldest - 1 else None
+            return EventPage(
+                events=matching[: max(1, min(limit, 1000))],
+                latest_sequence=self._sequence,
+                oldest_sequence=oldest,
+                dropped_before=dropped_before,
+            )

agent_webview/files.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+def ensure_private_directory(path: Path) -> Path:
+    """创建仅当前用户可访问的目录。"""
+    path.mkdir(parents=True, exist_ok=True, mode=0o700)
+    _chmod_private(path, 0o700)
+    return path
+
+
+def ensure_private_parent(path: Path) -> Path:
+    """只在父目录缺失时创建私有目录。"""
+    if path.is_dir():
+        return path
+    path.mkdir(parents=True, mode=0o700)
+    _chmod_private(path, 0o700)
+    return path
+
+
+def write_private_text(path: Path, content: str) -> None:
+    """原子写入仅当前用户可读写的文本文件。"""
+    ensure_private_parent(path.parent)
+    descriptor, temporary_name = tempfile.mkstemp(
+        dir=path.parent,
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        text=True,
+    )
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        _chmod_private(temporary, 0o600)
+        try:
+            os.replace(temporary, path)
+        except PermissionError:
+            # 部分 Windows 策略禁止替换已存在文件。
+            path.write_text(content, encoding="utf-8")
+        _chmod_private(path, 0o600)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def write_private_json(path: Path, value: dict[str, Any]) -> None:
+    write_private_text(
+        path,
+        json.dumps(value, ensure_ascii=False, indent=2),
+    )
+
+
+def restrict_file_permissions(path: Path) -> None:
+    _chmod_private(path, 0o600)
+
+
+def _chmod_private(path: Path, mode: int) -> None:
+    try:
+        path.chmod(mode)
+    except OSError:
+        if os.name != "nt":
+            raise

agent_webview/http_errors.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+
+def install_validation_handler(app: FastAPI) -> None:
+    @app.exception_handler(RequestValidationError)
+    async def validation_handler(
+        _: Request,
+        error: RequestValidationError,
+    ) -> JSONResponse:
+        errors = [
+            {
+                "field": ".".join(str(item) for item in detail["loc"]),
+                "type": detail["type"],
+            }
+            for detail in error.errors()
+        ]
+        return JSONResponse(
+            status_code=422,
+            content={"detail": "请求参数无效", "errors": errors},
+        )