compforge-repokit 0.15.0__py3-none-any.whl

repokit/forge/_http_state.py

@@ -0,0 +1,92 @@
+"""Caller-selected, credential-isolated HTTP coordination for short-lived processes."""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from .._process import Budget
+from .model import ForgeRateLimited
+
+
+class HttpState:
+    """Share cooldown and conditional responses, never application freshness policy.
+
+    +spec=`All processes using a state directory and credential serialize dispatch;
+    a persisted cooldown is checked after acquiring the lock and before network I/O.`
+    +link=component://docs/pr.md
+    """
+
+    def __init__(self, directory: Path, authority: str, credential: str):
+        identity = hashlib.sha256(f"{authority}\0{credential}".encode()).hexdigest()
+        self.home = directory / identity
+
+    @contextmanager
+    def acquire(self, budget: Budget) -> Iterator[None]:
+        self.home.mkdir(parents=True, exist_ok=True, mode=0o700)
+        fd = os.open(self.home / "request.lock", os.O_CREAT | os.O_RDWR, 0o600)
+        try:
+            while True:
+                budget.remaining()
+                try:
+                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except BlockingIOError:
+                    time.sleep(min(0.05, budget.remaining()))
+            yield
+        finally:
+            os.close(fd)
+
+    def read(self, name: str) -> dict[str, Any]:
+        try:
+            value = json.loads((self.home / name).read_text())
+        except FileNotFoundError:
+            return {}
+        if not isinstance(value, dict):
+            raise ValueError(f"invalid HTTP state: {name}")
+        return value
+
+    def write(self, name: str, value: dict[str, Any]) -> None:
+        path = self.home / name
+        temporary = path.with_suffix(f".{os.getpid()}.tmp")
+        fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as stream:
+            json.dump(value, stream)
+        temporary.replace(path)
+
+    def check(self, resource: str) -> None:
+        limits = self.read("limits.json")
+        for key in ("secondary", resource):
+            retry_at = float(limits.get(key, 0))
+            if retry_at > time.time():
+                raise ForgeRateLimited(resource, retry_at, secondary=key == "secondary")
+
+    def defer(self, limit: ForgeRateLimited) -> None:
+        limits = self.read("limits.json")
+        key = "secondary" if limit.secondary else limit.resource
+        if limit.secondary:
+            failures = int(limits.get("secondary_failures", 0)) + 1
+            # Consecutive secondary limits back off even without Retry-After.
+            limit.retry_at = max(
+                limit.retry_at, time.time() + min(3600, 60 * 2 ** min(failures - 1, 6))
+            )
+            limits["secondary_failures"] = failures
+        limits[key] = max(float(limits.get(key, 0)), limit.retry_at)
+        self.write("limits.json", limits)
+
+    def succeeded(self) -> None:
+        limits = self.read("limits.json")
+        if limits.pop("secondary_failures", None) is not None:
+            self.write("limits.json", limits)
+
+    @staticmethod
+    def cache_key(url: str, headers: dict[str, str]) -> str:
+        representation = json.dumps([url, sorted(headers.items())], sort_keys=True)
+        return hashlib.sha256(representation.encode()).hexdigest() + ".json"

repokit/forge/_page.py

@@ -0,0 +1,34 @@
+"""Bounded repository page positions; provider URLs never come from a cursor."""
+
+from __future__ import annotations
+
+import json
+
+from .model import ForgeError
+
+
+def page_position(scope: str, page_size: int | None, cursor: str | None) -> tuple[int, int]:
+    page = 1
+    size = 50 if page_size is None else page_size
+    if cursor is not None:
+        try:
+            value = json.loads(cursor)
+        except (ValueError, TypeError) as exc:
+            raise ForgeError("Invalid repository page cursor") from exc
+        if (
+            not isinstance(value, dict)
+            or value.get("version") != 2
+            or value.get("scope") != scope
+            or (page_size is not None and page_size != value.get("page_size"))
+        ):
+            raise ForgeError("Repository page cursor does not match this query")
+        page, size = value.get("page", 0), value.get("page_size", 0)
+    if type(page) is not int or page < 1 or type(size) is not int or not 1 <= size <= 100:
+        raise ForgeError("Repository page requires a positive page and page_size between 1 and 100")
+    return page, size
+
+
+def page_continuation(scope: str, page: int, page_size: int, more: bool) -> str | None:
+    if not more:
+        return None
+    return json.dumps({"version": 2, "scope": scope, "page": page + 1, "page_size": page_size})

