gitd-client 0.14.0__py3-none-any.whl

gitd/contract.py

@@ -0,0 +1,50 @@
+"""gitd's contract, read at run time from contract.json, which `make generate` builds from
+proto/gitd/v1/gitd.proto. Only protobuf's public API is used: no code is generated."""
+
+from __future__ import annotations
+
+from importlib import resources
+
+from google.protobuf import descriptor_pb2, descriptor_pool, json_format, message_factory
+from google.protobuf.descriptor import EnumDescriptor
+from google.protobuf.message import Message
+
+PACKAGE = "gitd.v1"
+CONTRACT_FILE = "contract.json"
+
+
+class Enumeration:
+    """An enumeration of the contract, by the names and numbers of its values."""
+
+    def __init__(self, descriptor: EnumDescriptor) -> None:
+        self.descriptor = descriptor
+
+    def number(self, name: str) -> int:
+        return self.descriptor.values_by_name[name].number
+
+    def name(self, number: int) -> str:
+        """The value's name, or an empty one for a value newer than this client."""
+        value = self.descriptor.values_by_number.get(number)
+        return value.name if value else ""
+
+
+class Contract:
+    """The messages and enumerations of gitd's API."""
+
+    def __init__(self, pool: descriptor_pool.DescriptorPool) -> None:
+        self.pool = pool
+
+    @classmethod
+    def load(cls) -> Contract:
+        text = resources.files(__package__).joinpath(CONTRACT_FILE).read_text(encoding="utf-8")
+        files = json_format.Parse(text, descriptor_pb2.FileDescriptorSet())
+        pool = descriptor_pool.DescriptorPool()
+        for file in files.file:
+            pool.Add(file)
+        return cls(pool)
+
+    def message(self, name: str) -> type[Message]:
+        return message_factory.GetMessageClass(self.pool.FindMessageTypeByName(f"{PACKAGE}.{name}"))
+
+    def enumeration(self, name: str) -> Enumeration:
+        return Enumeration(self.pool.FindEnumTypeByName(f"{PACKAGE}.{name}"))

gitd/credentials_calls.py

@@ -0,0 +1,69 @@
+"""The calls that manage the credentials gitd keeps: for a platform's own pages, never for
+an agent."""
+
+from __future__ import annotations
+
+from . import messages, methods
+from .connection import Connection
+from .kept_credentials import AppToCreate, Connected, KeptCredential, SignIn
+
+
+class Credentials:
+    """The credentials gitd keeps, as gitd.credentials.
+
+    app = gitd.credentials.begin_github_app("acme-agents", "https://platform.example.com/github/created",
+                                            organization="acme")
+    # the browser posts app.manifest to app.form_action; GitHub sends it back with a code
+    connected = gitd.credentials.complete_github_app(code, app.state)
+    """
+
+    def __init__(self, connection: Connection) -> None:
+        self.connection = connection
+
+    def list(self) -> list[KeptCredential]:
+        """Every credential gitd keeps, gitd.toml's included, never a secret."""
+        response = self.connection.call(methods.LIST_CONNECTIONS, messages.ListConnectionsRequest())
+        return [KeptCredential.from_message(connection) for connection in response.connections]
+
+    def remove(self, credential_id: str) -> None:
+        """Forgets a credential kept through the API."""
+        self.connection.call(methods.REMOVE_CONNECTION, messages.RemoveConnectionRequest(id=credential_id))
+
+    def add_token(self, url_prefix: str, token: str, *, user: str = "") -> KeptCredential:
+        """Keeps a token for the repositories under url_prefix, which names the host."""
+        request = messages.AddTokenRequest(url_prefix=url_prefix, token=token, user=user)
+        return KeptCredential.from_message(self.connection.call(methods.ADD_TOKEN, request).connection)
+
+    def add_github_app(
+        self, app_id: int, private_key: str, *, host: str = "", url_prefix: str = ""
+    ) -> KeptCredential:
+        """Keeps a GitHub App a platform already has, once GitHub takes the key as its own."""
+        request = messages.AddGitHubAppRequest(
+            host=host, app_id=app_id, private_key=private_key, url_prefix=url_prefix
+        )
+        return KeptCredential.from_message(self.connection.call(methods.ADD_GITHUB_APP, request).connection)
+
+    def begin_github_app(
+        self, name: str, redirect_url: str, *, organization: str = "", host: str = ""
+    ) -> AppToCreate:
+        """Starts creating the organisation's own GitHub App, named name; GitHub sends the
+        person back to redirect_url with a code and the state."""
+        request = messages.BeginGitHubAppRequest(
+            host=host, organization=organization, name=name, redirect_url=redirect_url
+        )
+        return AppToCreate.from_message(self.connection.call(methods.BEGIN_GITHUB_APP, request))
+
+    def complete_github_app(self, code: str, state: str) -> Connected:
+        """Finishes creating the App with the code and state GitHub sent back."""
+        request = messages.CompleteGitHubAppRequest(code=code, state=state)
+        return Connected.from_message(self.connection.call(methods.COMPLETE_GITHUB_APP, request))
+
+    def start_github_login(self, *, host: str = "") -> SignIn:
+        """Asks GitHub for the code a person enters to sign in through gitd's public App."""
+        request = messages.StartGitHubLoginRequest(host=host)
+        return SignIn.from_message(self.connection.call(methods.START_GITHUB_LOGIN, request))
+
+    def finish_github_login(self, login_id: str) -> Connected:
+        """Waits until the person has entered the code, and keeps the sign-in."""
+        request = messages.FinishGitHubLoginRequest(login_id=login_id)
+        return Connected.from_message(self.connection.call(methods.FINISH_GITHUB_LOGIN, request))

