diffbutler 0.5.0__py3-none-any.whl

diffbutler/forges/github/http.py

@@ -0,0 +1,326 @@
+"""Bounded async GET transport with conditional reads and origin confinement."""
+
+import asyncio
+import logging
+import math
+import random
+import time
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import ClassVar
+
+import httpx
+
+from diffbutler.domain.forge import RateLimit
+from diffbutler.forges.base import ForgeError
+from diffbutler.forges.diagnostics import (
+    RateLimitSource,
+    observe_cooldown,
+    observe_rate_limit,
+    observe_request,
+)
+
+
+def api_url(value: str) -> httpx.URL:
+    try:
+        url = httpx.URL(value)
+    except httpx.InvalidURL:
+        raise ForgeError("GitHub base_url must be a valid HTTPS API URL") from None
+    if (
+        url.scheme != "https"
+        or not url.host
+        or url.userinfo
+        or url.query
+        or url.fragment
+        or url.path not in {"", "/", "/api/v3", "/api/v3/"}
+    ):
+        raise ForgeError(
+            "GitHub base_url must be HTTPS, with no credentials/query and an optional /api/v3 path"
+        )
+    return url.copy_with(path=url.path.rstrip("/") + "/")
+
+
+@dataclass(frozen=True)
+class ReadResponse:
+    body: object
+    headers: httpx.Headers
+    next_page: bool
+
+
+class GitHubHTTP:
+    DEFAULT_REQUEST_INTERVAL: ClassVar[float] = 1.0
+    AUTHENTICATED_REQUEST_INTERVAL: ClassVar[float] = 0.1
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+        now: Callable[[], float] = time.time,
+        request_interval: float | None = None,
+        max_pacing_wait: float | None = None,
+    ) -> None:
+        self.base_url = api_url(base_url)
+        if token is not None and (
+            not token or not token.isascii() or any(character.isspace() for character in token)
+        ):
+            raise ForgeError("GitHub token is empty or contains whitespace")
+        self.authenticated = token is not None
+        self.observation_source = RateLimitSource(
+            str(self.base_url).rstrip("/"), self.authenticated
+        )
+        self.max_pacing_wait = max_pacing_wait
+        if max_pacing_wait is not None and (
+            not math.isfinite(max_pacing_wait) or max_pacing_wait < 0
+        ):
+            raise ValueError("Maximum pacing wait must be finite and nonnegative")
+        default_interval = (
+            self.AUTHENTICATED_REQUEST_INTERVAL
+            if self.authenticated
+            else self.DEFAULT_REQUEST_INTERVAL
+        )
+        self.request_interval = default_interval if request_interval is None else request_interval
+        if not math.isfinite(self.request_interval) or self.request_interval < 0:
+            raise ValueError("Request interval must be finite and nonnegative")
+        self.client = httpx.AsyncClient(
+            base_url=self.base_url,
+            transport=transport,
+            timeout=20,
+            follow_redirects=False,
+            headers={
+                **({"Authorization": f"Bearer {token}"} if token is not None else {}),
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+                "User-Agent": "DiffButler",
+            },
+        )
+        self.sleep = sleep
+        self.now = now
+        self.last_request: float | None = None
+        self.last_resource_request: dict[str, float] = {}
+        self.limits: dict[str, RateLimit] = {}
+        self.cache: OrderedDict[str, ReadResponse] = OrderedDict()
+        self.blocked_until = 0.0
+        self.lock = asyncio.Lock()
+
+    async def paced_get(self, url: httpx.URL, headers: dict[str, str]) -> httpx.Response:
+        """Pace every wire request, including redirects and retry attempts."""
+        resource = "search" if url.path.endswith("/search/issues") else "core"
+        limit = self.limits.get(resource)
+        if limit and limit.remaining <= 0 and limit.reset_at.timestamp() > self.now():
+            raise ForgeError(
+                "GitHub rate limit is exhausted",
+                retry_after=limit.reset_at.timestamp() - self.now(),
+            )
+        if self.blocked_until > self.now():
+            raise ForgeError(
+                "GitHub rate limit cooldown is active",
+                retry_after=self.blocked_until - self.now(),
+            )
+        if self.request_interval:
+            current = self.now()
+            ready = current
+            if self.last_request is not None:
+                ready = max(ready, self.last_request + self.request_interval)
+            previous = self.last_resource_request.get(resource)
+            if previous is not None:
+                interval = self.request_interval
+                if resource == "search" and not self.authenticated:
+                    interval = max(interval, 6.1)
+                if limit and 0 < limit.remaining <= limit.limit * 0.2:
+                    interval = max(
+                        interval, (limit.reset_at.timestamp() - previous) / limit.remaining
+                    )
+                ready = max(ready, previous + interval)
+            if ready > current:
+                logging.getLogger(__name__).info(
+                    "GitHub pacing resource=%s delay_s=%.3f", resource, ready - current
+                )
+                if self.max_pacing_wait is not None and ready - current > self.max_pacing_wait:
+                    delay = math.ceil(
+                        max(ready - current, limit.reset_at.timestamp() - current if limit else 0)
+                    )
+                    raise ForgeError(
+                        f"GitHub quota is low; retry after {delay} seconds. "
+                        "Resetting DiffButler does not reset GitHub quota.",
+                        retry_after=delay,
+                    )
+                await self.sleep(ready - current)
+        started = self.now()
+        self.last_request = started
+        self.last_resource_request[resource] = started
+        began = time.monotonic()
+        observe_request(self.observation_source, resource)
+        try:
+            response = await self.client.get(url, headers=headers)
+        except httpx.RequestError:
+            logging.getLogger(__name__).exception("GitHub transport failed resource=%s", resource)
+            raise
+        self.record_limit(response.headers)
+        quota = self.limits.get(resource)
+        logging.getLogger(__name__).log(
+            logging.DEBUG if response.is_success or response.status_code == 304 else logging.INFO,
+            "GitHub response resource=%s status=%d elapsed_s=%.3f "
+            "limit=%s remaining=%s reset=%s retry_after_s=%s",
+            resource,
+            response.status_code,
+            time.monotonic() - began,
+            quota.limit if quota else None,
+            quota.remaining if quota else None,
+            quota.reset_at.timestamp() if quota else None,
+            self.retry_delay(response),
+        )
+        return response
+
+    def checked_url(self, value: str | httpx.URL) -> httpx.URL:
+        try:
+            url = self.base_url.join(value)
+        except httpx.InvalidURL:
+            raise ForgeError("GitHub returned an invalid API URL") from None
+        if (
+            (url.scheme, url.host, url.port)
+            != (self.base_url.scheme, self.base_url.host, self.base_url.port)
+            or not url.path.startswith(self.base_url.path)
+            or url.userinfo
+            or url.fragment
+        ):
+            raise ForgeError("GitHub returned a URL outside the configured API origin")
+        return url
+
+    def record_limit(self, headers: httpx.Headers) -> None:
+        try:
+            resource = headers["x-ratelimit-resource"]
+            limit = RateLimit(
+                resource,
+                int(headers["x-ratelimit-remaining"]),
+                int(headers["x-ratelimit-limit"]),
+                datetime.fromtimestamp(int(headers["x-ratelimit-reset"]), UTC),
+            )
+            if limit.limit <= 0 or not 0 <= limit.remaining <= limit.limit:
+                return
+            self.limits[resource] = limit
+        except KeyError, ValueError, OverflowError, OSError:
+            return
+        observe_rate_limit(limit, self.observation_source, observed_at=self.now())
+        if limit.remaining == 0:
+            observe_cooldown(limit.reset_at.timestamp() + 1)
+
+    def retry_delay(self, response: httpx.Response) -> float | None:
+        headers = response.headers
+        if response.status_code not in {403, 429}:
+            return None
+        if "retry-after" in headers:
+            try:
+                delay = float(headers["retry-after"])
+                return max(0, delay) if math.isfinite(delay) else 60
+            except ValueError:
+                try:
+                    return max(
+                        0, parsedate_to_datetime(headers["retry-after"]).timestamp() - self.now()
+                    )
+                except ValueError, TypeError, OverflowError:
+                    return 60
+        if headers.get("x-ratelimit-remaining") == "0":
+            try:
+                delay = float(headers["x-ratelimit-reset"]) - self.now()
+                return max(0, delay) if math.isfinite(delay) else 60
+            except KeyError, ValueError:
+                return 60
+        # The response body is inspected only to classify the error, never surfaced.
+        if response.status_code == 429 or "rate limit" in response.text.lower():
+            return 60
+        return None
+
+    async def get(self, path: str, params: dict[str, str | int] | None = None) -> ReadResponse:
+        url = self.checked_url(path)
+        if params:
+            url = url.copy_merge_params(params)
+        async with self.lock:
+            return await self.read(url)
+
+    async def read(self, url: httpx.URL) -> ReadResponse:
+        key = str(url)
+        cached = self.cache.get(key)
+        headers: dict[str, str] = {}
+        if cached is not None:
+            if "etag" in cached.headers:
+                headers["If-None-Match"] = cached.headers["etag"]
+            elif "last-modified" in cached.headers:
+                headers["If-Modified-Since"] = cached.headers["last-modified"]
+        redirects = 0
+        for attempt in range(3):
+            try:
+                response = await self.paced_get(url, headers)
+                while response.status_code in {301, 302, 303, 307, 308}:
+                    redirects += 1
+                    if redirects > 3 or "location" not in response.headers:
+                        raise ForgeError("GitHub redirect limit exceeded or location missing")
+                    url = self.checked_url(url.join(response.headers["location"]))
+                    headers = {}
+                    response = await self.paced_get(url, {})
+            except httpx.RequestError:
+                if attempt < 2:
+                    await self.sleep(2**attempt + random.random())
+                    continue
+                raise ForgeError(
+                    "GitHub request failed; check network, TLS, and API availability"
+                ) from None
+            delay = self.retry_delay(response)
+            if delay is not None:
+                delay = max(delay, 1)
+                self.blocked_until = self.now() + delay
+                observe_cooldown(self.blocked_until)
+                # Return long waits to the caller instead of holding doctor open.
+                if delay > 5 or attempt == 2:
+                    raise ForgeError(
+                        "GitHub rate limit reached; retry after the reported cooldown",
+                        status=response.status_code,
+                        retry_after=delay,
+                    )
+                await self.sleep(delay + random.random())
+                continue
+            if response.status_code >= 500 and attempt < 2:
+                await self.sleep(2**attempt + random.random())
+                continue
+            if response.status_code == 304:
+                self.blocked_until = 0
+                if cached is None or redirects:
+                    raise ForgeError("GitHub returned 304 without a cached representation")
+                merged = httpx.Headers(cached.headers)
+                merged.update(response.headers)
+                result = ReadResponse(cached.body, merged, cached.next_page)
+                self.cache[key] = result
+                self.cache.move_to_end(key)
+                return result
+            if response.status_code != 200:
+                messages = {
+                    401: "GitHub authentication failed",
+                    403: "GitHub access denied; check token permissions and organization SSO",
+                    404: "GitHub resource is missing or inaccessible",
+                    422: "GitHub rejected the search or request parameters",
+                }
+                raise ForgeError(
+                    messages.get(response.status_code, "GitHub request failed"),
+                    status=response.status_code,
+                )
+            try:
+                body: object = response.json()
+            except ValueError:
+                raise ForgeError("GitHub returned invalid JSON") from None
+            result = ReadResponse(body, response.headers, "next" in response.links)
+            self.blocked_until = 0
+            self.cache[key] = result
+            self.cache.move_to_end(key)
+            while len(self.cache) > 256:
+                self.cache.popitem(last=False)
+            return result
+        raise ForgeError("GitHub retry budget exhausted")
+
+    async def close(self) -> None:
+        self.cache.clear()
+        await self.client.aclose()

