103 lines
2.9 KiB
ReStructuredText
103 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.
|