github2gerrit 0.1.10__py3-none-any.whl → 0.1.11__py3-none-any.whl

github2gerrit/external_api.py

@@ -106,7 +106,9 @@ class ApiCallContext:
 
 # Global metrics storage - in production this could be replaced with
 # proper metrics collection system (Prometheus, etc.)
-_METRICS: dict[ApiType, ApiMetrics] = {api_type: ApiMetrics() for api_type in ApiType}
+_METRICS: dict[ApiType, ApiMetrics] = {
+    api_type: ApiMetrics() for api_type in ApiType
+}
 
 
 def get_api_metrics(api_type: ApiType) -> ApiMetrics:
@@ -159,7 +161,10 @@ def _is_transient_error(exc: BaseException, api_type: ApiType) -> bool:
         reason = getattr(exc, "reason", None)
         if isinstance(
             reason,
-            socket.timeout | TimeoutError | ConnectionResetError | ConnectionAbortedError,
+            socket.timeout
+            | TimeoutError
+            | ConnectionResetError
+            | ConnectionAbortedError,
         ):
             return True
 
@@ -175,11 +180,14 @@ def _is_transient_error(exc: BaseException, api_type: ApiType) -> bool:
 
         # Check by class name or isinstance for mock/test exceptions
         exc_name = exc.__class__.__name__
-        if exc_name in ("RateLimitExceededException", "RateLimitExceededExceptionType") or isinstance(
-            exc, RateLimitExceededExceptionType
-        ):
+        if exc_name in (
+            "RateLimitExceededException",
+            "RateLimitExceededExceptionType",
+        ) or isinstance(exc, RateLimitExceededExceptionType):
             return True
-        if exc_name in ("GithubException", "GithubExceptionType") or isinstance(exc, GithubExceptionType):
+        if exc_name in ("GithubException", "GithubExceptionType") or isinstance(
+            exc, GithubExceptionType
+        ):
             status = getattr(exc, "status", None)
             if isinstance(status, int) and 500 <= status <= 599:
                 return True
@@ -187,12 +195,19 @@ def _is_transient_error(exc: BaseException, api_type: ApiType) -> bool:
             data = getattr(exc, "data", "")
             if isinstance(data, str | bytes):
                 try:
-                    text = data.decode("utf-8") if isinstance(data, bytes) else data
+                    text = (
+                        data.decode("utf-8")
+                        if isinstance(data, bytes)
+                        else data
+                    )
                     if "rate limit" in text.lower():
                         return True
                 except Exception:
                     # Ignore decode errors when checking for rate limit text
-                    log.debug("Failed to decode GitHub API error data for rate limit check")
+                    log.debug(
+                        "Failed to decode GitHub API error data for rate "
+                        "limit check"
+                    )
                     return False
 
     # Gerrit REST specific errors - check for wrapped HTTP errors
@@ -201,9 +216,13 @@ def _is_transient_error(exc: BaseException, api_type: ApiType) -> bool:
         if "HTTP 5" in str(exc) or "HTTP 429" in str(exc):
             return True
         # Also check for original HTTP errors that caused the GerritRestError
-        if hasattr(exc, "__cause__") and isinstance(exc.__cause__, urllib.error.HTTPError):
+        if hasattr(exc, "__cause__") and isinstance(
+            exc.__cause__, urllib.error.HTTPError
+        ):
             status = getattr(exc.__cause__, "code", None)
-            return (500 <= status <= 599) or (status == 429) if status else False
+            return (
+                (500 <= status <= 599) or (status == 429) if status else False
+            )
 
     # SSH/Git command errors - check stderr for common transient messages
     if api_type == ApiType.SSH:
@@ -321,7 +340,9 @@ def external_api_call(
                         attempt,
                         policy.max_attempts,
                         target,
-                        f"(timeout={policy.timeout}s)" if policy.timeout else "",
+                        f"(timeout={policy.timeout}s)"
+                        if policy.timeout
+                        else "",
                     )
 
                     # Call the actual function
