From 6aab8dc90ed311451d9508511b4a3bfa7a7b8f76 Mon Sep 17 00:00:00 2001 From: Akashdeep Dhar Date: Mon, 30 Oct 2023 13:04:18 +0530 Subject: [PATCH] Add documentation for FMN interactions Signed-off-by: Akashdeep Dhar --- docs/dist-git-move/index.rst | 8 ++ docs/dist-git-move/notifications.rst | 105 +++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 docs/dist-git-move/notifications.rst diff --git a/docs/dist-git-move/index.rst b/docs/dist-git-move/index.rst index 6bd900e..5b0a642 100644 --- a/docs/dist-git-move/index.rst +++ b/docs/dist-git-move/index.rst @@ -37,6 +37,14 @@ Requirements * Include additions to **Pagure** to support interactions with another platform * Include additions to **Anitya/The New Hotness** to support interactions with another platform +Index +---- + +.. toctree:: + :maxdepth: 1 + + notifications + Conclusions ---- diff --git a/docs/dist-git-move/notifications.rst b/docs/dist-git-move/notifications.rst new file mode 100644 index 0000000..4bff744 --- /dev/null +++ b/docs/dist-git-move/notifications.rst @@ -0,0 +1,105 @@ +.. _notifications: + +Pagure Dist Git Interactions With Fedora Notifications +==== + +Fedora Messaging Notifier is a family of systems to manage end-user +notifications triggered by +`Fedora Messaging `_ and it provides +a single place for all applications using Fedora Messaging to notify users of +events. + +Possible Interactions +---- + +The following are a set of documented interactions possible between Pagure Dist +Git and Fedora Notifications. + +Artifact Details +^^^^ + +- Fedora Notifications receives information about the permissions related to + a certain asset (which can be a package) from Pagure Dist Git. It receives + information about the assets (which can be a package) that a user or a group + has access to. +- Fedora Notifications provide its users with **artifact details** via an HTTP + GET endpoint that it retrieves from Pagure Dist Git. For more information, + please check the + `function definition `_ + provided here. +- The inputs required by the Fedora Notifications service to perform this + operation are *name patterns of artifacts to be returned*, + *name of the users whose artifacts are to be returned*, and + *name of the groups whose artifacts are to be returned*. +- This endpoint makes use of a + `FastAPI dependency `_ + called ``get_distgit_proxy``, more information related to which can be found + `here `_. + +The ``PagureAsyncProxy`` class +^^^^ + +- The URL of the existing Pagure Dist Git production deployment is referenced + here to instantiate an object of type ``PagureAsyncProxy`` class. For more + information, please check the + `method definition `_ + provided here. +- The + `method definition `_ + for **determining the next page parameters** is provided here. This is + extensively used for recursively navigating through the Pagure Dist Git + `API `_ results. +- The + `method definition `_ + for **retrieving project details** is provided here. This is dependent on + the values provided for the ``namespace``, ``pattern``, ``username`` and + ``owner`` parameters. +- The + `method definition `_ + for **retrieving project details associated with a certain user** is provided + here. This is dependent on the values provided for the ``username`` + parameter. +- The + `method definition `_ + for **retrieving project details associated with a certain project** is + provided here. This is dependent on the values for the ``name`` parameter. +- The + `method definition `_ + for **retrieving user details associated with a certain project** is provided + here. This is dependent on the values provided for the ``project_path`` + parameter. +- The + `method definition `_ + for **retrieving group details associated with a certain project** is provided + here. This is dependent on the values provided for the ``project_path`` + parameter. + +Changes proposed +---- + +In order to switch out Pagure Dist Git for an alternative that provides a +relatively compatible API pattern, the following changes must be made in the +placed mentioned below. + +Necessary +^^^^ + +- The Pagure Dist Git URL production deployment URL would have to change to + point towards the production deployment URL of the alternative. This + `method definition `_ + is where the URL is formatted to point towards the API. +- The method ``get_api_url`` has to be redefined depending on what the URL + pattern is for the alternative place where we move Pagure Dist Git assets to. + Here is the + `method definition `_ + of where the changes need to be made. + +Unnecessary +^^^^ + +- The ``APIClient`` class that is inherited by the ``PagureAsyncProxy`` class is + agnostic to the place where the assets are hosted so changing over from + Pagure Dist Git to an alternative would not necessitate a reworking while + checking for compatibilities is strongly recommended. The + `method definition `_ + can be found here.