98 lines
2.9 KiB
ReStructuredText
98 lines
2.9 KiB
ReStructuredText
|
.. _design_of_webhook2fedmsg:
|
||
|
|
|
||
|
|
Design document for webhook2fedmsg
|
||
|
|
==================================
|
||
|
|
|
||
|
|
This document will investigate the possibility to create a more general solution
|
||
|
|
converting various webhooks to fedora messaging messages.
|
||
|
|
|
||
|
|
|
||
|
|
External services
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
External services webhook2fedmsg will communicate with.
|
||
|
|
|
||
|
|
* Database
|
||
|
|
|
||
|
|
Will be used to store data about FAS user and tokens they added. We can consider supporting multiple tokens for each service per user.
|
||
|
|
For database it would be best to use existing `PostreSQL <https://pagure.io/fedora-infra/ansible/blob/main/f/roles/postgresql_server>`_
|
||
|
|
instance we already host in Fedora infra.
|
||
|
|
|
||
|
|
* Webhook services
|
||
|
|
|
||
|
|
The application will listen for webhooks from supported services. For each service should be separate backend, so it's easier to
|
||
|
|
remove/add new services.
|
||
|
|
|
||
|
|
* FAS
|
||
|
|
|
||
|
|
We need to authenticate user against Fedora Account System.
|
||
|
|
For authentication we can use `flask-oidc <https://github.com/fedora-infra/flask-oidc>`_ or `authlib <https://docs.authlib.org/en/latest/>`_
|
||
|
|
if `Flask <https://flask.palletsprojects.com/en/2.2.x/>`_ is not a framework of choice.
|
||
|
|
|
||
|
|
|
||
|
|
Use cases
|
||
|
|
---------
|
||
|
|
|
||
|
|
Use cases that need to be implemented by webhook2fedmsg.
|
||
|
|
|
||
|
|
|
||
|
|
* User login
|
||
|
|
|
||
|
|
User will be able to login through web interface using FAS account.
|
||
|
|
|
||
|
|
* User can add token for service
|
||
|
|
|
||
|
|
When logged in user can add token for any service known by webhook2fedmsg. We should support multiple tokens per service.
|
||
|
|
|
||
|
|
* User can modify/remove existing tokens
|
||
|
|
|
||
|
|
When logged in user should be able to modify/remove tokens for services he added earlier.
|
||
|
|
|
||
|
|
* User can list already added tokens
|
||
|
|
|
||
|
|
When logged in user should be able to see tokens he already added and for which service they are.
|
||
|
|
|
||
|
|
* User can see the URL for webhook
|
||
|
|
|
||
|
|
webhook2fedmsg should show on web interface URL that could be used to set up webhook on the service.
|
||
|
|
|
||
|
|
* Listening for webhook POST requests
|
||
|
|
|
||
|
|
The application will provide endpoint for incoming requests. Ideally one per service.
|
||
|
|
The webhook needs to be set by user on webhook service page.
|
||
|
|
|
||
|
|
* Validating webhook POST requests
|
||
|
|
|
||
|
|
Every incoming request from webhook services will be validated against the token database and search if it is valid token for service.
|
||
|
|
It will drop any invalid request.
|
||
|
|
|
||
|
|
* Processing webhook POST requests
|
||
|
|
|
||
|
|
Each message needs to be converted from webhook JSON to Fedora message. The webhook2fedmsg should provide Fedora messaging schema for topics emitted by it.
|
||
|
|
|
||
|
|
|
||
|
|
Endpoints
|
||
|
|
---------
|
||
|
|
|
||
|
|
Endpoints that should be provided by webhook2fedmsg.
|
||
|
|
|
||
|
|
* `/`
|
||
|
|
|
||
|
|
Index page. User is able to login here.
|
||
|
|
|
||
|
|
* `/tokens`
|
||
|
|
|
||
|
|
Token management page shows most information relevant to user - URLs for webhook endpoints, management of tokens.
|
||
|
|
|
||
|
|
* `/login`
|
||
|
|
|
||
|
|
Login page user is automatically redirected to, if not authenticated.
|
||
|
|
|
||
|
|
* `/<service>`
|
||
|
|
|
||
|
|
Endpoint where webhook service should sent POST requests.
|
||
|
|
|
||
|
|
* `/api`
|
||
|
|
|
||
|
|
Endpoint for API requests. API will be a nice to have alternative to web GUI.
|