 |
Elektra 0.11.0
|
|
Elektra 0.11.0
|
This document explains how to categorize errors and should act as a form of guideline. The categorization aims to reduce duplicated errors and the maintenance effort for errors.
Errors along with their unique code only primarily exist because they can be reacted differently on programmatically. To get an idea of programmatic reactions take a method call which returns a Timeout error. Naturally a senseful reaction would be to retry at a later point in time. So the reaction here would be to retry with a time based approach. On the other hand it does not make sense to differentiate between No Write Permission and No Read Permission as the application just knows that it simply cannot access the desired resource and tells the user to grant it.
Categories are hierarchically structured. In some categories you cannot put an error such as Permanent errors (see below) because they are too general and developers should choose a more specific category. Even though most categories which allow putting errors into are at the end of the hierarchy (leafs), it may also be the case that a more general category also allows errors to be put in (e.g., Resource Errors). The categories below are marked as concrete or abstract, meaning that you either can or cannot create errors for the category. Please choose the most specific category as possible when trying to assign an error to a category.
If you feel for a new category, please forge a design decision document and make a PR to Elektra's repo.
Now we will investigate each category in more detail and when to put an error/warning in there.
For a complete structural overview please visit the corresponding design decision document
The branch category Permanent Errors refer to such errors which cannot be fixed by retry at all. Permanent Errors are subdivided into
Resource Errors are all kind of permission, existence and resource errors which are essential for Elektra to operate. Resource errors is a branch category which also allows for errors to be put in. Compared to validation errors this category has its focus the underlying system resources whereas validation errors for usages with specifications. Examples are missing files/ directories or insufficient permission to execute certain commands (e.g. you would require sudo permissions). Reactions are fixing the permissions, remount, creating the file/directory and retry the operation. Compared to validation errors, administrators would change the specification or retry with a different value.
Out of Memory Errors are special resource errors which come from failed elektraMalloc calls primarily as no more memory could be allocated for the application. Errors with not enough hard disc space do not belong here but into Resource. Such errors will gain special handling in future releases and users cannot deal with such errors as of now.
Installation Errors are errors that are related to a wrong installation such as wrong plugin names, missing backends, initialization errors, misconfiguration of Elektra etc. Installation errors might also be non-Elektra specific but also from dependent library/applications such as gpg. Also, plugin configuration errors belong to Installation Errors as this happens during mounting. Users will have to reconfigure, reinstall, recompile (with other settings) Elektra in order to get rid of this error or fix the installation of the corresponding library/application.
Logical Errors is a branch category in which you indicate a logical flaw in the code such as internal errors, not implemented features, passing illegal parameters to functions, plugins which do not behave accordingly (wrong return codes, uncaught exceptions) or errors which should not happen such as going into a default branch when you are assured that all cases are covered. Usually such errors come with a message to report such failures to Elektra's bugtracker. Applications cannot handle such errors themselves.
Internal Errors are such errors which indicate a flaw or bug in the internal logic of Elektra. Examples are going into a default branch which you do never expect to happen. Another use case is if you use an external library and have to catch a generic exception. If you can however, catch the most specific exceptions and convert them into the appropriate category. If you have to use this error please add a message indicating that this bug should be reported.
Interface Errors indicate a wrong usage of Elektra's API. Compared to internal errors this category does not indicate a bug but a misuse. An example would be to pass a NULL pointer to kdbGet. Also, violations of the backend belong into this category. Compared to semantic validation errors, this category has its focus on detecting wrong usages of the API instead of a "retry with a
different value" approach. Also, validation errors focus on specifications of configurations whereas this category tries to handle specifications for APIs. Users should investigate the concrete reason and might use a different, more appropriate method or change their passed values before retrying.
Plugin Misbehavior Errors indicate that a plugin does not behave in an intended way. Unrecognized commands, unknown return codes, plugin creation errors, etc. belong to this category. Also, uncaught exceptions belong here because Elektra expects all exceptions to be caught. For wrong plugin versions please use Installation errors. Users can try to remount, recompile the plugin under different options or use a different plugin (e.g., switching to mini instead of ini).
Conflicting State Errors are errors where the current state is incompatible with the attempted operation. These kind of errors are usually in resolver plugins when the state of the file has changed without the system knowing. An example would be to try to push your changes into a Git repository where the remote branch has already changed. Try to synchronize your internal state and retry to get rid of this error. Examples are the need for calling kdbGet before kdbSet.
Validation Errors are heavily used for Elektra's configuration specification feature and should tell users that their given input does not match a certain pattern/type/expected semantic etc.
Validation errors can either be syntactic or semantic.
Syntactic Errors are errors which tell users or applications that the current format is not valid. Examples are wrong date formats or missing closing brackets ] inside of a regular expression when it is checked. Also, path related errors like missing slashes come into this category. Parsing errors are also associated with syntactic errors such as unexpected encounters like missing line endings, illegal characters or wrong encodings. Also, transformation and conversion errors are to be categorizes here because the format of the given input does not allow such actions. Since syntactic errors demand a specific format and structure, also structural validation errors belong here. Users should try a different value/format and retry setting it with Elektra.
Semantic Errors are errors which indicate a misunderstanding of the intended meaning between a user's/developer's/administrator's way of seeing a setting and the application's one. The main focus of this category is to enforce specifications compared to other categories. So if users provide input which do not match prespecified criteria even though syntactically everything is valid, this category should be used. Examples are references to non-existent keys (reference plugin), setting values to keys which require to be empty (required plugin), wrong provided values in a specification if you restricted the values (enum plugin), etc.
Users should try a different value or fix the underlying specification and retry again.
1.9.1