.. _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.