github2gerrit 0.1.5__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

@@ -0,0 +1,353 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2025 The Linux Foundation
+"""
+Centralized Gerrit URL construction utilities.
+
+This module provides a unified way to construct Gerrit URLs, ensuring
+consistent handling of GERRIT_HTTP_BASE_PATH and eliminating the need
+for manual URL construction throughout the codebase.
+"""
+
+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:
+    """
+    Centralized builder for Gerrit URLs with consistent base path handling.
+
+    This class encapsulates all Gerrit URL construction logic, ensuring that
+    GERRIT_HTTP_BASE_PATH is properly handled in all contexts. It provides
+    methods for building different types of URLs (API, web, hooks) and handles
+    the common fallback patterns used throughout the application.
+    """
+
+    def __init__(self, host: str, base_path: str | None = None):
+        """
+        Initialize the URL builder for a specific Gerrit host.
+
+        Args:
+            host: Gerrit hostname (without protocol)
+            base_path: Optional base path override. If None, reads from
+                      GERRIT_HTTP_BASE_PATH environment variable or discovers dynamically.
+        """
+        self.host = host.strip()
+
+        # Normalize base path - remove leading/trailing slashes and whitespace
+        if base_path is not None:
+            self._base_path = base_path.strip().strip("/")
+        else:
+            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'",
+            self.host,
+            self._base_path,
+        )
+
+    @property
+    def base_path(self) -> str:
+        """Get the normalized base path."""
+        return self._base_path
+
+    @property
+    def has_base_path(self) -> bool:
+        """Check if a base path is configured."""
+        return bool(self._base_path)
+
+    def _build_base_url(self, base_path_override: str | None = None) -> str:
+        """
+        Build the base URL with optional base path override.
+
+        Args:
+            base_path_override: Optional base path to use instead of the instance default
+
+        Returns:
+            Base URL with trailing slash
+        """
+        path = base_path_override if base_path_override is not None else self._base_path
+        if path:
+            return f"https://{self.host}/{path}/"
+        else:
+            return f"https://{self.host}/"
+
+    def api_url(self, endpoint: str = "", base_path_override: str | None = None) -> str:
+        """
+        Build a Gerrit REST API URL.
+
+        Args:
+            endpoint: API endpoint path (e.g., "/changes/", "/accounts/self")
+            base_path_override: Optional base path override for fallback scenarios
+
+        Returns:
+            Complete API URL
+        """
+        base_url = self._build_base_url(base_path_override)
+        # Ensure endpoint starts with / for proper URL joining
+        if endpoint and not endpoint.startswith("/"):
+            endpoint = "/" + endpoint
+        return urljoin(base_url, endpoint.lstrip("/"))
+
+    def web_url(self, path: str = "", base_path_override: str | None = None) -> str:
+        """
+        Build a Gerrit web UI URL.
+
+        Args:
+            path: Web path (e.g., "c/project/+/123", "dashboard")
+            base_path_override: Optional base path override for fallback scenarios
+
+        Returns:
+            Complete web URL
+        """
+        base_url = self._build_base_url(base_path_override)
+        if path:
+            # Remove leading slash if present to avoid double slashes
+            path = path.lstrip("/")
+            return urljoin(base_url, path)
+        return base_url.rstrip("/")
+
+    def change_url(
+        self,
+        project: str,
+        change_number: int,
+        base_path_override: str | None = None,
+    ) -> str:
+        """
+        Build a URL for a specific Gerrit change.
+
+        Args:
+            project: Gerrit project name
+            change_number: Gerrit change number
+            base_path_override: Optional base path override for fallback scenarios
+
+        Returns:
+            Complete change URL
+        """
+        # Don't URL-encode project names - Gerrit expects them as-is (backward compatibility)
+        path = f"c/{project}/+/{change_number}"
+        return self.web_url(path, base_path_override)
+
+    def hook_url(self, hook_name: str, base_path_override: str | None = None) -> str:
+        """
+        Build a URL for downloading Gerrit hooks.
+
+        Args:
+            hook_name: Name of the hook (e.g., "commit-msg")
+            base_path_override: Optional base path override for fallback scenarios
+
+        Returns:
+            Complete hook download URL
+        """
+        path = f"tools/hooks/{hook_name}"
+        return self.web_url(path, base_path_override)
+
+    def get_api_url_candidates(self, endpoint: str = "") -> list[str]:
+        """
+        Get the single API URL based on discovered/configured base path.
+
+        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:
+            A single API URL to use
+        """
+        return [self.api_url(endpoint)]
+
+    def get_hook_url_candidates(self, hook_name: str) -> list[str]:
+        """
+        Get the single hook URL based on discovered/configured base path.
+
+        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:
+            A single hook URL to use
+        """
+        return [self.hook_url(hook_name)]
+
+    def get_web_base_path(self, base_path_override: str | None = None) -> str:
+        """
+        Get the web base path for URL construction.
+
+        This is useful when you need just the path component for manual URL building.
+
+        Args:
+            base_path_override: Optional base path override
+
+        Returns:
+            Web base path with leading and trailing slashes (e.g., "/r/", "/")
+        """
+        path = base_path_override if base_path_override is not None else self._base_path
+        if path:
+            return f"/{path}/"
+        else:
+            return "/"
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        return f"GerritUrlBuilder(host='{self.host}', base_path='{self._base_path}')"
+
+
+def create_gerrit_url_builder(host: str, base_path: str | None = None) -> GerritUrlBuilder:
+    """
+    Factory function to create a GerritUrlBuilder instance.
+
+    This is the preferred way to create URL builders throughout the application.
+
+    Args:
+        host: Gerrit hostname
+        base_path: Optional base path override
+
+    Returns:
+        Configured GerritUrlBuilder instance
+    """
+    return GerritUrlBuilder(host, base_path)