droboticflow/scripts/verify_dcloud_operator_contracts.py
2026-06-23 13:37:29 +08:00

237 lines
8.6 KiB
Python

#!/usr/bin/env python3
from __future__ import annotations
import argparse
import json
import pathlib
import subprocess
import sys
from dataclasses import dataclass
from typing import Any
ROOT = pathlib.Path(__file__).resolve().parents[1]
DEFAULT_SOURCE_ROOT = ROOT / ".operator-source-repos" / "d-cloud"
@dataclass(frozen=True)
class SourceCheck:
path: str
contains: tuple[str, ...]
description: str
@dataclass(frozen=True)
class DCloudContract:
slug: str
repo_dir: str
expected_repo_suffix: str
expected_fat_route: str
expected_probe_endpoint: str
expected_probe_method: str
expected_probe_request_json: dict[str, Any] | None
source_checks: tuple[SourceCheck, ...]
CONTRACTS = (
DCloudContract(
slug="dcloud_embodied_annotation",
repo_dir="robo_annotation_backend",
expected_repo_suffix="/d-cloud/robo_annotation_backend",
expected_fat_route="/api/annoMidwareApi/api/v1",
expected_probe_endpoint="/api/annoMidwareApi/api/v1/me",
expected_probe_method="GET",
expected_probe_request_json=None,
source_checks=(
SourceCheck("pegasus/api/auth.py", ('@router.get("/me")',), "annotation service exposes GET /me"),
SourceCheck(
"pegasus/deps.py",
('Header(alias="d-user-id")', 'Header(alias="org-symbol")', 'Header(alias="sourceapp")'),
"annotation service requires D-Cloud identity headers",
),
SourceCheck("docs/apis.md", ("`/me`",), "annotation API docs include /me identity contract"),
),
),
DCloudContract(
slug="dcloud_data_generation",
repo_dir="data_generation",
expected_repo_suffix="/d-cloud/data_generation",
expected_fat_route="/api/generationApi",
expected_probe_endpoint="/api/generationApi/imgGeneration/tasks",
expected_probe_method="POST",
expected_probe_request_json={"currentPage": 1, "keyword": "", "pageSize": 10},
source_checks=(
SourceCheck("initialize/server.go", ('r.Group("/generationApi")',), "generation service registers /generationApi"),
SourceCheck(
"api/img_generation.go",
('apiGroup.Group("/imgGeneration")', 'imgGenerationGroup.POST("/tasks", h.ListTasks)'),
"generation service exposes POST /imgGeneration/tasks",
),
SourceCheck(
"common/middleware/request.go",
('GetHeader("d-user-id")', 'GetHeader("sourceapp")'),
"generation service reads D-Cloud identity headers",
),
),
),
)
def normalize_repo_url(value: str) -> str:
return value.strip().removesuffix(".git").rstrip("/")
def git_head(repo: pathlib.Path) -> str:
if not (repo / ".git").exists():
return ""
result = subprocess.run(
["git", "-C", str(repo), "rev-parse", "--short", "HEAD"],
text=True,
capture_output=True,
check=False,
)
return result.stdout.strip() if result.returncode == 0 else ""
def load_operator_metadata(slug: str) -> dict[str, Any]:
path = ROOT / "backend" / "operators" / "builtin" / slug / "operator.json"
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise SystemExit(f"operator metadata is missing: {path}") from exc
except json.JSONDecodeError as exc:
raise SystemExit(f"operator metadata is invalid JSON: {path}: {exc}") from exc
if not isinstance(payload, dict):
raise SystemExit(f"operator metadata must be a JSON object: {path}")
return payload
def metadata_value(payload: dict[str, Any], *path: str) -> Any:
value: Any = payload
for key in path:
if not isinstance(value, dict):
return None
value = value.get(key)
return value
def check_file_contains(repo: pathlib.Path, check: SourceCheck) -> dict[str, Any]:
path = repo / check.path
if not path.is_file():
return {
"name": check.description,
"status": "failed",
"path": check.path,
"message": "source file is missing",
}
text = path.read_text(encoding="utf-8", errors="replace")
missing = [needle for needle in check.contains if needle not in text]
if missing:
return {
"name": check.description,
"status": "failed",
"path": check.path,
"message": "source file does not contain the required contract markers",
"missingMarkers": missing,
}
return {"name": check.description, "status": "passed", "path": check.path}
def check_contract(source_root: pathlib.Path, contract: DCloudContract) -> dict[str, Any]:
metadata = load_operator_metadata(contract.slug)
external_api = metadata_value(metadata, "externalApi")
if not isinstance(external_api, dict):
external_api = {}
probe = external_api.get("acceptanceProbe")
if not isinstance(probe, dict):
probe = {}
repo = source_root / contract.repo_dir
checks: list[dict[str, Any]] = []
source_repo = normalize_repo_url(str(external_api.get("sourceRepo", "")))
checks.append(
{
"name": "operator metadata source repo",
"status": "passed" if source_repo.endswith(contract.expected_repo_suffix) else "failed",
"expectedSuffix": contract.expected_repo_suffix,
"actual": source_repo,
}
)
fat_route = str(external_api.get("fatRoute", "")).strip()
checks.append(
{
"name": "operator metadata FAT route",
"status": "passed" if fat_route == contract.expected_fat_route else "failed",
"expected": contract.expected_fat_route,
"actual": fat_route,
}
)
probe_endpoint = str(probe.get("endpoint", "")).strip()
checks.append(
{
"name": "acceptance probe endpoint",
"status": "passed" if probe_endpoint == contract.expected_probe_endpoint else "failed",
"expected": contract.expected_probe_endpoint,
"actual": probe_endpoint,
}
)
probe_method = (str(probe.get("method", "")).strip() or "POST").upper()
checks.append(
{
"name": "acceptance probe method",
"status": "passed" if probe_method == contract.expected_probe_method else "failed",
"expected": contract.expected_probe_method,
"actual": probe_method,
}
)
probe_request_json = probe.get("requestJson") if "requestJson" in probe else None
checks.append(
{
"name": "acceptance probe request JSON",
"status": "passed" if probe_request_json == contract.expected_probe_request_json else "failed",
"expected": contract.expected_probe_request_json,
"actual": probe_request_json,
}
)
if not repo.is_dir():
checks.append(
{
"name": "source repository checkout",
"status": "failed",
"path": str(repo),
"message": "clone the source repo before running this check",
}
)
else:
checks.append({"name": "source repository checkout", "status": "passed", "path": str(repo), "head": git_head(repo)})
checks.extend(check_file_contains(repo, check) for check in contract.source_checks)
status = "passed" if all(item["status"] == "passed" for item in checks) else "failed"
return {"slug": contract.slug, "status": status, "repoDir": contract.repo_dir, "checks": checks}
def main() -> int:
parser = argparse.ArgumentParser(description="Verify D-Cloud operator metadata against checked out source repos.")
parser.add_argument("--source-root", default=str(DEFAULT_SOURCE_ROOT), help="directory containing d-cloud source repo checkouts")
parser.add_argument("--json", action="store_true", help="emit JSON output")
args = parser.parse_args()
source_root = pathlib.Path(args.source_root).expanduser().resolve()
results = [check_contract(source_root, contract) for contract in CONTRACTS]
status = "passed" if all(item["status"] == "passed" for item in results) else "failed"
payload = {"status": status, "sourceRoot": str(source_root), "contracts": results}
if args.json:
print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
else:
for result in results:
print(f"{result['slug']}: {result['status']}")
for check in result["checks"]:
print(f" - {check['status']}: {check['name']}")
return 0 if status == "passed" else 1
if __name__ == "__main__":
sys.exit(main())