from __future__ import annotations from dataclasses import dataclass from datetime import datetime from typing import Any, Literal from urllib.parse import quote import httpx from fastapi import HTTPException, status from pydantic import ( AliasChoices, AliasPath, BaseModel, Field, TypeAdapter, ValidationError, field_validator, ) from app.models.app_settings import AppSettings _LOCAL_HTTP_HOSTS = {"localhost", "127.0.0.1", "::1", "forgejo"} def _authenticated_base_url(value: str) -> httpx.URL: """Require encrypted transport except for documented local Forgejo hosts.""" try: url = httpx.URL(value.strip()) except httpx.InvalidURL: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="Configure a valid Forgejo URL in setup.", ) from None local_http = url.scheme == "http" and ( url.host in _LOCAL_HTTP_HOSTS or url.host.endswith(".localhost") ) if ( not url.host or (url.scheme != "https" and not local_http) or url.userinfo or url.query or url.fragment ): raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="Configure an HTTPS Forgejo URL in setup. HTTP is only allowed for local Forgejo endpoints.", ) return url class Repo(BaseModel): """A repository returned by Forgejo.""" repo_name: str = Field(validation_alias="name") repo_full_name: str = Field(validation_alias="full_name") repo_owner: str = Field(validation_alias=AliasPath("owner", "username")) default_branch: str description: str | None visibility: Literal["private", "public"] = Field(validation_alias="private") html_url: str created_at: datetime updated_at: datetime archived: bool archived_at: datetime | None @field_validator("visibility", mode="before") @classmethod def map_visibility(cls, value: Any) -> Literal["private", "public"]: if not isinstance(value, bool): raise ValueError("expected a boolean") # noqa: TRY004 return "private" if value else "public" @dataclass(frozen=True) class RepoPage: repos: list[Repo] total_count: int | None has_next_page: bool class Commit(BaseModel): """A commit, normalized across Forgejo's two payload shapes. ``/branches`` nests a trimmed commit keyed ``id``/``timestamp``/``url``, while ``/commits`` returns a flat GitHub-style object keyed ``sha``/``commit.message``/``html_url``/``created``. Each field therefore accepts either shape. """ id: str = Field( validation_alias=AliasChoices("sha", "id"), pattern=r"^(?:[a-f0-9]{40}|[a-f0-9]{64})$", ) message: str = Field( validation_alias=AliasChoices("message", AliasPath("commit", "message")) ) url: str = Field(validation_alias=AliasChoices("html_url", "url")) created_at: datetime = Field( validation_alias=AliasChoices( "timestamp", "created_at", "created", AliasPath("commit", "committer", "date"), ) ) class Branch(BaseModel): """A branch returned by Forgejo.""" name: str protected: bool commit: Commit _REPOSITORIES = TypeAdapter(list[Repo]) _BRANCHES = TypeAdapter(list[Branch]) _BRANCH = TypeAdapter(Branch) _COMMITS = TypeAdapter(list[Commit]) _OBJECT = TypeAdapter(dict[str, Any]) def _malformed_response() -> HTTPException: return HTTPException( status_code=status.HTTP_502_BAD_GATEWAY, detail="Forgejo returned unexpected data. Check the Forgejo URL and try again.", ) def _parse_json[T](response: httpx.Response, adapter: TypeAdapter[T]) -> T: try: return adapter.validate_json(response.content) except ValidationError: raise _malformed_response() from None async def get_repos( app_settings: AppSettings, access_token: str, *, limit: int = 30, page: int = 1, owner: str | None = None, ) -> RepoPage: """Get the user's repositories from the Forgejo API. Forgejo paginates this endpoint and caps `limit` at the instance's max_response_items (50 on the default config), so a caller asking for everything silently gets one page. Paging is exposed here rather than looped internally so the caller can decide how many round trips to spend. Args: app_settings: The application settings. access_token: The Forgejo API token. limit: The maximum number of repositories to return. page: The page number to return. owner: Restrict results to repositories owned by this username. Returns: The repositories and Forgejo's total-count pagination metadata. """ params: dict[str, str | int] = {"limit": limit, "page": page} endpoint = f"/users/{quote(owner, safe='')}/repos" if owner else "/user/repos" path = f"/api/v1{endpoint}?{httpx.QueryParams(params)}" response = await _get(app_settings, path, access_token) repos = _parse_json(response, _REPOSITORIES) total_count_header = response.headers.get("x-total-count") try: total_count = int(total_count_header) if total_count_header else None except ValueError: total_count = None return RepoPage( repos=repos, total_count=total_count, has_next_page="next" in response.links, ) async def get_branches( app_settings: AppSettings, access_token: str, owner: str, repo: str, *, limit: int = 10, page: int = 1, ) -> list[Branch]: """Get the branches of a repository from the Forgejo API. Args: access_token: The Forgejo API token. owner: The owner of the repository. repo: The name of the repository. limit: The maximum number of branches to return. page: The page number to return. Returns: A list of branches. """ response = await _get( app_settings, f"/api/v1/repos/{quote(owner, safe='')}/{quote(repo, safe='')}/branches?" f"{httpx.QueryParams({'limit': limit, 'page': page})}", access_token, ) return _parse_json(response, _BRANCHES) async def get_branch_tip( app_settings: AppSettings, access_token: str, owner: str, repo: str, branch: str ) -> str: """Resolve a branch by name without letting Git choose a tag or other ref.""" response = await _get( app_settings, f"/api/v1/repos/{quote(owner, safe='')}/{quote(repo, safe='')}" f"/branches/{quote(branch, safe='')}", access_token, ) result = _parse_json(response, _BRANCH) if result.name != branch: raise _malformed_response() return result.commit.id async def get_commits( app_settings: AppSettings, access_token: str, owner: str, repo: str, *, ref: str, limit: int = 10, page: int = 1, ) -> list[Commit]: """Get the commits of a branch from the Forgejo API. Args: access_token: The Forgejo API token. owner: The owner of the repository. repo: The name of the repository. ref: The branch name, commit sha, or tag to list commits for. limit: The maximum number of commits to return. page: The page number to return. Returns: A list of commits. """ response = await _get( app_settings, f"/api/v1/repos/{quote(owner, safe='')}/{quote(repo, safe='')}/commits?" f"{httpx.QueryParams({'sha': ref, 'limit': limit, 'page': page})}", access_token, ) return _parse_json(response, _COMMITS) async def post(app_settings: AppSettings, path: str, data: dict) -> dict: """Send a POST request to the Forgejo API. Args: app_settings: The application settings. path: The path to the Forgejo API endpoint. data: The data to send in the request. Returns: The response from the Forgejo API. """ base_url = _authenticated_base_url(app_settings.forgejo_base_url) try: async with httpx.AsyncClient(base_url=base_url, timeout=30.0) as client: resp = await client.post( path, data=data, headers={"Accept": "application/json"} ) except httpx.RequestError: raise HTTPException( status_code=status.HTTP_502_BAD_GATEWAY, detail="Cannot reach Forgejo. Check your connection settings.", ) if resp.status_code != 200: raise HTTPException( status_code=status.HTTP_502_BAD_GATEWAY, detail=f"Forgejo returned an error ({resp.status_code}). Verify your OAuth configuration.", ) return _parse_json(resp, _OBJECT) async def get( app_settings: AppSettings, path: str, access_token: str ) -> dict[str, Any]: """Fetch a JSON object from the Forgejo API.""" return _parse_json(await _get(app_settings, path, access_token), _OBJECT) async def _get( app_settings: AppSettings, path: str, access_token: str ) -> httpx.Response: """Fetch a response without dropping headers needed for pagination.""" base_url = _authenticated_base_url(app_settings.forgejo_base_url) try: async with httpx.AsyncClient(base_url=base_url, timeout=30.0) as client: resp = await client.get( path, headers={"Authorization": f"token {access_token}"} ) except httpx.RequestError: raise HTTPException( status_code=status.HTTP_502_BAD_GATEWAY, detail="Cannot reach Forgejo. Check your connection settings.", ) if resp.status_code == 200: return resp if resp.status_code in {401, 403}: detail = ( "Forgejo rejected the access token. For repository browsing, " "check that your personal access token is valid and has " "read:user and read:repository scopes." ) else: detail = f"Forgejo returned an error ({resp.status_code}). Check the connection settings and try again." raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=detail)