rubin-gafaelfawr 15.1.0__py3-none-any.whl

rubin/gafaelfawr/__init__.py

@@ -0,0 +1,41 @@
+"""Client for Gafaelfawr."""
+
+from ._client import GafaelfawrClient
+from ._exceptions import (
+    GafaelfawrDiscoveryError,
+    GafaelfawrError,
+    GafaelfawrNotFoundError,
+    GafaelfawrValidationError,
+    GafaelfawrWebError,
+)
+from ._mock import (
+    MockGafaelfawr,
+    MockGafaelfawrAction,
+    register_mock_gafaelfawr,
+)
+from ._models import (
+    GafaelfawrGroup,
+    GafaelfawrNotebookQuota,
+    GafaelfawrQuota,
+    GafaelfawrTapQuota,
+    GafaelfawrUserInfo,
+)
+from ._tokens import create_token
+
+__all__ = [
+    "GafaelfawrClient",
+    "GafaelfawrDiscoveryError",
+    "GafaelfawrError",
+    "GafaelfawrGroup",
+    "GafaelfawrNotFoundError",
+    "GafaelfawrNotebookQuota",
+    "GafaelfawrQuota",
+    "GafaelfawrTapQuota",
+    "GafaelfawrUserInfo",
+    "GafaelfawrValidationError",
+    "GafaelfawrWebError",
+    "MockGafaelfawr",
+    "MockGafaelfawrAction",
+    "create_token",
+    "register_mock_gafaelfawr",
+]

rubin/gafaelfawr/_client.py

