gitd 0.7.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/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/messages.py

@@ -0,0 +1,30 @@
+"""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")
+
+STRATEGY = contract.enumeration("Strategy")
+ACCESS = contract.enumeration("ProbeResponse.Access")
+REASON = contract.enumeration("GitFailure.Reason")

gitd/methods.py

@@ -0,0 +1,32 @@
+"""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)

gitd/models.py

@@ -0,0 +1,285 @@
+"""What gitd answers, as plain dataclasses, each built from the message gitd sends. The
+messages are made from the contract at run time, so their fields are typed here as Any."""
+
+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 .timestamps import Timestamp
+
+STRATEGY_PREFIX = "STRATEGY_"
+ACCESS_PREFIX = "ACCESS_"
+REASON_PREFIX = "REASON_"
+
+
+class Strategy(StrEnum):
+    """How a workspace is made: a layer on a shared template, a block clone, or every file written."""
+
+    OVERLAY = "overlay"
+    REFLINK = "reflink"
+    COPY = "copy"
+
+    @classmethod
+    def from_message(cls, number: int) -> Strategy:
+        name = messages.STRATEGY.name(number).removeprefix(STRATEGY_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.COPY
+
+    @classmethod
+    def preference(cls, strategy: Strategy | None) -> int:
+        """The number a request carries: the strategy asked for, or none, for gitd to choose."""
+        name = strategy.value.upper() if strategy else "UNSPECIFIED"
+        return messages.STRATEGY.number(STRATEGY_PREFIX + name)
+
+
+class Access(StrEnum):
+    """Whether a repository can be read: by anyone, with a credential gitd keeps, or not at all."""
+
+    PUBLIC = "public"
+    REACHABLE = "reachable"
+    DENIED = "denied"
+
+    @classmethod
+    def from_message(cls, number: int) -> Access:
+        name = messages.ACCESS.name(number).removeprefix(ACCESS_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.DENIED
+
+
+@dataclass(frozen=True)
+class Progress:
+    """How far a fetch or checkout has gone; repository is the submodule's URL, empty for the
+    workspace's own repository."""
+
+    phase: str
+    percent: int
+    repository: str
+
+    @classmethod
+    def from_message(cls, progress: Any) -> Progress:
+        return cls(phase=progress.phase, percent=progress.percent, repository=progress.repository)
+
+
+@dataclass(frozen=True)
+class Layers:
+    """An overlay workspace's template (lower) and its own layer (upper, work)."""
+
+    lower: str
+    upper: str
+    work: str
+
+    @classmethod
+    def from_message(cls, layers: Any) -> Layers:
+        return cls(lower=layers.lower, upper=layers.upper, work=layers.work)
+
+
+@dataclass(frozen=True)
+class PendingSubmodule:
+    """A submodule that could not be checked out, and what git said."""
+
+    path: str
+    url: str
+    reason: str
+
+    @classmethod
+    def from_message(cls, submodule: Any) -> PendingSubmodule:
+        return cls(path=submodule.path, url=submodule.url, reason=submodule.failure.git_said)
+
+
+@dataclass(frozen=True)
+class Workspace:
+    """Where a workspace ended up. branch is empty when it is detached at a commit;
+    lfs_patterns are the files the repository keeps in git LFS, which are pointers here, as
+    gitd does not download them."""
+
+    path: str
+    commit: str
+    branch: str
+    strategy: Strategy
+    layers: Layers | None = None
+    pending_submodules: list[PendingSubmodule] = field(default_factory=list)
+    lfs_patterns: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_message(cls, path: str, result: Any) -> Workspace:
+        return cls(
+            path=path,
+            commit=result.commit,
+            branch=result.branch,
+            strategy=Strategy.from_message(result.strategy),
+            layers=Layers.from_message(result.layers) if result.HasField("layers") else None,
+            pending_submodules=[
+                PendingSubmodule.from_message(pending) for pending in result.pending_submodules
+            ],
+            lfs_patterns=list(result.lfs_patterns),
+        )
+
+
+@dataclass(frozen=True)
+class Submodule:
+    path: str
+    url: str
+    commit: str
+    checked_out: bool
+
+    @classmethod
+    def from_message(cls, submodule: Any) -> Submodule:
+        return cls(
+            path=submodule.path,
+            url=submodule.url,
+            commit=submodule.commit,
+            checked_out=submodule.checked_out,
+        )
+
+
+@dataclass(frozen=True)
+class Description:
+    """What a workspace is on disk. modified says whether it has uncommitted changes;
+    lfs_patterns are the files kept in git LFS, which are pointers here."""
+
+    url: str
+    commit: str
+    branch: str
+    modified: bool
+    strategy: Strategy
+    submodules: list[Submodule] = field(default_factory=list)
+    lfs_patterns: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_message(cls, response: Any) -> Description:
+        return cls(
+            url=response.url,
+            commit=response.commit,
+            branch=response.branch,
+            modified=response.modified,
+            strategy=Strategy.from_message(response.strategy),
+            submodules=[Submodule.from_message(submodule) for submodule in response.submodules],
+            lfs_patterns=list(response.lfs_patterns),
+        )
+
+
+@dataclass(frozen=True)
+class PublishedRepository:
+    """A repository a publish pushed. path is the submodule's, empty for the workspace's own
+    repository; subjects are the new commits' subjects, newest first."""
+
+    url: str
+    path: str
+    commit: str
+    subjects: list[str]
+
+    @classmethod
+    def from_message(cls, repository: Any) -> PublishedRepository:
+        return cls(
+            url=repository.url,
+            path=repository.path,
+            commit=repository.commit,
+            subjects=list(repository.subjects),
+        )
+
+
+@dataclass(frozen=True)
+class Refusal:
+    """Why gitd refused a call: its reason (BRANCH_REFUSED, AUTH_REQUIRED, …) and what git said."""
+
+    reason: str
+    said: str
+
+    @classmethod
+    def from_message(cls, failure: Any) -> Refusal:
+        return cls(reason=cls.reason_of(failure), said=failure.git_said)
+
+    @staticmethod
+    def reason_of(failure: Any) -> str:
+        return messages.REASON.name(failure.reason).removeprefix(REASON_PREFIX)
+
+
+@dataclass(frozen=True)
+class Published:
+    """What a publish pushed: the workspace's repository first, then each submodule."""
+
+    branch: str
+    repositories: list[PublishedRepository]
+
+    @classmethod
+    def from_message(cls, response: Any) -> Published:
+        pushed = [response.repository, *response.submodules] if response.HasField("repository") else []
+        return cls(
+            branch=response.branch,
+            repositories=[PublishedRepository.from_message(repository) for repository in pushed],
+        )
+
+
+@dataclass(frozen=True)
+class Info:
+    """Which gitd answers, and how it makes workspaces on its machine and why."""
+
+    version: str
+    git_version: str
+    pools: int
+    pools_bytes: int
+    templates: int
+    templates_bytes: int
+    strategy: Strategy
+    strategy_reason: str
+
+    @classmethod
+    def from_message(cls, response: Any) -> Info:
+        return cls(
+            version=response.version,
+            git_version=response.git_version,
+            pools=response.pools,
+            pools_bytes=response.pools_bytes,
+            templates=response.templates,
+            templates_bytes=response.templates_bytes,
+            strategy=Strategy.from_message(response.strategy),
+            strategy_reason=response.strategy_reason,
+        )
+
+
+@dataclass(frozen=True)
+class Probe:
+    """Whether a repository can be read, its default branch, and each branch's commit.
+    denied says why it cannot be read, when it cannot."""
+
+    access: Access
+    default_branch: str
+    branches: dict[str, str]
+    denied: str | None = None
+
+    @classmethod
+    def from_message(cls, response: Any) -> Probe:
+        return cls(
+            access=Access.from_message(response.access),
+            default_branch=response.default_branch,
+            branches=dict(response.commits),
+            denied=response.failure.git_said if response.HasField("failure") else None,
+        )
+
+
+@dataclass(frozen=True)
+class AuditEntry:
+    """One publish, done or refused, as the audit log keeps it. url is the workspace's
+    repository, empty when the workspace could not be opened; repositories is what was
+    pushed, the workspace's repository first, empty when refused."""
+
+    time: datetime
+    workspace: str
+    url: str
+    branch: str
+    repositories: list[PublishedRepository] = field(default_factory=list)
+    refused: Refusal | None = None
+
+    @classmethod
+    def from_message(cls, entry: Any) -> AuditEntry:
+        pushed = [entry.repository, *entry.submodules] if entry.HasField("repository") else []
+        return cls(
+            time=Timestamp.to_datetime(entry.time),
+            workspace=entry.workspace,
+            url=entry.url,
+            branch=entry.branch,
+            repositories=[PublishedRepository.from_message(repository) for repository in pushed],
+            refused=Refusal.from_message(entry.refusal) if entry.HasField("refusal") else None,
+        )

gitd/timestamps.py

@@ -0,0 +1,22 @@
+"""Between the contract's google.protobuf.Timestamp and Python's datetime."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+NANOSECONDS_PER_SECOND = 1_000_000_000
+
+
+class Timestamp:
+    """A Timestamp message read as a datetime, or written from one, always in UTC."""
+
+    @staticmethod
+    def to_datetime(message: Any) -> datetime:
+        return datetime.fromtimestamp(message.seconds + message.nanos / NANOSECONDS_PER_SECOND, tz=UTC)
+
+    @staticmethod
+    def fill(message: Any, moment: datetime) -> None:
+        seconds = moment.timestamp()
+        message.seconds = int(seconds // 1)
+        message.nanos = int(round((seconds % 1) * NANOSECONDS_PER_SECOND))

gitd-0.7.0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: gitd
+Version: 0.7.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
+License-Expression: Apache-2.0
+Keywords: ai-agents,git,grpc,sandbox,workspace
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: grpcio-status>=1.84.0
+Requires-Dist: grpcio>=1.84.0
+Requires-Dist: protobuf>=7.36.2
+Description-Content-Type: text/markdown
+
+# gitd for Python
+
+A client for [gitd](https://github.com/dooservice/gitd): instant, secretless git checkouts
+for agent sandboxes. Your agents work in their own copy and publish a branch; they never
+see your token.
+
+```sh
+pip install gitd
+```
+
+```python
+from gitd import Gitd, GitdError
+
+with Gitd() as gitd:                      # $GITD_SOCKET, then /run/gitd/gitd.sock
+    workspace = gitd.prepare("https://github.com/acme/web", "/var/lib/gitd/workspaces/agent-1")
+    print(workspace.path, workspace.commit, workspace.strategy)
+
+    # … the agent works in workspace.path with plain git, and commits …
+
+    published = gitd.publish(workspace.path, "agents/fix-login")
+    gitd.remove(workspace.path)
+```
+
+No call takes a credential: gitd reads and publishes with the ones it keeps.
+
+| Method | What it does |
+|---|---|
+| `prepare(url, path, *, branch, commit, submodules, full_history, strategy, on_progress)` | A workspace of a repository at a path under gitd's roots |
+| `update(path, *, branch, submodules, on_progress)` | To the tip of its branch, or of the branch given |
+| `checkout(path, commit, *, submodules, on_progress)` | To a commit, as a rollback does |
+| `describe(path)` | Its repository, commit, branch, uncommitted changes and submodules |
+| `publish(path, branch)` | Its commits pushed to a new branch |
+| `remove(path)` | Deleted; its pool stays |
+| `probe(url)` | Whether it can be read, its default branch and branches |
+| `info()` | Which gitd answers, and how it makes workspaces here and why |
+| `audit(*, since, url, limit)` | Every publish, done or refused, newest first |
+
+A refusal raises `GitdError`, with `reason` (`AUTH_REQUIRED`, `NOT_FOUND`, `PATH_REFUSED`,
+`BRANCH_REFUSED`, `BUSY`, …) and `said`, what git said. Decide from the reason, never from
+the message.
+
+[`examples/agent.py`](examples/agent.py) is an agent's whole round trip.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `src/gitd/client.py` | `Gitd`, the client |
+| `src/gitd/models.py` | What gitd answers, as dataclasses |
+| `src/gitd/errors.py` | `GitdError` |
+| `src/gitd/timestamps.py` | Between the contract's timestamps and `datetime` |
+| `src/gitd/connection.py` | The channel to the socket, and how calls are made |
+| `src/gitd/methods.py` | The gitd methods called, by their gRPC path |
+| `src/gitd/messages.py` | The messages of the contract the client uses |
+| `src/gitd/contract.py` | Reads the contract at run time, with protobuf's public API |
+| `src/gitd/contract.json` | The contract, built from [`proto/gitd/v1/gitd.proto`](../../proto/gitd/v1/gitd.proto) by `make generate` |
+
+No code is generated: the client reads gitd's contract when it starts.
+
+Python 3.11 or later, on Linux. Apache-2.0.

gitd-0.7.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+gitd/__init__.py,sha256=ryECu7i_jkjA4sn0A3mqEKVNN-iLlSSafMJ_Ei153WE,753
+gitd/client.py,sha256=J0eLNka23N4F1kd_zbV5FmyEZUPr9GXWHOMyp5w3mcY,4831
+gitd/connection.py,sha256=gAQl4Ov3CIIHdmmrZ0vXAOCH6S0VjXOjPFT-TNDgJLY,2548
+gitd/contract.json,sha256=_mw_aEfMoU77syjO0EPDEYpdHF1pxiIu4dpdvIi9IZs,35828
+gitd/contract.py,sha256=_hvrks2Lu4Ugcp53aYSxiO83n8EsaoA2BTqmF7r5lPc,1826
+gitd/errors.py,sha256=QU8NWOyfh5Z6I4irwUds6c6DsouRWDyB_sERdOvGK0M,1326
+gitd/messages.py,sha256=oqI_PyUJ6YqBN3FcbB6u9Rcb5gLrW-wnwodCj0KpUi0,1299
+gitd/methods.py,sha256=_coa3-ZugO2ejmHuEH9VlbMSbhY5ad1b_vln_NySNbA,1105
+gitd/models.py,sha256=Xs-wN0tOf5DSHPdpAjfqH98rLFvNr2Kilra1IvjL5rk,8918
+gitd/timestamps.py,sha256=mroL2g5H6WN5gWxSCrtGG-xo5sznqsFrB5-LUYZ2xIY,717
+gitd-0.7.0.dist-info/METADATA,sha256=UMQ1AhNTl2R18LKFZmVe0lVrwTN-WNEd9NWpaVyQu2E,3384
+gitd-0.7.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+gitd-0.7.0.dist-info/RECORD,,

gitd-0.7.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any