Merge pull request #1269 from TOMToolkit/feature/pass-user-from-view-to-facilities

Feature/pass user from view to facilities

Author: phycodurus

docs/api/tom_observations/facilities.rst

@@ -37,4 +37,16 @@ Blanco
 ******
 
 .. automodule:: tom_observations.facilities.blanco
-    :members:
+    :members:
+
+
+********************************
+Facilities as ``INSTALLED_APPS``
+********************************
+
+The following Facilities are implemented as ``INSTALLED_APPS``. As such,
+each resides in its own git repository:
+
+* `Neil Gehrels Swift Observatory (tom_swift) <https://github.com/TOMToolkit/tom_swift>`__
+* `European Southern Observatory (tom_eso) <https://github.com/TOMToolkit/tom_eso>`__
+* `Liverpool Telescope (tom_lt) <https://github.com/TOMToolkit/tom_lt>`__

docs/observing/observation_module.rst

@@ -349,6 +349,39 @@ Even if the facilities you observe at are not API-accessible, you
 can still add them to your TOM’s airmass plots to judge what targets to
 observe when.
 
+How to add User-specific credentials to your Facility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Observation facilities typically require credentials (username and password or API key)
+to interact and submit observation requests. That is, you have to "log in" to use the Facility's
+API or client library.
+
+A TOM can be configured to provide common Facility credentials for every User of the TOM.
+These are specified in the ``FACILITIES`` dictionary of ``settings.py``. In this case, the TOM
+administrator would be resposible for maintaining the appropriate credentials. All observation
+requests from the TOM would use those same credentials.
+
+While you may write your Facility to use that mechanism, a few additional steps allow your
+Facility to provide for individual, User-specific credentials. Each TOM user can thus manage
+their own credentials and use them to submit their own observation requests.
+
+In outline, your Facility must:
+
+  1. Create a FaciltyProfile model in your Facility's ``models.py``. (Your Facility is typically
+  implmemented as an ``INSTALLED_APP`` and as such has a ``models.py`` module). This is described
+  and demonstrated in the `tom_demoapp <https://github.com/TOMToolkit/tom_demoapp>`__ and documented
+  `here <https://github.com/TOMToolkit/tom_demoapp/wiki/Integration-Points#profile-details>`__.
+
+  2. The fields of your Facility's Profile model would store the required credentials (for example,
+  a username and password or an API-key). Sensitive data such as passwords and API-keys should be
+  saved in an encrypted fashion and that is described
+  :doc:`here <../customization/encrypted_model_fields>`.
+
+  3. Finally, your Facility class must access these credentials to intereact with your Facility.
+  An example of this can be found in the TOMToolkit
+  `ESOFacility <https://github.com/TOMToolkit/tom_eso/blob/6e3575c7e44cdb09f3df83740f2e9f522afbb603/tom_eso/eso.py#L378>`__.
+
+
 Happy developing!
 
 

tom_common/models.py

@@ -65,7 +65,8 @@ def __get__(self, instance, owner):
         if not isinstance(cipher, Fernet):
             raise AttributeError(
                 f"A Fernet cipher must be set on the '{owner.__name__}' instance "
-                f"as '_cipher' to access property '{self.property_name}'."
+                f"as '_cipher' to access property '{self.property_name}'. "
+                f"Please use session_utils.get_encrypted_field() instead of direct access."
             )
 
         encrypted_value = getattr(instance, self.db_field_name)

tom_observations/facility.py

@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
 import copy
+from enum import Enum
 import logging
 import requests
 
@@ -8,13 +9,32 @@
 from django import forms
 from django.conf import settings
 from django.contrib.auth.models import Group
+from django.core.exceptions import ImproperlyConfigured
 from django.core.files.base import ContentFile
 from django.utils.module_loading import import_string
 
 from tom_targets.models import Target
 
 logger = logging.getLogger(__name__)
 