@@ -0,0 +1,364 @@
+"""Client for the Gafaelfawr authorization and identity service."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timedelta
+
+import structlog
+from cachetools import TTLCache
+from httpx import AsyncClient, HTTPError, HTTPStatusError, Timeout
+from pydantic import BaseModel, ValidationError
+from rubin.repertoire import DiscoveryClient
+from structlog.stdlib import BoundLogger
+
+from ._constants import CACHE_LIFETIME, CACHE_SIZE
+from ._exceptions import (
+    GafaelfawrDiscoveryError,
+    GafaelfawrNotFoundError,
+    GafaelfawrValidationError,
+    GafaelfawrWebError,
+)
+from ._models import (
+    AdminTokenRequest,
+    GafaelfawrGroup,
+    GafaelfawrUserInfo,
+    NewToken,
+    TokenType,
+)
+
+__all__ = ["GafaelfawrClient"]
+
+
+class GafaelfawrClient:
+    """Client for the Gafaelfawr service API.
+
+    Parameters
+    ----------
+    http_client
+        Existing ``httpx.AsyncClient`` to use instead of creating a new one.
+        This allows the caller to reuse an existing client and connection
+        pool.
+    discovery_client
+        If given, Repertoire_ discovery client to use. Otherwise, a new client
+        will be created.
+    logger
+        Logger to use. If not given, the default structlog logger will be
+        used.
+    timeout
+        Timeout for Gafaelfawr operations. If not given, defaults to the
+        timeout of the underlying HTTPX_ client.
+    userinfo_cache_lifetime
+        How long to cache user information for a token.
+    userinfo_cache_size
+        How many cache entries for the cache of user information by token.
+    """
+
+    def __init__(
+        self,
+        http_client: AsyncClient | None = None,
+        *,
+        discovery_client: DiscoveryClient | None = None,
+        logger: BoundLogger | None = None,
+        timeout: timedelta | None = None,
+        userinfo_cache_lifetime: timedelta = CACHE_LIFETIME,
+        userinfo_cache_size: int = CACHE_SIZE,
+    ) -> None:
+        self._client = http_client or AsyncClient()
+        self._discovery = discovery_client or DiscoveryClient(self._client)
+        self._logger = logger or structlog.get_logger()
+        self._userinfo_cache_lifetime = userinfo_cache_lifetime
+        self._userinfo_cache_size = userinfo_cache_size
+
+        # Whether the HTTP client needs to be explicitly closed because we
+        # created it.
+        self._close_client = http_client is not None
+
+        # The default timeout is the underlying timeout of the HTTPX client.
+        if timeout is not None:
+            self._timeout: float | Timeout = timeout.total_seconds()
+        else:
+            self._timeout = self._client.timeout
+
+        # Maintain two caches of user information, one indexed by token (when
+        # requesting user information for the user corresponding to the token)
+        # and one indexed by username (when requesting user information with a
+        # privileged token). Most users of the client will only make one type
+        # of call, but hopefully the overhead is tiny.
+        self._userinfo_token_cache: TTLCache[str, GafaelfawrUserInfo]
+        self._userinfo_token_cache = TTLCache(
+            userinfo_cache_size, userinfo_cache_lifetime.total_seconds()
+        )
+        self._userinfo_token_lock = asyncio.Lock()
+        self._userinfo_username_cache: TTLCache[str, GafaelfawrUserInfo]
+        self._userinfo_username_cache = TTLCache(
+            userinfo_cache_size, userinfo_cache_lifetime.total_seconds()
+        )
+        self._userinfo_username_lock = asyncio.Lock()
+
+    async def aclose(self) -> None:
+        """Close the HTTP connection pool, if one wasn't provided.
+
+        Only closes the pool if a new one was created. Does nothing if an
+        external HTTP connection pool was passed into the constructor. The
+        object must not be used after calling this method.
+        """
+        if self._close_client:
+            await self._client.aclose()
+
+    async def clear_cache(self) -> None:
+        """Clear all internal caches."""
+        async with self._userinfo_token_lock:
+            self._userinfo_token_cache = TTLCache(
+                self._userinfo_cache_size,
+                self._userinfo_cache_lifetime.total_seconds(),
+            )
+        async with self._userinfo_username_lock:
+            self._userinfo_username_cache = TTLCache(
+                self._userinfo_cache_size,
+                self._userinfo_cache_lifetime.total_seconds(),
+            )
+
+    async def create_service_token(
+        self,
+        token: str,
+        username: str,
+        *,
+        scopes: list[str],
+        expires: datetime | None = None,
+        name: str | None = None,
+        uid: int | None = None,
+        gid: int | None = None,
+        groups: list[GafaelfawrGroup] | None = None,
+    ) -> str:
+        """Create a new service token.
+
+        Parameters
+        ----------
+        token
+            Token to use to authenticate to the Gafaelfawr API. This token
+            must have the ``admin:token`` scope.
+        username
+            Username for which to create a token. Must begin with ``bot-``.
+        scopes
+            List of scopes to grant to the new token.
+        expires
+            Expiration date of te new token, or `None` to create a token that
+            never expires.
+        name
+            Full name override. If `None`, the full name will be determined
+            from LDAP if configured, and otherwise not set.
+        uid
+            UID override. If `None`, the UID will be determined from Firestore
+            or LDAP if configured, and otherwise not set.
+        gid
+            Primary GID override. If `None`, the primary GID will be
+            determined from Firestore or LDAP if configured, and otherwise not
+            set.
+        groups
+            Group membership override. If `None`, the group membership will be
+            determined from LDAP if configured, and otherwise not set.
+
+        Returns
+        -------
+        str
+            Newly-created token.
+
+        Raises
+        ------
+        GafaelfawrValidationError
+            Raised if the response from Gafaelfawr is invalid.
+        GafaelfawrWebError
+            Raised if there is some problem talking to the Gafaelfawr API,
+            such as an invalid token or network or service failure.
+        rubin.repertoire.RepertoireError
+            Raised if there was an error talking to service discovery.
+        """
+        url = await self._url_for("tokens")
+        request = AdminTokenRequest(
+            username=username,
+            token_type=TokenType.service,
+            scopes=scopes,
+            expires=expires,
+            name=name,
+            uid=uid,
+            gid=gid,
+            groups=groups,
+        )
+        result = await self._post(url, NewToken, token, body=request)
+        return result.token
+
+    async def get_user_info(
+        self, token: str, username: str | None = None
+    ) -> GafaelfawrUserInfo:
+        """Get information about the user, with caching.
+
+        Parameters
+        ----------
+        token
+            Token to use to authenticate to the Gafaelfawr API.
+        username
+            Username for which to request user information, if given. If not
+            given, the user information for the user corresponding to the
+            authentication token will be retrieved. This parameter may only be
+            provided when authenticating with a token with ``admin:userinfo``
+            scope.
+
+        Returns
+        -------
+        GafaelfawrUserInfo
+            User information for the user.
+
+        Raises
+        ------
+        GafaelfawrNotFoundError
+            Raised if no user information for the requested user could be
+            found. This will always be the case when the ``username``
+            parameter is provided and Gafaelfawr is not configured to use LDAP
+            for user information, since in that case user information can only
+            be retrieved with a user's token.
+        GafaelfawrValidationError
+            Raised if the response from Gafaelfawr is invalid.
+        GafaelfawrWebError
+            Raised if there is some problem talking to the Gafaelfawr API,
+            such as an invalid token or network or service failure.
+        rubin.repertoire.RepertoireError
+            Raised if there was an error talking to service discovery.
+        """
+        if username is not None:
+            if userinfo := self._userinfo_username_cache.get(username):
+                return userinfo
+            async with self._userinfo_username_lock:
+                if userinfo := self._userinfo_username_cache.get(username):
+                    return userinfo
+                url = await self._url_for(f"users/{username}")
+                userinfo = await self._get(url, GafaelfawrUserInfo, token)
+                self._userinfo_username_cache[username] = userinfo
+                return userinfo
+        else:
+            if userinfo := self._userinfo_token_cache.get(token):
+                return userinfo
+            async with self._userinfo_token_lock:
+                if userinfo := self._userinfo_token_cache.get(token):
+                    return userinfo
+                url = await self._url_for("user-info")
+                userinfo = await self._get(url, GafaelfawrUserInfo, token)
+                self._userinfo_token_cache[token] = userinfo
+                return userinfo
+
+    async def _get[T: BaseModel](
+        self, url: str, model: type[T], token: str
+    ) -> T:
+        """Make an HTTP GET request and validate the results.
+
+        Parameters
+        ----------
+        url
+            URL at which to make the request.
+        model
+            Expected type of the response.
+        token
+            Gafaelfawr token used for authentication.
+
+        Returns
+        -------
+        pydantic.BaseModel
+            Validated model of the requested type.
+
+        Raises
+        ------
+        GafaelfawrNotFoundError
+            Raised if the requested URL returned a 404 response.
+        GafaelfawrValidationError
+            Raised if the response from Gafaelfawr is invalid.
+        GafaelfawrWebError
+            Raised if there is some problem talking to the Gafaelfawr API,
+            such as an invalid token or network or service failure.
+        """
+        headers = {"Authorization": f"Bearer {token}"}
+        try:
+            r = await self._client.get(
+                url, headers=headers, timeout=self._timeout
+            )
+            r.raise_for_status()
+            return model.model_validate(r.json())
+        except HTTPError as e:
+            if isinstance(e, HTTPStatusError):
+                if e.response.status_code == 404:
+                    raise GafaelfawrNotFoundError.from_exception(e) from e
+            raise GafaelfawrWebError.from_exception(e) from e
+        except ValidationError as e:
+            raise GafaelfawrValidationError.from_exception(e) from e
+
+    async def _post[T: BaseModel](
+        self, url: str, model: type[T], token: str, *, body: BaseModel
+    ) -> T:
+        """Make an HTTP GET request and validate the results.
+
+        Parameters
+        ----------
+        url
+            URL at which to make the request.
+        model
+            Expected type of the response.
+        token
+            Gafaelfawr token used for authentication.
+        body
+            Pydantic model to send as the POST body.
+
+        Returns
+        -------
+        pydantic.BaseModel
+            Validated model of the requested type.
+
+        Raises
+        ------
+        GafaelfawrValidationError
+            Raised if the response from Gafaelfawr is invalid.
+        GafaelfawrWebError
+            Raised if there is some problem talking to the Gafaelfawr API,
+            such as an invalid token or network or service failure.
+        """
+        headers = {"Authorization": f"Bearer {token}"}
+        try:
+            r = await self._client.post(
+                url,
+                headers=headers,
+                json=body.model_dump(mode="json"),
+                timeout=self._timeout,
+            )
+            r.raise_for_status()
+            return model.model_validate(r.json())
+        except HTTPError as e:
+            raise GafaelfawrWebError.from_exception(e) from e
+        except ValidationError as e:
+            raise GafaelfawrValidationError.from_exception(e) from e
+
+    async def _url_for(self, route: str) -> str:
+        """Construct the URL for a Gafaelfawr API route.
+
+        Parameters
+        ----------
+        route
+            Route relative to the Gafaelfawr API base URL. Must not start with
+            ``/``.
+
+        Returns
+        -------
+        str
+            Full URL to use.
+
+        Raises
+        ------
+        GafaelfawrDiscoveryError
+            Raised if Gafaelfawr is missing from service discovery.
+        rubin.repertoire.RepertoireError
+            Raised if there was an error talking to service discovery.
+        """
+        base_url = await self._discovery.url_for_internal(
+            "gafaelfawr", version="v1"
+        )
+        if not base_url:
+            msg = "gafaelfawr (v1) service not found in service discovery"
+            raise GafaelfawrDiscoveryError(msg)
+        return f"{base_url.rstrip('/')}/{route}"

rubin/gafaelfawr/_constants.py

@@ -0,0 +1,17 @@
+"""Constants for the Gafaelfawr client."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+__all__ = ["CACHE_LIFETIME", "CACHE_SIZE"]
+
+CACHE_LIFETIME = timedelta(minutes=5)
+"""How long to cache user information retrieved from Gafaelfawr.
+
+Gafaelfawr policy says that this should not be any longer than five minutes so
+that changes to the user's groups are picked up correctly.
+"""
+
+CACHE_SIZE = 1000
+"""Maximum number of users whose information is cached in memory."""

