Publish curated Unraid-AppOps-Gateway source from aaf7d11821a86be65c91fead97a6a4758c4fbacd

backend/app/services/deployment_broker.py

@@ -1,9 +1,10 @@
 """Client for the private, typed deployment broker surface.
 
-The client only sends a canonical DeploymentPlanV1 to a configured controller.
-It neither exposes a command field nor calls a Docker socket/Portainer exec
-endpoint.  The controller independently validates repository, revision and
-runtime topology before it can mutate production.
+The client sends a canonical DeploymentPlanV1 or a closed fixed-target
+operation to a configured controller. It neither exposes a command field nor
+calls a Docker socket/Portainer exec endpoint. The controller independently
+validates repository, revision and runtime topology before it can mutate
+production.
 """
 
 from __future__ import annotations
@@ -200,7 +201,15 @@ class DeploymentBrokerClient:
         except httpx.RequestError as exc:
             return {"status": "unreachable", "reason": redact_message(str(exc))}
         if response.status_code in {401, 403}:
-            return {"status": "unauthorized", "reason": "deployment_broker_authentication_failed"}
+            rejected = {"status": "unauthorized", "reason": "deployment_broker_authentication_failed"}
+            try:
+                auth_payload = response.json()
+            except ValueError:
+                auth_payload = None
+            if ("noMutation" in error_response_fields and isinstance(auth_payload, dict)
+                    and isinstance(auth_payload.get("noMutation"), bool)):
+                rejected["noMutation"] = auth_payload["noMutation"]
+            return rejected
         try:
             decoded = response.json()
         except ValueError:
@@ -316,6 +325,55 @@ class DeploymentBrokerClient:
             error_response_fields=frozenset({"noMutation"}),
         )
 
+    def hub_delivery_operation(self, stage: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Use the fixed Hub signed-delivery gate without retrying uncertain requests."""
+        if stage not in {"preflight", "revalidate"} or not isinstance(payload, dict):
+            raise ValueError("Hub delivery stage is invalid")
+        if stage == "preflight":
+            if (set(payload) != {"revision"} or not isinstance(payload.get("revision"), str)
+                    or not re.fullmatch(r"[0-9a-f]{40}", payload["revision"])):
+                raise ValueError("Hub delivery preflight contract is invalid")
+        elif (set(payload) != {"revision", "expectedPreflightSha256", "idempotencyKey"}
+              or not isinstance(payload.get("revision"), str)
+              or not re.fullmatch(r"[0-9a-f]{40}", payload["revision"])
+              or not isinstance(payload.get("expectedPreflightSha256"), str)
+              or not re.fullmatch(r"[0-9a-f]{64}", payload["expectedPreflightSha256"])
+              or not isinstance(payload.get("idempotencyKey"), str)
+              or not re.fullmatch(r"[A-Za-z0-9._:-]{8,128}", payload["idempotencyKey"])):
+            raise ValueError("Hub delivery revalidation contract is invalid")
+        result = self._request(
+            "POST", f"/v1/appops/hub-delivery/{stage}",
+            secret=settings.mcp_token or "", payload=payload,
+            error_response_fields=frozenset({"noMutation"}),
+        )
+        if stage == "revalidate" and (
+            result.get("status") == "unreachable" or type(result.get("noMutation")) is not bool
+        ):
+            return {
+                "status": "unknown",
+                "reason": "hub_delivery_outcome_unknown",
+                "noMutation": False,
+            }
+        if stage == "preflight" and result.get("status") == "unreachable":
+            return {
+                "status": "unavailable",
+                "reason": "hub_delivery_preflight_unavailable",
+                "noMutation": True,
+            }
+        if stage == "preflight" and type(result.get("noMutation")) is not bool:
+            return {
+                "status": "unavailable",
+                "reason": "hub_delivery_preflight_response_invalid",
+                "noMutation": True,
+            }
+        if stage == "preflight" and result.get("noMutation") is not True:
+            return {
+                "status": "unknown",
+                "reason": "hub_delivery_preflight_mutation_unexpected",
+                "noMutation": False,
+            }
+        return result
+
     def registered_legacy_operation(self, stage: str, payload: dict[str, Any]) -> dict[str, Any]:
         """Signed fixed-stage metadata adoption/recovery for existing registered targets."""
         if stage not in {"observe", "baseline", "preflight", "adopt", "status", "rollback", "delivery"}: