gitd 0.8.0__tar.gz → 0.9.0__tar.gz

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gitd"
-version = "0.8.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.8.0 → gitd-0.9.0}/src/gitd/__init__.py

@@ -4,6 +4,8 @@ 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 (
@@ -78,4 +80,7 @@ __all__ = [
     "Submodule",
     "Workspace",
     "WarmLayer",
+    "Endpoint",
+    "IssuedToken",
+    "TokenInfo",
 ]

{gitd-0.8.0 → gitd-0.9.0}/src/gitd/client.py

@@ -11,6 +11,7 @@ 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
@@ -19,18 +20,32 @@ 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.
+    """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) -> None:
-        self.connection = Connection(socket, timeout)
+    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
@@ -121,11 +136,15 @@ class Gitd:
         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."""
-        request: Any = messages.PublishRequest(path=path, branch=branch, requested_by=requested_by)
+        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:

{gitd-0.8.0 → gitd-0.9.0}/src/gitd/connection.py

@@ -1,4 +1,5 @@
-"""The channel to gitd's Unix socket, and how a call on it is made and read."""
+"""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
 
@@ -15,18 +16,62 @@ 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. The socket defaults to $GITD_SOCKET, then /run/gitd/gitd.sock; the
-    timeout, in seconds, bounds every call, which gitd otherwise bounds itself."""
+    """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) -> None:
+    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
-        self.channel = grpc.insecure_channel(f"unix:{self.socket}")
+        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()
@@ -43,7 +88,7 @@ class Connection:
             response_deserializer=method.response.FromString,
         )
         try:
-            return invoke(request, timeout=self.timeout)
+            return invoke(request, timeout=self.timeout, metadata=self.metadata)
         except grpc.RpcError as error:
             raise GitdError.from_rpc_error(error) from None
 
@@ -55,7 +100,7 @@ class Connection:
             response_deserializer=method.response.FromString,
         )
         try:
-            yield from invoke(request, timeout=self.timeout)
+            yield from invoke(request, timeout=self.timeout, metadata=self.metadata)
         except grpc.RpcError as error:
             raise GitdError.from_rpc_error(error) from None
 
@@ -72,7 +117,7 @@ class Connection:
             response_deserializer=method.response.FromString,
         )
         try:
-            for response in invoke(request, timeout=self.timeout):
+            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))

{gitd-0.8.0 → gitd-0.9.0}/src/gitd/contract.json

@@ -283,6 +283,10 @@
                 {
                   "name": "REASON_UNSUPPORTED",
                   "number": 14
+                },
+                {
+                  "name": "REASON_LIMIT_REACHED",
+                  "number": 15
                 }
               ]
             }
@@ -349,6 +353,13 @@
               "label": "LABEL_OPTIONAL",
               "type": "TYPE_STRING",
               "jsonName": "warm"
+            },
+            {
+              "name": "pool_inside",
+              "number": 9,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_BOOL",
+              "jsonName": "poolInside"
             }
           ]
         },
@@ -460,6 +471,13 @@
               "label": "LABEL_REPEATED",
               "type": "TYPE_STRING",
               "jsonName": "lfsPatterns"
+            },
+            {
+              "name": "pool_objects",
+              "number": 7,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "poolObjects"
             }
           ]
         },
@@ -964,6 +982,13 @@
               "type": "TYPE_MESSAGE",
               "typeName": ".gitd.v1.Provenance",
               "jsonName": "provenance"
+            },
+            {
+              "name": "sandbox",
+              "number": 7,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "sandbox"
             }
           ]
         },
@@ -1900,6 +1925,13 @@
               "type": "TYPE_MESSAGE",
               "typeName": ".gitd.v1.Provenance",
               "jsonName": "provenance"
+            },
+            {
+              "name": "sandbox",
+              "number": 13,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "sandbox"
             }
           ]
         },
@@ -1960,6 +1992,14 @@
                 {
                   "name": "ACTION_PRESET_REMOVED",
                   "number": 6
+                },
+                {
+                  "name": "ACTION_TOKEN_ISSUED",
+                  "number": 7
+                },
+                {
+                  "name": "ACTION_TOKEN_REVOKED",
+                  "number": 8
                 }
               ]
             }
@@ -2667,6 +2707,160 @@
         },
         {
           "name": "RemovePresetResponse"
+        },
+        {
+          "name": "IssueTokenRequest",
+          "field": [
+            {
+              "name": "url",
+              "number": 1,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "url"
+            },
+            {
+              "name": "branch",
+              "number": 2,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "branch"
+            },
+            {
+              "name": "lifetime_seconds",
+              "number": 3,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_INT64",
+              "jsonName": "lifetimeSeconds"
+            },
+            {
+              "name": "read_only",
+              "number": 4,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_BOOL",
+              "jsonName": "readOnly"
+            },
+            {
+              "name": "sandbox",
+              "number": 5,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "sandbox"
+            }
+          ]
+        },
+        {
+          "name": "IssueTokenResponse",
+          "field": [
+            {
+              "name": "token",
+              "number": 1,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "token"
+            },
+            {
+              "name": "info",
+              "number": 2,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_MESSAGE",
+              "typeName": ".gitd.v1.TokenInfo",
+              "jsonName": "info"
+            },
+            {
+              "name": "clone_url",
+              "number": 3,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "cloneUrl"
+            }
+          ]
+        },
+        {
+          "name": "TokenInfo",
+          "field": [
+            {
+              "name": "id",
+              "number": 1,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "id"
+            },
+            {
+              "name": "url",
+              "number": 2,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "url"
+            },
+            {
+              "name": "sandbox",
+              "number": 3,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "sandbox"
+            },
+            {
+              "name": "writable",
+              "number": 4,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_BOOL",
+              "jsonName": "writable"
+            },
+            {
+              "name": "issued_at",
+              "number": 5,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_MESSAGE",
+              "typeName": ".google.protobuf.Timestamp",
+              "jsonName": "issuedAt"
+            },
+            {
+              "name": "expires_at",
+              "number": 6,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_MESSAGE",
+              "typeName": ".google.protobuf.Timestamp",
+              "jsonName": "expiresAt"
+            }
+          ]
+        },
+        {
+          "name": "RevokeTokenRequest",
+          "field": [
+            {
+              "name": "id",
+              "number": 1,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_STRING",
+              "jsonName": "id"
+            },
+            {
+              "name": "remove_sandbox",
+              "number": 2,
+              "label": "LABEL_OPTIONAL",
+              "type": "TYPE_BOOL",
+              "jsonName": "removeSandbox"
+            }
+          ]
+        },
+        {
+          "name": "RevokeTokenResponse"
+        },
+        {
+          "name": "ListTokensRequest"
+        },
+        {
+          "name": "ListTokensResponse",
+          "field": [
+            {
+              "name": "tokens",
+              "number": 1,
+              "label": "LABEL_REPEATED",
+              "type": "TYPE_MESSAGE",
+              "typeName": ".gitd.v1.TokenInfo",
+              "jsonName": "tokens"
+            }
+          ]
         }
       ],
       "enumType": [
@@ -2888,6 +3082,26 @@
               "outputType": ".gitd.v1.RemovePresetResponse"
             }
           ]
+        },
+        {
+          "name": "EndpointService",
+          "method": [
+            {
+              "name": "IssueToken",
+              "inputType": ".gitd.v1.IssueTokenRequest",
+              "outputType": ".gitd.v1.IssueTokenResponse"
+            },
+            {
+              "name": "RevokeToken",
+              "inputType": ".gitd.v1.RevokeTokenRequest",
+              "outputType": ".gitd.v1.RevokeTokenResponse"
+            },
+            {
+              "name": "ListTokens",
+              "inputType": ".gitd.v1.ListTokensRequest",
+              "outputType": ".gitd.v1.ListTokensResponse"
+            }
+          ]
         }
       ],
       "options": {

gitd-0.9.0/src/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-0.9.0/src/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-0.8.0 → gitd-0.9.0}/src/gitd/messages.py

@@ -41,6 +41,12 @@ 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")

{gitd-0.8.0 → gitd-0.9.0}/src/gitd/methods.py

@@ -37,6 +37,9 @@ 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)