repokit/forge/_rest.py

@@ -0,0 +1,233 @@
+"""RestClient — the single HTTP transport shared by every forge adapter.
+
+The GitHub and GitLab REST surfaces differ only in base URL, auth header, and JSON
+shapes; the request mechanics (urllib, params encoding, JSON body, error typing,
+timeouts) are identical. So this is the ONE place that touches urllib — swap it for the
+SDK / an MCP server later and the adapters stay put. Adapters parametrize it with their
+base URL + headers and speak verbs (`get/post/put/patch`); they never import urllib.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from contextlib import nullcontext
+from email.message import Message
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+from ..budget import current_budget, operation
+from ._http_state import HttpState
+from .model import ForgeAuthError, ForgeError, ForgeNotFound, ForgeOutcomeUnknown, ForgeRateLimited
+
+DEFAULT_TIMEOUT = 10
+logger = logging.getLogger(__name__)
+
+
+class RestClient:
+    def __init__(
+        self,
+        base_url: str,
+        headers: dict[str, str],
+        *,
+        timeout: int = DEFAULT_TIMEOUT,
+        state: HttpState | None = None,
+        resource: str = "core",
+    ):
+        self.base_url = base_url.rstrip("/")
+        self._headers = dict(headers)
+        self.timeout = timeout
+        self.state, self.resource = state, resource
+        self.requests = 0
+        self.not_modified = 0
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> Any:
+        """`<base_url>/<path>`, returns parsed JSON (None on empty body).
+
+        `params` list values encode as repeated keys (e.g. GitLab `iids[]`).
+        Conditional responses are revalidated on every read. Cooldown is checked
+        under the dispatch lock; no automatic retries, including for mutations.
+        """
+        url = (
+            f"{self.base_url}/{path.lstrip('/')}" if path else self.base_url
+        )  # "" → repo root, no trailing slash
+        if params:
+            url += "?" + urllib.parse.urlencode(params, doseq=True)
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = dict(self._headers)
+        if data is not None:
+            headers.setdefault("Content-Type", "application/json")
+        budget = current_budget(self.timeout)
+        # A timeout/cancellation before dispatch is a known non-action.
+        budget.remaining()
+        mutating = method.upper() not in ("GET", "HEAD", "OPTIONS")
+        if (
+            body
+            and isinstance(body.get("query"), str)
+            and body["query"].lstrip().startswith("query")
+        ):
+            mutating = False
+        dispatched = False
+        try:
+            with self.state.acquire(budget) if self.state else nullcontext():
+                if self.state:
+                    self.state.check(self.resource)
+                key = HttpState.cache_key(url, headers)
+                cached = self.state.read(key) if self.state and method.upper() == "GET" else {}
+                if cached.get("etag"):
+                    headers["If-None-Match"] = cached["etag"]
+                req = urllib.request.Request(url, data=data, headers=headers, method=method.upper())
+                try:
+                    timeout = budget.remaining()
+                    self.requests += 1
+                    dispatched = True
+                    with urllib.request.urlopen(req, timeout=timeout) as resp:
+                        raw = resp.read((16 << 20) + 1)
+                        budget.remaining()
+                        if len(raw) > 16 << 20:
+                            raise ValueError("response exceeds 16 MiB")
+                        value = json.loads(raw) if raw else None
+                        limit = self._limit(resp.headers, value, graphql=body is not None)
+                        if limit:
+                            if self.state:
+                                self.state.defer(limit)
+                            # A successful final request is usable even when remaining=0.
+                            if isinstance(value, dict) and value.get("errors"):
+                                raise limit
+                        if self.state and method.upper() == "GET" and resp.headers.get("ETag"):
+                            self.state.write(key, {"etag": resp.headers["ETag"], "body": value})
+                        if self.state:
+                            self.state.succeeded()
+                        logger.info(
+                            "forge request method=%s path=%s resource=%s status=%s",
+                            method,
+                            path,
+                            self.resource,
+                            resp.status,
+                        )
+                        return value
+                except urllib.error.HTTPError as e:
+                    if e.code == 304 and "body" in cached:
+                        limit = self._limit(e.headers, {})
+                        if limit and self.state:
+                            self.state.defer(limit)
+                        self.not_modified += 1
+                        if self.state:
+                            self.state.succeeded()
+                        logger.info(
+                            "forge request method=%s path=%s resource=%s status=304",
+                            method,
+                            path,
+                            self.resource,
+                        )
+                        return cached["body"]
+                    raw_error = e.read(65536)
+                    try:
+                        value = json.loads(raw_error)
+                    except ValueError:
+                        value = {}
+                    limit = self._limit(e.headers, value, status=e.code)
+                    if limit:
+                        if self.state:
+                            self.state.defer(limit)
+                        logger.warning(
+                            "forge cooldown path=%s resource=%s retry_at=%s secondary=%s",
+                            path,
+                            limit.resource,
+                            limit.retry_at,
+                            limit.secondary,
+                        )
+                        raise limit from e
+                    if e.code in (401, 403):
+                        raise ForgeAuthError(f"{method} {path} → HTTP {e.code}") from e
+                    if e.code == 404:
+                        raise ForgeNotFound(f"{method} {path} → 404") from e
+                    error = ForgeOutcomeUnknown if mutating and e.code >= 500 else ForgeError
+                    raise error(
+                        f"{method} {path} → HTTP {e.code}"
+                        + (
+                            "; inspect remote state before retrying"
+                            if error is ForgeOutcomeUnknown
+                            else ""
+                        )
+                    ) from e
+        except (urllib.error.URLError, TimeoutError, OSError, ValueError) as e:
+            error = ForgeOutcomeUnknown if mutating and dispatched else ForgeError
+            raise error(
+                f"{method} {path} → {e}"
+                + ("; inspect remote state before retrying" if error is ForgeOutcomeUnknown else "")
+            ) from e
+
+    def _limit(
+        self, headers: Message, value: Any, *, status: int = 200, graphql: bool = False
+    ) -> ForgeRateLimited | None:
+        remaining = headers.get("x-ratelimit-remaining")
+        reset = headers.get("x-ratelimit-reset")
+        retry = headers.get("retry-after")
+        message = str(value.get("message", "")).lower() if isinstance(value, dict) else ""
+        errors = (value.get("errors") or []) if graphql and isinstance(value, dict) else []
+        limited = any(isinstance(e, dict) and e.get("type") == "RATE_LIMITED" for e in errors)
+        if (
+            remaining != "0"
+            and not limited
+            and not (status in (403, 429) and (status == 429 or retry or "rate limit" in message))
+        ):
+            return None
+        now = time.time()
+        retry_at = now + 60
+        if reset and remaining == "0":
+            retry_at = max(now + 1, float(reset))
+        if retry:
+            try:
+                retry_at = max(retry_at if remaining == "0" else now, now + float(retry))
+            except ValueError:
+                retry_at = max(retry_at, parsedate_to_datetime(retry).timestamp())
+        return ForgeRateLimited(
+            headers.get("x-ratelimit-resource", self.resource),
+            retry_at,
+            secondary=remaining != "0" and not limited,
+        )
+
+    def get(self, path: str, **params: Any) -> Any:
+        return self.request("GET", path, params=params or None)
+
+    def get_all(self, path: str, *, per_page: int = 100, **params: Any) -> list[Any]:
+        """Fetch every page from a list endpoint using the page/per_page convention shared
+        by GitHub and GitLab. Keeping the loop here makes "all" a transport guarantee instead
+        of an adapter promise that silently stops at its first page."""
+        if per_page <= 0 or per_page > 100:
+            raise ValueError("per_page must be between 1 and 100")
+        with operation(timeout=self.timeout):
+            out: list[Any] = []
+            page = 1
+            while True:
+                current_budget(self.timeout).remaining()
+                batch = self.get(path, **params, page=page, per_page=per_page)
+                if not isinstance(batch, list):
+                    raise ForgeError(f"GET {path} page {page}: expected a list response")
+                out.extend(batch)
+                if len(out) > 10_000:
+                    raise ForgeError(f"GET {path}: inventory exceeds 10000 entries")
+                if len(batch) < per_page:
+                    return out
+                page += 1
+
+    def post(self, path: str, body: dict[str, Any]) -> Any:
+        return self.request("POST", path, body=body)
+
+    def put(self, path: str, body: dict[str, Any]) -> Any:
+        return self.request("PUT", path, body=body)
+
+    def patch(self, path: str, body: dict[str, Any]) -> Any:
+        return self.request("PATCH", path, body=body)

repokit/forge/creation.py

@@ -0,0 +1,88 @@
+"""Resolve and create a pull request using the existing Forge operation contract."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from harness_common import Repository
+
+from .model import Forge, ForgeError, PullRequest
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class PullRequestCreation:
+    pull_request: PullRequest
+    created: bool
+    source_repository: Repository
+    target_repository: Repository
+
+
+def ensure_pull_request(
+    forge: Forge,
+    *,
+    source_branch: str,
+    title: str,
+    body: str = "",
+    target_repository: str | None = None,
+    target_branch: str | None = None,
+) -> PullRequestCreation:
+    """Reuse an unambiguous open PR, or create it in the explicit destination.
+
+    @spec Omitted destination means the source repository, never its fork parent.
+    Omitted base preserves an existing PR's base; only creation resolves the default.
+    Reuse does not edit title/body. Ambiguous reads and uncertain writes propagate;
+    query-before-create is not an exactly-once guarantee across concurrent callers.
+    @link component://docs/pr.md
+    """
+    if not source_branch or target_branch == "":
+        raise ValueError("pull request branches must be nonempty")
+    source = forge.repository()
+    destination = source
+    if target_repository is not None:
+        name, separator, path = target_repository.partition("/")
+        if not separator or not path or name != source.forge.name:
+            raise ValueError(
+                f"target repository {target_repository!r} must be a Repository ID "
+                f"within Forge {source.forge.name!r}"
+            )
+        destination = Repository(source.forge, path)
+    client = forge if destination.id() == source.id() else forge.for_repository(destination.path)
+    candidates = [
+        pr
+        for pr in client.prs_for_branch(source_branch, source_repository=source)
+        if pr.is_open and (target_branch is None or pr.target_branch == target_branch)
+    ]
+    if len(candidates) > 1:
+        raise ForgeError(
+            f"multiple open pull requests for {source.id()}:{source_branch} "
+            f"in {destination.id()}: {[pr.number for pr in candidates]}"
+        )
+    if candidates:
+        pr = candidates[0]
+        created = False
+    else:
+        base = target_branch or client.default_branch()
+        if not base:
+            raise ForgeError(f"cannot determine default branch for {destination.id()}")
+        pr = client.create(
+            source_repository=source,
+            source_branch=source_branch,
+            target_repository=destination,
+            target_branch=base,
+            title=title,
+            body=body,
+        )
+        created = True
+    logger.info(
+        "pull request %s source=%s:%s target=%s:%s number=%s",
+        "created" if created else "reused",
+        source.id(),
+        source_branch,
+        destination.id(),
+        pr.target_branch,
+        pr.number,
+    )
+    return PullRequestCreation(pr, created, source, destination)