//Cloudogu EcoSystem Docs

Guidelines for Handling Errors in the Baseline Tool

This document describes the guidelines to be followed when handling errors in the Baseline Tool.

Guidelines - Backend

1. Struct WithCode serves as a communication medium

WithCode is a separate error type (struct) and is used within the baseline backend to pass information to the end user in the event of an error. Attention is paid to the wording and structure of the existing errors and their error codes and texts. These can be found in the file errorMessages.go in the package customerror. package.

The type WithCode allows to link several error messages together and thus to create very flexible and detailed error messages. It is also possible to define and pass parameters.

In general, there are three different types of errors in the Baseline Tool: Context errors, technical errors and generic Errors

Context errors

Context errors are used to tell the user the context of the operation being performed. An example of context error is "The projects could not be loaded". The context error is very important so that the user can easily understand the relationship between the error message and the operation. In a concatenation of WithCode-errors, the first error should always be a context error. Which context error belongs to a request handler method is defined in the corresponding method itself.

Technical errors

Technical errors serve to communicate the cause of an error to the user in a simple, plausible and understandable form. It should be noted that a technical error can consist of several technical errors. An example of a technical error is "The connection to the Nexus cannot be established. Please contact your administrators to have them check the Nexus and the project configuration." . As you can see, the technical errors serve to solve problems and help the user to understand them and, if necessary, to fix them.

Generic errors

Generic errors are used to replace complex problems or unhandled errors with a user-friendly generic error message.

2. Collection of error codes and translation texts in a central location

All error codes and translation texts are collected in a central location - the file errorMessages.go. The error texts are grouped here by language (currently only German).

3. Error handling in request handlers via central error handling method

Each endpoint is assigned its own context error (see above), which is returned as a top-level error when an error occurs.

For error handling in the request handlers there is in the file requestErrorHandler.go in the package customerror the method HandleErrorAndShouldAbort, which handles the error handling for all request handler methods.

The method checks whether the current request should be aborted by the error that has occurred, and writes the error into the request context.

The default status code written into the request context is 500 - internal server error. In the However, the correct status code for known errors can and should be defined in the request handlers. For example, the correct status code for the error case when requesting a project, if the project cannot be found, is 404 - Status not found. The definition of these status codes takes place in the form of a map in the individual methods of the request handler and is passed as a parameter to the method for error handling of requests.

4. Own, concrete errors outside the request handler

In order to make errors recognisable in various places and to be able to react to a concrete error, it is possible to define your own errors outside of a request handler. This is usually for atomic errors that occur in the own code (i.e. no errors when calling another method).

Example: Based on the name, the appropriate collector for collecting artefacts is to be created and returned. If no matching collector can be found for the name, an error should be returned. Here a specially defined error is used, which means that no collector with the corresponding name exists. This is an atomic error, which is technically returned if no corresponding collector exists for the name passed as a parameter. In the request handler, a separate status code can then be defined for this error using the error code.

For non-atomic errors or errors that do not need to be separately identifiable, fmt.errorf(...) can still be used. can still be used.

Guidelines - Frontend

1. Persistent error messages

Error messages should not be closed automatically after they are displayed.

2. Toasts with CustomSnackbar

Successful or erroneous operations that are displayed as a toast notification to the user must use the exported functions showSuccess and showError of the CustomSnackbar. The CustomSnackbar ensures the formatting and accessibility of the notifications.