gitd/endpoint_calls.py

@@ -0,0 +1,52 @@
+"""The calls of gitd's endpoint: tokens for sandboxes elsewhere. What a sandbox pushes is
+published with Gitd.publish and its sandbox."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+from . import messages, methods
+from .connection import Connection
+from .endpoint_tokens import IssuedToken, TokenInfo
+
+
+class Endpoint:
+    """gitd's endpoint, as gitd.endpoint.
+
+    issued = gitd.endpoint.issue("https://github.com/acme/web", lifetime=timedelta(hours=2))
+    # in the sandbox: git clone issued.authenticated_url() …; git push origin HEAD:agents/fix
+    gitd.publish("", "agents/fix", sandbox=issued.info.sandbox)
+    """
+
+    def __init__(self, connection: Connection) -> None:
+        self.connection = connection
+
+    def issue(
+        self,
+        url: str,
+        *,
+        branch: str = "",
+        lifetime: timedelta | None = None,
+        read_only: bool = False,
+        sandbox: str = "",
+    ) -> IssuedToken:
+        """A token for a sandbox: it reads url and pushes to its own sandbox repository (an
+        earlier one when sandbox names it), for lifetime (an hour by default, a day at most)."""
+        request = messages.IssueTokenRequest(
+            url=url,
+            branch=branch,
+            lifetime_seconds=int(lifetime.total_seconds()) if lifetime else 0,
+            read_only=read_only,
+            sandbox=sandbox,
+        )
+        return IssuedToken.from_message(self.connection.call(methods.ISSUE_TOKEN, request))
+
+    def revoke(self, token_id: str, *, remove_sandbox: bool = False) -> None:
+        """Ends a token now, and removes its sandbox repository when asked."""
+        request = messages.RevokeTokenRequest(id=token_id, remove_sandbox=remove_sandbox)
+        self.connection.call(methods.REVOKE_TOKEN, request)
+
+    def tokens(self) -> list[TokenInfo]:
+        """The tokens alive, never their secrets."""
+        response = self.connection.call(methods.LIST_TOKENS, messages.ListTokensRequest())
+        return [TokenInfo.from_message(info) for info in response.tokens]

gitd/endpoint_tokens.py

@@ -0,0 +1,55 @@
+"""Tokens of gitd's endpoint, for sandboxes that clone over HTTP instead of mounting a
+workspace: a microVM, a remote sandbox, a CI runner elsewhere."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from .timestamps import Timestamp
+
+
+@dataclass(frozen=True)
+class TokenInfo:
+    """A token as gitd shows it, never its secret: what it reads, the sandbox repository it
+    pushes to when writable, and until when."""
+
+    id: str
+    url: str
+    sandbox: str
+    writable: bool
+    issued_at: datetime
+    expires_at: datetime
+
+    @classmethod
+    def from_message(cls, info: Any) -> TokenInfo:
+        return cls(
+            id=info.id,
+            url=info.url,
+            sandbox=info.sandbox,
+            writable=info.writable,
+            issued_at=Timestamp.to_datetime(info.issued_at),
+            expires_at=Timestamp.to_datetime(info.expires_at),
+        )
+
+
+@dataclass(frozen=True)
+class IssuedToken:
+    """A token just issued: its secret, shown this once, and where the sandbox clones from —
+    git clone https://x:<secret>@… — never the git host's credential."""
+
+    secret: str
+    clone_url: str
+    info: TokenInfo
+
+    @classmethod
+    def from_message(cls, response: Any) -> IssuedToken:
+        return cls(
+            secret=response.token, clone_url=response.clone_url, info=TokenInfo.from_message(response.info)
+        )
+
+    def authenticated_url(self) -> str:
+        """The clone URL with the secret in it, for the sandbox's git."""
+        scheme, rest = self.clone_url.split("://", 1)
+        return f"{scheme}://x:{self.secret}@{rest}"

