User accounts service¶

`consortium.server.services.user_accounts_service` ¶

`UserAccountsService(user_accounts_json_file, authorization_service)` ¶

`get_user_account_by_user_account_id(user_account_id)` ¶

Returns a user account by its ID.

Parameters:

Name	Type	Description	Default
`user_account_id`	`str \| UUID`	The ID of the user account to retrieve.	required

Returns:

Type	Description
`UserAccountModel`	The requested user account.

Raises:

Type	Description
`UserAccountIDNotFoundError`	If no user account with the given ID exists.

`get_user_account_by_username(username)` ¶

Returns a user account by its username.

Parameters:

Name	Type	Description	Default
`username`	`str`	The username of the account to retrieve.	required

Returns:

Type	Description
`UserAccountModel`	The requested user account.

Raises:

Type	Description
`UserAccountUsernameNotFoundError`	If no user account with the given username exists.

`get_all_user_accounts()` ¶

Returns all registered user accounts.

Returns:

Type	Description
`list[UserAccountModel]`	A list of all user accounts. Empty if none exist.

`create_user_account(username, password, role)` ¶

Creates a new user account and adds it to the in-memory registry.

Parameters:

Name	Type	Description	Default
`username`	`str`	The username for the new account. Must be non-empty and unique.	required
`password`	`str`	The password for the new account. Must be non-empty.	required
`role`	`str`	The role to assign to the new account.	required

Returns:

Type	Description
`UserAccountModel`	The newly created user account.

Raises:

Type	Description
`EmptyUserAccountUsernameError`	If `username` is empty.
`EmptyUserAccountPasswordError`	If `password` is empty.
`InvalidUserAccountRoleError`	If `role` is not a valid user role value.
`UserAccountUsernameAlreadyExistsError`	If an account with the given username already exists.

`update_user_account_by_user_account_id(user_account_id, username=None, password=None, role=None)` ¶

Updates a user account's username, password, and/or role.

Only fields that are not None are updated. A field submitted with the value the account already holds is a no op: it is validated, then left unchanged and unlogged. Submitting an account's own username is therefore accepted rather than reported as a conflict.

Parameters:

Name	Type	Description	Default
`user_account_id`	`str \| UUID`	The ID of the user account to update.	required
`username`	`str \| None`	The new username. When `None`, the username is not changed.	`None`
`password`	`str \| None`	The new password. When `None`, the password is not changed.	`None`
`role`	`str \| None`	The new role. When `None`, the role is not changed.	`None`

Returns:

Type	Description
`UserAccountModel`	The updated user account, whether or not any field changed.

Raises:

Type	Description
`UserAccountIDNotFoundError`	If no user account with the given ID exists.
`EmptyUserAccountUsernameError`	If `username` is an empty string.
`EmptyUserAccountPasswordError`	If `password` is an empty string.
`InvalidUserAccountRoleError`	If `role` is not a valid user role value.
`UserAccountUsernameAlreadyExistsError`	If a different account already has the given username.

`delete_user_account_by_user_account_id(user_account_id)` ¶

Deletes a user account from the in-memory registry.

Parameters:

Name	Type	Description	Default
`user_account_id`	`str \| UUID`	The ID of the user account to delete.	required

Raises:

Type	Description
`UserAccountIDNotFoundError`	If no user account with the given ID exists.

`authenticate_user_account_credentials(username, password)` ¶

Validates a username and password against registered user accounts.

Parameters:

Name	Type	Description	Default
`username`	`str`	The username to authenticate.	required
`password`	`str`	The password to validate.	required

Returns:

Type	Description
`UserAccountModel`	The authenticated user account.

Raises:

Type	Description
`UserAccountAuthenticationError`	If the username does not exist or the password does not match.

`load_user_accounts_from_user_accounts_file(user_accounts_filepath)` ¶

Reads user accounts from a JSON file and adds them to the in-memory registry.

Delegates parsing to read_user_accounts_from_user_accounts_file and then registers each parsed account.

Parameters:

Name	Type	Description	Default
`user_accounts_filepath`	`Path`	Path to the JSON file to read accounts from.	required

Returns:

Type	Description
`list[UserAccountModel]`	The list of user accounts loaded from the file.

