mongrade 0.1.0a1__py3-none-any.whl

mongrade/__init__.py

@@ -0,0 +1,26 @@
+# coding=utf-8
+"""Mongrade 的稳定公共 API；导入时不建立连接或加载业务模块。"""
+
+from ._version import __version__
+from .catalog import load_catalog
+from .executor import adopt, migrate, preflight, recover
+from .models import Catalog, MigrationError, Plan, Revision
+from .planner import diagnose, plan, verify
+from .state import connect
+
+__all__ = [
+    "Catalog",
+    "MigrationError",
+    "Plan",
+    "Revision",
+    "__version__",
+    "adopt",
+    "connect",
+    "diagnose",
+    "load_catalog",
+    "migrate",
+    "plan",
+    "preflight",
+    "recover",
+    "verify",
+]

mongrade/__main__.py

@@ -0,0 +1,7 @@
+# coding=utf-8
+"""支持 python -m mongrade，行为与安装后的控制台入口一致。"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mongrade/_version.py

@@ -0,0 +1,4 @@
+# coding=utf-8
+"""包版本的唯一声明位置，供运行时和标准构建后端静态读取。"""
+
+__version__ = "0.1.0a1"

mongrade/catalog.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+# coding=utf-8
+"""静态发现单链；任何只读路径均不导入 revision。"""
+
+import ast
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Union
+
+from .models import Catalog, Revision, digest, require
+
+
+def file_sha(path: Path) -> str:
+    """计算发布制品原始字节的 SHA256。"""
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def require_catalog_unchanged(catalog: Catalog) -> None:
+    """复核磁盘发布制品；缓存图不能作为启动放行依据。"""
+    require(
+        load_catalog(catalog.path).sha256 == catalog.sha256, "release_artifact_drift"
+    )
+
+
+def read_json(path: Path) -> Dict[str, Any]:
+    """读取 UTF-8 JSON，拒绝重复字段以避免有歧义的发布配置。"""
+
+    def pairs(items: Any) -> Dict[str, Any]:
+        result = {}
+        for key, value in items:
+            require(key not in result, "duplicate_json_key")
+            result[key] = value
+        return result
+
+    return json.loads(path.read_text(encoding="utf-8"), object_pairs_hook=pairs)
+
+
+def validate_checks(checks: Any, resources: Dict[str, Any]) -> None:
+    """验证声明式后置检查，不执行脚本。"""
+    require(isinstance(checks, list) and bool(checks), "postchecks_required")
+    for check in checks:
+        require(
+            isinstance(check, dict) and check.get("resource") in resources,
+            "invalid_check_resource",
+        )
+        require(
+            set(check)
+            <= {"resource", "exists", "filter", "count", "min_count", "index"},
+            "unknown_check",
+        )
+        require(
+            any(key in check for key in ("exists", "count", "min_count", "index")),
+            "empty_check",
+        )
+        if "index" in check:
+            expected = check["index"]
+            require(
+                isinstance(expected, dict)
+                and {"name", "key"} <= set(expected)
+                and set(expected) <= {"name", "key", "unique"},
+                "unsupported_index_postcheck",
+            )
+            require(
+                isinstance(expected["name"], str)
+                and isinstance(expected["key"], list)
+                and bool(expected["key"]),
+                "invalid_index_postcheck",
+            )
+
+
+def load_catalog(path: Union[str, Path]) -> Catalog:
+    """静态加载业务项目及单链版本图，异常时拒绝后续执行。"""
+    path = Path(path).resolve()
+    project = read_json(path)
+    require(
+        project.get("format") == 1 and project.get("engine") == "v1.0.0",
+        "incompatible_project_format",
+    )
+    require(
+        re.fullmatch(r"[A-Za-z0-9_-]{1,80}", project.get("domain", "")),
+        "invalid_domain",
+    )
+    for field in ("database", "auth_source", "control_database", "ledger"):
+        require(
+            isinstance(project.get(field), str)
+            and re.fullmatch(r"[A-Za-z0-9_-]{1,100}", project[field]),
+            "invalid_" + field,
+        )
+    require(project["ledger"] != "_commonlib_migration_coordination", "ledger_conflict")
+    coordination = project.get(
+        "coordination_collection", "_commonlib_migration_coordination"
+    )
+    require(
+        isinstance(coordination, str)
+        and re.fullmatch(r"[A-Za-z0-9_-]{1,100}", coordination)
+        and coordination != project["ledger"],
+        "invalid_coordination_collection",
+    )
+    legacy = project.get("legacy")
+    if legacy:
+        require(
+            legacy.get("database") == project["database"], "legacy_database_conflict"
+        )
+        require(
+            legacy.get("collection")
+            not in (
+                project["ledger"],
+                coordination,
+                "_commonlib_migration_coordination",
+            ),
+            "legacy_ledger_conflict",
+        )
+    resources = project.get("resources", {})
+    require(isinstance(resources, dict) and bool(resources), "resources_required")
+    physical = set()
+    for alias, resource in resources.items():
+        require(re.fullmatch(r"[A-Za-z0-9_-]{1,80}", alias), "invalid_alias")
+        require(
+            set(resource) <= {"database", "collection", "index", "owner"}
+            and resource.get("owner") == project["domain"],
+            "resource_owner_conflict",
+        )
+        require(
+            resource.get("database") == project["database"],
+            "multi_database_resources_not_supported_v1",
+        )
+        name = resource.get("collection", "")
+        require(
+            re.fullmatch(r"[A-Za-z0-9_-]{1,100}", name)
+            and name not in (project["ledger"], coordination),
+            "invalid_resource_collection",
+        )
+        require(
+            not legacy or name != legacy["collection"], "resource_metadata_conflict"
+        )
+        key = (resource["database"], name, resource.get("index"))
+        require(key not in physical, "duplicate_resource")
+        physical.add(key)
+    revisions = {}
+    versions = path.parent / "versions"
+    require(versions.is_dir(), "versions_missing")
+    artifacts = sorted(list(versions.glob("*.py")) + list(versions.glob("*.pyc")))
+    for script in artifacts:
+        if script.name in ("__init__.py", "__init__.pyc"):
+            continue
+        require(not script.is_symlink(), "revision_symlink_rejected")
+        artifact_sha256 = file_sha(script)
+        source_sha256 = artifact_sha256
+        if script.suffix == ".py":
+            tree = ast.parse(script.read_text(encoding="utf-8-sig"))
+            assignments = [
+                node
+                for node in tree.body
+                if isinstance(node, ast.Assign)
+                and any(
+                    isinstance(target, ast.Name) and target.id == "MIGRATION"
+                    for target in node.targets
+                )
+            ]
+            require(len(assignments) == 1, "literal_metadata_required")
+            metadata = ast.literal_eval(assignments[0].value)
+        else:
+            metadata = read_json(script.with_suffix(".json"))
+            require(
+                metadata.pop("artifact_sha256", None) == file_sha(script),
+                "pyc_artifact_digest_mismatch",
+            )
+            source_sha256 = metadata.pop("source_sha256", None)
+            require(
+                isinstance(source_sha256, str)
+                and re.fullmatch(r"[0-9a-f]{64}", source_sha256),
+                "pyc_source_digest_required",
+            )
+        require(
+            isinstance(metadata, dict)
+            and set(metadata)
+            == {"revision", "parent", "resources", "risk", "checks", "resume"},
+            "invalid_revision_metadata",
+        )
+        revision = metadata["revision"]
+        require(
+            isinstance(revision, str)
+            and re.fullmatch(r"[A-Za-z0-9_-]{1,80}", revision),
+            "invalid_revision",
+        )
+        require(revision not in revisions, "duplicate_revision_or_source_and_pyc")
+        require(metadata["risk"] in ("additive", "destructive"), "unsupported_risk")
+        require(isinstance(metadata["resume"], bool), "invalid_resume_contract")
+        require(
+            isinstance(metadata["resources"], list)
+            and bool(metadata["resources"])
+            and set(metadata["resources"]) <= set(resources),
+            "invalid_revision_resources",
+        )
+        validate_checks(metadata["checks"], resources)
+        revisions[revision] = Revision(
+            revision,
+            metadata["parent"],
+            script,
+            source_sha256,
+            artifact_sha256,
+            metadata,
+        )
+    require(bool(revisions), "empty_graph")
+    ordered: List[Revision] = []
+    parent = None
+    while len(ordered) < len(revisions):
+        children = [r for r in revisions.values() if r.parent == parent]
+        require(len(children) == 1, "broken_cycle_or_branch")
+        child = children[0]
+        require(child not in ordered, "cycle")
+        ordered.append(child)
+        parent = child.revision
+    return Catalog(
+        path,
+        project,
+        tuple(ordered),
+        digest(
+            {
+                "project": project,
+                "revisions": [
+                    (r.metadata, r.sha256, r.artifact_sha256) for r in ordered
+                ],
+            }
+        ),
+    )

mongrade/cli.py

@@ -0,0 +1,189 @@
+# coding=utf-8
+"""独立命令行入口；CommonLib 可以显式注入项目目录和已经判定的角色。"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Optional, Sequence, Union
+
+from ._version import __version__
+from .catalog import load_catalog, read_json
+from .executor import adopt, migrate, recover
+from .models import Catalog, MigrationError, digest, require
+from .planner import diagnose, plan, verify
+from .state import classify_error, connect
+
+
+def public_result(value: Any) -> Any:
+    """将 checkpoint、旧记录和证据正文转换为摘要，供控制台安全输出。"""
+    if isinstance(value, dict):
+        return {
+            key: digest(item)
+            if key in {"checkpoint", "rows", "evidence", "recovery_confirmation"}
+            else public_result(item)
+            for key, item in value.items()
+        }
+    if isinstance(value, (tuple, list)):
+        return [public_result(item) for item in value]
+    return value
+
+
+def _create_revision(catalog: Catalog, revision: Optional[str]) -> None:
+    require(
+        revision is not None and re.fullmatch(r"[A-Za-z0-9_-]{1,80}", revision),
+        "revision_id_required",
+    )
+    require(
+        revision not in [item.revision for item in catalog.revisions],
+        "duplicate_revision",
+    )
+    resource = next(iter(catalog.project["resources"]))
+    metadata = {
+        "revision": revision,
+        "parent": catalog.revisions[-1].revision,
+        "resources": [resource],
+        "risk": "additive",
+        "resume": False,
+        "checks": [{"resource": resource, "exists": True}],
+    }
+    source = (
+        '# coding=utf-8\n"""服务自有迁移；发布前补齐风险和数据后检。"""\n'
+        "MIGRATION = " + repr(metadata) + "\n\ndef upgrade(context):\n"
+        '    raise NotImplementedError("请实现迁移和后置检查")\n'
+    )
+    with (catalog.path.parent / "versions" / (str(revision) + ".py")).open(
+        "x", encoding="utf-8"
+    ) as output:
+        output.write(source)
+
+
+def main(
+    argv: Optional[Sequence[str]] = None,
+    *,
+    project_root: Optional[Union[str, Path]] = None,
+    execution_role: Optional[str] = None,
+) -> int:
+    """执行独立 CLI，成功返回0，失败返回非0。
+
+    Args:
+        argv: 参数列表；默认读取进程参数。
+        project_root: 业务项目目录，默认为当前工作目录，而非 site-packages。
+        execution_role: 适配器已经判定的角色；提供后禁止命令行覆盖。
+
+    Returns:
+        进程退出码。连接和脚本错误仅输出脱敏的错误类别。
+
+    """
+    parser = argparse.ArgumentParser(description="Mongrade：MongoDB 版本化迁移工具")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument(
+        "command",
+        choices=(
+            "diagnose",
+            "verify",
+            "plan",
+            "migrate",
+            "graph",
+            "show",
+            "adopt",
+            "recover",
+            "create",
+            "tui",
+        ),
+    )
+    parser.add_argument("--project", default="mongo_migrations/project.json")
+    parser.add_argument(
+        "--role",
+        choices=("author", "deploy"),
+        default=execution_role or os.environ.get("MIGRATION_EXECUTION_ROLE", "deploy"),
+    )
+    parser.add_argument("--uri-env", default="MONGRADE_URI")
+    parser.add_argument("--target", default="head")
+    parser.add_argument("--evidence")
+    parser.add_argument("--confirmation")
+    parser.add_argument("--confirm-plan-sha256")
+    parser.add_argument("--revision-id")
+    args = parser.parse_args(argv)
+    try:
+        role = args.role
+        require(role in ("author", "deploy"), "invalid_execution_role")
+        require(
+            execution_role is None or role == execution_role,
+            "execution_role_override_rejected",
+        )
+        root = (
+            Path(project_root).resolve()
+            if project_root is not None
+            else Path.cwd().resolve()
+        )
+        path = (root / args.project).resolve()
+        require(
+            role == "author"
+            or path == (root / "mongo_migrations/project.json").resolve(),
+            "deploy_requires_service_project",
+        )
+        catalog = load_catalog(path)
+        if args.command == "create":
+            require(role == "author", "deploy_cannot_create_revision")
+            _create_revision(catalog, args.revision_id)
+            print("[OK] revision_created_requires_release_review")
+            return 0
+        if args.command == "graph":
+            print(
+                json.dumps(
+                    [revision.metadata for revision in catalog.revisions],
+                    ensure_ascii=True,
+                )
+            )
+            return 0
+        uri = os.environ.get(args.uri_env)
+        if not uri:
+            raise MigrationError("mongo_uri_environment_required")
+        evidence = read_json(root / args.evidence) if args.evidence else {}
+        with connect(uri, catalog) as client:
+            command = args.command
+            if command == "tui":
+                print(
+                    json.dumps(
+                        public_result(diagnose(client, catalog)),
+                        default=str,
+                        ensure_ascii=True,
+                    )
+                )
+                print("[1] diagnose  [2] verify  [3] plan  [0] exit")
+                command = {"1": "diagnose", "2": "verify", "3": "plan"}.get(
+                    input("> ").strip()
+                )
+                if command is None:
+                    return 0
+            if command in ("diagnose", "show"):
+                result = diagnose(client, catalog)
+            elif command == "verify":
+                result = verify(client, catalog)
+            elif command == "recover":
+                require(args.confirmation is not None, "recovery_confirmation_required")
+                result = recover(
+                    client, catalog, evidence, read_json(root / args.confirmation), role
+                )
+            else:
+                approved = plan(client, catalog, args.target, evidence)
+                if command == "plan":
+                    result = {"plan_sha256": approved.sha256, "facts": approved.facts}
+                else:
+                    require(
+                        args.confirm_plan_sha256 == approved.sha256,
+                        "plan_confirmation_required",
+                    )
+                    operation = adopt if command == "adopt" else migrate
+                    result = operation(client, catalog, approved, evidence, role)
+            print(json.dumps(public_result(result), default=str, ensure_ascii=True))
+            return 0
+    except (Exception, KeyboardInterrupt) as error:
+        reason = (
+            str(error) if isinstance(error, MigrationError) else classify_error(error)
+        )
+        print("[ERROR] " + reason, file=sys.stderr)
+        return 1

