doc: Add doc to present what are pilots and their endpoints

Author: Robin-Van-de-Merghel

diracx-core/src/diracx/core/exceptions.py

@@ -102,42 +102,11 @@ def __init__(self, job_id, detail: str = ""):
 class NotReadyError(DiracError):
     """Tried to access a value which is asynchronously loaded but not yet available."""
 
+class PilotNotFoundError(DiracError):
+    """At least one pilot is not found"""
 
-class DiracFormattedError(DiracError):
-    # TODO: Refactor?
-    pattern = "Error %s"
+class PilotAlreadyExistsError(DiracError):
+    """At least one pilot already exists, we avoid collitions."""
 
-    def __init__(self, data: dict[str, str], detail: str = ""):
-        self.data = data
-
-        parts = [f"({key}: {value})" for key, value in data.items()]
-        message = type(self).pattern % (" ".join(parts))
-        if detail:
-            message += f": {detail}"
-
-        super().__init__(message)
-
-
-class PilotNotFoundError(DiracFormattedError):
-    pattern = "Pilot %s not found"
-
-    def __init__(
-        self,
-        data: dict[str, str],
-        detail: str = "",
-        non_existing_pilots: set = set(),
-    ):
-        super().__init__(data, detail)
-        self.non_existing_pilots = non_existing_pilots
-
-
-class PilotAlreadyExistsError(DiracFormattedError):
-    pattern = "Pilot %s already exists"
-
-
-class PilotJobsNotFoundError(DiracFormattedError):
-    pattern = "Pilots or Jobs %s not found"
-
-
-class PilotAlreadyAssociatedWithJobError(DiracFormattedError):
-    pattern = "Pilot is already associated with a job %s "
+class PilotAlreadyAssociatedWithJobError(DiracError):
+    """We can't associate a pilot with the same job twice."""

diracx-db/src/diracx/db/sql/pilots/db.py

@@ -102,7 +102,6 @@ async def add_jobs_to_pilot(self, job_to_pilot_mapping: list[dict[str, Any]]):
         except IntegrityError as e:
             if "foreign key" in str(e.orig).lower():
                 raise PilotNotFoundError(
-                    data={"pilot_stamps": str(job_to_pilot_mapping)},
                     detail="at least one of these pilots do not exist",
                 ) from e
 
@@ -111,7 +110,7 @@ async def add_jobs_to_pilot(self, job_to_pilot_mapping: list[dict[str, Any]]):
                 or "unique constraint" in str(e.orig).lower()
             ):
                 raise PilotAlreadyAssociatedWithJobError(
-                    data={"job_to_pilot_mapping": str(job_to_pilot_mapping)}
+                    detail="at least one of these pilots is already associated with a given job." 
                 ) from e
 
             # Other errors to catch
@@ -194,7 +193,7 @@ async def update_pilot_fields(
 
         if res.rowcount != len(pilot_stamps_to_fields_mapping):
             raise PilotNotFoundError(
-                data={"mapping": str(pilot_stamps_to_fields_mapping)}
+                "at least one of the given pilot does not exist."
             )
 
     # ----------------------------- Search Functions -----------------------------

diracx-logic/src/diracx/logic/pilots/management.py

@@ -34,7 +34,7 @@ async def register_new_pilots(
     if len(existing_pilots) > 0:
         found_keys = {pilot["PilotStamp"] for pilot in existing_pilots}
 
-        raise PilotAlreadyExistsError(data={"pilot_stamps": str(found_keys)})
+        raise PilotAlreadyExistsError(f"The following pilots already exist: {found_keys}")
 
     await pilot_db.add_pilots(
         pilot_stamps=pilot_stamps,

diracx-routers/tests/pilots/test_pilot_creation.py

@@ -68,7 +68,7 @@ async def test_create_pilots(normal_test_client):
     assert r.status_code == 409
     assert (
         r.json()["detail"]
-        == f"Pilot (pilot_stamps: {{'{pilot_stamps[0]}'}}) already exists"
+        == f"The following pilots already exist: {{'{pilot_stamps[0]}'}}"
     )
 
     #  -------------- Register a pilot that does not exists **but** was called before in an error --------------

docs/dev/explanations/pilots.md

@@ -0,0 +1,21 @@
+## Presentation
+
+Pilots are a piece of software that is running on *worker nodes*. There are two types of pilots: "DIRAC pilots", and "DiracX pilots". The first type corresponds to pilots with proxies, sent by DIRAC; and the second type corresponds to pilots with secrets. Both kinds will eventually interact with DiracX using tokens (DIRAC pilots by exchanging their proxies for tokens, DiracX by exchanging their secrets for tokens). 
+
+## Management
+
+Their management is adapted in DiracX, and each feature has its own route in DiracX. We will split the `/pilots` route into two parts: 
+
+1. `/api/pilots/*` to allow administrators and users to access and modify pilots
+2. `/api/pilots/internal/*` is allocated for pilots resources: only DiracX pilots will have access to these resources
+
+Each part has its own security policy: we want to prevent pilots to access users resources and vice-versa. To differenciate DIRAC pilots from users, we can get their token and compare their properties: `GENERIC_PILOT` is the property that defines a pilot. For DiracX pilots, we can differenciate them by looking at the token structure: they don't have properties, but a "stamp" (their identifier).
+
+## Endpoints
+
+We ordered our endpoints like so:
+
+1. Creation: `POST /api/pilots/`
+2. Deletion: `DELETE /api/pilots/`
+3. Modification: `PATCH /api/pilots/metadata`
+