+
+class CredentialStatus(Enum):
+    """
+    Enum representing the status of facility credentials.
+
+    This enum is used to track the state of credentials throughout the facility lifecycle,
+    providing clear information about whether credentials are available, where they came from,
+    and any validation issues.
+    """
+    NOT_INITIALIZED = "not_initialized"  # set_user() hasn't been called yet
+    NO_PROFILE = "no_profile"            # User has no Profile (raises ImproperlyConfigured)
+    PROFILE_EMPTY = "profile_empty"      # Profile exists but credentials empty
+    USING_DEFAULTS = "using_defaults"    # Using settings.FACILITIES defaults
+    USING_USER_CREDS = "using_user_creds"  # Using user's Profile credentials
+    VALIDATION_FAILED_AUTH = "validation_failed_auth"  # Credentials failed (401/403)
+    VALIDATION_FAILED_NETWORK = "validation_failed_network"  # Network/server issue
+
+
 DEFAULT_FACILITY_CLASSES = [
     'tom_observations.facilities.lco.LCOFacility',
     'tom_observations.facilities.gemini.GEMFacility',
@@ -67,8 +87,17 @@ class BaseObservationForm(forms.Form):
     observation_type = forms.CharField(required=False, max_length=50, widget=forms.HiddenInput())
 
     def __init__(self, *args, **kwargs):
+        # DEBUG: Log what parameters are being passed
+        logger.debug(f'BaseObservationForm.__init__ kwargs: {kwargs}')
+
+        # Accept facility parameter but don't require it (for backward compatibility)
+        facility = kwargs.pop('facility', None)
         self.validation_message = 'This observation is valid.'
         super().__init__(*args, **kwargs)
+
+        # Store facility reference if provided
+        if facility is not None:
+            self.facility = facility
         self.helper = FormHelper()
         if settings.TARGET_PERMISSIONS_ONLY:
             self.common_layout = Layout('facility', 'target_id', 'observation_type')
@@ -195,10 +224,91 @@ class BaseObservationFacility(ABC):
 
     def __init__(self):
         self.user = None
+        self.credential_status = CredentialStatus.NOT_INITIALIZED
 
     def set_user(self, user):
         self.user = user
 
+    def _is_credential_empty(self, credential):
+        """
+        Check if a credential is empty (None, empty string, or whitespace only).
+
+        Args:
+            credential: The credential value to check
+
+        Returns:
+            bool: True if credential is empty, False otherwise
+        """
+        return credential is None or (isinstance(credential, str) and not credential.strip())
+
+    def _get_setting_credentials(self, facility_name, credential_keys):
+        """
+        Safely get credentials from settings.FACILITIES.
+
+        Args:
+            facility_name (str): Name of the facility in settings.FACILITIES
+            credential_keys (list): List of credential key names to retrieve
+
+        Returns:
+            dict: Dictionary mapping credential keys to their values
+
+        Raises:
+            ImproperlyConfigured: If facility or required keys are missing from settings
+        """
+        if not hasattr(settings, 'FACILITIES') or facility_name not in settings.FACILITIES:
+            raise ImproperlyConfigured(
+                f"No configuration found for '{facility_name}' in settings.FACILITIES. "
+                f"Please add default credentials to settings.FACILITIES['{facility_name}']."
+            )
+
+        facility_settings = settings.FACILITIES[facility_name]
+        credentials = {}
+
+        for key in credential_keys:
+            if key not in facility_settings:
+                raise ImproperlyConfigured(
+                    f"Required credential key '{key}' not found in "
+                    f"settings.FACILITIES['{facility_name}']. "
+                    f"Please add '{key}' to the facility configuration."
+                )
+            credentials[key] = facility_settings[key]
+
+        return credentials
+
+    def _raise_no_profile_error(self, user, facility_name):
+        """
+        Raise ImproperlyConfigured for missing user profile.
+
+        Args:
+            user: Django User instance
+            facility_name (str): Name of the facility
+
+        Raises:
+            ImproperlyConfigured: Always raises with informative message
+        """
+        raise ImproperlyConfigured(
+            f"User '{user.username}' has no {facility_name}Profile configured. "
+            f"Please create a {facility_name}Profile for this user in the admin interface."
+        )
+
+    def _raise_no_defaults_error(self, user, facility_name):
+        """
+        Raise ImproperlyConfigured when default credentials are needed but missing.
+
+        Args:
+            user: Django User instance
+            facility_name (str): Name of the facility
+
+        Raises:
+            ImproperlyConfigured: Always raises with informative message
+        """
+        raise ImproperlyConfigured(
+            f"User '{user.username}' has no credentials configured and no default credentials "
+            f"found in settings.FACILITIES['{facility_name}']. "
+            f"Please configure either user credentials in {facility_name}Profile or "
+            f"default credentials in settings."
+        )
+
     def all_data_products(self, observation_record):
         from tom_dataproducts.models import DataProduct
         products = {'saved': [], 'unsaved': []}
@@ -227,7 +337,27 @@ def all_data_products(self, observation_record):
     def get_form(self, observation_type):
         """
         This method takes in an observation type and returns the form type that matches it.
+
+        Note: This method returns form classes, not instances, to support composite form creation
+        in ObservationCreateView. Use create_form_instance() for direct form instantiation.
+        """
+
+    def create_form_instance(self, observation_type, **kwargs):
+        """
+        Create a form instance with facility context injected.
+
+        The ObservationCreateView handles setting the user context on the facility instance
+        via set_user() in its dispatch() method. Forms receive the facility instance and
+        can query it for user-specific data (credentials, API clients, etc.) rather than
+        handling business logic themselves.
+
+        :param observation_type: The type of observation form to create
+        :param kwargs: Additional keyword arguments for form instantiation
+        :return: Form instance configured for the observation type
         """
+        form_class = self.get_form(observation_type)
+        kwargs['facility'] = self
+        return form_class(**kwargs)
 
     def get_form_classes_for_display(self, **kwargs):
         """