gitd 0.7.0__tar.gz → 0.9.0__tar.gz

{gitd-0.7.0 → gitd-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gitd
-Version: 0.7.0
+Version: 0.9.0
 Summary: Client for gitd: instant, secretless git checkouts for agent sandboxes
 Project-URL: Homepage, https://github.com/dooservice/gitd
 Project-URL: Source, https://github.com/dooservice/gitd/tree/main/sdk/python

{gitd-0.7.0 → gitd-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gitd"
-version = "0.7.0"
+version = "0.9.0"
 description = "Client for gitd: instant, secretless git checkouts for agent sandboxes"
 readme = "README.md"
 license = "Apache-2.0"

gitd-0.9.0/src/gitd/__init__.py

@@ -0,0 +1,86 @@
+"""Client for gitd: instant, secretless git checkouts for agent sandboxes."""
+
+from .changes import ChangedFile, ChangeKind, Changes, Diff
+from .client import Gitd
+from .comparison import Comparison, Conflict, Event, EventKind, Side
+from .connection import DEFAULT_SOCKET, SOCKET_VARIABLE
+from .endpoint_calls import Endpoint
+from .endpoint_tokens import IssuedToken, TokenInfo
+from .errors import GitdError
+from .kept_credentials import AppToCreate, Connected, CredentialKind, KeptCredential, SignIn
+from .models import (
+    Access,
+    AuditEntry,
+    ConfigurationChange,
+    Description,
+    Info,
+    Layers,
+    PendingSubmodule,
+    Probe,
+    Progress,
+    Published,
+    PublishedRepository,
+    Refusal,
+    Strategy,
+    Submodule,
+    Workspace,
+)
+from .publishing_settings import (
+    OpenedPullRequest,
+    Opening,
+    Preset,
+    PresetOrigin,
+    Provenance,
+    PublishSettings,
+    PullRequestOptions,
+    PullRequestSettings,
+)
+from .warm_layers import WarmLayer
+
+__all__ = [
+    "Comparison",
+    "Conflict",
+    "Event",
+    "EventKind",
+    "Side",
+    "ChangeKind",
+    "ChangedFile",
+    "Changes",
+    "Diff",
+    "AppToCreate",
+    "ConfigurationChange",
+    "Connected",
+    "CredentialKind",
+    "KeptCredential",
+    "OpenedPullRequest",
+    "Opening",
+    "Preset",
+    "PresetOrigin",
+    "Provenance",
+    "PublishSettings",
+    "PullRequestOptions",
+    "PullRequestSettings",
+    "SignIn",
+    "DEFAULT_SOCKET",
+    "SOCKET_VARIABLE",
+    "Access",
+    "AuditEntry",
+    "Description",
+    "Gitd",
+    "GitdError",
+    "Info",
+    "Layers",
+    "PendingSubmodule",
+    "Probe",
+    "Progress",
+    "Published",
+    "PublishedRepository",
+    "Refusal",
+    "Strategy",
+    "Submodule",
+    "Workspace",
+    "WarmLayer",
+    "Endpoint",
+    "IssuedToken",
+    "TokenInfo",
+]

gitd-0.9.0/src/gitd/changes.py

@@ -0,0 +1,77 @@
+"""What was changed in a workspace, and its diff, as plain dataclasses built from the
+messages gitd answers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from . import messages
+
+KIND_PREFIX = "KIND_"
+
+
+class ChangeKind(StrEnum):
+    """How a file changed: added, modified or deleted."""
+
+    ADDED = "added"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+
+    @classmethod
+    def from_message(cls, number: int) -> ChangeKind:
+        name = messages.CHANGE_KIND.name(number).removeprefix(KIND_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.MODIFIED
+
+
+@dataclass(frozen=True)
+class ChangedFile:
+    """A file changed, relative to the workspace, with its lines; a binary one counts none."""
+
+    path: str
+    kind: ChangeKind
+    added_lines: int
+    removed_lines: int
+    binary: bool
+
+    @classmethod
+    def from_message(cls, file: Any) -> ChangedFile:
+        return cls(
+            path=file.path,
+            kind=ChangeKind.from_message(file.kind),
+            added_lines=file.added_lines,
+            removed_lines=file.removed_lines,
+            binary=file.binary,
+        )
+
+
+@dataclass(frozen=True)
+class Changes:
+    """What was changed in a workspace since gitd put it on base, committed or not.
+    from_layer says it was read from the agent's own layer, with no git run in the workspace."""
+
+    base: str
+    from_layer: bool
+    files: list[ChangedFile] = field(default_factory=list)
+
+    @classmethod
+    def from_message(cls, response: Any) -> Changes:
+        return cls(
+            base=response.base,
+            from_layer=response.from_layer,
+            files=[ChangedFile.from_message(file) for file in response.files],
+        )
+
+
+@dataclass(frozen=True)
+class Diff:
+    """The unified diff of a workspace's changes; truncated says it was cut short."""
+
+    base: str
+    diff: str
+    truncated: bool
+
+    @classmethod
+    def from_message(cls, response: Any) -> Diff:
+        return cls(base=response.base, diff=response.diff, truncated=response.truncated)

gitd-0.9.0/src/gitd/client.py

@@ -0,0 +1,238 @@
+"""The gitd client."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from datetime import datetime
+from typing import Any
+
+from . import messages, methods
+from .changes import Changes, Diff
+from .comparison import Comparison, Conflict, Event, Side
+from .connection import Connection, OnProgress
+from .credentials_calls import Credentials
+from .endpoint_calls import Endpoint
+from .models import AuditEntry, Description, Info, Probe, Published, Strategy, Workspace
+from .publishing_calls import Publishing
+from .publishing_settings import Provenance, PullRequestOptions
+from .timestamps import Timestamp
+from .warm_layers import WarmLayer
+
+
+class Gitd:
+    """A gitd on its Unix socket, or at url on the network with key naming the caller's
+    tenant. No call on workspaces takes a credential: gitd reads and publishes with the ones
+    it keeps, which a platform manages through gitd.credentials, and publishing follows the
+    rules it sets through gitd.publishing. Sandboxes elsewhere get tokens of gitd's own
+    through gitd.endpoint.
+
+        with Gitd() as gitd:
+            workspace = gitd.prepare("https://github.com/acme/web", "/var/lib/gitd/workspaces/agent-1")
+
+        with Gitd(url="https://gitd.internal:9420", key=open("/run/secrets/acme").read()) as gitd:
+            ...
+    """
+
+    def __init__(
+        self,
+        socket: str | None = None,
+        *,
+        timeout: float | None = None,
+        url: str | None = None,
+        key: str | None = None,
+        ca_file: str | None = None,
+    ) -> None:
+        self.connection = Connection(socket, timeout, url=url, key=key, ca_file=ca_file)
+        self.credentials = Credentials(self.connection)
+        self.publishing = Publishing(self.connection)
+        self.endpoint = Endpoint(self.connection)
+
+    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,
+        warm: str = "",
+        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. warm names a warm layer to stand on, its
+        dependencies installed already: the workspace is then made by overlay, at the commit
+        the layer was sealed at, or not at all."""
+        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),
+            warm=warm,
+        )
+        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,
+        *,
+        requested_by: str = "",
+        pull_request: PullRequestOptions | None = None,
+        provenance: Provenance | None = None,
+        sandbox: str = "",
+    ) -> Published:
+        """Pushes what was committed in a workspace to a new branch, with the credential gitd
+        keeps, and opens its pull request when the publishing settings or pull_request say
+        so. requested_by is who asked for the work, as their account on the host. With
+        sandbox, and path empty, publishes the branch a sandbox pushed through the endpoint."""
+        request: Any = messages.PublishRequest(
+            path=path, branch=branch, requested_by=requested_by, sandbox=sandbox
+        )
+        if pull_request is not None:
+            request.pull_request.CopyFrom(pull_request.to_message())
+        if provenance is not None:
+            request.provenance.CopyFrom(provenance.to_message())
+        return Published.from_message(self.connection.call(methods.PUBLISH, request))
+
+    def changes(self, path: str, *, include_ignored: bool = False) -> Changes:
+        """What was changed in a workspace since gitd put it on its commit, committed or not."""
+        request = messages.ChangesRequest(path=path, include_ignored=include_ignored)
+        return Changes.from_message(self.connection.call(methods.CHANGES, request))
+
+    def diff(
+        self,
+        path: str,
+        files: list[str] | None = None,
+        *,
+        max_bytes: int = 0,
+        include_ignored: bool = False,
+    ) -> Diff:
+        """The unified diff of a workspace's changes, of some files or all, cut short at
+        max_bytes (512 KiB by default)."""
+        request = messages.DiffRequest(
+            path=path, files=files or [], max_bytes=max_bytes, include_ignored=include_ignored
+        )
+        return Diff.from_message(self.connection.call(methods.DIFF, request))
+
+    def compare(
+        self,
+        first: Side,
+        second: Side,
+        *,
+        url: str = "",
+        with_diff: bool = False,
+        max_bytes: int = 0,
+        include_ignored: bool = False,
+    ) -> Comparison:
+        """How two works of one repository differ, from first to second; url is the
+        repository when both are branches."""
+        request = messages.CompareRequest(
+            first=first.to_message(),
+            second=second.to_message(),
+            url=url,
+            with_diff=with_diff,
+            max_bytes=max_bytes,
+            include_ignored=include_ignored,
+        )
+        return Comparison.from_message(self.connection.call(methods.COMPARE, request))
+
+    def conflicts(self, sides: list[Side], *, url: str = "") -> list[Conflict]:
+        """Which pairs of works do not merge cleanly, and on which files; a workspace stands
+        for what it committed."""
+        request = messages.ConflictsRequest(sides=[side.to_message() for side in sides], url=url)
+        response = self.connection.call(methods.CONFLICTS, request)
+        return [Conflict.from_message(conflict) for conflict in response.conflicts]
+
+    def watch(self, paths: list[str] | None = None) -> Iterator[Event]:
+        """What happens to the workspaces at paths, or to every one, as it happens."""
+        request = messages.WatchRequest(paths=paths or [])
+        for event in self.connection.stream(methods.WATCH, request):
+            yield Event.from_message(event)
+
+    def seal(self, path: str, name: str) -> WarmLayer:
+        """Seals what was installed in an overlay workspace as the warm layer name of its
+        repository, for workspaces made later at the same commit to stand on. The layer is
+        moved, not copied: the workspace is removed."""
+        response = self.connection.call(methods.SEAL, messages.SealRequest(path=path, name=name))
+        return WarmLayer.from_message(response.warm)
+
+    def warm_layers(self, url: str) -> list[WarmLayer]:
+        """The warm layers of a repository."""
+        response = self.connection.call(methods.LIST_WARM, messages.ListWarmRequest(url=url))
+        return [WarmLayer.from_message(warm) for warm in response.warm]
+
+    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-0.9.0/src/gitd/comparison.py

