sqlseed-web 0.2.4__py3-none-any.whl

sqlseed_web/app.py

@@ -0,0 +1,26 @@
+"""Public ASGI factory and console entry point for the Web workbench."""
+
+from __future__ import annotations
+
+import argparse
+
+from sqlseed_web._application import create_app
+
+__all__ = ["create_app", "main"]
+
+
+def main() -> None:
+    """Run the dev server (``sqlseed-web`` console script)."""
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description="Start the local sqlseed Web workbench.")
+    parser.add_argument(
+        "--manage-plugins", action="store_true", help="Start plugin maintenance only; disable database and AI APIs."
+    )
+    args = parser.parse_args()
+    if args.manage_plugins:
+        uvicorn.run(create_app(manage_plugins=True), host="127.0.0.1", port=8630, log_level="info")
+    else:
+        from sqlseed_web.supervisor import run_supervised
+
+        run_supervised()

sqlseed_web/managed_worker.py

@@ -0,0 +1,184 @@
+"""Fresh business and maintenance workers controlled by the stable launcher."""
+
+from __future__ import annotations
+
+import os
+import signal
+import socket
+import threading
+import time
+from multiprocessing.connection import Connection
+from typing import TYPE_CHECKING, Any, Protocol
+
+from fastapi import HTTPException
+
+from sqlseed_web.plugin_management import ExecuteRequest, PlanRequest
+from sqlseed_web.worker_control import ControlChannel, ControlError, ControlMessageTooLarge, validate_control_result
+
+if TYPE_CHECKING:
+    import uvicorn
+
+    from sqlseed_web.runtime_lifecycle import RuntimeGate
+
+
+class RemotePluginManager:
+    """The HTTP worker cannot execute package operations itself."""
+
+    enabled = True
+
+    def __init__(self, channel: ControlChannel, token: str) -> None:
+        self.channel = channel
+        self.token = token
+
+    def _call(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        try:
+            return self.channel.call(method, params)
+        except ControlError as exc:
+            raise HTTPException(exc.status_code, detail=exc.detail) from exc
+        except (OSError, RuntimeError) as exc:
+            raise HTTPException(
+                503, detail={"code": "supervisor_unavailable", "message": "服务正在切换，请稍后重试。"}
+            ) from exc
+
+    def status(self) -> dict[str, Any]:
+        return self._call("management", {})
+
+    def plan(self, body: PlanRequest) -> dict[str, Any]:
+        return self._call("plan", body.model_dump())
+
+    def execute(self, body: ExecuteRequest) -> dict[str, Any]:
+        return self._call("execute", body.model_dump())
+
+    def task_snapshot(self, task_id: str | None = None) -> dict[str, Any]:
+        return self._call("task", {"task_id": task_id})
+
+    def recover(self) -> dict[str, Any]:
+        return self._call("recover", {})
+
+
+class InheritedDescriptor(Protocol):
+    def detach(self) -> int: ...
+
+
+def prepare_runtime_session() -> dict[str, Any]:
+    """Pause only if the complete recovery snapshot can be transferred safely."""
+    from sqlseed_web.runtime_lifecycle import runtime_gate
+    from sqlseed_web.runtime_session import export_session
+
+    runtime_gate.pause_if_idle()
+    try:
+        snapshot = export_session()
+        try:
+            validate_control_result(snapshot)
+        except ControlMessageTooLarge as exc:
+            raise HTTPException(
+                409,
+                detail={
+                    "code": "plugin_session_too_large",
+                    "message": "当前连接与会话信息过多，无法安全暂存；请减少连接后再管理插件。",
+                },
+            ) from exc
+        return snapshot
+    except Exception:
+        runtime_gate.resume()
+        raise
+
+
+def _worker_control(method: str, mode: str, server: uvicorn.Server | None, gate: RuntimeGate) -> dict[str, Any]:
+    if method == "activity":
+        return gate.activity()
+    if method == "prepare":
+        return prepare_runtime_session()
+    if method == "resume":
+        gate.resume()
+        return {}
+    if method == "shutdown":
+        if mode == "business":
+            from sqlseed_web.runtime_session import close_session
+
+            gate.pause_if_idle()
+            close_session()
+        if server is not None:
+            server.should_exit = True
+        return {}
+    raise ValueError("unsupported worker control method")
+
+
+def _drain_worker_runtime(mode: str, gate: RuntimeGate) -> None:
+    """Close admission and finish existing leases before closing database sessions."""
+    gate.close_admission()
+    while any(gate.activity().values()):
+        time.sleep(0.05)
+    if mode == "business":
+        from sqlseed_web.runtime_session import close_session
+
+        close_session()
+
+
+def run_worker(
+    listener: socket.socket,
+    connection: Connection,
+    mode: str,
+    session: dict[str, Any],
+    token: str,
+    lock_descriptor: InheritedDescriptor | None = None,
+) -> None:
+    """Spawn target: the parent owns signals, listener lifetime, and package state."""
+    import uvicorn
+
+    from sqlseed_web._application import create_app
+    from sqlseed_web.runtime_lifecycle import runtime_gate
+
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+    signal.signal(signal.SIGTERM, signal.SIG_IGN)
+    channel = ControlChannel(connection)
+    manager = RemotePluginManager(channel, token)
+    result: dict[str, Any] = {}
+    server: uvicorn.Server | None = None
+    thread: threading.Thread | None = None
+    lock_fd = lock_descriptor.detach() if lock_descriptor is not None else None
+
+    def control(method: str, params: dict[str, Any]) -> dict[str, Any]:
+        return _worker_control(method, mode, server, runtime_gate)
+
+    channel.start(control)
+    try:
+        runtime_gate.pause_if_idle()
+        if mode == "business":
+            from sqlseed_web.runtime_session import restore_session
+
+            result = (
+                restore_session(session)
+                if session
+                else {
+                    "restored_connections": 0,
+                    "failed_connections": [],
+                    "ai_session_restored": True,
+                }
+            )
+        app = create_app(manage_plugins=mode == "maintenance", management_service=manager, supervised_worker=True)
+        config = uvicorn.Config(
+            app, log_level="warning", access_log=False, lifespan="on", timeout_graceful_shutdown=None
+        )
+        server = uvicorn.Server(config)
+        thread = threading.Thread(
+            target=server.run, kwargs={"sockets": [listener]}, daemon=False, name="sqlseed-http-worker"
+        )
+        thread.start()
+        while thread.is_alive() and not server.started:
+            time.sleep(0.01)
+        if server.started:
+            channel.call("worker_ready", {"mode": mode, "restoration": result})
+        while thread.is_alive():
+            if channel.wait_closed(0.1):
+                break
+    finally:
+        _drain_worker_runtime(mode, runtime_gate)
+        if server is not None:
+            server.should_exit = True
+        if thread is not None:
+            thread.join()
+        channel.close()
+        listener.close()
+        if lock_fd is not None:
+            os.close(lock_fd)

sqlseed_web/operation_errors.py

@@ -0,0 +1,42 @@
+"""Recoverable generation failures, including the active connection's DBAPI errors."""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from typing import TYPE_CHECKING
+
+from sqlalchemy.exc import SQLAlchemyError
+from sqlseed.generators._protocol import ConfigurationError, GenerationError, UnknownGeneratorError
+
+if TYPE_CHECKING:
+    from sqlseed.core.orchestrator import DataOrchestrator
+
+
+def generation_errors(
+    orch: DataOrchestrator | None = None, *, additional: tuple[type[Exception], ...] = ()
+) -> tuple[type[Exception], ...]:
+    """Describe core's validation/provider contract and the loaded database driver.
+
+    Raw cursor failures retain their native driver class. Reading that class
+    avoids importing optional drivers or opening a connection just to catch an
+    error. Programmer errors outside these operational contracts propagate.
+    """
+    errors: tuple[type[Exception], ...] = (
+        ConfigurationError,
+        GenerationError,
+        UnknownGeneratorError,
+        ValueError,
+        TypeError,
+        RuntimeError,
+        OSError,
+        ArithmeticError,
+        re.error,
+        SQLAlchemyError,
+        sqlite3.Error,
+    )
+    if orch is not None and (engine := getattr(orch.database_adapter, "_engine", None)) is not None:
+        error_type = engine.dialect.loaded_dbapi.Error
+        if isinstance(error_type, type) and issubclass(error_type, Exception):
+            errors += (error_type,)
+    return errors + additional

sqlseed_web/plugin_environment.py

@@ -0,0 +1,231 @@
+"""Interpreter-bound package metadata and lifetime environment admission."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import sysconfig
+import tempfile
+from dataclasses import dataclass
+from importlib import metadata
+from pathlib import Path
+from typing import IO, Any
+
+from packaging.requirements import Requirement
+from packaging.utils import canonicalize_name
+from packaging.version import Version
+
+from sqlseed_web.settings_environment import AI_INSTALL_REQUIREMENT, _installer
+
+COMPONENT_DISTRIBUTIONS = {
+    "ai": "sqlseed-ai",
+    "cli": "sqlseed-cli",
+    "mcp": "mcp-server-sqlseed",
+    "mimesis": "mimesis",
+}
+
+
+@dataclass(frozen=True)
+class Environment:
+    """A server-owned target; none of these fields are accepted from HTTP."""
+
+    prefix: Path
+    executable: str
+    tool: str | None
+    tool_executable: str | None
+    reason: str | None
+
+
+def _venv_directory_restriction(prefix: Path) -> str | None:
+    """Check isolation and write access, retaining the last applicable restriction."""
+    reason = None
+    try:
+        configuration = (prefix / "pyvenv.cfg").read_text(encoding="utf-8")
+        if re.search(r"include-system-site-packages\s*=\s*true", configuration, re.IGNORECASE):
+            reason = "共享系统 site-packages 的环境不支持界面管理。"
+        locations = {
+            prefix,
+            Path(sysconfig.get_path("purelib")).resolve(),
+            Path(sysconfig.get_path("platlib")).resolve(),
+        }
+        for location in locations:
+            if not location.is_relative_to(prefix):
+                reason = "Python 安装目录位于 virtualenv 之外，不支持界面管理。"
+            else:
+                if (location / "EXTERNALLY-MANAGED").exists():
+                    reason = "此环境由外部工具管理，请使用原环境管理工具。"
+                if not location.is_dir() or not os.access(location, os.W_OK) or not location.stat().st_mode & 0o222:
+                    reason = "当前 Python 环境不可写，请使用原环境管理工具。"
+        if reason is None:
+            with tempfile.TemporaryFile(dir=prefix) as probe:
+                probe.write(b"sqlseed environment write probe")
+                probe.flush()
+    except (OSError, UnicodeError):
+        reason = "无法验证当前 Python 环境的写入权限。"
+    return reason
+
+
+def _environment() -> Environment:
+    prefix = Path(sys.prefix).resolve()
+    reason = None
+    if sys.platform == "win32":
+        reason = "Windows 暂不支持界面组件管理；请使用页面提供的 PowerShell 命令手动管理环境。"
+    elif sys.prefix == sys.base_prefix or not (prefix / "pyvenv.cfg").is_file():
+        reason = "仅支持当前 Web 所在的独立 virtualenv；系统 Python 请使用原环境管理工具。"
+    elif (prefix / "EXTERNALLY-MANAGED").exists():
+        reason = "此环境由外部工具管理，请使用原环境管理工具。"
+    else:
+        reason = _venv_directory_restriction(prefix)
+    installer = _installer()
+    if reason is None and installer.tool is None:
+        reason = "当前 Python 环境没有可用的 pip 或 uv；请使用原环境管理工具。"
+    return Environment(prefix, sys.executable, installer.tool, installer.tool_executable, reason)
+
+
+class EnvironmentLock:
+    """Shared normal servers and an exclusive maintenance server cannot coexist.
+
+    The lock is held through shutdown, including any package worker. It never
+    removes the lock file, preventing old/new inode races between processes.
+    """
+
+    def __init__(self, prefix: Path, *, exclusive: bool) -> None:
+        self.path = prefix / ".sqlseed-web-environment.lock"
+        self.exclusive = exclusive
+        self._file: IO[bytes] | None = None
+
+    def acquire(self) -> None:
+        if self._file is not None:
+            return
+        handle = self.path.open("a+b")
+        try:
+            if sys.platform == "win32":
+                import msvcrt
+
+                handle.seek(0, os.SEEK_END)
+                if handle.tell() == 0:
+                    handle.write(b"\0")
+                    handle.flush()
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK if self.exclusive else msvcrt.LK_NBRLCK, 1)
+            else:
+                import fcntl
+
+                fcntl.flock(handle.fileno(), (fcntl.LOCK_EX if self.exclusive else fcntl.LOCK_SH) | fcntl.LOCK_NB)
+        except OSError as exc:
+            handle.close()
+            raise RuntimeError("另一个 Web 进程正在使用此 Python 环境，请先停止它。") from exc
+        self._file = handle
+
+    def release(self) -> None:
+        if self._file is not None:
+            self._file.close()
+            self._file = None
+
+    def fileno(self) -> int:
+        """Retain this same OS lock in an owned serving child until it exits."""
+        if self._file is None:
+            raise RuntimeError("环境锁尚未持有。")
+        return self._file.fileno()
+
+
+@dataclass(frozen=True)
+class InstalledPackage:
+    """Validated installed metadata, independent of already imported modules."""
+
+    version: str
+    requirements: tuple[str, ...]
+
+
+def _distribution_paths() -> list[str]:
+    return sys.path
+
+
+def installed_packages(prefix: Path) -> dict[str, InstalledPackage]:
+    result: dict[str, InstalledPackage] = {}
+    try:
+        for distribution in metadata.distributions(path=_distribution_paths()):
+            if not Path(str(distribution.locate_file(""))).resolve().is_relative_to(prefix.resolve()):
+                raise ValueError("distribution metadata is outside the managed environment")
+            name = distribution.metadata["Name"]
+            if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", name):
+                raise ValueError("invalid distribution name")
+            normalized = canonicalize_name(name)
+            version = str(Version(distribution.version))
+            requirements = tuple(sorted(distribution.requires or []))
+            for requirement in requirements:
+                Requirement(requirement)
+            item = InstalledPackage(version, requirements)
+            if normalized in result and result[normalized] != item:
+                raise ValueError("conflicting distribution metadata")
+            result[normalized] = item
+        if not {"sqlseed", "sqlseed-web", "faker"}.issubset(result):
+            raise ValueError("required distribution metadata is absent")
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        raise RuntimeError("已安装组件的元数据无法安全解析；请先修复当前 Python 环境。") from exc
+    return result
+
+
+def required_by(distribution: str, packages: dict[str, InstalledPackage]) -> list[str]:
+    """Only active base requirements block removal; extras are not installed-state facts."""
+    result = []
+    for name, package in packages.items():
+        if name == distribution:
+            continue
+        for text in package.requirements:
+            requirement = Requirement(text)
+            if canonicalize_name(requirement.name) == distribution and (
+                requirement.marker is None or requirement.marker.evaluate({"extra": ""})
+            ):
+                result.append(name)
+                break
+    return sorted(result)
+
+
+def installer_arguments(environment: Environment, action: str, distribution: str, constraints: Path) -> list[str]:
+    """Construct fixed argv with no shell and no configurable target or package."""
+    if distribution not in COMPONENT_DISTRIBUTIONS.values() or action not in {"install", "uninstall"}:
+        raise ValueError("unsupported component operation")
+    if environment.tool == "pip":
+        args = [environment.executable, "-m", "pip", "--isolated", action, "--disable-pip-version-check", "--no-input"]
+        if action == "install":
+            args += ["--constraint", str(constraints), "--only-binary=:all:"]
+        else:
+            args += ["--yes"]
+    elif environment.tool == "uv" and environment.tool_executable:
+        args = [
+            environment.tool_executable,
+            "--no-config",
+            "pip",
+            action,
+            "--python",
+            environment.executable,
+            "--no-python-downloads",
+        ]
+        if action == "install":
+            args += ["--constraints", str(constraints), "--only-binary=:all:"]
+    else:
+        raise RuntimeError("没有可用的安装工具。")
+    requirement = AI_INSTALL_REQUIREMENT if action == "install" and distribution == "sqlseed-ai" else distribution
+    return [*args, requirement]
+
+
+def package_status(packages: dict[str, InstalledPackage], unavailable: str | None) -> list[dict[str, Any]]:
+    result = []
+    for identifier, distribution in COMPONENT_DISTRIBUTIONS.items():
+        package = packages.get(distribution)
+        users = required_by(distribution, packages)
+        reason = unavailable or (f"由 {', '.join(users)} 使用，请先卸载这些可选组件。" if users else None)
+        result.append(
+            {
+                "id": identifier,
+                "installed": package is not None,
+                "version": package.version if package else None,
+                "can_install": not unavailable and package is None,
+                "can_uninstall": not unavailable and package is not None and not users,
+                "reason": reason,
+                "required_by": users,
+            }
+        )
+    return result