diffbutler/forges/github/mapping.py

@@ -0,0 +1,157 @@
+"""Validate GitHub response shapes before exposing immutable domain values."""
+
+from datetime import datetime
+from typing import cast
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, ValidationError
+
+from diffbutler.domain.forge import PRRef, PullRequest
+from diffbutler.forges.base import ForgeError
+
+
+class ResponseModel(BaseModel):
+    model_config = ConfigDict(extra="ignore", strict=True)
+
+
+class User(ResponseModel):
+    login: str
+    name: str | None = None
+
+
+class Organization(ResponseModel):
+    login: str
+
+
+class Team(ResponseModel):
+    slug: str
+    organization: Organization | None = None
+
+
+class Repository(ResponseModel):
+    full_name: str
+
+
+class Branch(ResponseModel):
+    sha: str
+    ref: str
+    repo: Repository | None
+
+
+class Label(ResponseModel):
+    name: str
+
+
+class Pull(ResponseModel):
+    additions: int | None = Field(default=None, ge=0)
+    deletions: int | None = Field(default=None, ge=0)
+    changed_files: int | None = Field(default=None, ge=0)
+    labels: list[Label] = Field(default_factory=list[Label])
+
+    number: int = Field(gt=0)
+    title: str
+    user: User | None
+    state: str
+    merged: bool
+    draft: bool = False
+    head: Branch
+    base: Branch
+    # HTTP JSON dates are strings. Parse them separately rather than coercing
+    # malformed booleans, IDs, or list contents via non-strict model validation.
+    created_at: str
+    updated_at: str
+    assignees: list[User] = Field(default_factory=list[User])
+    requested_reviewers: list[User]
+    requested_teams: list[Team]
+
+
+class DateValue(BaseModel):
+    value: AwareDatetime
+
+
+def timestamp(value: str) -> datetime:
+    return DateValue.model_validate({"value": value}).value
+
+
+class SearchHit(ResponseModel):
+    pull_request: dict[str, str | None]
+
+
+class SearchResult(ResponseModel):
+    total_count: int = Field(ge=0)
+    incomplete_results: bool
+    items: list[SearchHit]
+
+
+def parse[T: BaseModel](model: type[T], value: object) -> T:
+    try:
+        return model.model_validate(value)
+    except ValidationError:
+        raise ForgeError("GitHub returned an unexpected response shape") from None
+
+
+def objects(value: object) -> list[object]:
+    if not isinstance(value, list):
+        raise ForgeError("GitHub returned an unexpected list response")
+    return cast(list[object], value)
+
+
+def pull_request(value: object, *, forge: str, web_base: str) -> PullRequest:
+    data = parse(Pull, value)
+    try:
+        if data.base.repo is None:
+            raise ValueError("base repository missing")
+        owner, name = data.base.repo.full_name.split("/")
+        ref = PRRef(forge, owner.lower(), name.lower(), data.number)
+        if data.state not in {"open", "closed"}:
+            raise ValueError("unknown pull request state")
+        return PullRequest(
+            ref=ref,
+            title=data.title,
+            author=data.user.login if data.user else "[deleted]",
+            url=f"{web_base}/{owner}/{name}/pull/{data.number}",
+            state="merged" if data.merged else ("closed" if data.state == "closed" else "open"),
+            head_sha=data.head.sha,
+            base_sha=data.base.sha,
+            head_ref=data.head.ref,
+            base_ref=data.base.ref,
+            is_draft=data.draft,
+            created_at=timestamp(data.created_at),
+            updated_at=timestamp(data.updated_at),
+            additions=data.additions,
+            deletions=data.deletions,
+            files=data.changed_files,
+            labels=tuple(label.name for label in data.labels),
+            assignees=tuple(user.login.lower() for user in data.assignees),
+            requested_users=tuple(user.login.lower() for user in data.requested_reviewers),
+            requested_teams=tuple(
+                f"{owner.lower()}/{team.slug.lower()}" for team in data.requested_teams
+            ),
+        )
+    except ValueError:
+        raise ForgeError("GitHub returned invalid pull request identity or dates") from None
+
+
+class IssueEvent(ResponseModel):
+    id: int
+    event: str
+    created_at: str
+    requested_reviewer: User | None = None
+    requested_team: Team | None = None
+
+
+class Review(ResponseModel):
+    body: str | None = None
+    id: int
+    user: User | None
+    state: str
+    submitted_at: str | None = None
+    commit_id: str | None = None
+
+
+class Comment(ResponseModel):
+    id: int
+    user: User | None
+    body: str
+    created_at: str
+    commit_id: str | None = None
+    pull_request_review_id: int | None = None

