Service Messages Feature Description

Use Case

Mastodon instances like mastodon.art provide their community rules via a mandatory dialog that has to be accepted before sign up. Similarly Forgejo instances could benefit from a dedicated “Service Messages” Mechanism that allows organizations to prominently show their guidelines to users on certain occasions in the login flow. The requirement here is that agreement to the guidelines happens after sign up. Also this feature is a requirement for compliance within regulated entities. Here, regulators require that certain legal information reach the user and the user decision to accept the info needs to be recorded.

For example:

• Community Guidelines could be shown to users once on first sign in and after they have been updated with a prominent pop up
  • Acceptance of these guidelines may be a condition to continue

See uctkm002-admin-sets-service for an exemplary flow

Requirements

• uctkm002-1: When a user logs in for the first time, an “Service Message” should be shown to the user.
• uctkm002-2: When the Service Message is changed, it should be shown again to all users on their next login.
• uctkm002-3: Due to compliance, it is necessary to document that the user has seen and agreed to the message presented. To continue interacting with forgejo an “Accept” Button needs to be clicked.
• uctkm002-4: When the “Accept” Button named in uctkm002-3 is clicked, the timestamp of the consent action must be saved in the database.
• (Not needed currently) uctkm002-5: If more than one text needs to be shown to the user, the admin can create and manage these texts in Forgejo and set options for them individually.
• (Not needed currently) uctkm002-6: A “Service Message” can be configured so that it either requires interaction to proceed (it can be blocking the user flow) or is shown passively and can be discarded by the user at will.

Feature Description

A Service Message is a notification to all users that can only be set by an instance admin. There is currently one kind of Service Message: “modal”.

• A “Modal” is visually prominent and stops the user in their workflow so interaction is mandatory
• To continue, the user must press the Confirm button
• On confirming the Modal, the confirmation time stamp will be saved along with the user id in the service_message struct
• On denying the Modal, the user is logged out
• The aim of the Modal is to make sure information is read and acknowledged and the acknowledgment is recorded

The management UI will provide a typed text input field with markdown and preview capability. Saving the field will immediately show the service message to any logged in user (also the admin) after their next request to the UI. With this behaviour we can also reach users who might be logged in for a longer period of time.

Technical Diagrams

The connection between templates and routers/web is described here uctkm002-frontend-backend-connection.

An initial technical view of how a confirmation may be saved: uctkm002-saving-confirmation.

ADR

Web Endpoints for Management

To avoid conflicts with the existing structure the service message was implemented using:

• A dedicated web endpoint admin/service_message for the management of the feature is implemented
• A dedicated template admin/service_message and a dedicated form is used

POST /admin/service_message/ # Create, Update POST /admin/service_message/delete_modal # Delete GET /admin/service_message/ # Show current service message

Logic for showing the service message

Uctkm002-1&2 have in common, that the user has not accepted an existing modal service message yet. Leveraging that fact, we just need to check the following:

• Did the user accept the service message yet?
• Is the service message timestamp of the user older than the timestamp of the current service message?

If any of these questions are answered yes, the service message is shown.

Distinction by type

Considering the requirements and feature description, it becomes apparent that probably only few types of Service Messages will exist (and be shown at the same time).

So for now it makes sense to have typed input fields in the admin management UI. Those fields will then send a form POST to {{AppSubUrl}}/admin/service_message?sm_type="modal". This saves us creating and managing options while being clearer to the admin as well. Currently modal will be the only type. If more Service Messages need to be shown, the process could include adding types like banner.

Confirm button and saving a timestamp to database

The confirm button triggers a POST action against {{AppSubUrl}}/user/{username}/confirm?sm_type=sm.type. See uctkm002-saving-confirmation for the full flow.

It makes sense to save the confirmation in the user model for the following reasons:

1. Saving the confirmation per user in ServiceMessage would require potentially hundreds of thousands of requests to the DB to a single table.
2. Cleanup Jobs would need to be done to also delete users from the ServiceMessage table
3. RAM usage will increase if we always have a huge list of users loaded when a ServiceMessage is loaded from DB
4. The user/{username} endpoint requires an authenticated request, so we can make sure the user is already logged in.
5. The User Model is already loaded and interacted upon when a user is logged in