saltext.github 1.1.0__py3-none-any.whl

saltext/github/utils/__init__.py

@@ -0,0 +1,72 @@
+import typing
+from collections.abc import Mapping
+from types import EllipsisType
+
+from salt.exceptions import CommandExecutionError
+
+K = typing.TypeVar("K")
+V = typing.TypeVar("V")
+
+
+@typing.overload
+def filter_unset(
+    data: Mapping[K, V | None],
+    unset: None = None,
+) -> dict[K, V]: ...
+@typing.overload
+def filter_unset(
+    data: Mapping[K, V | EllipsisType],
+    unset: EllipsisType,
+) -> dict[K, V]: ...
+@typing.overload
+def filter_unset(
+    data: Mapping[K, V],
+    unset: object,
+) -> dict[K, V]: ...
+def filter_unset(
+    data: Mapping[K, V],
+    unset: object = None,
+) -> dict[K, object]:
+    """
+    Remove all unset values in a dictionary and return the filtered result.
+
+    data
+        Dictionary to filter.
+
+    unset
+        Identity of what counts as unset; evaluated via ``is not``.
+        Defaults to ``None``. Other working examples: ``...`` (ellipsis),
+        a specific object such as ``salt.defaults.NOT_SET`` or
+        a string literal (not recommended though).
+    """
+    return {k: v for k, v in data.items() if v is not unset}
+
+
+def filter_fields(data, fields):
+    """
+    Reduce the entities in a collection to a subset of their fields.
+
+    data
+        List of mappings or mapping of key to mapping.
+
+    fields
+        Single field name or list of field names. A list reduces each
+        entity to a mapping of the listed fields, a single name to the
+        field's value. ``None`` (the default) returns ``data`` unchanged.
+    """
+    if fields is None:
+        return data
+
+    def _reduce(entity):
+        try:
+            if isinstance(fields, str):
+                return entity[fields]
+            return {field: entity[field] for field in fields}
+        except KeyError as err:
+            raise CommandExecutionError(
+                f"Unknown field {err}. Available fields: {', '.join(entity)}"
+            ) from None
+
+    if isinstance(data, Mapping):
+        return {key: _reduce(val) for key, val in data.items()}
+    return [_reduce(entity) for entity in data]

saltext/github/utils/gh/__init__.py

@@ -0,0 +1,14 @@
+"""
+Connection library for GitHub.
+
+The submodules of this package provide reusable primitives for talking
+to the GitHub API on behalf of an organization, built around
+:class:`~saltext.github.utils.gh.client.GitHubConnection`.
+They raise :class:`~saltext.github.utils.gh.exceptions.GitHubApiError`
+(or its more specific subclass
+:class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`)
+on API errors.
+"""
+
+from saltext.github.utils.gh.exceptions import GitHubApiError  # noqa: F401
+from saltext.github.utils.gh.exceptions import GitHubNotFoundError  # noqa: F401

saltext/github/utils/gh/actions.py

