arc/docs/dist-git-move/notifications.rst
Ryan Lerch ba720c3d77 fix parsing errors and sphinx warnings
Signed-off-by: Ryan Lerch <rlerch@redhat.com>
2023-11-20 13:04:34 +00:00

98 lines
4.9 KiB
ReStructuredText

.. _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 <https://fedora-messaging.readthedocs.io/>`_ 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
<https://github.com/fedora-infra/fmn/blob/develop/fmn/api/handlers/misc.py#L55>`__
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
<https://fastapi.tiangolo.com/tutorial/dependencies/>`_ called ``get_distgit_proxy``,
more information related to which can be found `here
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L284>`__.
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
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L69>`__
provided here.
- The `method definition
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L72>`__ for
**determining the next page parameters** is provided here. This is extensively used
for recursively navigating through the Pagure Dist Git `API
<https://pagure.io/api/0>`_ results.
- The `method definition
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L86>`__ 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
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L115>`__ 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
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L157>`__ 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
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L127>`__ 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
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L142>`__ 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
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L285>`__ 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
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/pagure.py#L69>`__ 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
<https://github.com/fedora-infra/fmn/blob/develop/fmn/backends/base.py#L39>`__ can be
found here.