Source code for smarter.apps.account.hierarchy

"""
The account hierarchy, and the resources that it shares.

Accounts form a tree (:doc:`ADR-036 </adr/036-account-hierarchy>`). Each :class:`~smarter.apps.account.models.Account`
has a ``parent``, and the Smarter account is the root: an account whose ``parent`` is null is directly under
it. Separately from the tree, an account's ``share_scope`` names the audience of its resources: itself or one of
its ancestors, whose whole subtree may then read them. Null means that the account shares nothing.

A user profile may read the resources of an account X if the profile's account is X, or descends from
``X.share_scope``. This module computes that list of accounts, nearest first, caches it, and resolves a
resource's name against it.

.. code-block:: python

    from smarter.apps.account.hierarchy import readable_account_ids, resolve_by_name

    account_ids = readable_account_ids(user_profile.account_id)
    connection = resolve_by_name(SqlConnection.objects, "stackademy_hr", user_profile)
"""

from typing import TYPE_CHECKING, Optional, TypeVar

from cache_results import cache_results

from smarter.common.const import SMARTER_ACCOUNT_NUMBER
from smarter.lib import logging
from smarter.lib.django.waffle import SmarterWaffleSwitches

if TYPE_CHECKING:
    from smarter.apps.account.models import (
        MetaDataWithOwnershipModel,
        SmarterQuerySetWithPermissions,
        UserProfile,
    )

logger = logging.getSmarterLogger(__name__, any_switches=[SmarterWaffleSwitches.ACCOUNT_LOGGING])
logger_prefix = logging.SmarterFormattedText.text(__name__)

MAX_ACCOUNT_TREE_DEPTH = 32
"""
The deepest that the account tree may be.

An organization's chart is a handful of levels deep. The limit guards the walk up the tree against a cycle
that a direct database edit could create.
"""

READABLE_ACCOUNTS_CACHE_TIMEOUT = 60 * 60
"""
How long, in seconds, an account's readable accounts are cached.

:class:`~smarter.apps.account.models.Account` invalidates them whenever the tree or its sharing changes, so the
timeout only bounds how long a direct database edit that bypasses ``Account.save()`` goes unnoticed.
"""

_RT = TypeVar("_RT", bound="MetaDataWithOwnershipModel")


