github2gerrit 0.1.6__py3-none-any.whl → 0.1.7__py3-none-any.whl

github2gerrit/gerrit_rest.py

@@ -0,0 +1,298 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2025 The Linux Foundation
+"""
+Gerrit REST helper with retry, timeout, and transient error detection.
+
+This module provides a thin, typed wrapper for issuing Gerrit REST calls
+with:
+- Bounded retries using exponential backoff with jitter
+- Request timeouts
+- Transient error classification (HTTP 5xx/429 and common network errors)
+- Centralized URL handling via GerritUrlBuilder
+
+It prefers pygerrit2 when available and falls back to urllib otherwise.
+
+Usage:
+    from github2gerrit.gerrit_rest import build_client_for_host
+
+    client = build_client_for_host("gerrit.example.org", timeout=8.0)
+    items = client.get("/changes/?q=project:foo limit:1&n=1&o=CURRENT_REVISION")
+
+Design notes:
+- The surface area is intentionally small and focused on JSON calls.
+- Authentication (HTTP basic auth) is supported when username/password are
+  provided.
+- Base URLs should be created via the URL builder to respect base paths.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+from typing import Final
+from urllib.parse import urljoin
+
+from .external_api import ApiType
+from .external_api import RetryPolicy
+from .external_api import external_api_call
+from .gerrit_urls import create_gerrit_url_builder
+from .utils import log_exception_conditionally
+
+
+log = logging.getLogger("github2gerrit.gerrit_rest")
+
+# Optional pygerrit2 import
+try:  # pragma: no cover - exercised indirectly by tests that monkeypatch
+    from pygerrit2 import GerritRestAPI as _PygerritRestApi  # type: ignore[import-not-found, unused-ignore]
+    from pygerrit2 import HTTPBasicAuth as _PygerritHttpAuth  # type: ignore[import-not-found, unused-ignore]
+except Exception:  # pragma: no cover - absence path
+    _PygerritRestApi = None
+    _PygerritHttpAuth = None
+
+
+_MSG_PYGERRIT2_REQUIRED_AUTH: Final[str] = "pygerrit2 is required for HTTP authentication"
+
+_TRANSIENT_ERR_SUBSTRINGS: Final[tuple[str, ...]] = (
+    "timed out",
+    "temporarily unavailable",
+    "temporary failure",
+    "connection reset",
+    "connection aborted",
+    "broken pipe",
+    "connection refused",
+    "bad gateway",
+    "service unavailable",
+    "gateway timeout",
+)
+
+
+# Removed individual retry logic functions - now using centralized framework
+
+
+class GerritRestError(RuntimeError):
+    """Raised for non-retryable REST errors or exhausted retries."""
+
+
+@dataclass(frozen=True)
+class _Auth:
+    user: str
+    password: str
+
+
+def _mask_secret(s: str) -> str:
+    if not s:
+        return s
+    if len(s) <= 4:
+        return "****"
+    return s[:2] + "*" * (len(s) - 4) + s[-2:]
+
+
+class GerritRestClient:
+    """
+    Simple JSON REST client for Gerrit with retry/timeout handling.
+
+    - If pygerrit2 is available, use it directly (preferred).
+    - Otherwise, use urllib with manual request construction.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        auth: tuple[str, str] | None = None,
+        timeout: float = 8.0,
+        max_attempts: int = 5,
+    ) -> None:
+        # Normalize base URL to end with '/'
+        base_url = base_url.rstrip("/") + "/"
+        self._base_url: str = base_url
+        self._timeout: float = float(timeout)
+        self._attempts: int = int(max_attempts)
+        self._retry_policy = RetryPolicy(
+            max_attempts=max_attempts,
+            timeout=timeout,
+        )
+        self._auth: _Auth | None = None
+        if auth and auth[0] and auth[1]:
+            self._auth = _Auth(auth[0], auth[1])
+
+        # Build pygerrit client if library is present; otherwise None
+        if _PygerritRestApi is not None:
+            if self._auth is not None:
+                if _PygerritHttpAuth is None:
+                    raise GerritRestError(_MSG_PYGERRIT2_REQUIRED_AUTH)
+                self._client: Any = _PygerritRestApi(
+                    url=self._base_url, auth=_PygerritHttpAuth(self._auth.user, self._auth.password)
+                )
+            else:
+                self._client = _PygerritRestApi(url=self._base_url)
+        else:
+            self._client = None
+
+        log.debug(
+            "GerritRestClient(base_url=%s, timeout=%.1fs, attempts=%d, auth_user=%s)",
+            self._base_url,
+            self._timeout,
+            self._attempts,
+            self._auth.user if self._auth else "",
+        )
+
+    # Public API
+
+    def get(self, path: str) -> Any:
+        """HTTP GET, returning parsed JSON."""
+        return self._request_json_with_retry("GET", path)
+
+    def post(self, path: str, data: Any | None = None) -> Any:
+        """HTTP POST with JSON payload, returning parsed JSON."""
+        return self._request_json_with_retry("POST", path, data=data)
+
+    def put(self, path: str, data: Any | None = None) -> Any:
+        """HTTP PUT with JSON payload, returning parsed JSON."""
+        return self._request_json_with_retry("PUT", path, data=data)
+
+    # Internal helpers
+
+    def _request_json_with_retry(self, method: str, path: str, data: Any | None = None) -> Any:
+        """Perform a JSON request with retry using external API framework."""
+
+        @external_api_call(ApiType.GERRIT_REST, f"{method.lower()}", policy=self._retry_policy)
+        def _do_request() -> Any:
+            return self._request_json(method, path, data)
+
+        return _do_request()
+
+    def _request_json(self, method: str, path: str, data: Any | None = None) -> Any:
+        """Perform a JSON request (retry logic handled by decorator)."""
+        if not path:
+            msg_required = "path is required"
+            raise ValueError(msg_required)
+
+        # Normalize absolute vs relative path
+        rel = path[1:] if path.startswith("/") else path
+        url = urljoin(self._base_url, rel)
+
+        try:
+            if self._client is not None and method == "GET" and data is None:
+                # pygerrit2 path: only using GET to keep behavior consistent with current usage
+                log.debug("Gerrit REST GET via pygerrit2: %s", url)
+                # pygerrit2.get expects a relative path; keep 'path' argument as-is
+                return self._client.get("/" + rel if not path.startswith("/") else path)
+
+            # urllib path (or non-GET with pygerrit2 absent)
+            headers = {"Accept": "application/json"}
+            body_bytes: bytes | None = None
+            if data is not None:
+                headers["Content-Type"] = "application/json"
+                body_bytes = json.dumps(data).encode("utf-8")
+
+            if self._auth is not None:
+                token = base64.b64encode(f"{self._auth.user}:{self._auth.password}".encode()).decode("ascii")
+                headers["Authorization"] = f"Basic {token}"
+            scheme = urllib.parse.urlparse(url).scheme
+            if scheme not in ("http", "https"):
+                msg_scheme = f"Unsupported URL scheme for Gerrit REST: {scheme}"
+                raise GerritRestError(msg_scheme)
+            req = urllib.request.Request(url, data=body_bytes, method=method, headers=headers)
+            log.debug("Gerrit REST %s %s (auth_user=%s)", method, url, self._auth.user if self._auth else "")
+
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                status = getattr(resp, "status", None)
+                content = resp.read()
+                # Gerrit prepends ")]}'" in JSON responses to prevent JSON hijacking; strip if present
+                text = content.decode("utf-8", errors="replace")
+                text = _strip_xssi_guard(text)
+                return _json_loads(text)
+
+        except urllib.error.HTTPError as http_exc:
+            status = getattr(http_exc, "code", None)
+            msg = f"Gerrit REST {method} {url} failed with HTTP {status}"
+            log_exception_conditionally(log, msg)
+            raise GerritRestError(msg) from http_exc
+
+        except Exception as exc:
+            msg = f"Gerrit REST {method} {url} failed: {exc}"
+            log_exception_conditionally(log, msg)
+            raise GerritRestError(msg) from exc
+
+    def __repr__(self) -> str:  # pragma: no cover - convenience
+        masked = ""
+        if self._auth is not None:
+            masked = f"{self._auth.user}:{_mask_secret(self._auth.password)}@"
+        return f"GerritRestClient(base_url='{self._base_url}', auth='{masked}')"
+
+
+def _json_loads(s: str) -> Any:
+    try:
+        return json.loads(s)
+    except Exception as exc:
+        msg_parse = f"Failed to parse JSON response: {exc}"
+        raise GerritRestError(msg_parse) from exc
+
+
+def _strip_xssi_guard(text: str) -> str:
+    # Gerrit typically prefixes JSON with XSSI guard ")]}'"
+    # Strip the guard and any trailing newline after it.
+    if text.startswith(")]}'"):
+        # Common patterns: ")]}'\n" or ")]}'\r\n"
+        if text[4:6] == "\r\n":
+            return text[6:]
+        if text[4:5] == "\n":
+            return text[5:]
+        return text[4:]
+    return text
+
+
+# Removed _sleep function - using centralized retry framework
+
+
+def build_client_for_host(
+    host: str,
+    *,
+    timeout: float = 8.0,
+    max_attempts: int = 5,
+    http_user: str | None = None,
+    http_password: str | None = None,
+) -> GerritRestClient:
+    """
+    Build a GerritRestClient for a given host using the centralized URL builder.
+
+    - Uses auto-discovered or environment-provided base path.
+    - Reads HTTP auth from arguments or environment:
+      GERRIT_HTTP_USER / GERRIT_HTTP_PASSWORD
+      If user is not provided, falls back to GERRIT_SSH_USER_G2G per project norms.
+
+    Args:
+      host: Gerrit hostname (no scheme)
+      timeout: Request timeout in seconds.
+      max_attempts: Max retry attempts for transient failures.
+      http_user: Optional HTTP user.
+      http_password: Optional HTTP password/token.
+
+    Returns:
+      Configured GerritRestClient.
+    """
+    builder = create_gerrit_url_builder(host)
+    base_url = builder.api_url()
+    user = (
+        (http_user or "").strip()
+        or os.getenv("GERRIT_HTTP_USER", "").strip()
+        or os.getenv("GERRIT_SSH_USER_G2G", "").strip()
+    )
+    passwd = (http_password or "").strip() or os.getenv("GERRIT_HTTP_PASSWORD", "").strip()
+    auth: tuple[str, str] | None = (user, passwd) if user and passwd else None
+    return GerritRestClient(base_url=base_url, auth=auth, timeout=timeout, max_attempts=max_attempts)
+
+
+__all__ = [
+    "GerritRestClient",
+    "GerritRestError",
+    "build_client_for_host",
+]