mongrade/context.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+# coding=utf-8
+"""受信 revision 的显式资源及合作式停写上下文；不是沙箱。"""
+
+from typing import Any
+
+from .models import Revision, require
+
+READS = {"find_one", "count_documents", "index_information"}
+ADDITIONS = {"insert_one", "insert_many", "create_index"}
+DESTRUCTIVE = {
+    "update_one",
+    "update_many",
+    "replace_one",
+    "delete_one",
+    "delete_many",
+    "drop_index",
+    "drop",
+}
+
+
+class Resource:
+    """按声明资源执行操作并复核准入；不是安全沙箱。"""
+
+    def __init__(self, context: Any, resource: Any) -> None:
+        """绑定资源声明和当前执行上下文。"""
+        self._context, self._resource = context, resource
+
+    def __getattr__(self, method: str) -> Any:
+        """只暴露受审操作，并在每次调用前后验证执行权。"""
+        require(
+            method in READS | ADDITIONS | DESTRUCTIVE, "unsupported_resource_operation"
+        )
+
+        def invoke(*args: Any, **kwargs: Any) -> Any:
+            context, resource = self._context, self._resource
+            context.guard()
+            require(
+                method not in DESTRUCTIVE or context.destructive,
+                "destructive_operation_requires_review",
+            )
+            if method == "create_index":
+                require(
+                    set(kwargs) <= {"name", "unique"}, "unsupported_index_options_v1"
+                )
+            if resource.get("index"):
+                require(
+                    method in READS or method in ("create_index", "drop_index"),
+                    "index_owner_cannot_write_collection_data",
+                )
+                if method == "create_index":
+                    require(
+                        kwargs.get("name") == resource["index"], "index_scope_conflict"
+                    )
+                if method == "drop_index":
+                    require(
+                        args and args[0] == resource["index"], "index_scope_conflict"
+                    )
+            result = getattr(
+                context._state.client[resource["database"]][resource["collection"]],
+                method,
+            )(*args, **kwargs)
+            context.guard()
+            return result
+
+        return invoke
+
+
+class Context:
+    """迁移脚本的显式资源和 checkpoint 上下文。"""
+
+    def __init__(self, state: Any, revision: Revision, guard: Any) -> None:
+        """绑定运行状态、当前版本及本次准入复核函数。"""
+        self._state, self._revision, self._guard = state, revision, guard
+        self.destructive = revision.metadata["risk"] == "destructive"
+
+    def guard(self) -> None:
+        """复核锁及切换前提，失锁时停止后续写入。"""
+        self._state.guard()
+        self._guard()
+
+    def resource(self, alias: str) -> Resource:
+        """取得当前 revision 已声明的资源别名。"""
+        require(alias in self._revision.metadata["resources"], "undeclared_resource")
+        self.guard()
+        return Resource(self, self._state.project["resources"][alias])
+
+    @property
+    def checkpoint(self) -> Any:
+        """读取或保存当前运行版本的受保护进度。"""
+        self.guard()
+        return self._state.read()["running"]["checkpoint"]
+
+    def save_checkpoint(self, value: Any) -> None:
+        """锁和维护证据仍有效时保存批次进度。"""
+        self.guard()
+        self._state.checkpoint(value)