@@ -0,0 +1,195 @@
+"""
+Operations on GitHub Actions repository secrets and settings.
+"""
+
+import base64
+import logging
+
+from nacl import encoding
+from nacl import public
+
+from saltext.github.utils import filter_unset
+
+log = logging.getLogger(__name__)
+
+
+def list_secrets(conn, repo_name, *, owner=None):
+    """
+    Return all Actions secrets of a repository. Secret values are write-only,
+    so this only carries metadata (``name``, ``created_at``, ``updated_at``).
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    return conn.repo_query(owner, repo_name, "actions", "secrets", per_page=100)["secrets"]
+
+
+def get_secret(conn, repo_name, name, *, owner=None):
+    """
+    Return the metadata of a single Actions secret.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    name
+        Secret name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+
+    Raises :class:`~saltext.github.utils.gh.exceptions.GitHubNotFoundError`
+    if the secret does not exist.
+    """
+    return conn.repo_query(owner, repo_name, "actions", "secrets", name)
+
+
+def get_public_key(conn, repo_name, *, owner=None):
+    """
+    Return the public key used for encrypting Actions secrets of a repository,
+    a mapping with ``key_id`` and (base64-encoded) ``key``.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    return conn.repo_query(owner, repo_name, "actions", "secrets", "public-key")
+
+
+def encrypt_secret(public_key, value):
+    """
+    Encrypt a secret value for upload using a repository public key
+    (libsodium sealed box). Returns the base64-encoded ciphertext.
+
+    public_key
+        Base64-encoded public key of the repository, as returned
+        by :func:`get_public_key` in ``key``.
+
+    value
+        Secret value to encrypt.
+    """
+    sealed_box = public.SealedBox(public.PublicKey(public_key.encode(), encoding.Base64Encoder))
+    return base64.b64encode(sealed_box.encrypt(value.encode())).decode()
+
+
+def set_secret(conn, repo_name, name, value, *, owner=None):
+    """
+    Create or update an Actions secret. The value is encrypted to the
+    repository public key before leaving this host.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    name
+        Secret name.
+
+    value
+        Plaintext secret value.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    pubkey = get_public_key(conn, repo_name, owner=owner)
+    conn.repo_query(
+        owner,
+        *(repo_name, "actions", "secrets", name),
+        method="PUT",
+        data={
+            "encrypted_value": encrypt_secret(pubkey["key"], value),
+            "key_id": pubkey["key_id"],
+        },
+    )
+
+
+def delete_secret(conn, repo_name, name, *, owner=None):
+    """
+    Remove an Actions secret from a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    name
+        Secret name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    conn.repo_query(owner, repo_name, "actions", "secrets", name, method="DELETE")
+
+
+def get_workflow_permissions(conn, repo_name, *, owner=None):
+    """
+    Return the default workflow permissions granted to the ``GITHUB_TOKEN``
+    in a repository, a mapping with ``default_workflow_permissions``
+    (``read``/``write``) and ``can_approve_pull_request_reviews``.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    return conn.repo_query(owner, repo_name, "actions", "permissions", "workflow")
+
+
+def set_workflow_permissions(
+    conn,
+    repo_name,
+    *,
+    default_workflow_permissions=None,
+    can_approve_pull_request_reviews=None,
+    owner=None,
+):
+    """
+    Update the default workflow permissions granted to the ``GITHUB_TOKEN``
+    in a repository.
+
+    conn
+        :class:`~saltext.github.utils.gh.client.GitHubConnection` to use.
+
+    repo_name
+        Repository name.
+
+    default_workflow_permissions
+        Default permissions for the ``GITHUB_TOKEN``, either ``read``
+        or ``write``.
+
+    can_approve_pull_request_reviews
+        Allow GitHub Actions to approve pull requests.
+
+    owner
+        Owner of the repository. Defaults to the connection's owner.
+    """
+    conn.repo_query(
+        owner,
+        *(repo_name, "actions", "permissions", "workflow"),
+        method="PUT",
+        data=filter_unset(
+            {
+                "default_workflow_permissions": default_workflow_permissions,
+                "can_approve_pull_request_reviews": can_approve_pull_request_reviews,
+            }
+        ),
+    )

saltext/github/utils/gh/cache.py

@@ -0,0 +1,126 @@
+"""
+Optional persistent cross-process cache for slow-changing GitHub API
+data, backed by the minion's :py:mod:`salt.cache` (``cachedir``).
+
+Attached to every profile-resolved
+:class:`~saltext.github.utils.gh.client.GitHubConnection` as its
+``store`` unless the profile opts out via :ghconf:`cache`. Particularly
+useful for ``salt-call --local`` setups, where every invocation starts
+a fresh process and the in-memory caches never survive.
+
+Two kinds of data are stored, namespaced by a token/API URL-derived
+identity so rotated credentials or different endpoints never share
+entries:
+
+* Repository file contents (fetched for
+  :ghconf:`resource:grains_files`), validated against the repository's
+  ``pushed_at`` timestamp – entries are served until the repository
+  receives a new push. Negative lookups (missing files) are cached the
+  same way.
+* Metadata that is stable for a given token/owner: account types
+  (organization vs user) and the token's user login. These are stored
+  indefinitely.
+
+All storage errors degrade gracefully to cache misses.
+"""
+
+import logging
+
+log = logging.getLogger(__name__)
+
+CACHE_ROOT = "saltext_github"
+#: Sentinel for missing cache entries (``None`` is a valid cached value).
+MISS = object()
+
+
+class PersistentCache:
+    """
+    ``salt.cache``-backed store, see the module docstring.
+
+    opts
+        The minion configuration (``__opts__``), selecting the cache
+        backend and ``cachedir``.
+
+    ident
+        Identity string namespacing all entries, derived from the
+        connection's token and API URL
+        (:attr:`~saltext.github.utils.gh.client.GitHubConnection.ident`).
+    """
+
+    def __init__(self, opts, ident):
+        # Local import: salt.cache pulls in the loader machinery, which
+        # not all importers of this package need.
+        import salt.cache  # pylint: disable=import-outside-toplevel
+
+        self._cache = salt.cache.factory(opts)
+        self._base = f"{CACHE_ROOT}/{ident}"
+
+    def _fetch(self, bank, key):
+        try:
+            return self._cache.fetch(f"{self._base}/{bank}", key)
+        except Exception as err:  # pylint: disable=broad-except
+            log.warning("Failed reading from the persistent GitHub cache: %s", err)
+            return None
+
+    def _store(self, bank, key, value):
+        try:
+            self._cache.store(f"{self._base}/{bank}", key, value)
+        except Exception as err:  # pylint: disable=broad-except
+            log.warning("Failed writing to the persistent GitHub cache: %s", err)
+
+    def get_meta(self, key):
+        """
+        Return a stored metadata value, or :data:`MISS`.
+        """
+        data = self._fetch("meta", key)
+        if isinstance(data, dict) and "value" in data:
+            return data["value"]
+        return MISS
+
+    def set_meta(self, key, value):
+        """
+        Store a metadata value.
+        """
+        self._store("meta", key, {"value": value})
+
+    def get_file(self, owner, repo, path, pushed_at):
+        """
+        Return a repository file's stored content (which is ``None`` for
+        cached negative lookups), or :data:`MISS` when there is no entry
+        or the stored entry does not match ``pushed_at``.
+        """
+        if not pushed_at:
+            return MISS
+        entry = self._fetch(f"files/{owner.lower()}", repo.lower())
+        if (
+            isinstance(entry, dict)
+            and entry.get("pushed_at") == pushed_at
+            and path in entry.get("files", {})
+        ):
+            return entry["files"][path]
+        return MISS
+
+    def set_file(self, owner, repo, path, content, pushed_at):
+        """
+        Store a repository file's content (``None`` for a negative
+        lookup) under the repository's current ``pushed_at``. Entries
+        stored for a different ``pushed_at`` are discarded.
+        """
+        if not pushed_at:
+            return
+        bank = f"files/{owner.lower()}"
+        key = repo.lower()
+        entry = self._fetch(bank, key)
+        if not isinstance(entry, dict) or entry.get("pushed_at") != pushed_at:
+            entry = {"pushed_at": pushed_at, "files": {}}
+        entry["files"][path] = content
+        self._store(bank, key, entry)
+
+    def flush_repo(self, owner, repo):
+        """
+        Drop all stored file contents of one repository.
+        """
+        try:
+            self._cache.flush(f"{self._base}/files/{owner.lower()}", repo.lower())
+        except Exception as err:  # pylint: disable=broad-except
+            log.warning("Failed flushing the persistent GitHub cache: %s", err)