GafaelfawrClient#

class rubin.gafaelfawr.GafaelfawrClient(http_client=None, *, discovery_client=None, logger=None, timeout=None, userinfo_cache_lifetime=datetime.timedelta(seconds=300), userinfo_cache_size=1000)#

Bases: object

Client for the Gafaelfawr service API.

Parameters:

  • http_client (Optional[AsyncClient], default: None) – 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 (Optional[DiscoveryClient], default: None) – If given, Repertoire discovery client to use. Otherwise, a new client will be created.

  • logger (Optional[BoundLogger], default: None) – Logger to use. If not given, the default structlog logger will be used.

  • timeout (Optional[timedelta], default: None) – Timeout for Gafaelfawr operations. If not given, defaults to the timeout of the underlying HTTPX client.

  • userinfo_cache_lifetime (timedelta, default: datetime.timedelta(seconds=300)) – How long to cache user information for a token.

  • userinfo_cache_size (int, default: 1000) – How many cache entries for the cache of user information by token.

Methods Summary

aclose()

Close the HTTP connection pool, if one wasn't provided.

clear_cache()

Clear all internal caches.

create_service_token(token, username, *, scopes)

Create a new service token.

get_user_info(token[, username])

Get information about the user, with caching.

list_groups(token)

List all known groups.

list_users(token)

List all known groups.

Methods Documentation

async aclose()#

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.

Return type:

None

async clear_cache()#

Clear all internal caches.

Return type:

None

async create_service_token(token, username, *, scopes, expires=None, name=None, uid=None, gid=None, groups=None)#

Create a new service token.

Parameters:

  • token (str) – Token to use to authenticate to the Gafaelfawr API. This token must have the admin:token scope.

  • username (str) – Username for which to create a token. Must begin with bot-.

  • scopes (list[str]) – List of scopes to grant to the new token.

  • expires (Optional[datetime], default: None) – Expiration date of te new token, or None to create a token that never expires.

  • name (Optional[str], default: None) – Full name override. If None, the full name will be determined from LDAP if configured, and otherwise not set.

  • uid (Optional[int], default: None) – UID override. If None, the UID will be determined from Firestore or LDAP if configured, and otherwise not set.

  • gid (Optional[int], default: None) – Primary GID override. If None, the primary GID will be determined from Firestore or LDAP if configured, and otherwise not set.

  • groups (Optional[list[GafaelfawrGroup]], default: None) – Group membership override. If None, the group membership will be determined from LDAP if configured, and otherwise not set.

Returns:

Newly-created token.

Return type:

str

Raises:
async get_user_info(token, username=None)#

Get information about the user, with caching.

Parameters:

  • token (str) – Token to use to authenticate to the Gafaelfawr API.

  • username (Optional[str], default: None) – 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:

User information for the user.

Return type:

GafaelfawrUserInfo

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.

async list_groups(token)#

List all known groups.

This method may only be called with a token with admin:userinfo scope, and group information is only available from a Gafaelfawr instance that uses LDAP as a backing store for user information. Only LDAP information will be returned, not any overrides present in tokens.

Parameters:

token (str) – Gafaelfawr token used for authentication.

Raises:
Return type:

GafaelfawrGroups

async list_users(token)#

List all known groups.

This method may only be called with a token with admin:userinfo scope, and user information is only available from a Gafaelfawr instance that uses LDAP as a backing store for user information. Only LDAP information will be returned, not any overrides present in tokens or bot users created outside of LDAP.

Parameters:

token (str) – Gafaelfawr token used for authentication.

Raises:
Return type:

list[GafaelfawrUserInfo]