flip_api.db.seed.main_users
===========================

.. py:module:: flip_api.db.seed.main_users


Functions
---------

.. autoapisummary::

   flip_api.db.seed.main_users.ensure_user_and_role
   flip_api.db.seed.main_users._ensure_user_and_role_resilient
   flip_api.db.seed.main_users.seed_main_users


Module Contents
---------------

.. py:function:: ensure_user_and_role(email: str, role_ref: flip_api.db.models.user_models.RoleRef, session: sqlmodel.Session) -> None

   Look up the Cognito user for ``email`` and grant them ``role_ref``.

   Cognito is the source of truth for user identity, so this function does
   not create or maintain a local users row. It only ensures the
   ``user_role`` grant exists for the Cognito sub corresponding to the
   given email.

   :param email: The user's email, used to look up the corresponding Cognito user.
   :type email: str
   :param role_ref: The role to assign to the user if they don't already have it.
   :type role_ref: RoleRef
   :param session: The SQLModel session used for DB reads and writes.
   :type session: Session


.. py:function:: _ensure_user_and_role_resilient(email: str, role_ref: flip_api.db.models.user_models.RoleRef, session: sqlmodel.Session) -> None

   Run ``ensure_user_and_role`` but tolerate transient Cognito-side HTTP failures.

   Seeding now reads from Cognito on every boot. A 5xx blip mid-deploy would
   otherwise couple flip-api liveness to Cognito read availability — log the skip
   loudly and continue with the remaining users instead.

   Definitive 4xx failures (e.g. 400 "no email/id provided", 403 if a future
   auth gate is added) still propagate: those are config / programming errors
   that should fail boot loudly rather than producing a platform with quietly
   missing grants.

   :param email: The user's email used to look up the corresponding Cognito user.
   :type email: str
   :param role_ref: The role to grant if missing.
   :type role_ref: RoleRef
   :param session: The SQLModel session used for DB reads and writes.
   :type session: Session


.. py:function:: seed_main_users(session: sqlmodel.Session) -> None

   Seed role grants for the well-known admin/researcher/observer emails.

   Resolves each email to its Cognito sub and ensures the corresponding
   ``user_role`` row exists. No local users-table state is created.

   :param session: The SQLModel session used for DB reads and writes.
   :type session: Session