1 files changed, 63 insertions, 0 deletions
diff --git a/doc/wiki/Design.Storage.ErrorHandling.txt b/doc/wiki/Design.Storage.ErrorHandling.txt
new file mode 100644
index 0000000..7497598
--- /dev/null
+++ b/doc/wiki/Design.Storage.ErrorHandling.txt
@@ -0,0 +1,63 @@
+Lib-storage Error Handling
+==========================
+
+'src/lib-storage/mail-error.h' describes different types of errors and has some
+other error-related functions and macros.
+
+Only errors returning "int" can actually return a failure.
+
+ * Functions that return a pointer will never return failure with NULL. Only
+   "find" type of functions can return NULL, which means "not found".
+ * Iterators usually work by the init() returning iterator pointer and next()
+   returning a boolean. If there were any errors in either init() or next(),
+   deinit() finally returns a failure.
+
+Getting lib-storage errors
+--------------------------
+
+ * 'mailbox_list_*()' functions set their errors to the given mailbox_list
+   structure. You can get these errors with 'mailbox_list_get_last_error()'.
+ * All other functions that have some way of accessing mail_storage (mailbox,
+   mail, transactions, etc.) set their errors to the storage. You can get these
+   errors with 'mail_storage_get_last_error()'.
+    * Mail user and namespace functions have their own error handling,
+      typically by returning error strings as parameters.
+ * Both '*_get_last_error()' functions should be called soon after the error is
+   noticed, before other failing lib-storage calls overwrite the error.
+    * In deinit failures it usually doesn't matter if you get the first or the
+      last error, so it's easier to just call all the different deinit
+      functions and finally look up what the last failure was.
+
+Setting lib-storage errors
+--------------------------
+
+Errors can be set with two calls:
+
+ * 'mail_storage_set_error()' and 'mailbox_list_set_error()' should be used
+   when the error is user's fault in some way. For example invalid mailbox
+   name, out of quota, etc. The error string will be shown to user. It won't be
+   written to a log file.
+ * 'mail_storage_set_critical()' and 'mailbox_list_set_critical()' should be
+   used when the error is a problem in the system and sysadmin should be
+   notified. For example out of disk space or just in general an unexpected
+   syscall failure. The error string that will be shown to user is the
+   "Internal error occurred", but it will be logged as an error.
+ * The reason for the separation of these two is:
+    1. Only log errors that sysadmin can do something about.
+    2. Never show user anything even potentially sensitive about the system,
+       such as path names.
+
+There are also a few other calls that aren't used as often, but can be helpful:
+
+ * 'mail_storage_set_internal_error()' and 'mailbox_list_set_internal_error()'
+   simply set the user-visible error message to "Internal error occurred".
+   These can be used if the actual error was already logged.
+ * 'mail_storage_set_error_from_errno()' and
+   'mailbox_list_set_error_from_errno()' set the user-visible error message
+   based on some common 'errno' values. Currently:
+    * EACCESS, EPERM, EROFS: Permission denied
+    * ENOSPC, EDQUOT: Not enough disk space
+    * ENOENT, ENOTDIR: Not found
+    * ELOOP: Directory structure is broken
+
+(This file was created from the wiki on 2019-06-19 12:42)