rubin/gafaelfawr/_exceptions.py

@@ -0,0 +1,81 @@
+"""Exceptions for the Gafaelfawr client."""
+
+from __future__ import annotations
+
+from typing import Self, override
+
+from pydantic import ValidationError
+from safir.slack.blockkit import (
+    SentryEventInfo,
+    SlackCodeBlock,
+    SlackException,
+    SlackMessage,
+    SlackWebException,
+)
+
+__all__ = [
+    "GafaelfawrDiscoveryError",
+    "GafaelfawrError",
+    "GafaelfawrNotFoundError",
+    "GafaelfawrValidationError",
+    "GafaelfawrWebError",
+]
+
+
+class GafaelfawrError(SlackException):
+    """Base class for Gafaelfawr client exceptions."""
+
+
+class GafaelfawrDiscoveryError(GafaelfawrError):
+    """Gafaelfawr was not found in service discovery."""
+
+
+class GafaelfawrValidationError(GafaelfawrError):
+    """Gafaelfawr response did not validate against the expected model."""
+
+    @classmethod
+    def from_exception(cls, exc: ValidationError) -> Self:
+        """Create an exception from a Pydantic parse failure.
+
+        Parameters
+        ----------
+        exc
+            Pydantic exception.
+
+        Returns
+        -------
+        GafaelfawrValidationError
+            Constructed exception.
+        """
+        error = f"{type(exc).__name__}: {exc!s}"
+        return cls("Unable to parse reply from Gafaelfawr", error)
+
+    def __init__(self, message: str, error: str) -> None:
+        super().__init__(message)
+        self._message = message
+        self.error = error
+
+    @override
+    def __str__(self) -> str:
+        return f"{self._message}: {self.error}"
+
+    @override
+    def to_slack(self) -> SlackMessage:
+        message = super().to_slack()
+        block = SlackCodeBlock(heading="Validation error", code=self.error)
+        message.attachments.append(block)
+        return message
+
+    @override
+    def to_sentry(self) -> SentryEventInfo:
+        info = super().to_sentry()
+        info.contexts["validation_info"] = {"error": self.error}
+        return info
+
+
+class GafaelfawrWebError(SlackWebException, GafaelfawrError):
+    """An HTTP request failed."""
+
+
+class GafaelfawrNotFoundError(GafaelfawrWebError):
+    """An HTTP request failed with a 404 response."""

