1 files changed, 91 insertions, 0 deletions
diff --git a/doc/wiki/Design.Storage.MailNamespace.txt b/doc/wiki/Design.Storage.MailNamespace.txt
new file mode 100644
index 0000000..1613a87
--- /dev/null
+++ b/doc/wiki/Design.Storage.MailNamespace.txt
@@ -0,0 +1,91 @@
+Mail Namespace
+==============
+
+'src/lib-storage/mail-namespace.h' describes mail namespaces. See
+<Namespaces.txt> for more information about what they are actually about.
+
+Hierarchy separators and namespace prefixes
+-------------------------------------------
+
+A namespace and <mailbox list> [Design.Storage.MailboxList.txt] has 1:1
+relationship. A namespace is mainly about dealing with hierarchy separators and
+namespace prefixes, which mailbox list doesn't know or care much about.
+
+Mailbox lists have their native hierarchy separators. For example with FS
+layout the separator is '/', because child mailboxes are physically in
+subdirectories and '/' is the separator for directories. With Maildir++ layout
+the separator is (currently) hardcoded to '.' in the maildir directory name, so
+that's its native hierarchy separator.
+
+Dovecot allows separators to be configurable, so namespaces have two
+separators:
+
+ * 'ns->sep' is the configured virtual separator, which defaults to same as
+   native separator.
+ * 'ns->real_sep' is the native separator.
+
+Namespaces also have prefixes. The prefixes are visible for users/clients and
+they appear to be part of the actual mailbox name. One commonly used namespace
+prefix is "INBOX.", so all mailboxes (other than INBOX itself) appear to be
+children of the INBOX.
+
+So the same mailbox can be visible in three different forms:
+
+ * Virtual name uses the virtual separator and namespace prefix. For example
+   "INBOX/foo/bar".
+ * Storage name uses the native separator and doesn't have a namespace prefix.
+   For example "foo.bar".
+ * Physical directory name on disk can be different again. For example with
+   Maildir++ it could be ".../Maildir/.foo.bar" (not the leading dot before
+   "foo").
+
+Users and owners
+----------------
+
+When accessing other users' shared mailboxes, there's a difference between a
+namespace's user and owner:
+
+ * 'ns->user' points to the mail user actually accessing the mailbox (e.g. the
+   IMAP connection's mail user).
+ * 'ns->owner' points to the mail user who shared the mailbox.
+
+The distinction can be important sometimes. For example if user adds or removes
+messages from the shared mailbox, the owner's quota must be updated instead of
+the user's.
+
+Functions
+---------
+
+Functions about finding namespaces:
+
+ * 'mail_namespace_find()' returns namespace for given virtual name and changes
+   the virtual name -> storage name. It also has a few variations:
+    * 'mail_namespace_find_visible()' skips hidden=yes namespaces.
+    * 'mail_namespace_find_subscribable()' skips subscriptions=no namespaces.
+    * 'mail_namespace_find_unsubscribable()' skips subscriptions=yes
+      namespaces.
+ * 'mail_namespace_find_inbox()' returns the namespace with inbox=yes. (There
+   can be only one.)
+ * 'mail_namespace_find_prefix()' returns namespace that has the given prefix.
+    * 'mail_namespace_find_prefix_nosep()' does the same, but ignores the
+      trailing separator in prefix (e.g. "foo" would find namespace with
+      prefix=foo/).
+
+Functions about translating between virtual and storage names when the
+namespace is known:
+
+ * 'mail_namespace_fix_sep()' changes virtual separators -> native separators.
+ * 'mail_namespace_get_storage_name()' changes virtual name -> storage name.
+ * 'mail_namespace_get_vname()' changes storage name -> virtual name.
+ * 'mail_namespace_update_name()' returns FALSE if virtual name doesn't
+   actually match the given namespace. Otherwise returns TRUE and changes
+   virtual name -> storage name.
+
+A single namespace can currently point to only a single storage, but there is
+already some code that attempts to make the transition to multiple storages per
+namespace easier. In general you shouldn't try to access 'ns->storage'
+directly. When creating new mailboxes,'mail_namespace_get_default_storage()'
+returns the storage that should be used. For other purposes you should find the
+storage via <mailbox list> [Design.Storage.MailboxList.txt] functions.
+
+(This file was created from the wiki on 2019-06-19 12:42)