Raises:

Type	Description
`UserAccountsFileSystemError`	If the file cannot be read, for example because it does not exist, the process lacks read permission, or the path points to a directory.
`UserAccountsFileEncodingError`	If the file's bytes are not valid UTF-8.
`UserAccountsFileJSONError`	If the file is not valid JSON.
`UserAccountsFileSchemaError`	If the JSON does not follow the expected schema, including when an entry is missing a required field, carries an empty username or password, or carries an unrecognised field.
`InvalidUserAccountRoleError`	If an entry's role is not one of the roles currently registered with the authorization service.
`UserAccountUsernameAlreadyExistsError`	If a username from the file conflicts with an already-registered account.
`UserAccountsFileDuplicateUsernamesError`	If the file itself contains duplicate usernames.

`read_user_accounts_from_user_accounts_file(user_accounts_filepath)` ¶

Reads and validates user accounts from a JSON file without registering them.

Validates the file path, JSON structure, and schema. Checks that usernames are unique against both existing registered accounts and entries within the file itself.

Parameters:

Name	Type	Description	Default
`user_accounts_filepath`	`Path`	Path to the JSON file to read accounts from.	required

Returns:

Type	Description
`list[UserAccountModel]`	The list of parsed user accounts.

Raises:

Type	Description
`UserAccountsFileSystemError`	If the file cannot be read, for example because it does not exist, the process lacks read permission, or the path points to a directory.
`UserAccountsFileEncodingError`	If the file's bytes are not valid UTF-8.
`UserAccountsFileJSONError`	If the file is not valid JSON.
`UserAccountsFileSchemaError`	If the JSON does not follow the expected schema, including when an entry is missing a required field, carries an empty username or password, or carries an unrecognised field.
`InvalidUserAccountRoleError`	If an entry's role is not one of the roles currently registered with the authorization service.
`UserAccountUsernameAlreadyExistsError`	If a username from the file conflicts with an already-registered account.
`UserAccountsFileDuplicateUsernamesError`	If the file itself contains duplicate usernames.

`write_user_accounts_to_user_accounts_file(user_accounts_filepath)` ¶

Serializes and writes all registered user accounts to a JSON file.

Parameters:

Name	Type	Description	Default
`user_accounts_filepath`	`Path`	Path to the file to write accounts to.	required

Returns:

Type	Description
`int`	The number of bytes written.

Raises:

Type	Description
`UserAccountsFileSystemError`	If the file cannot be written, for example because the process lacks write permission, the path points to a directory, or the disk is full.

`load_framework_user_accounts()` ¶

Loads user accounts from the framework's configured user accounts file.

Every failure this can encounter is a UserAccountsServiceError, so all of them are logged and reported through the return value rather than raised. Callers that need the server to react to a failed load have to check that return value: it is the only signal, and a False leaves the service with no accounts registered.

Returns:

Type	Description
`bool`	`True` if accounts were loaded successfully, `False` if a
`bool`	`UserAccountsServiceError` occurred.

`reload_framework_user_accounts()` ¶

Deletes all existing user accounts then reloads them from the framework's file.

Every failure this can encounter is a UserAccountsServiceError, so all of them are logged and reported through the return value rather than raised. The existing accounts are deleted before the reload is attempted, so a False leaves the service with no accounts registered rather than with the previous set.

Returns:

Type	Description
`bool`	`True` if accounts were reloaded successfully, `False` if a
`bool`	`UserAccountsServiceError` occurred.

`write_framework_user_accounts()` ¶

Writes all in-memory user accounts to the framework's configured user accounts file.

Failures propagate rather than being reported through the return value. A failed write means the in-memory registry and the file have diverged and the change will be lost on the next restart, which a caller that just accepted a change has to be able to react to. log_and_propagate_error_on_service_method logs the error on the way out, so nothing is lost by not catching it here.

Returns:

Type	Description
`int`	The number of bytes written.

Raises:

Type	Description
`UserAccountsFileSystemError`	If the file cannot be written, for example because the process lacks write permission, the configured path points to a directory, or the disk is full.

User accounts service¶

consortium.server.services.user_accounts_service ¶