@@ -0,0 +1,111 @@
+"""Two works compared, their conflicts, and what happens to workspaces, as plain
+dataclasses that write the messages gitd takes and read those it answers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from . import messages
+from .changes import ChangedFile
+from .timestamps import Timestamp
+
+KIND_PREFIX = "KIND_"
+
+
+@dataclass(frozen=True)
+class Side:
+    """One work: a workspace, by its path, or a branch gitd published or its pool holds."""
+
+    workspace: str = ""
+    branch: str = ""
+
+    @classmethod
+    def of_workspace(cls, path: str) -> Side:
+        return cls(workspace=path)
+
+    @classmethod
+    def of_branch(cls, name: str) -> Side:
+        return cls(branch=name)
+
+    @classmethod
+    def from_message(cls, side: Any) -> Side:
+        return cls(workspace=side.workspace, branch=side.branch)
+
+    def to_message(self) -> Any:
+        if self.workspace:
+            return messages.Side(workspace=self.workspace)
+        return messages.Side(branch=self.branch)
+
+
+@dataclass(frozen=True)
+class Comparison:
+    """How two works differ, from the first to the second, and the diff when asked."""
+
+    files: list[ChangedFile] = field(default_factory=list)
+    diff: str = ""
+    truncated: bool = False
+
+    @classmethod
+    def from_message(cls, response: Any) -> Comparison:
+        return cls(
+            files=[ChangedFile.from_message(file) for file in response.files],
+            diff=response.diff,
+            truncated=response.truncated,
+        )
+
+
+@dataclass(frozen=True)
+class Conflict:
+    """Two works that do not merge cleanly, and the files they conflict on."""
+
+    first: Side
+    second: Side
+    paths: list[str]
+
+    @classmethod
+    def from_message(cls, conflict: Any) -> Conflict:
+        return cls(
+            first=Side.from_message(conflict.first),
+            second=Side.from_message(conflict.second),
+            paths=list(conflict.paths),
+        )
+
+
+class EventKind(StrEnum):
+    """What happened to a workspace."""
+
+    MADE = "made"
+    CHANGED = "changed"
+    PUBLISHED = "published"
+    REFUSED = "refused"
+    REMOVED = "removed"
+
+    @classmethod
+    def from_message(cls, number: int) -> EventKind:
+        name = messages.EVENT_KIND.name(number).removeprefix(KIND_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.CHANGED
+
+
+@dataclass(frozen=True)
+class Event:
+    """What happened to a workspace, when; a publish's branch, and its pull request or why it
+    was refused."""
+
+    kind: EventKind
+    path: str
+    time: datetime
+    branch: str
+    detail: str
+
+    @classmethod
+    def from_message(cls, event: Any) -> Event:
+        return cls(
+            kind=EventKind.from_message(event.kind),
+            path=event.path,
+            time=Timestamp.to_datetime(event.time),
+            branch=event.branch,
+            detail=event.detail,
+        )

gitd-0.9.0/src/gitd/connection.py

@@ -0,0 +1,128 @@
+"""The channel to gitd — its Unix socket, or its address on the network — and how a call on
+it is made and read."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Iterator
+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"
+URL_VARIABLE = "GITD_URL"
+KEY_VARIABLE = "GITD_KEY"
+KEY_FILE_VARIABLE = "GITD_KEY_FILE"
+CA_FILE_VARIABLE = "GITD_CA_FILE"
+
+OnProgress = Callable[[Progress], None]
+
+
+class Connection:
+    """A channel to gitd: at url on the network (default $GITD_URL: https://host:port, or
+    http:// on a private network), else on its socket (default $GITD_SOCKET, then
+    /run/gitd/gitd.sock). key names the caller's tenant (default the file $GITD_KEY_FILE names,
+    then $GITD_KEY); ca_file is the authority of a certificate the system does not trust
+    (default $GITD_CA_FILE). The timeout, in seconds, bounds every call, which gitd otherwise
+    bounds itself."""
+
+    def __init__(
+        self,
+        socket: str | None,
+        timeout: float | None,
+        url: str | None = None,
+        key: str | None = None,
+        ca_file: str | None = None,
+    ) -> None:
+        self.socket = socket or os.environ.get(SOCKET_VARIABLE) or DEFAULT_SOCKET
+        self.timeout = timeout
+        key = key or self.key_from_environment()
+        self.metadata = (("authorization", f"Bearer {key}"),) if key else ()
+        url = url or os.environ.get(URL_VARIABLE)
+        if not url:
+            self.channel = grpc.insecure_channel(f"unix:{self.socket}")
+            return
+        secure, target = self.target_of(url)
+        if not secure:
+            self.channel = grpc.insecure_channel(target)
+            return
+        ca_file = ca_file or os.environ.get(CA_FILE_VARIABLE)
+        roots = open(ca_file, "rb").read() if ca_file else None  # noqa: SIM115
+        self.channel = grpc.secure_channel(target, grpc.ssl_channel_credentials(root_certificates=roots))
+
+    @staticmethod
+    def key_from_environment() -> str:
+        key_file = os.environ.get(KEY_FILE_VARIABLE)
+        if key_file:
+            with open(key_file) as opened:
+                return opened.read().strip()
+        return os.environ.get(KEY_VARIABLE, "").strip()
+
+    @staticmethod
+    def target_of(url: str) -> tuple[bool, str]:
+        """Whether url is served over TLS, and the host:port gRPC dials."""
+        for scheme, secure, port in (("https://", True, 443), ("http://", False, 80)):
+            if url.startswith(scheme):
+                host = url[len(scheme) :].rstrip("/")
+                return secure, host if ":" in host else f"{host}:{port}"
+        raise GitdError("BAD_ADDRESS", f"{url!r} is not the address of a gitd: https://host:port")
+
+    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, metadata=self.metadata)
+        except grpc.RpcError as error:
+            raise GitdError.from_rpc_error(error) from None
+
+    def stream(self, method: Method, request: Message) -> Iterator[Any]:
+        """Makes a call that streams messages until gitd or the caller ends it."""
+        invoke: grpc.UnaryStreamMultiCallable[Message, Any] = self.channel.unary_stream(
+            method.path,
+            request_serializer=self.serialize,
+            response_deserializer=method.response.FromString,
+        )
+        try:
+            yield from invoke(request, timeout=self.timeout, metadata=self.metadata)
+        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, metadata=self.metadata):
+                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")