github2gerrit/gerrit_urls.py

@@ -12,11 +12,143 @@ from __future__ import annotations
 
 import logging
 import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
 from urllib.parse import urljoin
 
 
 log = logging.getLogger(__name__)
 
+_BASE_PATH_CACHE: dict[str, str] = {}
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def http_error_301(self, req: Any, fp: Any, code: int, msg: str, headers: Any) -> Any:
+        return fp
+
+    def http_error_302(self, req: Any, fp: Any, code: int, msg: str, headers: Any) -> Any:
+        return fp
+
+    def http_error_303(self, req: Any, fp: Any, code: int, msg: str, headers: Any) -> Any:
+        return fp
+
+    def http_error_307(self, req: Any, fp: Any, code: int, msg: str, headers: Any) -> Any:
+        return fp
+
+    def http_error_308(self, req: Any, fp: Any, code: int, msg: str, headers: Any) -> Any:
+        return fp
+
+
+def _discover_base_path_for_host(host: str, timeout: float = 5.0) -> str:
+    """
+    Discover Gerrit HTTP base path for the given host by probing redirects.
+
+    Strategy:
+    - Probe '/dashboard/self' and '/' without following redirects.
+    - If redirected, infer base path from the first non-endpoint path segment.
+    - If no redirect and 200 OK at '/dashboard/self', assume no base path.
+    - Cache discovery results per host for the process lifetime.
+    """
+    try:
+        if not host:
+            return ""
+        cached = _BASE_PATH_CACHE.get(host)
+        if cached is not None:
+            return cached
+
+        opener = urllib.request.build_opener(_NoRedirect)
+        opener.addheaders = [("User-Agent", "github2gerrit/urls-discovery")]
+        probes = ["/dashboard/self", "/"]
+        known_endpoints = {
+            "changes",
+            "accounts",
+            "dashboard",
+            "c",
+            "q",
+            "admin",
+            "login",
+            "settings",
+            "plugins",
+            "Documentation",
+        }
+
+        for scheme in ("https", "http"):
+            for probe in probes:
+                url = f"{scheme}://{host}{probe}"
+                parsed_url = urllib.parse.urlparse(url)
+                if parsed_url.scheme not in ("https", "http"):
+                    log.debug("Skipping non-HTTP(S) probe URL: %s", url)
+                    continue
+                try:
+                    resp = opener.open(url, timeout=timeout)
+                    code = getattr(resp, "getcode", lambda: None)() or getattr(resp, "status", 0)
+                    # If we reached the page without redirects
+                    if code == 200:
+                        _BASE_PATH_CACHE[host] = ""
+                        log.info("Gerrit base path: ''")
+                        return ""
+                    # Handle 3xx responses when redirects are disabled (no-redirect opener)
+                    if code in (301, 302, 303, 307, 308):
+                        headers = getattr(resp, "headers", {}) or {}
+                        loc = headers.get("Location") or headers.get("location") or ""
+                        if loc:
+                            # Normalize to absolute path
+                            parsed = urllib.parse.urlparse(loc)
+                            path = (
+                                parsed.path
+                                if parsed.scheme or parsed.netloc
+                                else urllib.parse.urlparse(f"https://{host}{loc}").path
+                            )
+                            # Determine candidate base path
+                            segs = [s for s in path.split("/") if s]
+                            base = ""
+                            if segs:
+                                first = segs[0]
+                                if first not in known_endpoints:
+                                    base = first
+                            _BASE_PATH_CACHE[host] = base
+                            log.info("Gerrit base path: '%s'", base)
+                            return base
+                    # If we get any other non-redirect response, try next probe
+                    continue
+                except urllib.error.HTTPError as e:
+                    # HTTPError doubles as the response; capture Location for redirects
+                    code = e.code
+                    loc = e.headers.get("Location") or e.headers.get("location") or ""
+                    if code in (301, 302, 303, 307, 308) and loc:
+                        # Normalize to absolute path
+                        parsed = urllib.parse.urlparse(loc)
+                        path = (
+                            parsed.path
+                            if parsed.scheme or parsed.netloc
+                            else urllib.parse.urlparse(f"https://{host}{loc}").path
+                        )
+                        # Determine candidate base path
+                        segs = [s for s in path.split("/") if s]
+                        base = ""
+                        if segs:
+                            first = segs[0]
+                            if first not in known_endpoints:
+                                base = first
+                        _BASE_PATH_CACHE[host] = base
+                        log.info("Gerrit base path: '%s'", base)
+                        return base
+                    # Non-redirect error; try next probe
+                    continue
+                except Exception as exc:
+                    log.debug("Gerrit base path probe failed for %s%s: %s", host, probe, exc)
+                    continue
+
+    except Exception as exc:
+        log.debug("Gerrit base path discovery error for %s: %s", host, exc)
+        return ""
+    # Default if nothing conclusive after exhausting all probes
+    _BASE_PATH_CACHE[host] = ""
+    log.info("Gerrit base path: ''")
+    return ""
+
 
 class GerritUrlBuilder:
     """
@@ -35,7 +167,7 @@ class GerritUrlBuilder:
         Args:
             host: Gerrit hostname (without protocol)
             base_path: Optional base path override. If None, reads from
-                      GERRIT_HTTP_BASE_PATH environment variable.
+                      GERRIT_HTTP_BASE_PATH environment variable or discovers dynamically.
         """
         self.host = host.strip()
 