diffbutler/forges/github/setup.py

@@ -0,0 +1,86 @@
+"""Read-only visibility and credential checks before first-run configuration is saved."""
+
+import asyncio
+
+from diffbutler.domain.forge import PRQuery, identity_part
+from diffbutler.forges.base import ForgeError
+from diffbutler.forges.github.http import GitHubHTTP
+from diffbutler.forges.github.mapping import ResponseModel, User, parse
+
+
+class RepositoryAccess(ResponseModel):
+    full_name: str
+    private: bool
+    visibility: str | None = None
+
+
+async def detect_login(base_url: str, token: str) -> str | None:
+    """Best-effort identity lookup; failures leave setup's manual prompt available."""
+    try:
+        async with asyncio.timeout(10):
+            http = GitHubHTTP(base_url, token, max_pacing_wait=5)
+            try:
+                response = await http.get("user")
+                login = parse(User, response.body).login
+                identity_part(login)
+                return login
+            finally:
+                await http.close()
+    except ForgeError, ValueError, TimeoutError:
+        return None
+
+
+async def repository_access(http: GitHubHTTP, repository: str) -> RepositoryAccess:
+    PRQuery(repository=repository)
+    response = await http.get(f"repos/{repository}")
+    access = parse(RepositoryAccess, response.body)
+    if access.full_name.lower() != repository.lower():
+        raise ForgeError("GitHub returned a different repository; check owner/name")
+    return access
+
+
+async def repository_is_public(base_url: str, repository: str) -> bool:
+    http = GitHubHTTP(base_url, None, max_pacing_wait=5)
+    try:
+        access = await repository_access(http, repository)
+        return not access.private and access.visibility in {None, "public"}
+    except ForgeError as exc:
+        if exc.status in {401, 403, 404} and exc.retry_after is None:
+            return False
+        raise
+    finally:
+        await http.close()
+
+
+async def validate_access(
+    base_url: str,
+    repository: str,
+    login: str,
+    token: str | None,
+) -> str:
+    identity_part(login)
+    http = GitHubHTTP(base_url, token, max_pacing_wait=5)
+    try:
+        try:
+            response = await http.get("user" if token is not None else f"users/{login}")
+        except ForgeError as exc:
+            if exc.status == 401:
+                raise ForgeError(
+                    "Invalid GitHub token in the selected environment variable"
+                ) from None
+            if exc.status == 404 and token is None:
+                raise ForgeError("GitHub username was not found") from None
+            raise
+        user = parse(User, response.body)
+        try:
+            identity_part(user.login)
+        except ValueError:
+            raise ForgeError("GitHub returned an invalid account identity") from None
+        if user.login.lower() != login.lower():
+            raise ForgeError("GitHub token belongs to a different username")
+        await repository_access(http, repository)
+        # Validate pull-request read permissions, not just repository metadata access.
+        await http.get(f"repos/{repository}/pulls", {"per_page": 1, "state": "open"})
+        return user.login
+    finally:
+        await http.close()

