208 lines
8.2 KiB
Python
Executable File
208 lines
8.2 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Fail when checked-in API, event, MCP or n8n contracts drift from the code."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import hashlib
|
|
import json
|
|
import re
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
import yaml
|
|
|
|
from app.core.config import get_settings
|
|
from app.main import app
|
|
|
|
ROOT = Path(__file__).resolve().parents[1]
|
|
|
|
|
|
def fail(message: str, failures: list[str]) -> None:
|
|
failures.append(message)
|
|
|
|
|
|
def check_openapi(failures: list[str]) -> None:
|
|
committed = yaml.safe_load((ROOT / "contracts/openapi.yaml").read_text(encoding="utf-8"))
|
|
generated = app.openapi()
|
|
if committed != generated:
|
|
fail(
|
|
"contracts/openapi.yaml differs from app.openapi(); regenerate it with "
|
|
"scripts/generate-openapi.py",
|
|
failures,
|
|
)
|
|
|
|
|
|
def check_mcp(failures: list[str]) -> None:
|
|
contract = json.loads((ROOT / "contracts/mcp-tools.json").read_text(encoding="utf-8"))
|
|
contracted = {
|
|
(tool["endpoint"]["method"].upper(), tool["endpoint"]["path"])
|
|
for tool in contract["tools"]
|
|
if tool.get("read_only") is True and isinstance(tool.get("endpoint"), dict)
|
|
}
|
|
generated = app.openapi()
|
|
implemented = {
|
|
(method.upper(), path)
|
|
for path, operations in generated["paths"].items()
|
|
if path.startswith("/api/v1/integrations/mcp/")
|
|
for method in operations
|
|
if method.lower() in {"get", "post", "put", "patch", "delete"}
|
|
}
|
|
if len(contracted) != len(contract["tools"]):
|
|
fail("Every MCP tool must be read-only and declare its provider endpoint", failures)
|
|
if contracted != implemented:
|
|
fail(
|
|
f"MCP endpoint drift: contract={sorted(contracted)!r}, code={sorted(implemented)!r}",
|
|
failures,
|
|
)
|
|
if any(method not in {"GET", "POST"} for method, _path in contracted):
|
|
fail("MCP contract exposes an unsupported mutation method", failures)
|
|
|
|
|
|
def check_event_schema(failures: list[str]) -> None:
|
|
schema = json.loads((ROOT / "contracts/events.schema.json").read_text(encoding="utf-8"))
|
|
expected_envelope = {
|
|
"event_id",
|
|
"event_type",
|
|
"occurred_at",
|
|
"correlation_id",
|
|
"aggregate",
|
|
"data",
|
|
}
|
|
expected_data = {
|
|
"vehicle_ref",
|
|
"inspection_ref",
|
|
"resulting_vehicle_status",
|
|
"attention_reasons",
|
|
}
|
|
if set(schema.get("required", [])) != expected_envelope:
|
|
fail("Event envelope required fields drifted", failures)
|
|
data_schema = schema.get("properties", {}).get("data", {})
|
|
if set(data_schema.get("required", [])) != expected_data:
|
|
fail("vehicle.returned.v1 data fields drifted", failures)
|
|
event_type = schema.get("properties", {}).get("event_type", {}).get("const")
|
|
if event_type != "vehicle.returned.v1":
|
|
fail("Unexpected event_type contract", failures)
|
|
|
|
|
|
def check_workflows(failures: list[str]) -> None:
|
|
workflows_dir = ROOT / "n8n/workflows"
|
|
manifest = (workflows_dir / "MANIFEST.md").read_text(encoding="utf-8")
|
|
expected = {
|
|
"fleet-ops-vehicle-return.json": "mobilityops-return-processing",
|
|
"fleet-ops-data-quality-scan.json": "mobilityops-scheduled-quality-scan",
|
|
"fleet-ops-ragcore-procedure-sync.json": "6wbkc4d1AouGpmWT",
|
|
"fleet-ops-error-handler.json": "Xppn2rAEqUuyiCJF",
|
|
"fleet-ops-alert-receiver.json": "mobilityops-alert-receiver",
|
|
}
|
|
declared_hashes = set(re.findall(r"`([0-9a-f]{64})`", manifest))
|
|
for filename, workflow_id in expected.items():
|
|
path = workflows_dir / filename
|
|
raw = path.read_bytes()
|
|
digest = hashlib.sha256(raw).hexdigest()
|
|
if digest not in declared_hashes:
|
|
fail(f"{filename} checksum is missing or stale in MANIFEST.md", failures)
|
|
definition = json.loads(raw)
|
|
if definition.get("id") != workflow_id:
|
|
fail(f"{filename} has unexpected workflow id", failures)
|
|
serialized = raw.decode("utf-8")
|
|
if "http://fleetops.itworx.tech" in serialized:
|
|
fail(f"{filename} contains a cleartext Fleet Ops callback", failures)
|
|
if filename == "fleet-ops-vehicle-return.json":
|
|
check_return_workflow_timing(definition, failures)
|
|
if filename == "fleet-ops-ragcore-procedure-sync.json":
|
|
check_ragcore_sync_workflow(definition, failures)
|
|
|
|
|
|
def check_ragcore_sync_workflow(definition: dict, failures: list[str]) -> None:
|
|
"""Keep the sync identity stable and reject HTTP error bodies as successful syncs."""
|
|
nodes_by_name = {node.get("name"): node for node in definition.get("nodes", [])}
|
|
upload = nodes_by_name.get("Upload to RAGcore", {})
|
|
credential = upload.get("credentials", {}).get("httpHeaderAuth", {})
|
|
if credential.get("name") != "RAGcore Sync Token":
|
|
fail("RAGcore upload must use the dedicated sync credential", failures)
|
|
|
|
parameters = upload.get("parameters", {}).get("bodyParameters", {}).get("parameters", [])
|
|
field_names = {
|
|
item.get("name") for item in parameters if isinstance(item, dict)
|
|
}
|
|
required = {"space_id", "source_id", "external_id", "locale", "file"}
|
|
if not required.issubset(field_names):
|
|
fail(
|
|
"RAGcore upload must preserve source_id, external_id and locale provenance",
|
|
failures,
|
|
)
|
|
|
|
summary_code = (
|
|
nodes_by_name.get("Summarize sync result", {}).get("parameters", {}).get("jsCode", "")
|
|
)
|
|
if not all(token in summary_code for token in ("job_id", "status_url", "failed += 1")):
|
|
fail("RAGcore sync summary must accept only a real AcceptedJob response", failures)
|
|
|
|
|
|
def check_return_workflow_timing(definition: dict, failures: list[str]) -> None:
|
|
"""Keep nested retry budgets inside the dispatcher's recoverable delivery lease."""
|
|
nodes_by_name = {node.get("name"): node for node in definition.get("nodes", [])}
|
|
validation_code = (
|
|
nodes_by_name.get("Validate and derive follow-up", {}).get("parameters", {}).get("jsCode", "")
|
|
)
|
|
if not all(field in validation_code for field in ("event_id", "correlation_id")):
|
|
fail(
|
|
"Vehicle-return workflow must preserve event_id and correlation_id for its callback",
|
|
failures,
|
|
)
|
|
required_nodes = ("Record follow-up", "Report workflow heartbeat")
|
|
workflow_budget_ms = 0
|
|
for name in required_nodes:
|
|
node = nodes_by_name.get(name)
|
|
if not isinstance(node, dict):
|
|
fail(f"Vehicle-return workflow is missing timing-critical node {name!r}", failures)
|
|
return
|
|
options = node.get("parameters", {}).get("options", {})
|
|
timeout_ms = options.get("timeout")
|
|
if node.get("retryOnFail") is not True:
|
|
fail(f"{name!r} must retain bounded retries", failures)
|
|
return
|
|
max_tries = node.get("maxTries")
|
|
wait_ms = node.get("waitBetweenTries", 0)
|
|
if not all(
|
|
isinstance(value, int) and not isinstance(value, bool) and value > 0
|
|
for value in (timeout_ms, max_tries)
|
|
) or (
|
|
max_tries < 2
|
|
or not isinstance(wait_ms, int)
|
|
or isinstance(wait_ms, bool)
|
|
or wait_ms < 0
|
|
):
|
|
fail(f"{name!r} has an invalid timeout/retry budget", failures)
|
|
return
|
|
workflow_budget_ms += timeout_ms * max_tries + wait_ms * (max_tries - 1)
|
|
|
|
settings = get_settings()
|
|
dispatcher_timeout_ms = settings.n8n_http_timeout_seconds * 1000
|
|
lease_ms = settings.n8n_delivery_lease_seconds * 1000
|
|
if not workflow_budget_ms < dispatcher_timeout_ms < lease_ms:
|
|
fail(
|
|
"Vehicle-return timing contract violated: complete callback/heartbeat retry "
|
|
f"budget {workflow_budget_ms}ms must be below dispatcher timeout "
|
|
f"{dispatcher_timeout_ms:g}ms, which must be below delivery lease {lease_ms:g}ms",
|
|
failures,
|
|
)
|
|
|
|
|
|
def main() -> int:
|
|
failures: list[str] = []
|
|
check_openapi(failures)
|
|
check_mcp(failures)
|
|
check_event_schema(failures)
|
|
check_workflows(failures)
|
|
if failures:
|
|
for failure in failures:
|
|
print(f"ERROR: {failure}", file=sys.stderr)
|
|
return 1
|
|
print("OpenAPI, event, MCP and n8n contracts are synchronized.")
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|