@@ -43,7 +175,12 @@ class GerritUrlBuilder:
         if base_path is not None:
             self._base_path = base_path.strip().strip("/")
         else:
-            self._base_path = os.getenv("GERRIT_HTTP_BASE_PATH", "").strip().strip("/")
+            env_bp = os.getenv("GERRIT_HTTP_BASE_PATH", "").strip().strip("/")
+            if env_bp:
+                self._base_path = env_bp
+            else:
+                discovered = _discover_base_path_for_host(self.host)
+                self._base_path = discovered.strip().strip("/")
 
         log.debug(
             "GerritUrlBuilder initialized for host=%s, base_path='%s'",
@@ -149,73 +286,33 @@ class GerritUrlBuilder:
 
     def get_api_url_candidates(self, endpoint: str = "") -> list[str]:
         """
-        Get a list of candidate API URLs for fallback scenarios.
+        Get the single API URL based on discovered/configured base path.
 
-        This method returns URLs in order of preference:
-        1. URL with configured base path (if any)
-        2. URL with /r/ base path (common fallback)
-        3. URL with no base path (root)
+        This method avoids hard-coded fallbacks by relying on dynamic detection
+        of Gerrit's HTTP base path (or explicit configuration).
 
         Args:
             endpoint: API endpoint path
 
         Returns:
-            List of candidate URLs to try
+            A single API URL to use
         """
-        candidates = []
-
-        # Primary URL with configured base path
-        if self.has_base_path:
-            candidates.append(self.api_url(endpoint))
-
-        # Common fallback: /r/ base path
-        if self._base_path != "r":
-            candidates.append(self.api_url(endpoint, base_path_override="r"))
-
-        # Final fallback: no base path
-        if self.has_base_path:
-            candidates.append(self.api_url(endpoint, base_path_override=""))
-
-        # If no base path was configured, add the primary URL
-        if not self.has_base_path:
-            candidates.append(self.api_url(endpoint))
-
-        return candidates
+        return [self.api_url(endpoint)]
 
     def get_hook_url_candidates(self, hook_name: str) -> list[str]:
         """
-        Get a list of candidate hook URLs for fallback scenarios.
+        Get the single hook URL based on discovered/configured base path.
 
-        This method returns URLs in order of preference for downloading hooks:
-        1. URL with configured base path (if any)
-        2. URL with /r/ base path (common for hooks)
-        3. URL with no base path (root)
+        This method avoids hard-coded fallbacks by relying on dynamic detection
+        of Gerrit's HTTP base path (or explicit configuration).
 
         Args:
             hook_name: Name of the hook to download
 
         Returns:
-            List of candidate URLs to try
+            A single hook URL to use
         """
-        candidates = []
-
-        # Primary URL with configured base path
-        if self.has_base_path:
-            candidates.append(self.hook_url(hook_name))
-
-        # Common fallback: /r/ base path (very common for hooks)
-        if self._base_path != "r":
-            candidates.append(self.hook_url(hook_name, base_path_override="r"))
-
-        # Final fallback: no base path
-        if self.has_base_path:
-            candidates.append(self.hook_url(hook_name, base_path_override=""))
-
-        # If no base path was configured, add the primary URL
-        if not self.has_base_path:
-            candidates.append(self.hook_url(hook_name))
-
-        return candidates
+        return [self.hook_url(hook_name)]
 
     def get_web_base_path(self, base_path_override: str | None = None) -> str:
         """