Publish curated ITWorx_MCP_Hub source from 7fde2770ba344c684b7e7a6b74f763dc19e7c560

packages/connector_kit/gitea.py

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 import base64
+import copy
 import ipaddress
 import json
 import re
 import time
 from collections.abc import Mapping
+from datetime import UTC, datetime
 from pathlib import Path
 from threading import RLock
 from typing import Any, Protocol, cast
@@ -331,6 +333,13 @@ class GiteaClient:
     """Small bounded Gitea API client with same-origin redirect enforcement."""
 
     _path_part = re.compile(r"^[^/\\?#\x00-\x1f\x7f]+$")
+    _semver = re.compile(
+        r"v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)"
+        r"(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?"
+        r"(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?"
+    )
+    _version_cache_seconds = 30
+    _supported_ranges = (">=1.14.0 <1.15.0", ">=1.25.0 <1.28.0", ">=28.0.0 <29.0.0")
 
     def __init__(
         self,
@@ -347,7 +356,8 @@ class GiteaClient:
             follow_redirects=False,
             transport=transport,
         )
-        self._merge_strategy_key: str | None = None
+        self._version_lock = RLock()
+        self._version_cache: tuple[float, dict[str, Any]] | None = None
 
     def close(self) -> None:
         self._client.close()
@@ -813,27 +823,100 @@ class GiteaClient:
             ),
         )
 
-    def _merge_strategy_field(self) -> str:
-        """Resolve the versioned Gitea merge field before the single write attempt."""
+    def upstream_compatibility(self, *, force_refresh: bool = False) -> dict[str, Any]:
+        """Read the upstream version, independent of this connector's build version.
 
-        if self._merge_strategy_key is not None:
-            return self._merge_strategy_key
-        payload = self._request(self._path("version"))
-        version = payload.get("version") if isinstance(payload, dict) else None
-        legacy_match = re.fullmatch(r"1\.(14|25|26|27)(?:\.\d+)?(?:[-+].*)?", str(version or ""))
-        modern_match = re.fullmatch(r"(28)(?:\.\d+){1,2}(?:[-+].*)?", str(version or ""))
-        if legacy_match is None and modern_match is None:
+        Diagnostics cache for 30 seconds; each merge negotiates again immediately
+        before its one write. Failed probes replace cached success and never fall
+        back to the connector version. Gitea 28 drops the historical ``1.`` prefix.
+        """
+        with self._version_lock:
+            now = time.monotonic()
+            if (
+                not force_refresh
+                and self._version_cache is not None
+                and now - self._version_cache[0] < self._version_cache_seconds
+            ):
+                return copy.deepcopy(self._version_cache[1])
+            diagnostics: dict[str, Any] = {
+                "source": "/api/v1/version",
+                "upstreamVersion": None,
+                "normalizedVersion": None,
+                "compatibility": "UNKNOWN",
+                "reason": "upstream_version_missing_or_malformed",
+                "mergeStrategyField": None,
+                "supportedRanges": list(self._supported_ranges),
+                "prereleasesSupported": False,
+                "checkedAt": datetime.now(UTC).isoformat(),
+                "cacheSeconds": self._version_cache_seconds,
+                "errorCode": None,
+            }
+            try:
+                payload = self._request(self._path("version"))
+            except GiteaError as exc:
+                diagnostics.update(
+                    compatibility="UNAVAILABLE",
+                    reason="upstream_version_probe_failed",
+                    errorCode=exc.code,
+                )
+            else:
+                version = payload.get("version") if isinstance(payload, dict) else None
+                # Do not reflect arbitrary upstream data (or secret-like content).
+                if isinstance(version, str) and len(version) <= 128:
+                    version = version.strip()
+                    match = self._semver.fullmatch(version)
+                    if match is not None:
+                        release = tuple(int(match.group(index)) for index in (1, 2, 3))
+                        prerelease = match.group(4)
+                        invalid_prerelease = prerelease is not None and any(
+                            part.isdigit() and len(part) > 1 and part.startswith("0")
+                            for part in prerelease.split(".")
+                        )
+                        if not invalid_prerelease:
+                            # Arbitrary SemVer suffixes can contain opaque credentials.
+                            # Display only the numeric release; negotiate the full parsed version.
+                            display_version = ("v" if version.startswith("v") else "") + ".".join(
+                                str(part) for part in release
+                            )
+                            diagnostics.update(
+                                upstreamVersion=display_version,
+                                normalizedVersion=display_version.removeprefix("v"),
+                                compatibility="UNSUPPORTED",
+                                reason="upstream_release_outside_tested_ranges",
+                            )
+                            supported = (
+                                (1, 14, 0) <= release < (1, 15, 0)
+                                or (1, 25, 0) <= release < (1, 28, 0)
+                                or (28, 0, 0) <= release < (29, 0, 0)
+                            )
+                            if prerelease is not None:
+                                diagnostics["reason"] = "upstream_prerelease_not_tested"
+                            elif supported:
+                                diagnostics.update(
+                                    compatibility="SUPPORTED",
+                                    reason="upstream_release_in_tested_ranges",
+                                    mergeStrategyField=("Do" if release < (1, 26, 0) else "do"),
+                                )
+            self._version_cache = (time.monotonic(), copy.deepcopy(diagnostics))
+            return diagnostics
+
+    def _merge_strategy_field(self) -> str:
+        """Negotiate against the current upstream immediately before the merge write."""
+        diagnostics = self.upstream_compatibility(force_refresh=True)
+        if diagnostics["compatibility"] != "SUPPORTED":
             raise GiteaError(
-                "GITEA_VERSION_UNSUPPORTED",
+                diagnostics["errorCode"] or "GITEA_VERSION_UNSUPPORTED",
                 (
                     "Gitea merge compatibility requires an identified "
-                    "1.14, 1.25, 1.26, 1.27, or 28.x server"
+                    "1.14, 1.25, 1.26, 1.27, or 28.x stable server; "
+                    f"{diagnostics['reason']}"
                 ),
+                category="compatibility",
+                expected_state="Stable upstream release in tested compatibility ranges",
+                actual_state=str(diagnostics["compatibility"]),
+                recovery_hint="Inspect gitea.capabilities.get upstreamGitea diagnostics",
             )
-        self._merge_strategy_key = (
-            "Do" if legacy_match is not None and legacy_match.group(1) in {"14", "25"} else "do"
-        )
-        return self._merge_strategy_key
+        return str(diagnostics["mergeStrategyField"])
 
     def update_pull_request_branch(
         self,