TokenDatabaseStore

class gafaelfawr.storage.token.TokenDatabaseStore(session)

Bases: object

Stores and manipulates tokens in the database.

Tokens exist in both Redis and in the database. Redis is the source of truth for the validity of the token and the only data store that holds the supplemental user information that will eventually be replaced by an identity management system. The database is the canonical store for user-given token names and for the relationship between tokens.

Parameters:

session (async_scoped_session) – The database session proxy.

Methods Summary

add(data, *[, token_name, parent])	Store a new token.
count_unique_sessions()	Count the number of unique users with active session tokens.
count_user_tokens()	Count the number of unexpired user tokens.
delete(key)	Delete a token.
delete_expired()	Delete entries for expired tokens from the database.
get_children(key)	Return all children (recursively) of a token.
get_info(key)	Return information about a token.
get_internal_token_key(token_data, service, ...)	Retrieve an existing internal child token.
get_notebook_token_key(token_data, min_expires)	Retrieve an existing notebook child token.
list_orphaned()	List all orphaned tokens.
list_tokens(*[, username, token_type, limit])	List tokens.
list_with_parents()	List all tokens including parent information.
modify(key, *[, token_name, scopes, ...])	Modify a token.

Methods Documentation

async add(data, *, token_name=None, parent=None)

Store a new token.

Parameters:

• data (TokenData) – The corresponding data.

• token_name (str | None, default: None) – The human-given name for the token.

• service – The service for an internal token.

• parent (str | None, default: None) – The key of the parent of this token.

Raises:

DuplicateTokenNameError – Raised if the user already has a token by that name.

Return type:

None

async count_unique_sessions()

Count the number of unique users with active session tokens.

Returns:

Count of users.

Return type:

int

async count_user_tokens()

Count the number of unexpired user tokens.

Returns:

Count of user tokens.

Return type:

int

async delete(key)

Delete a token.

Parameters:

• token – The key of the token to delete.

• key (str)

Returns:

Whether the token was found to be deleted.

Return type:

bool

async delete_expired()

Delete entries for expired tokens from the database.

Returns:

The deleted tokens.

Return type:

list of TokenInfo

async get_children(key)

Return all children (recursively) of a token.

Parameters:

• str – The key of the token.

• key (str)

Returns:

The keys of all child tokens of that token, recursively. The direct child tokens will be at the beginning of the list, and other tokens will be listed in a breadth-first search order.

Return type:

list of str

async get_info(key)

Return information about a token.

Parameters:

key (str) – The key of the token.

Returns:

Information about that token or None if it doesn’t exist in the database.

Return type:

TokenInfo or None

async get_internal_token_key(token_data, service, scopes, min_expires)

Retrieve an existing internal child token.

Parameters:

• token_data (TokenData) – The data for the parent token.

• service (str) – The service to which the internal token is delegated.

• scopes (set[str]) – The scopes of the delegated token.

• min_expires (datetime) – The minimum expiration time for the token.

Returns:

The key of an existing internal child token with the desired properties, or None if none exist.

Return type:

str or None

async get_notebook_token_key(token_data, min_expires)

Retrieve an existing notebook child token.

Parameters:

• token_data (TokenData) – The data for the parent token.

• min_expires (datetime) – The minimum expiration time for the token.

Returns:

The key of an existing notebook child token, or None if none exist.

Return type:

str or None

async list_orphaned()

List all orphaned tokens.

Tokens are orphaned if they appear in the subtoken table but their parent column is null.

Returns:

Information about the tokens.

Return type:

list of TokenInfo

async list_tokens(*, username=None, token_type=None, limit=None)

List tokens.

Parameters:

• username (str | None, default: None) – Limit the returned tokens to ones for the given username.

• token_type (TokenType | None, default: None) – Limit the returned tokens to ones of the given type.

• limit (int | None, default: None) – Limit the number of tokens returned to this count.

Returns:

Information about the tokens.

Return type:

list of TokenInfo

async list_with_parents()

List all tokens including parent information.

This is a slower and more expensive query than list, used for audits.

Returns:

Information about the tokens.

Return type:

list of TokenInfo

async modify(key, *, token_name=None, scopes=None, expires=None, no_expire=False)

Modify a token.

Parameters:

• token – Token to modify.

• token_name (str | None, default: None) – New name for the token.

• scopes (set[str] | None, default: None) – New scopes for the token.

• expires (datetime | None, default: None) – New expiration time for the token.

• no_expire (bool, default: False) – If set, the token should not expire. This is a separate parameter because passing None to expires is ambiguous.

• key (str)

Returns:

Information for the updated token or None if it was not found.

Return type:

TokenInfo or None

Raises:

DuplicateTokenNameError – Raised if the user already has a token by that name.