"""
The owners of the folders of a repository that ``manage.py load_from_github`` loads.
``load_from_github`` applies a repository's manifests as one user, so that every resource belongs to one account.
An organization of several accounts (ADR-036) keeps its resources in the accounts of the departments that own them:
its IT department's Secrets and Connections in IT's account, its HR assistant in HR's, and so on. A repository says
which by mapping its folders to their owners. The Stackademy project, https://github.com/smarter-sh/stackademy, is the
reference.
The scheme
----------
- **The file.** ``owners.yaml``, :data:`OWNERS_CONFIG`, at the repository's root. Its model is
:class:`RepositoryOwnersConfig`:
.. code-block:: yaml
owners:
- path: departments/it # a folder, relative to the repository's root
username: stackademy_it_admin # the user who applies, and so owns, its manifests
accountNumber: "2718-2818-0001" # the account in which they own them
- **Which folder.** A manifest belongs to the deepest folder of the file that contains it, so a folder's owner may
be overridden for one of its subfolders. A manifest in no listed folder is applied by ``load_from_github``'s own
user, as before.
- **The organization itself.** Account and User manifests are always applied by ``load_from_github``'s own user,
wherever they are, because they declare the accounts and the people that own the rest, and must exist first.
- **Where it applies.** Only when the repository is loaded into the Smarter account, as ``manage.py
initialize_platform`` loads it: an organization's resources exist once. Loaded into any other account, e.g. by
``manage.py initialize_account``, which copies a repository's plugins and LLMClients into a new account, the
manifests of owned folders are skipped, because they belong to their owners, not to that account.
- **Failures.** An owner who doesn't exist, or doesn't belong to the account that the file names, fails each of
their manifests, and not the others. A file that is not valid fails ``load_from_github`` before anything is applied.
"""
import os
from typing import Optional
import yaml
from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
from smarter.common.exceptions import SmarterValueError
from smarter.lib import logging
from smarter.lib.django.validators import SmarterValidator
logger = logging.getLogger(__name__)
logger_prefix = logging.SmarterFormattedText.text(__name__)
OWNERS_CONFIG = "owners.yaml"
"""A repository's owners file, at its root, :class:`RepositoryOwnersConfig`."""
[docs]
class RepositoryOwner(BaseModel):
"""One folder of ``owners.yaml``, and the user who applies, and so owns, its manifests."""
model_config = ConfigDict(extra="forbid", frozen=True)
path: str = Field(
...,
description="The folder, relative to the repository's root, e.g. departments/it.",
examples=["departments/it"],
)
username: str = Field(
..., description="The user who applies the folder's manifests.", examples=["stackademy_it_admin"]
)
accountNumber: str = Field(
...,
description="The account in which the user owns them, which the user must belong to.",
examples=["2718-2818-0001"],
)
[docs]
@field_validator("path")
@classmethod
def validate_path(cls, v: str) -> str:
"""
Validate that the path is a folder inside the repository.
:param v: The path.
:returns: The path, normalized, without a trailing separator.
:raises ValueError: If it is empty, absolute, the repository's root, or leaves the repository.
"""
if not v or not v.strip():
raise ValueError("path is required.")
path = os.path.normpath(v.strip())
if os.path.isabs(path) or path in (".", "..") or path.startswith(".." + os.sep):
raise ValueError(f"path {v} must be a folder inside the repository.")
return path
[docs]
@field_validator("accountNumber")
@classmethod
def validate_account_number(cls, v: str) -> str:
"""
Validate that the account number has the form 1234-5678-9012.
:param v: The account number.
:returns: The account number.
:raises ValueError: If it isn't an account number.
"""
if not SmarterValidator.is_valid_account_number(v):
raise ValueError(f"{v} is not an account number, e.g. 1234-5678-9012.")
return v
[docs]
class RepositoryOwnersConfig(BaseModel):
"""
A repository's ``owners.yaml``: which user applies the manifests of each of its folders.
See the scheme in :mod:`smarter.apps.account.repository_owners`.
"""
model_config = ConfigDict(extra="forbid", frozen=True)
owners: list[RepositoryOwner] = Field(default_factory=list, description="The folders and their owners.")
[docs]
@field_validator("owners")
@classmethod
def validate_unique_paths(cls, v: list[RepositoryOwner]) -> list[RepositoryOwner]:
"""
Validate that each folder is listed once.
:param v: The owners.
:returns: The owners.
:raises ValueError: If a folder is listed more than once.
"""
paths = [owner.path for owner in v]
if len(paths) != len(set(paths)):
raise ValueError("Each folder may be listed only once.")
return v
[docs]
def owner_for(self, path: str) -> Optional[RepositoryOwner]:
"""
Return the owner of the deepest listed folder that contains a file.
:param path: The file, relative to the repository's root, e.g. ``departments/hr/plugins/hr.yaml``.
:returns: Its folder's owner, or None if no listed folder contains it.
:rtype: Optional[RepositoryOwner]
"""
file_path = os.path.normpath(path)
retval: Optional[RepositoryOwner] = None
deepest = -1
for owner in self.owners:
folder = owner.path + os.sep
if not file_path.startswith(folder):
continue
depth = owner.path.count(os.sep)
if depth > deepest:
deepest = depth
retval = owner
return retval
[docs]
def owners_config_path(local_path: str) -> str:
"""
Return the path of a repository's owners file, whether or not it exists.
:param local_path: The repository's clone.
:returns: ``<local_path>/owners.yaml``.
:rtype: str
"""
return os.path.join(local_path, OWNERS_CONFIG)
[docs]
def load_owners_config(local_path: str) -> Optional[RepositoryOwnersConfig]:
"""
Read and validate a repository's ``owners.yaml``.
:param local_path: The repository's clone.
:returns: The configuration, or None if the repository has none.
:rtype: Optional[RepositoryOwnersConfig]
:raises SmarterValueError: If the file is not valid YAML, or not a valid configuration.
"""
filespec = owners_config_path(local_path)
if not os.path.isfile(filespec):
return None
try:
with open(filespec, encoding="utf-8") as f:
data = yaml.safe_load(f) or {}
config = RepositoryOwnersConfig.model_validate(data)
except (yaml.YAMLError, ValidationError) as e:
raise SmarterValueError(f"{OWNERS_CONFIG} is not valid: {e}") from e
logger.debug("%s.load_owners_config() %s lists %s folders", logger_prefix, OWNERS_CONFIG, len(config.owners))
return config
__all__ = [
"OWNERS_CONFIG",
"RepositoryOwner",
"RepositoryOwnersConfig",
"load_owners_config",
"owners_config_path",
]