gitd/errors.py

@@ -0,0 +1,36 @@
+"""A refusal from gitd."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import grpc
+from grpc_status import rpc_status
+
+from . import messages
+from .models import Refusal
+
+
+class GitdError(Exception):
+    """A refusal from gitd: its reason (AUTH_REQUIRED, NOT_FOUND, PATH_REFUSED, BUSY, …) and
+    what git said. Tell users what happened from the reason, never by parsing the message."""
+
+    def __init__(self, reason: str, said: str, code: grpc.StatusCode | None = None) -> None:
+        super().__init__(f"{reason}: {said}" if reason else said)
+        self.reason = reason
+        self.said = said
+        self.code = code
+
+    @classmethod
+    def from_rpc_error(cls, error: grpc.RpcError) -> GitdError:
+        """Reads the GitFailure gitd attaches to a refused call, if there is one."""
+        if not isinstance(error, grpc.Call):
+            return cls("", str(error))
+        status = rpc_status.from_call(error)
+        details = list(status.details) if status else []
+        for detail in details:
+            if detail.Is(messages.GitFailure.DESCRIPTOR):
+                failure: Any = messages.GitFailure()
+                detail.Unpack(failure)
+                return cls(Refusal.reason_of(failure), failure.git_said, error.code())
+        return cls("", error.details() or "", error.code())

gitd/kept_credentials.py

@@ -0,0 +1,107 @@
+"""The credentials gitd keeps, and the steps of connecting GitHub, as plain dataclasses
+built from the messages gitd answers. None of them ever holds a secret."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from . import messages
+from .timestamps import Timestamp
+
+KIND_PREFIX = "KIND_"
+
+
+class CredentialKind(StrEnum):
+    """What a credential is: a token, an SSH key, a GitHub App, or a person signed in."""
+
+    TOKEN = "token"
+    SSH_KEY = "ssh_key"
+    GITHUB_APP = "github_app"
+    GITHUB_LOGIN = "github_login"
+
+    @classmethod
+    def from_message(cls, number: int) -> CredentialKind:
+        name = messages.CONNECTION_KIND.name(number).removeprefix(KIND_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.TOKEN
+
+
+@dataclass(frozen=True)
+class KeptCredential:
+    """One credential gitd keeps: its id to remove it by, what it is, the repositories it
+    opens, whom it acts as (an App's bot or a person), an App's id and where it is managed,
+    when a sign-in stops renewing, and whether gitd.toml declares it."""
+
+    id: str
+    kind: CredentialKind
+    url_prefix: str
+    acts_as: str
+    app_id: int
+    manage_url: str
+    expires: datetime | None
+    from_file: bool
+    created: datetime | None
+
+    @classmethod
+    def from_message(cls, connection: Any) -> KeptCredential:
+        return cls(
+            id=connection.id,
+            kind=CredentialKind.from_message(connection.kind),
+            url_prefix=connection.url_prefix,
+            acts_as=connection.acts_as,
+            app_id=connection.app_id,
+            manage_url=connection.manage_url,
+            expires=Timestamp.to_datetime(connection.expires) if connection.HasField("expires") else None,
+            from_file=connection.from_file,
+            created=Timestamp.to_datetime(connection.created) if connection.HasField("created") else None,
+        )
+
+
+@dataclass(frozen=True)
+class Connected:
+    """A GitHub App or sign-in gitd now keeps, and where it is installed on repositories."""
+
+    credential: KeptCredential
+    install_url: str
+
+    @classmethod
+    def from_message(cls, response: Any) -> Connected:
+        return cls(
+            credential=KeptCredential.from_message(response.connection), install_url=response.install_url
+        )
+
+
+@dataclass(frozen=True)
+class AppToCreate:
+    """What a browser posts to GitHub to create an App: where (form_action), the manifest,
+    as a form field named manifest, and the state GitHub sends back with the code."""
+
+    form_action: str
+    manifest: str
+    state: str
+
+    @classmethod
+    def from_message(cls, response: Any) -> AppToCreate:
+        return cls(form_action=response.form_action, manifest=response.manifest, state=response.state)
+
+
+@dataclass(frozen=True)
+class SignIn:
+    """A sign-in waiting for a person: the code they enter at verification_url, for how
+    long, and the id to finish it by."""
+
+    user_code: str
+    verification_url: str
+    login_id: str
+    expires_in_seconds: int
+
+    @classmethod
+    def from_message(cls, response: Any) -> SignIn:
+        return cls(
+            user_code=response.user_code,
+            verification_url=response.verification_url,
+            login_id=response.login_id,
+            expires_in_seconds=response.expires_in_seconds,
+        )

gitd/messages.py

@@ -0,0 +1,92 @@
+"""The messages and enumerations of gitd's contract that this client uses."""
+
+from .contract import Contract
+
+contract = Contract.load()
+
+InfoRequest = contract.message("InfoRequest")
+InfoResponse = contract.message("InfoResponse")
+ProbeRequest = contract.message("ProbeRequest")
+ProbeResponse = contract.message("ProbeResponse")
+Revision = contract.message("Revision")
+PrepareRequest = contract.message("PrepareRequest")
+PrepareResponse = contract.message("PrepareResponse")
+UpdateRequest = contract.message("UpdateRequest")
+UpdateResponse = contract.message("UpdateResponse")
+CheckoutRequest = contract.message("CheckoutRequest")
+CheckoutResponse = contract.message("CheckoutResponse")
+DescribeRequest = contract.message("DescribeRequest")
+DescribeResponse = contract.message("DescribeResponse")
+PublishRequest = contract.message("PublishRequest")
+PublishResponse = contract.message("PublishResponse")
+RemoveRequest = contract.message("RemoveRequest")
+RemoveResponse = contract.message("RemoveResponse")
+AuditRequest = contract.message("AuditRequest")
+AuditResponse = contract.message("AuditResponse")
+GitFailure = contract.message("GitFailure")
+PullRequestOptions = contract.message("PullRequestOptions")
+Provenance = contract.message("Provenance")
+ChangesRequest = contract.message("ChangesRequest")
+ChangesResponse = contract.message("ChangesResponse")
+DiffRequest = contract.message("DiffRequest")
+DiffResponse = contract.message("DiffResponse")
+Side = contract.message("Side")
+CompareRequest = contract.message("CompareRequest")
+CompareResponse = contract.message("CompareResponse")
+ConflictsRequest = contract.message("ConflictsRequest")
+ConflictsResponse = contract.message("ConflictsResponse")
+WatchRequest = contract.message("WatchRequest")
+WatchResponse = contract.message("WatchResponse")
+SealRequest = contract.message("SealRequest")
+SealResponse = contract.message("SealResponse")
+ListWarmRequest = contract.message("ListWarmRequest")
+ListWarmResponse = contract.message("ListWarmResponse")
+IssueTokenRequest = contract.message("IssueTokenRequest")
+IssueTokenResponse = contract.message("IssueTokenResponse")
+RevokeTokenRequest = contract.message("RevokeTokenRequest")
+RevokeTokenResponse = contract.message("RevokeTokenResponse")
+ListTokensRequest = contract.message("ListTokensRequest")
+ListTokensResponse = contract.message("ListTokensResponse")
+
+ListConnectionsRequest = contract.message("ListConnectionsRequest")
+ListConnectionsResponse = contract.message("ListConnectionsResponse")
+RemoveConnectionRequest = contract.message("RemoveConnectionRequest")
+RemoveConnectionResponse = contract.message("RemoveConnectionResponse")
+AddTokenRequest = contract.message("AddTokenRequest")
+AddTokenResponse = contract.message("AddTokenResponse")
+AddGitHubAppRequest = contract.message("AddGitHubAppRequest")
+AddGitHubAppResponse = contract.message("AddGitHubAppResponse")
+BeginGitHubAppRequest = contract.message("BeginGitHubAppRequest")
+BeginGitHubAppResponse = contract.message("BeginGitHubAppResponse")
+CompleteGitHubAppRequest = contract.message("CompleteGitHubAppRequest")
+CompleteGitHubAppResponse = contract.message("CompleteGitHubAppResponse")
+StartGitHubLoginRequest = contract.message("StartGitHubLoginRequest")
+StartGitHubLoginResponse = contract.message("StartGitHubLoginResponse")
+FinishGitHubLoginRequest = contract.message("FinishGitHubLoginRequest")
+FinishGitHubLoginResponse = contract.message("FinishGitHubLoginResponse")
+
+PublishSettings = contract.message("PublishSettings")
+PullRequestSettings = contract.message("PullRequestSettings")
+GetSettingsRequest = contract.message("GetSettingsRequest")
+GetSettingsResponse = contract.message("GetSettingsResponse")
+SetSettingsRequest = contract.message("SetSettingsRequest")
+SetSettingsResponse = contract.message("SetSettingsResponse")
+RemoveSettingsRequest = contract.message("RemoveSettingsRequest")
+RemoveSettingsResponse = contract.message("RemoveSettingsResponse")
+Preset = contract.message("Preset")
+ListPresetsRequest = contract.message("ListPresetsRequest")
+ListPresetsResponse = contract.message("ListPresetsResponse")
+SetPresetRequest = contract.message("SetPresetRequest")
+SetPresetResponse = contract.message("SetPresetResponse")
+RemovePresetRequest = contract.message("RemovePresetRequest")
+RemovePresetResponse = contract.message("RemovePresetResponse")
+
+STRATEGY = contract.enumeration("Strategy")
+ACCESS = contract.enumeration("ProbeResponse.Access")
+REASON = contract.enumeration("GitFailure.Reason")
+CONNECTION_KIND = contract.enumeration("Connection.Kind")
+CHANGE_ACTION = contract.enumeration("ConfigurationChange.Action")
+OPENING = contract.enumeration("PullRequestSettings.Open")
+PRESET_ORIGIN = contract.enumeration("Preset.Origin")
+CHANGE_KIND = contract.enumeration("ChangedFile.Kind")
+EVENT_KIND = contract.enumeration("WatchResponse.Kind")

gitd/methods.py

@@ -0,0 +1,58 @@
+"""The gitd methods this client calls, by their gRPC path and the message each answers with."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from google.protobuf.message import Message
+
+from . import messages
+from .contract import PACKAGE
+
+
+@dataclass(frozen=True)
+class Method:
+    service: str
+    name: str
+    response: type[Message]
+
+    @property
+    def path(self) -> str:
+        return f"/{PACKAGE}.{self.service}/{self.name}"
+
+
+INFO = Method("ServerService", "Info", messages.InfoResponse)
+AUDIT = Method("ServerService", "Audit", messages.AuditResponse)
+PROBE = Method("RepositoryService", "Probe", messages.ProbeResponse)
+PREPARE = Method("WorkspaceService", "Prepare", messages.PrepareResponse)
+UPDATE = Method("WorkspaceService", "Update", messages.UpdateResponse)
+CHECKOUT = Method("WorkspaceService", "Checkout", messages.CheckoutResponse)
+DESCRIBE = Method("WorkspaceService", "Describe", messages.DescribeResponse)
+PUBLISH = Method("WorkspaceService", "Publish", messages.PublishResponse)
+REMOVE = Method("WorkspaceService", "Remove", messages.RemoveResponse)
+CHANGES = Method("WorkspaceService", "Changes", messages.ChangesResponse)
+DIFF = Method("WorkspaceService", "Diff", messages.DiffResponse)
+COMPARE = Method("WorkspaceService", "Compare", messages.CompareResponse)
+CONFLICTS = Method("WorkspaceService", "Conflicts", messages.ConflictsResponse)
+WATCH = Method("WorkspaceService", "Watch", messages.WatchResponse)
+SEAL = Method("WorkspaceService", "Seal", messages.SealResponse)
+LIST_WARM = Method("WorkspaceService", "ListWarm", messages.ListWarmResponse)
+ISSUE_TOKEN = Method("EndpointService", "IssueToken", messages.IssueTokenResponse)
+REVOKE_TOKEN = Method("EndpointService", "RevokeToken", messages.RevokeTokenResponse)
+LIST_TOKENS = Method("EndpointService", "ListTokens", messages.ListTokensResponse)
+
+LIST_CONNECTIONS = Method("ConnectionService", "ListConnections", messages.ListConnectionsResponse)
+REMOVE_CONNECTION = Method("ConnectionService", "RemoveConnection", messages.RemoveConnectionResponse)
+ADD_TOKEN = Method("ConnectionService", "AddToken", messages.AddTokenResponse)
+ADD_GITHUB_APP = Method("ConnectionService", "AddGitHubApp", messages.AddGitHubAppResponse)
+BEGIN_GITHUB_APP = Method("ConnectionService", "BeginGitHubApp", messages.BeginGitHubAppResponse)
+COMPLETE_GITHUB_APP = Method("ConnectionService", "CompleteGitHubApp", messages.CompleteGitHubAppResponse)
+START_GITHUB_LOGIN = Method("ConnectionService", "StartGitHubLogin", messages.StartGitHubLoginResponse)
+FINISH_GITHUB_LOGIN = Method("ConnectionService", "FinishGitHubLogin", messages.FinishGitHubLoginResponse)
+
+GET_SETTINGS = Method("PublishingService", "GetSettings", messages.GetSettingsResponse)
+SET_SETTINGS = Method("PublishingService", "SetSettings", messages.SetSettingsResponse)
+REMOVE_SETTINGS = Method("PublishingService", "RemoveSettings", messages.RemoveSettingsResponse)
+LIST_PRESETS = Method("PublishingService", "ListPresets", messages.ListPresetsResponse)
+SET_PRESET = Method("PublishingService", "SetPreset", messages.SetPresetResponse)
+REMOVE_PRESET = Method("PublishingService", "RemovePreset", messages.RemovePresetResponse)