gitd 0.7.0__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gitd
-Version: 0.7.0
+Version: 0.8.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.8.0}/pyproject.toml

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

gitd-0.8.0/src/gitd/__init__.py

@@ -0,0 +1,81 @@
+"""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 .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",
+]

gitd-0.8.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.8.0/src/gitd/client.py

@@ -0,0 +1,219 @@
+"""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 .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. 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.
+
+        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)
+        self.credentials = Credentials(self.connection)
+        self.publishing = Publishing(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,
+    ) -> 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."""
+        request: Any = messages.PublishRequest(path=path, branch=branch, requested_by=requested_by)
+        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.8.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.7.0 → gitd-0.8.0}/src/gitd/connection.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import os
-from collections.abc import Callable
+from collections.abc import Callable, Iterator
 from typing import Any
 
 import grpc
@@ -47,6 +47,18 @@ class Connection:
         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)
+        except grpc.RpcError as error:
+            raise GitdError.from_rpc_error(error) from None
+
     def follow(
         self,
         method: Method,