Reworks custom email settings and adds `failed` and `finished` states

Feature context

Click to expand 👇

Right now it is not possible to customize the Service Desk email address (intake and sending) in its entirety. On self-hosted instances you have more control over the used addresses, but you will still have a rather cryptic target email address for a specific service desk in a project. For .com users it's currently not possible to customize the Service Desk email at all.

There is a proposal and a further exploration around this issue. A summary of the solution path is the following: Users set up their custom email to forward all emails to the cryptic Service Desk email and provide SMTP credentials so we can send emails on their behalf. This way customers seeking support will only see the custom email address in their communication.

There is further discussion about improving and changing the general infrastructure, but this approach is a MVC to solve the issue for our customers.

🗺 How does it contribute to the whole feature?

This MR is part of a series of MRs that will follow in order to complete this feature. See #329990 (comment 1227384943) for a detailed breakdown. Here's a summary:

1. ✅ Using SMTP credentials. Foundation work.
2. ✅ Verify email ownership, correct function and setup
3. 🎯 Add settings and validation to Settings page.
   • Backend
     1. ✅ Create and Destroy Services
     2. ✅ CustomEmailController
   • Frontend
     1. ✅ CustomEmail component foundation with initial resource fetching
     2. ✅ CustomEmailForm component with resource saving
     3. ✅ CustomEmailStateStarted and CustomEmailConfirmModal components (with resource deletion) - MR dependency ❗ (merged)
     4. 🎯 CustomEmail component with failed and finished states
4. Ingest replies from custom email (16.4)
5. 👷🏻 Add documentation

What does this MR do and why?

⚠ Adds Service Desk settings custom email verific... (!128637 - merged) is a merge request dependency and this MR targets the dependency's branch to clean up diffs. Once !128637 (merged) has been merged, I'll rebase this MR on the current master. Rebased on master

🎏 This feature is hidden behind a feature flag and not used on production yet.

This MR introduces the following:

1. Refactor of custom email settings app. In !129004 (comment 1511990887) we decided to use one component instead of three components to display information for different states of custom email. This led to renaming CustomEmail to CustomEmailWrapper and CustomEmailStateStarted to CustomEmail. See !129004 (84df7f11) and !129004 (43fd0d95)
2. Adds template for the failed state that additionally displays an error label and description. See !129004 (8358c768)
3. Adds template for the finished state. Displays a toggle that enables/disables the use of the custom email address. See !129004 (3fb1a520). Started in !129209 (closed) but continued here.

The text for the error messages is basically taken from the app/views/notify/service_desk_verification_result_email.html.haml email template.

Screenshots or screen recordings

Screenshots are required for UI changes, and strongly recommended for all other merge requests.

started state

Unchanged from introducing MR Adds Service Desk settings custom email verific... (!128637 - merged) Just renamed component and incorporated other states into it.

finished state

The component displays the finished state with the toggle to enable/disable the custom email address.

With disabled custom email address

With enabled custom email address (incl. toast)

failed state

The component displays a generic set of text plus the reset button and a dynamic portion based on the verification error. Please find all possible versions as screenshots below:

SMTP host issue

Invalid credentials

Mail not received within timeframe

Incorrect from

Incorrect token

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

1. Turn on (at least) incoming_email in your gitlab.yml so you can use Service Desk. You can add an example configuration, it doesn't matter for this MR. The below should do the trick. If not copy the full config of incoming_email from the production section:

   incoming_email:
    enabled: true
    address: "gitlab-incoming+%{key}@gmail.com"

2. Enable service_desk_custom_email feature flag 🎏, e.g. for Flight project:

   Feature.enable(:service_desk_custom_email, Project.find(7)) # or your project id

3. Browse to http://127.0.0.1:3000/flightjs/Flight/edit and expand the Service Desk section and find the custom email card below the general settings.

4. Fill in a sample GMail address and provide invalid credentials. Use e.g. smtp.gmail.com as SMTP address. You need to provide a resolvable address as SMTP address.

5. You should first see the screen that your verification has started and shortly after that the failed state with the Invalid credentials error.

6. Now you can reset the configuration and start over again by pressing the "Reset custom email". button.

7. To test all other errors, reset the custom email configuration and run the following script from the rails console:

   project = Project.find(7)
   current_user = User.first
   custom_email = 'support@example.com'
   
   setting = ServiceDeskSetting.find_or_create_by!(project_id: project.id)
   setting.update!(custom_email: custom_email)
   
   credential = ServiceDesk::CustomEmailCredential.create!(
     project_id: project.id,
     smtp_address: 'smtp.gmail.com', # we need a valid smtp address
     smtp_port: 587,
     smtp_username: custom_email,
     smtp_password: 'supersecret'
   )
   
   verification = ServiceDesk::CustomEmailVerification.new(
     project_id: project.id
   )
   verification.mark_as_started!(current_user)
   verification.mark_as_failed!(:smtp_host_issue)

8. Reload the settings page and find the new error

9. Try these add-ons to simulate all remaining errors:

   verification.mark_as_started!(current_user)
   verification.mark_as_failed!(:mail_not_received_within_timeframe)

   verification.mark_as_started!(current_user)
   verification.mark_as_failed!(:incorrect_from)

   verification.mark_as_started!(current_user)
   verification.mark_as_failed!(:incorrect_token)

10. Now let's simulate a verified custom email address. Run the following in the console:

    verification.mark_as_started!(current_user)
    verification.mark_as_finished!

11. Hit refresh on the settings page and you should see the finished state. Toggle the use of the custom email. In the network tab of the developer tools, you should see API calls that return either custom_email_enabled: true or false. You should also see a toast message.

12. Reset the custom email. After resetting you should see the form.

13. Whenever you'd like to rollback everything run this on the console:

    project = Project.find(7)
    current_user = User.first
    ::ServiceDesk::CustomEmails::DestroyService.new(
      project: project,
      current_user: current_user
    ).execute

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

• I have evaluated the MR acceptance checklist for this MR.