@@ -343,7 +364,8 @@ def external_api_call(
                             policy.jitter_factor,
                         )
                         log.warning(
-                            "[%s] %s attempt %d/%d failed (%.2fs): %s; retrying in %.2fs",
+                            "[%s] %s attempt %d/%d failed (%.2fs): %s; "
+                            "retrying in %.2fs",
                             api_type.value,
                             operation,
                             attempt,
@@ -355,11 +377,14 @@ def external_api_call(
                         time.sleep(delay)
                         continue
                     # Final failure - log and re-raise
-                    reason = "final attempt" if is_final_attempt else "non-retryable"
+                    reason = (
+                        "final attempt" if is_final_attempt else "non-retryable"
+                    )
                     log_exception_conditionally(
                         log,
                         f"[{api_type.value}] {operation} failed ({reason}) "
-                        f"after {attempt} attempt(s) in {duration:.2f}s: {target}",
+                        f"after {attempt} attempt(s) in {duration:.2f}s: "
+                        f"{target}",
                     )
                     _update_metrics(api_type, context, success=False, exc=exc)
                     raise
@@ -394,17 +419,26 @@ def external_api_call(
 
 def log_api_metrics_summary() -> None:
     """Log a summary of all API metrics."""
-    log.info("=== External API Metrics Summary ===")
+    log.debug("=== External API Metrics Summary ===")
     for api_type in ApiType:
         metrics = _METRICS[api_type]
         if metrics.total_calls == 0:
             continue
 
-        success_rate = (metrics.successful_calls / metrics.total_calls * 100) if metrics.total_calls > 0 else 0.0
-        avg_duration = metrics.total_duration / metrics.total_calls if metrics.total_calls > 0 else 0.0
+        success_rate = (
+            (metrics.successful_calls / metrics.total_calls * 100)
+            if metrics.total_calls > 0
+            else 0.0
+        )
+        avg_duration = (
+            metrics.total_duration / metrics.total_calls
+            if metrics.total_calls > 0
+            else 0.0
+        )
 
-        log.info(
-            "[%s] Calls: %d, Success: %.1f%%, Avg Duration: %.2fs, Retries: %d, Timeouts: %d, Transient Errors: %d",
+        log.debug(
+            "[%s] Calls: %d, Success: %.1f%%, Avg Duration: %.2fs, "
+            "Retries: %d, Timeouts: %d, Transient Errors: %d",
             api_type.value,
             metrics.total_calls,
             success_rate,
@@ -447,7 +481,9 @@ def curl_download(
     if policy is None:
         policy = RetryPolicy(max_attempts=3, timeout=timeout)
 
-    @external_api_call(ApiType.HTTP_DOWNLOAD, "curl_download", target=url, policy=policy)
+    @external_api_call(
+        ApiType.HTTP_DOWNLOAD, "curl_download", target=url, policy=policy
+    )
     def _do_curl() -> tuple[int, str]:
         cmd = ["curl"]
 
@@ -473,16 +509,28 @@ def curl_download(
 
         # Helper functions for raising errors to comply with TRY301
         def _raise_curl_failed(returncode: int, error_msg: str) -> None:
-            raise RuntimeError(_MSG_CURL_FAILED_WITH_RC.format(_MSG_CURL_FAILED, returncode, error_msg))
+            raise RuntimeError(
+                _MSG_CURL_FAILED_WITH_RC.format(
+                    _MSG_CURL_FAILED, returncode, error_msg
+                )
+            )
 
         def _raise_no_output() -> None:
             raise RuntimeError(_MSG_CURL_NO_OUTPUT)
 
         def _raise_timeout(timeout_val: float) -> None:
-            raise TimeoutError(_MSG_CURL_TIMEOUT_WITH_TIME.format(_MSG_CURL_TIMEOUT, timeout_val))
+            raise TimeoutError(
+                _MSG_CURL_TIMEOUT_WITH_TIME.format(
+                    _MSG_CURL_TIMEOUT, timeout_val
+                )
+            )
 
         def _raise_download_failed(exc: Exception) -> None:
-            raise RuntimeError(_MSG_CURL_DOWNLOAD_FAILED_WITH_EXC.format(_MSG_CURL_DOWNLOAD_FAILED, exc)) from exc
+            raise RuntimeError(
+                _MSG_CURL_DOWNLOAD_FAILED_WITH_EXC.format(
+                    _MSG_CURL_DOWNLOAD_FAILED, exc
+                )
+            ) from exc
 
         # Initialize variables
         result = None
@@ -493,7 +541,8 @@ def curl_download(
                 cmd,
                 capture_output=True,
                 text=True,
-                timeout=timeout + 5,  # Give subprocess a bit more time than curl
+                timeout=timeout
+                + 5,  # Give subprocess a bit more time than curl
                 check=False,
             )
 
@@ -501,7 +550,9 @@ def curl_download(
             http_status = result.stdout.strip() if result.stdout else "unknown"
 
             if result.returncode != 0:
-                error_msg = result.stderr.strip() if result.stderr else _MSG_CURL_FAILED
+                error_msg = (
+                    result.stderr.strip() if result.stderr else _MSG_CURL_FAILED
+                )
                 _raise_curl_failed(result.returncode, error_msg)
 
             # Verify file was created

github2gerrit/gerrit_query.py

@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2025 The Linux Foundation
+"""
+Gerrit query utilities for topic-based change discovery.
+
+This module provides functions to query Gerrit REST API for changes
+based on topics, with support for pagination and safe parsing.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from .gerrit_rest import GerritRestClient
+
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class GerritChange:
+    """Represents a Gerrit change from query results."""
+
+    change_id: str
+    number: str
+    subject: str
+    status: str
+    current_revision: str
+    files: list[str]
+    commit_message: str
+    topic: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GerritChange":
+        """Create GerritChange from Gerrit REST API response."""
+        # Extract files from current revision
+        files = []
+        current_revision = data.get("current_revision", "")
+        if current_revision and "revisions" in data:
+            revision_data = data["revisions"].get(current_revision, {})
+            files = list(revision_data.get("files", {}).keys())
+
+        # Extract commit message
+        commit_message = ""
+        if current_revision and "revisions" in data:
+            revision_data = data["revisions"].get(current_revision, {})
+            commit_message = revision_data.get("commit", {}).get("message", "")
+
+        return cls(
+            change_id=data.get("change_id", ""),
+            number=str(data.get("_number", "")),
+            subject=data.get("subject", ""),
+            status=data.get("status", ""),
+            current_revision=current_revision,
+            files=files,
+            commit_message=commit_message,
+            topic=data.get("topic"),
+        )
+
+
+def query_changes_by_topic(
+    client: GerritRestClient,
+    topic: str,
+    *,
+    statuses: list[str] | None = None,
+    max_results: int = 100,
+) -> list[GerritChange]:
+    """
+    Query Gerrit for changes matching the given topic.
+
+    Args:
+        client: Gerrit REST client
+        topic: Topic name to search for
+        statuses: List of change statuses to include (default: ["NEW"])
+        max_results: Maximum number of results to return
+
+    Returns:
+        List of GerritChange objects
+    """
+    if statuses is None:
+        statuses = ["NEW"]
+
+    # Build query string
+    status_query = " OR ".join(f"status:{status}" for status in statuses)
+    query = f"topic:{topic} AND ({status_query})"
+
+    log.debug("Querying Gerrit for changes: %s", query)
+
+    try:
+        changes = _execute_query_with_pagination(
+            client, query, max_results=max_results
+        )
+        log.debug(
+            "Found %d changes for topic '%s' with statuses %s",
+            len(changes),
+            topic,
+            statuses,
+        )
+    except Exception as exc:
+        log.warning(
+            "Failed to query Gerrit changes for topic '%s': %s", topic, exc
+        )
+        return []
+    else:
+        return changes
+
+
+def _execute_query_with_pagination(
+    client: GerritRestClient,
+    query: str,
+    *,
+    max_results: int = 100,
+    page_size: int = 25,
+) -> list[GerritChange]:
+    """
+    Execute Gerrit query with pagination support.
+
+    Args:
+        client: Gerrit REST client
+        query: Gerrit query string
+        max_results: Maximum total results to return
+        page_size: Results per page
+
+    Returns:
+        List of GerritChange objects
+    """
+    all_changes: list[GerritChange] = []
+    start = 0
+
+    while len(all_changes) < max_results:
+        remaining = max_results - len(all_changes)
+        current_limit = min(page_size, remaining)
+
+        try:
+            # Build query URL with parameters
+            # Gerrit REST API: /changes/?q=query&n=limit&S=skip&o=options
+            query_params = [
+                f"q={query}",
+                f"n={current_limit}",
+                f"S={start}",
+                "o=CURRENT_REVISION",
+                "o=CURRENT_FILES",
+                "o=CURRENT_COMMIT",
+            ]
+            query_path = f"/changes/?{'&'.join(query_params)}"
+
+            response = client.get(query_path)
+
+            if not response:
+                break
+
+            # Gerrit REST API returns a list of change objects
+            if not isinstance(response, list):
+                log.warning(
+                    "Unexpected Gerrit query response format: %s",
+                    type(response),
+                )
+                break
+
+            page_changes = []
+            for change_data in response:
+                try:
+                    change = GerritChange.from_dict(change_data)
+                    page_changes.append(change)
+                except Exception as exc:
+                    log.debug("Skipping malformed change data: %s", exc)
+                    continue
+
+            all_changes.extend(page_changes)
+
+            # If we got fewer results than requested, we've reached the end
+            if len(page_changes) < current_limit:
+                break
+
+            start += len(page_changes)
+
+        except Exception as exc:
+            log.warning(
+                "Failed to fetch Gerrit changes page (start=%d, limit=%d): %s",
+                start,
+                current_limit,
+                exc,
+            )
+            break
+
+    return all_changes[:max_results]
+
+
+def extract_pr_metadata_from_commit_message(
+    commit_message: str,
+) -> dict[str, str]:
+    """
+    Extract GitHub PR metadata trailers from a commit message.
+
+    Args:
+        commit_message: Full commit message text
+
+    Returns:
+        Dictionary with extracted metadata (GitHub-PR, GitHub-Hash, etc.)
+    """
+    metadata = {}
+
+    # Look for trailer-style metadata at the end of the commit message
+    lines = commit_message.strip().split("\n")
+
+    # Find the start of trailers (after the last blank line)
+    trailer_start = 0
+    for i in range(len(lines) - 1, -1, -1):
+        if not lines[i].strip():
+            trailer_start = i + 1
+            break
+
+    # Parse trailer lines
+    for raw_line in lines[trailer_start:]:
+        line = raw_line.strip()
+        if ":" in line:
+            key, value = line.split(":", 1)
+            key = key.strip()
+            value = value.strip()
+            if key.startswith("GitHub-"):
+                metadata[key] = value
+
+    return metadata
+
+
+def validate_pr_metadata_match(
+    gerrit_changes: list[GerritChange],
+    expected_pr_url: str,
+    expected_github_hash: str,
+) -> list[GerritChange]:
+    """
+    Filter Gerrit changes to only those matching the expected PR metadata.
+
+    This prevents cross-PR contamination by ensuring changes belong to
+    the same GitHub PR based on trailer metadata.
+
+    Args:
+        gerrit_changes: List of changes from Gerrit query
+        expected_pr_url: Expected GitHub PR URL
+        expected_github_hash: Expected GitHub-Hash trailer value
+
+    Returns:
+        Filtered list of changes matching the PR metadata
+    """
+    validated_changes = []
+
+    for change in gerrit_changes:
+        metadata = extract_pr_metadata_from_commit_message(
+            change.commit_message
+        )
+
+        # Check GitHub-PR URL match
+        pr_url = metadata.get("GitHub-PR", "")
+        if pr_url and pr_url != expected_pr_url:
+            log.debug(
+                "Excluding change %s: PR URL mismatch (expected=%s, found=%s)",
+                change.change_id,
+                expected_pr_url,
+                pr_url,
+            )
+            continue
+
+        # Check GitHub-Hash match
+        github_hash = metadata.get("GitHub-Hash", "")
+        if github_hash and github_hash != expected_github_hash:
+            log.debug(
+                "Excluding change %s: GitHub-Hash mismatch "
+                "(expected=%s, found=%s)",
+                change.change_id,
+                expected_github_hash,
+                github_hash,
+            )
+            continue
+
+        validated_changes.append(change)
+
+    if len(validated_changes) != len(gerrit_changes):
+        log.info(
+            "Filtered Gerrit changes: %d -> %d "
+            "(excluded %d due to metadata mismatch)",
+            len(gerrit_changes),
+            len(validated_changes),
+            len(gerrit_changes) - len(validated_changes),
+        )
+
+    return validated_changes

github2gerrit/gerrit_rest.py

@@ -50,14 +50,20 @@ 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]
+    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"
+_MSG_PYGERRIT2_REQUIRED_AUTH: Final[str] = (
+    "pygerrit2 is required for HTTP authentication"
+)
 
 _TRANSIENT_ERR_SUBSTRINGS: Final[tuple[str, ...]] = (
     "timed out",
@@ -129,7 +135,10 @@ class GerritRestClient:
                 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)
+                    url=self._base_url,
+                    auth=_PygerritHttpAuth(
+                        self._auth.user, self._auth.password
+                    ),
                 )
             else:
                 self._client = _PygerritRestApi(url=self._base_url)
@@ -137,7 +146,8 @@ class GerritRestClient:
             self._client = None
 
         log.debug(
-            "GerritRestClient(base_url=%s, timeout=%.1fs, attempts=%d, auth_user=%s)",
+            "GerritRestClient(base_url=%s, timeout=%.1fs, attempts=%d, "
+            "auth_user=%s)",
             self._base_url,
             self._timeout,
             self._attempts,
@@ -160,16 +170,22 @@ class GerritRestClient:
 
     # Internal helpers
 
-    def _request_json_with_retry(self, method: str, path: str, data: Any | None = None) -> Any:
+    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)
+        @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:
+    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"
@@ -181,10 +197,14 @@ class GerritRestClient:
 
         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
+                # 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)
+                # 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"}
@@ -194,19 +214,29 @@ class GerritRestClient:
                 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")
+                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 "")
+            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
+                # 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)
@@ -267,7 +297,8 @@ def build_client_for_host(
     - 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.
+      If user is not provided, falls back to GERRIT_SSH_USER_G2G per project
+      norms.
 
     Args:
       host: Gerrit hostname (no scheme)
@@ -286,9 +317,13 @@ def build_client_for_host(
         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()
+    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)
+    return GerritRestClient(
+        base_url=base_url, auth=auth, timeout=timeout, max_attempts=max_attempts
+    )
 
 
 __all__ = [