gitd 0.7.0__py3-none-any.whl

gitd/__init__.py

@@ -0,0 +1,42 @@
+"""Client for gitd: instant, secretless git checkouts for agent sandboxes."""
+
+from .client import Gitd
+from .connection import DEFAULT_SOCKET, SOCKET_VARIABLE
+from .errors import GitdError
+from .models import (
+    Access,
+    AuditEntry,
+    Description,
+    Info,
+    Layers,
+    PendingSubmodule,
+    Probe,
+    Progress,
+    Published,
+    PublishedRepository,
+    Refusal,
+    Strategy,
+    Submodule,
+    Workspace,
+)
+
+__all__ = [
+    "DEFAULT_SOCKET",
+    "SOCKET_VARIABLE",
+    "Access",
+    "AuditEntry",
+    "Description",
+    "Gitd",
+    "GitdError",
+    "Info",
+    "Layers",
+    "PendingSubmodule",
+    "Probe",
+    "Progress",
+    "Published",
+    "PublishedRepository",
+    "Refusal",
+    "Strategy",
+    "Submodule",
+    "Workspace",
+]

gitd/client.py

@@ -0,0 +1,124 @@
+"""The gitd client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from . import messages, methods
+from .connection import Connection, OnProgress
+from .models import AuditEntry, Description, Info, Probe, Published, Strategy, Workspace
+from .timestamps import Timestamp
+
+
+class Gitd:
+    """A gitd on its Unix socket. No call takes a credential: gitd reads and publishes with
+    the ones it keeps.
+
+        with Gitd() as gitd:
+            workspace = gitd.prepare("https://github.com/acme/web", "/var/lib/gitd/workspaces/agent-1")
+    """
+
+    def __init__(self, socket: str | None = None, *, timeout: float | None = None) -> None:
+        self.connection = Connection(socket, timeout)
+
+    def __enter__(self) -> Gitd:
+        return self
+
+    def __exit__(self, *exception: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self.connection.close()
+
+    def info(self) -> Info:
+        """Which gitd answers, and how it makes workspaces here and why."""
+        return Info.from_message(self.connection.call(methods.INFO, messages.InfoRequest()))
+
+    def probe(self, url: str) -> Probe:
+        """Whether a repository can be read with the credentials gitd keeps, and its branches."""
+        return Probe.from_message(self.connection.call(methods.PROBE, messages.ProbeRequest(url=url)))
+
+    def prepare(
+        self,
+        url: str,
+        path: str,
+        *,
+        branch: str | None = None,
+        commit: str | None = None,
+        submodules: bool = False,
+        full_history: bool = False,
+        strategy: Strategy | None = None,
+        on_progress: OnProgress | None = None,
+    ) -> Workspace:
+        """Makes a workspace of a repository at a path under gitd's roots, at a commit, a
+        branch, or the default branch. strategy is a preference: gitd falls back to copy when
+        it cannot make one that way here."""
+        if commit:
+            revision = messages.Revision(commit=commit)
+        elif branch:
+            revision = messages.Revision(branch=branch)
+        else:
+            revision = None
+        request = messages.PrepareRequest(
+            url=url,
+            path=path,
+            revision=revision,
+            with_submodules=submodules,
+            full_history=full_history,
+            strategy=Strategy.preference(strategy),
+        )
+        return Workspace.from_message(path, self.connection.follow(methods.PREPARE, request, on_progress))
+
+    def update(
+        self,
+        path: str,
+        *,
+        branch: str | None = None,
+        submodules: bool = False,
+        on_progress: OnProgress | None = None,
+    ) -> Workspace:
+        """Brings a workspace to the tip of its branch, or of the branch given."""
+        request = messages.UpdateRequest(path=path, branch=branch or "", with_submodules=submodules)
+        return Workspace.from_message(path, self.connection.follow(methods.UPDATE, request, on_progress))
+
+    def checkout(
+        self,
+        path: str,
+        commit: str,
+        *,
+        submodules: bool = False,
+        on_progress: OnProgress | None = None,
+    ) -> Workspace:
+        """Moves a workspace to a commit, as a rollback does."""
+        request = messages.CheckoutRequest(path=path, commit=commit, with_submodules=submodules)
+        return Workspace.from_message(path, self.connection.follow(methods.CHECKOUT, request, on_progress))
+
+    def describe(self, path: str) -> Description:
+        """What a workspace is on disk, without the network."""
+        response = self.connection.call(methods.DESCRIBE, messages.DescribeRequest(path=path))
+        return Description.from_message(response)
+
+    def publish(self, path: str, branch: str) -> Published:
+        """Pushes what was committed in a workspace to a new branch, with the token gitd keeps."""
+        response = self.connection.call(methods.PUBLISH, messages.PublishRequest(path=path, branch=branch))
+        return Published.from_message(response)
+
+    def remove(self, path: str) -> None:
+        """Deletes a workspace; its pool stays."""
+        self.connection.call(methods.REMOVE, messages.RemoveRequest(path=path))
+
+    def audit(
+        self,
+        *,
+        since: datetime | None = None,
+        url: str | None = None,
+        limit: int | None = None,
+    ) -> list[AuditEntry]:
+        """The audit log: every publish, done or refused, newest first; from since on, of
+        the repository at url, at most limit of them (100 by default, never more than 1000)."""
+        request: Any = messages.AuditRequest(url=url or "", limit=limit or 0)
+        if since is not None:
+            Timestamp.fill(request.since, since)
+        response = self.connection.call(methods.AUDIT, request)
+        return [AuditEntry.from_message(entry) for entry in response.entries]

gitd/connection.py

@@ -0,0 +1,71 @@
+"""The channel to gitd's Unix socket, and how a call on it is made and read."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from typing import Any
+
+import grpc
+from google.protobuf.message import Message
+
+from .errors import GitdError
+from .methods import Method
+from .models import Progress
+
+DEFAULT_SOCKET = "/run/gitd/gitd.sock"
+SOCKET_VARIABLE = "GITD_SOCKET"
+
+OnProgress = Callable[[Progress], None]
+
+
+class Connection:
+    """A channel to gitd. The socket defaults to $GITD_SOCKET, then /run/gitd/gitd.sock; the
+    timeout, in seconds, bounds every call, which gitd otherwise bounds itself."""
+
+    def __init__(self, socket: str | None, timeout: float | None) -> None:
+        self.socket = socket or os.environ.get(SOCKET_VARIABLE) or DEFAULT_SOCKET
+        self.timeout = timeout
+        self.channel = grpc.insecure_channel(f"unix:{self.socket}")
+
+    def close(self) -> None:
+        self.channel.close()
+
+    @staticmethod
+    def serialize(message: Message) -> bytes:
+        return message.SerializeToString()
+
+    def call(self, method: Method, request: Message) -> Any:
+        """Makes a call that answers once."""
+        invoke: grpc.UnaryUnaryMultiCallable[Message, Any] = self.channel.unary_unary(
+            method.path,
+            request_serializer=self.serialize,
+            response_deserializer=method.response.FromString,
+        )
+        try:
+            return invoke(request, timeout=self.timeout)
+        except grpc.RpcError as error:
+            raise GitdError.from_rpc_error(error) from None
+
+    def follow(
+        self,
+        method: Method,
+        request: Message,
+        on_progress: OnProgress | None,
+    ) -> Any:
+        """Makes a call that streams its progress, and reads it to its result."""
+        invoke: grpc.UnaryStreamMultiCallable[Message, Any] = self.channel.unary_stream(
+            method.path,
+            request_serializer=self.serialize,
+            response_deserializer=method.response.FromString,
+        )
+        try:
+            for response in invoke(request, timeout=self.timeout):
+                event = response.WhichOneof("event")
+                if event == "progress" and on_progress is not None:
+                    on_progress(Progress.from_message(response.progress))
+                elif event == "result":
+                    return response.result
+        except grpc.RpcError as error:
+            raise GitdError.from_rpc_error(error) from None
+        raise GitdError("", "gitd ended the call without a result")