diffbutler/forges/registry.py

@@ -0,0 +1,23 @@
+"""Construct configured read adapters without exposing credentials to the core."""
+
+from diffbutler.config.settings import Forge
+from diffbutler.forges.base import ForgeError, ReadForge
+from diffbutler.forges.github.adapter import GitHubForge
+from diffbutler.forges.github.auth import resolve_token
+from diffbutler.forges.github.http import GitHubHTTP
+
+
+async def open_forge(config: Forge) -> ReadForge:
+    if config.kind != "github":
+        raise ForgeError("GitLab adapter is not implemented")
+    token = (
+        await resolve_token(config.base_url, config.token_env)
+        if config.token_env is not None
+        else None
+    )
+    return GitHubForge(
+        GitHubHTTP(config.base_url, token),
+        include_team_requests=config.include_team_requests,
+        repositories=tuple(config.repositories),
+        public_login=config.login if token is None else None,
+    )

diffbutler/reviewers/__init__.py

@@ -0,0 +1 @@
+"""Background review and native session adapters."""

diffbutler/reviewers/base.py

@@ -0,0 +1,101 @@
+"""Background-only adapter seam. Contracts alone do not enforce process isolation."""
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+from uuid import UUID
+
+from diffbutler.domain.diff import DiffIndex
+from diffbutler.domain.forge import PullRequest
+from diffbutler.domain.review import ChangedFile, SourceFile
+
+
+class SourceReader(Protocol):
+    """Pinned PR source: BASE means the comparison merge base, HEAD the PR head."""
+
+    async def read_file(self, source: SourceFile) -> bytes | None: ...
+
+
+class ReviewSources(SourceReader, Protocol):
+    """Prepared sources pinned to the PR revisions."""
+
+    @property
+    def base_sha(self) -> str: ...
+
+    @property
+    def comparison_base_sha(self) -> str: ...
+
+    @property
+    def head_sha(self) -> str: ...
+
+    @property
+    def changed_files(self) -> tuple[ChangedFile, ...]: ...
+
+    @property
+    def limitations(self) -> tuple[str, ...]: ...
+
+    async def read_diff(self) -> str: ...
+
+
+@dataclass(frozen=True)
+class ReviewBudget:
+    timeout_s: int = 900
+
+    def __post_init__(self) -> None:
+        if self.timeout_s <= 0:
+            raise ValueError("review budgets must be positive")
+
+
+@dataclass(frozen=True)
+class ReviewContext:
+    pr: PullRequest
+    session_id: UUID
+    run_id: UUID
+    diff: str
+    changed_files: tuple[ChangedFile, ...]
+    sources: SourceReader
+    instructions: str
+    schema_json: str
+    budget: ReviewBudget
+    comparison_base_sha: str
+    diff_index: DiffIndex | None = None
+    checkout_path: Path | None = None
+    limitations: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ReviewerCapabilities:
+    resume: bool = False
+    discussion: bool = False
+    delete_session: bool = False
+
+
+@dataclass(frozen=True)
+class ReviewProgress:
+    text: str
+
+
+@dataclass(frozen=True)
+class ReviewOutput:
+    """Untrusted output, not parsed findings or evidence of forge publication."""
+
+    stdout: bytes
+    stderr: bytes
+    exit_code: int
+    backend_session_id: str | None = None
+
+
+type ReviewEvent = ReviewProgress | ReviewOutput
+
+
+class Reviewer(Protocol):
+    @property
+    def id(self) -> str: ...
+
+    @property
+    def capabilities(self) -> ReviewerCapabilities: ...
+
+    def review(self, context: ReviewContext) -> AsyncIterator[ReviewEvent]:
+        """Stream captured progress and one final output; never own a terminal."""
+        ...