rubin/gafaelfawr/_mock.py

@@ -0,0 +1,280 @@
+"""Mock for the parts of the Gafaelfawr API used by the client."""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from collections.abc import Callable, Iterable
+from datetime import UTC, datetime
+from enum import Enum
+from functools import wraps
+from typing import TYPE_CHECKING, Concatenate
+from urllib.parse import urljoin
+
+from httpx import Request, Response
+from rubin.repertoire import DiscoveryClient
+
+from ._models import AdminTokenRequest, GafaelfawrUserInfo, NewToken, TokenData
+from ._tokens import create_token
+
+if TYPE_CHECKING:
+    import respx
+
+__all__ = [
+    "MockGafaelfawr",
+    "MockGafaelfawrAction",
+    "register_mock_gafaelfawr",
+]
+
+
+class MockGafaelfawrAction(Enum):
+    """Possible actions that could fail."""
+
+    CREATE_TOKEN = "create_token"
+    USER_INFO = "user_info"
+
+
+class MockGafaelfawr:
+    """Mock for the parts of the Gafaelfawr API used by the client."""
+
+    def __init__(self) -> None:
+        self._fail: defaultdict[str, set[MockGafaelfawrAction]]
+        self._fail = defaultdict(set)
+        self._tokens: dict[str, TokenData] = {}
+        self._user_info: dict[str, GafaelfawrUserInfo | None] = {}
+
+    def create_token(
+        self,
+        username: str,
+        *,
+        expires: datetime | None = None,
+        scopes: Iterable[str] | None = None,
+    ) -> str:
+        """Create a token for the given username.
+
+        This token will only be recognized by the same instance of the
+        Gafaelfawr mock.
+
+        Parameters
+        ----------
+        username
+            Username the token is for.
+        expires
+            If provided, sets the expiration time of the token.
+        scopes
+            If provided, list of scopes to assign to the token. This is
+            primarily needed if the client will call a privileged API
+            endpoint.
+
+        Returns
+        -------
+        str
+            New Gafaelfawr token.
+        """
+        token = create_token()
+        self._tokens[token] = TokenData(
+            token=token,
+            username=username,
+            expires=expires,
+            scopes=set(scopes) if scopes else set(),
+        )
+        return token
+
+    def fail_on(
+        self,
+        username: str,
+        actions: MockGafaelfawrAction | Iterable[MockGafaelfawrAction],
+    ) -> None:
+        """Configure the API to fail on requests for the given user.
+
+        This can be used by test suites to test handling of Gafaelfawr
+        failures.
+
+        Parameters
+        ----------
+        username
+            Username for which operations should fail.
+        actions
+            An action or iterable of actions that should fail. Pass in the
+            empty list to restore regular operations for this user.
+        """
+        if isinstance(actions, MockGafaelfawrAction):
+            self._fail[username] = {actions}
+        else:
+            self._fail[username] = set(actions)
+
+    def install_routes(self, respx_mock: respx.Router, base_url: str) -> None:
+        """Install the mock routes for the Gafaelfawr API.
+
+        Parameters
+        ----------
+        respx_mock
+            Mock router to use to install routes.
+        base_url
+            Base URL for the mock routes.
+        """
+        prefix = base_url.rstrip("/") + "/"
+        handler = self._handle_user_info
+        respx_mock.get(urljoin(prefix, "user-info")).mock(side_effect=handler)
+        handler = self._handle_create_token
+        respx_mock.post(urljoin(prefix, "tokens")).mock(side_effect=handler)
+
+        # These routes require regex matching of the username.
+        base_regex = re.escape(base_url.rstrip("/"))
+        regex = re.compile(base_regex + "/users/(?P<username>[^/]+)$")
+        respx_mock.get(url__regex=regex).mock(side_effect=self._handle_user)
+
+    def set_user_info(
+        self, username: str, user_info: GafaelfawrUserInfo | None
+    ) -> None:
+        """Set the user information for a given user.
+
+        Parameters
+        ----------
+        username
+            Username for which to set a quota.
+        user_info
+            User information to return for that user, or `None` to return a
+            404 error.
+        """
+        assert user_info is None or user_info.username == username, (
+            f"User info for wrong user ({user_info.username} != {username}"
+        )
+        self._user_info[username] = user_info
+
+    @staticmethod
+    def _check[**P](
+        *,
+        fail_on: MockGafaelfawrAction | None = None,
+        required_scope: str | None = None,
+    ) -> Callable[
+        [
+            Callable[
+                Concatenate[MockGafaelfawr, Request, TokenData, P], Response
+            ]
+        ],
+        Callable[Concatenate[MockGafaelfawr, Request, P], Response],
+    ]:
+        """Wrap `MockGafaelfawr` methods to perform common checks.
+
+        There are various common checks that should be performed for every
+        request to the mock, and the token always has to be extracted from the
+        requst and injected as an additional argument to the method. This
+        wrapper performs those checks and then injects the token data into the
+        underlying handler.
+
+        Paramaters
+        ----------
+        fail_on
+            If this user is configured to fail on this action, return a
+            failure rather than calling the underlying handler.
+
+        Returns
+        -------
+        typing.Callable
+            Decorator to wrap `MockGafaelfawr` methods.
+        """
+
+        def decorator(
+            f: Callable[
+                Concatenate[MockGafaelfawr, Request, TokenData, P], Response
+            ],
+        ) -> Callable[Concatenate[MockGafaelfawr, Request, P], Response]:
+            @wraps(f)
+            def wrapper(
+                mock: MockGafaelfawr,
+                request: Request,
+                *args: P.args,
+                **kwargs: P.kwargs,
+            ) -> Response:
+                authorization = request.headers["Authorization"]
+                scheme, token = authorization.split(None, 1)
+                if scheme.lower() != "bearer":
+                    return Response(403)
+                token_data = mock._tokens.get(token)
+                if not token_data:
+                    return Response(403)
+                if fail_on and fail_on in mock._fail[token_data.username]:
+                    return Response(500)
+                if required_scope and required_scope not in token_data.scopes:
+                    return Response(403)
+                if token_data.expires:
+                    if token_data.expires <= datetime.now(tz=UTC):
+                        return Response(401)
+                return f(mock, request, token_data, *args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    @_check(
+        fail_on=MockGafaelfawrAction.CREATE_TOKEN, required_scope="admin:token"
+    )
+    def _handle_create_token(
+        self, request: Request, token_data: TokenData
+    ) -> Response:
+        body = AdminTokenRequest.model_validate_json(request.content.decode())
+        if not body.username.startswith("bot-"):
+            return Response(422)
+        token = self.create_token(
+            body.username,
+            expires=body.expires,
+            scopes=body.scopes,
+        )
+        userinfo = GafaelfawrUserInfo(
+            username=body.username,
+            name=body.name,
+            uid=body.uid,
+            gid=body.gid,
+            groups=body.groups or [],
+        )
+        self.set_user_info(body.username, userinfo)
+        response = NewToken(token=token)
+        return Response(200, json=response.model_dump(mode="json"))
+
+    @_check(required_scope="admin:userinfo")
+    def _handle_user(
+        self,
+        request: Request,
+        token_data: TokenData,
+        *,
+        username: str,
+    ) -> Response:
+        if MockGafaelfawrAction.USER_INFO in self._fail[username]:
+            return Response(500)
+        elif user_info := self._user_info.get(username):
+            result = user_info.model_dump(mode="json", exclude_defaults=True)
+            return Response(200, json=result)
+        else:
+            return Response(404)
+
+    @_check(fail_on=MockGafaelfawrAction.USER_INFO)
+    def _handle_user_info(
+        self, request: Request, token_data: TokenData
+    ) -> Response:
+        if user_info := self._user_info.get(token_data.username):
+            result = user_info.model_dump(mode="json", exclude_defaults=True)
+            return Response(200, json=result)
+        else:
+            return Response(404)
+
+
+async def register_mock_gafaelfawr(respx_mock: respx.Router) -> MockGafaelfawr:
+    """Mock out Gafaelfawr.
+
+    Parameters
+    ----------
+    respx_mock
+        Mock router.
+
+    Returns
+    -------
+    MockGafaelfawr
+        Mock Gafaelfawr API object.
+    """
+    discovery_client = DiscoveryClient()
+    url = await discovery_client.url_for_internal("gafaelfawr", version="v1")
+    assert url, "Service gafaelfawr (v1) not found in Repertoire"
+    mock = MockGafaelfawr()
+    mock.install_routes(respx_mock, url)
+    return mock

rubin/gafaelfawr/_models.py

@@ -0,0 +1,165 @@
+"""Models for the Gafaelawr API understood by the client.
+
+These models are intentionally not shared with the server implementation since
+they may have to handle multiple versions of the server. They are simplified
+compared to the server models, and only the ones starting with ``Gafaelfawr``
+are exposed to users of the module.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field
+
+__all__ = [
+    "AdminTokenRequest",
+    "GafaelfawrGroup",
+    "GafaelfawrNotebookQuota",
+    "GafaelfawrQuota",
+    "GafaelfawrTapQuota",
+    "GafaelfawrUserInfo",
+    "NewToken",
+    "TokenData",
+    "TokenType",
+]
+
+
+class GafaelfawrGroup(BaseModel):
+    """Information about a single group."""
+
+    name: Annotated[str, Field(title="Name of the group")]
+
+    id: Annotated[int, Field(title="Numeric GID of the group")]
+
+
+class GafaelfawrNotebookQuota(BaseModel):
+    """Notebook Aspect quota information for a user."""
+
+    cpu: Annotated[float, Field(title="CPU equivalents", examples=[4.0])]
+
+    memory: Annotated[float, Field(title="Maximum memory use (GiB)")]
+
+    spawn: Annotated[
+        bool,
+        Field(title="Spawning allowed"),
+    ] = True
+
+    @property
+    def memory_bytes(self) -> int:
+        """Maximum memory use in bytes."""
+        return int(self.memory * 1024 * 1024 * 1024)
+
+    def to_logging_context(self) -> dict[str, Any]:
+        """Convert to variables for a structlog logging context."""
+        result = {"cpu": self.cpu, "memory": f"{self.memory} GiB"}
+        if not self.spawn:
+            result["spawn"] = False
+        return result
+
+
+class GafaelfawrTapQuota(BaseModel):
+    """TAP quota information for a user."""
+
+    concurrent: Annotated[int, Field(title="Concurrent queries")]
+
+    def to_logging_context(self) -> dict[str, Any]:
+        """Convert to variables for a structlog logging context."""
+        return {"concurrent": self.concurrent}
+
+
+class GafaelfawrQuota(BaseModel):
+    """Quota information for a user."""
+
+    api: Annotated[
+        dict[str, int],
+        Field(
+            title="API quotas",
+            description=("Mapping of service names to requests per minute"),
+        ),
+    ] = {}
+
+    notebook: Annotated[
+        GafaelfawrNotebookQuota | None, Field(title="Notebook Aspect quotas")
+    ] = None
+
+    tap: Annotated[
+        dict[str, GafaelfawrTapQuota], Field(title="TAP quotas")
+    ] = {}
+
+
+class GafaelfawrUserInfo(BaseModel):
+    """Information about a user."""
+
+    username: Annotated[str, Field(..., title="Username")]
+
+    name: Annotated[str | None, Field(title="Preferred full name")] = None
+
+    email: Annotated[str | None, Field(title="Email address")] = None
+
+    uid: Annotated[int | None, Field(title="UID number")] = None
+
+    gid: Annotated[int | None, Field(title="Primary GID")] = None
+
+    groups: Annotated[list[GafaelfawrGroup], Field(title="Groups")] = []
+
+    quota: Annotated[GafaelfawrQuota | None, Field(title="Quota")] = None
+
+    @property
+    def supplemental_groups(self) -> list[int]:
+        """Supplemental GIDs."""
+        return [g.id for g in self.groups]
+
+
+class TokenData(BaseModel):
+    """Metadata about a token, used internally by the mock."""
+
+    token: Annotated[str, Field(title="Associated token")]
+
+    username: Annotated[str, Field(title="Username")]
+
+    scopes: Annotated[set[str], Field(title="Token scopes")] = set()
+
+    expires: Annotated[datetime | None, Field(title="Expiration time")] = None
+
+
+class TokenType(Enum):
+    """The class of token.
+
+    This includes only the subset of token types used by the client.
+    """
+
+    service = "service"
+
+
+class AdminTokenRequest(BaseModel):
+    """A request to create a new token via the admin interface."""
+
+    username: Annotated[str, Field(title="User for which to issue a token")]
+
+    token_type: Annotated[TokenType, Field(title="Token type")]
+
+    scopes: Annotated[list[str], Field(title="Token scopes")] = []
+
+    expires: Annotated[datetime | None, Field(title="Token expiration")] = None
+
+    name: Annotated[str | None, Field(title="Preferred full name")] = None
+
+    email: Annotated[str | None, Field(title="Email address")] = None
+
+    uid: Annotated[int | None, Field(title="UID number")] = None
+
+    gid: Annotated[int | None, Field(title="Primary GID")] = None
+
+    groups: Annotated[
+        list[GafaelfawrGroup] | None,
+        Field(title="Groups"),
+    ] = None
+
+
+class NewToken(BaseModel):
+    """Response to a token creation request."""
+
+    token: Annotated[str, Field(title="Newly-created token")]

rubin/gafaelfawr/_tokens.py

@@ -0,0 +1,28 @@
+"""Functions for creating tokens."""
+
+from __future__ import annotations
+
+import base64
+import os
+
+__all__ = ["create_token"]
+
+
+def create_token() -> str:
+    """Create a new random Gafaelfawr token.
+
+    Normally, users of Gafaelfawr should use the Gafaelfawr API to create new
+    tokens. This function is intended only for creating new bootstrap tokens
+    that will be injected into the Gafaelfawr server via configuration, or for
+    creating syntactically valid tokens for use with the Gafaelfawr mock.
+
+    Returns
+    -------
+    str
+        New random Gafaelfawr token. This token will not be registered with
+        any running Gafaelfawr instance and therefore will not be usable
+        without other measures, such as configuring it as a bootstrap token.
+    """
+    key = base64.urlsafe_b64encode(os.urandom(16)).decode().rstrip("=")
+    secret = base64.urlsafe_b64encode(os.urandom(16)).decode().rstrip("=")
+    return f"gt-{key}.{secret}"

rubin_gafaelfawr-15.1.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: rubin-gafaelfawr
+Version: 15.1.0
+Summary: Client for Gafaelfawr authentication and identity service.
+Author-email: "Association of Universities for Research in Astronomy, Inc. (AURA)" <sqre-admin@lists.lsst.org>
+License-Expression: MIT
+Project-URL: Homepage, https://gafaelfawr.lsst.io
+Project-URL: Source, https://github.com/lsst-sqre/gafaelfawr
+Project-URL: Change log, https://gafaelfawr.lsst.io/changelog.html
+Project-URL: Issue tracker, https://github.com/lsst-sqre/gafaelfawr/issues
+Keywords: rubin,lsst
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cachetools<7,>=6.1
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pydantic-settings<3,>=2.6
+Requires-Dist: rubin-repertoire<1,>=0.6
+Requires-Dist: structlog>24
+Dynamic: license-file
+
+# rubin-gafaelfawr
+
+rubin-gafaelfawr is a client for [Gafaelfawr](https://gafaelfawr.lsst.io), which provides authentication and authorization for [Phalanx](https://phalanx.lsst.io/).
+This package provides the Python client, Pydantic models, and a testing mock for applications that need to use the Gafaelfawr API directly.
+
+rubin-gafaelfawr is available from [PyPI](https://pypi.org/project/rubin-gafaelfawr/):
+
+```sh
+pip install rubin-gafaelfawr
+```
+
+For full documentation, see [the Gafaelfawr user guide](https://gafaelfawr.lsst.io/user-guide/).

rubin_gafaelfawr-15.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+rubin/gafaelfawr/__init__.py,sha256=KWkUt8P3BhyByQ_NFFvTVyD8yaKCA-Ure5JOeHxnTPA,924
+rubin/gafaelfawr/_client.py,sha256=JXEkaHESqlRhN8PsxDLjgrROWleWUW3IBULfkaH2qvs,13268
+rubin/gafaelfawr/_constants.py,sha256=CzdvNVFxKAaTJk3kFPGuDzgf9XrGZeOSIYS6kilLX8U,490
+rubin/gafaelfawr/_exceptions.py,sha256=-FImkqs_PGvPMA4uYV9H4QGKGESIquGGSFPMLkP-c_k,2097
+rubin/gafaelfawr/_mock.py,sha256=hTtzS4Sj5bLLHvt65GTM3Gc2iGvRrEn7G2xDNhI6sZ8,9075
+rubin/gafaelfawr/_models.py,sha256=AJnG5RX58WlXCOoyylY36eW3zlkjRmJ9jjyocP0a_Q4,4613
+rubin/gafaelfawr/_tokens.py,sha256=ydHPhdZxJoqoUB4giHBVShMtwa2ABjcTG7VXHoDJs9Y,955
+rubin/gafaelfawr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rubin_gafaelfawr-15.1.0.dist-info/licenses/LICENSE,sha256=doQ1mktl7PtOAr55gjC1t2W-cs_p08b48zuteNGWS3E,1253
+rubin_gafaelfawr-15.1.0.dist-info/METADATA,sha256=43rqQTjzGVhU2bEBFKINQ9qMKQ85ehkl2JGuZBHOKG8,1802
+rubin_gafaelfawr-15.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rubin_gafaelfawr-15.1.0.dist-info/top_level.txt,sha256=H4T4WkAdqgaG1jgfW1hpFRQhwpqYfHVm3n1gRUpxKcw,6
+rubin_gafaelfawr-15.1.0.dist-info/RECORD,,

rubin_gafaelfawr-15.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rubin_gafaelfawr-15.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright 2018-2019 The Board of Trustees of the Leland Stanford Junior University, through SLAC National Accelerator Laboratory
+Copyright 2020-2025 Association of Universities for Research in Astronomy, Inc. (AURA)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rubin_gafaelfawr-15.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rubin