[docs] def root_account_id() -> Optional[int]: """ The id of the root of the account tree, the Smarter account. :returns: The Smarter account's id, or None if this platform has not created it yet. """ # pylint: disable=C0415 from smarter.apps.account.models import Account try: root = Account.get_cached_object(account_number=SMARTER_ACCOUNT_NUMBER) except Account.DoesNotExist: return None if root is None: return None return root.pk
[docs] def ancestor_ids(account_id: int) -> list[int]: """ The account and its ancestors, nearest first, ending with the root. It reads the database, not the cache, so that :meth:`Account.save` can validate a change to the tree against the tree as it is. :param account_id: The account's id. :returns: ``[account_id, parent_id, grandparent_id, ..., root_id]``. An account whose ``parent`` is null is directly under the root. The root's own list is ``[root_id]``. :raises ValueError: if the walk up the tree meets an account twice, or goes deeper than :data:`MAX_ACCOUNT_TREE_DEPTH`. """ # pylint: disable=C0415 from smarter.apps.account.models import Account retval: list[int] = [] current_id: Optional[int] = account_id while current_id is not None: if current_id in retval: raise ValueError(f"The account tree has a cycle at account id {current_id}.") if len(retval) >= MAX_ACCOUNT_TREE_DEPTH: raise ValueError( f"The account tree is deeper than {MAX_ACCOUNT_TREE_DEPTH} levels at account id {account_id}." ) retval.append(current_id) current_id = Account.objects.filter(pk=current_id).values_list("parent_id", flat=True).first() root_id = root_account_id() if root_id is not None and root_id not in retval: retval.append(root_id) return retval
[docs] @cache_results(timeout=READABLE_ACCOUNTS_CACHE_TIMEOUT) def readable_account_ids(account_id: int) -> tuple[int, ...]: """ The accounts whose resources a member of this account may read, nearest first. The account itself comes first. Then each account whose ``share_scope`` is this account or one of its ancestors, ordered by how near that ``share_scope`` is: an IT department that shares with its company comes before the Smarter account, which shares with everyone. Ties go to the lower id, so that the order is stable. Cached until :func:`invalidate_readable_account_ids`, which :class:`Account` calls whenever the tree or its sharing changes. :param account_id: The account's id. :returns: The ids of the readable accounts, nearest first. """ # pylint: disable=C0415 from smarter.apps.account.models import Account ancestors = ancestor_ids(account_id) sharing_accounts = Account.objects.filter(share_scope_id__in=ancestors).values_list("pk", "share_scope_id") ranked: list[tuple[int, int]] = [] for sharing_account_id, share_scope_id in sharing_accounts: if sharing_account_id == account_id: continue distance = ancestors.index(share_scope_id) ranked.append((distance, sharing_account_id)) ranked.sort() retval = [account_id] for _, sharing_account_id in ranked: retval.append(sharing_account_id) logger.debug( "%s.readable_account_ids() account id %s may read the resources of %s accounts.", logger_prefix, account_id, len(retval), ) return tuple(retval)
[docs] def invalidate_readable_account_ids() -> None: """ Forget every account's readable accounts. A change to one account's ``parent`` or ``share_scope`` can change what the members of any other account may read, so every entry goes. The tree changes rarely, so this is cheap enough. """ # pylint: disable=C0415 from smarter.apps.account.models import Account account_ids = list(Account.objects.values_list("pk", flat=True)) for account_id in account_ids: readable_account_ids.invalidate(account_id) # type: ignore logger.debug( "%s.invalidate_readable_account_ids() invalidated %s accounts.", logger_prefix, len(account_ids), )
[docs] def resolve_by_name(queryset: "SmarterQuerySetWithPermissions[_RT]", name: str, user_profile: "UserProfile") -> _RT: """ The resource that a user profile means by ``name``, in its account tree. Nearest wins: the profile's own resource, else its account's, else that of the nearest account that shares with it (:func:`readable_account_ids`). Ties go to the most recently updated. Only the profile's own account tree counts, never what the user may read otherwise. A superuser reads every account, and a user with profiles in several accounts reads all of them, but a resource that names another, e.g. an HR department's plugin that names a Connection, must find the same one whoever wrote it. Otherwise the members of HR would read, through the plugin, whatever its author can. :param queryset: The resources of one kind, e.g. ``SqlConnection.objects``. :param name: The resource's name. :param user_profile: The profile that names it, e.g. a plugin's owner. :returns: The resource. :raises django.core.exceptions.ObjectDoesNotExist: the model's own ``DoesNotExist``, which subclasses it, if no account in the profile's tree has a resource of that name. """ model = queryset.model readable = readable_account_ids(user_profile.account_id) # type: ignore[attr-defined] candidates = queryset.filter(name=name, user_profile__account_id__in=readable).select_related("user_profile") candidates = model.restrict_readable(candidates, user_profile.user) matches = list(candidates) if not matches: raise model.DoesNotExist(f"{model.__name__} {name} does not exist, or is not shared with you.") def precedence(resource: _RT) -> tuple[int, float]: owner_account_id = resource.user_profile.account_id # type: ignore[attr-defined] if resource.user_profile_id == user_profile.pk: # type: ignore[attr-defined] rank = 0 else: rank = readable.index(owner_account_id) + 1 updated_at = 0.0 if resource.updated_at: updated_at = resource.updated_at.timestamp() return rank, -updated_at retval = min(matches, key=precedence) logger.debug( "%s.resolve_by_name() %s %s resolved to id %s, owned by account id %s.", logger_prefix, model.__name__, name, retval.pk, retval.user_profile.account_id, # type: ignore[attr-defined] ) return retval
__all__ = [ "MAX_ACCOUNT_TREE_DEPTH", "READABLE_ACCOUNTS_CACHE_TIMEOUT", "ancestor_ids", "invalidate_readable_account_ids", "readable_account_ids", "resolve_by_name", "root_account_id", ]