1 files changed, 249 insertions, 0 deletions
diff --git a/doc/wiki/Design.Lua.txt b/doc/wiki/Design.Lua.txt
new file mode 100644
index 0000000..805e00b
--- /dev/null
+++ b/doc/wiki/Design.Lua.txt
@@ -0,0 +1,249 @@
+Dovecot Lua support
+===================
+
+Since v2.3.0 dovecot supports Lua scripting. Dovecot supports lua 5.0 or newer.
+See also:
+
+ * <Lua based authentication> [AuthDatabase.Lua.txt]. Since v2.3.0
+ * <Lua push notifications> [Plugins.PushNotification.txt]. Since v2.3.4
+
+lib-lua
+-------
+
+Dovecot provides a lib-lua internal helper as part of libdovecot.so. It has
+facilities for loading scripts from various sources, and also helps with
+reusing scripts by keeping track of which scripts are loaded. Each script has
+it's own memory pool, which is guaranteed to be released when script is
+unloaded.
+
+When script is loaded, *script_load* function is called if found. This can
+return non-zero to indicate that the script has a problem.
+
+C API
+-----
+
+ * 'dlua_register_dovecot(script)'
+
+Register dovecot variable. This item can also be extended by context specific
+tables, like authentication database adds *dovecot.auth*.
+
+ * 'dlua_push_event(event)'
+
+Pushes an Dovecot Event to stack.
+
+Lua API
+-------
+
+ * 'i_debug(text)'
+ * 'i_error(text)'
+ * 'i_info(text)'
+ * 'i_warning(text)'
+
+Functions within dovecot variable that do generic logging
+
+Event functions are available from v2.3.4 on
+
+ * 'dovecot.event()'
+ * 'dovecot.event(parent)'
+
+Creates a new event for dovecot
+
+object event
+------------
+
+Note:
+
+ * object event_passthrough has same API, except the 'passthrough_event' method
+   is not present.
+
+Functions:
+
+ * 'append_log_prefix("prefix")' - set prefix to append
+ * 'replace_log_prefix("prefix")' - replace append prefix
+ * 'set_name("name")' - set name for event
+ * 'add_str("key","value")' - add a key-value pair to event
+ * 'add_int("key",1)' - add a key-value pair to event
+ * 'add_timeval("key",seconds)' - add a key-value pair to event
+ * 'inc_int("key",1)' - increment key-value pair
+ * 'log_debug("message")' - emit debug message
+ * 'log_info("message")' - emit info message
+ * 'log_warning("message")' - emit warning message
+ * 'log_error("message")' - emit error message
+ * 'passthrough_event()' - returns an passthrough event. A log message *must
+   be* logged or else a panic will occur.
+
+mail-lua
+--------
+
+Available from v2.3.4 on
+
+mail-lua is a plugin that can be loaded to provide API for mail storage Lua
+plugins. Mail-lua provides a common script to be used in mail storage instead
+of per-plugin scripts.
+
+C API
+-----
+
+ * 'dlua_register_mail_storage(script)'
+
+Register storage Lua interface to script context
+
+ * 'bool mail_lua_plugin_get_script(user, script_r)'
+
+Returns script context if available. If FALSE is returned, no Lua script has
+been loaded, and you should optionally deal this yourself.
+
+ * 'dlua_push_mail_user(script, user)'
+
+Pushes a mail user on top of stack.
+
+ * 'dlua_push_mailbox(script, box)'
+
+Pushes a mailbox on top of stack.
+
+ * 'dlua_push_mail(script, mail)'
+
+Pushes a mail on top of stack.
+
+Lua API
+-------
+
+When mail user is created, a script is loaded if present as *mail_lua_script*
+and *mail_user_created* is called if present in script.
+
+On deinitialization, *mail_user_deinit_pre* is called first, if present,
+followed by *mail_user_deinit*.
+
+dovecot.storage
+---------------
+
+Following constants are specified
+
+ * 'STATUS_MESSAGES'
+ * 'STATUS_RECENT'
+ * 'STATUS_UIDNEXT'
+ * 'STATUS_UIDVALIDITY'
+ * 'STATUS_UNSEEN'
+ * 'STATUS_FIRST_UNSEEN_SEQ'
+ * 'STATUS_KEYWORDS'
+ * 'STATUS_HIGHESTMODSEQ'
+ * 'STATUS_PERMANENT_FLAGS'
+ * 'STATUS_FIRST_RECENT_UID'
+ * 'STATUS_HIGHESTPVTMODSEQ'
+ * 'MAILBOX_FLAG_READONLY'
+ * 'MAILBOX_FLAG_SAVEONLY'
+ * 'MAILBOX_FLAG_DROP_RECENT'
+ * 'MAILBOX_FLAG_NO_INDEX_FILES'
+ * 'MAILBOX_FLAG_KEEP_LOCKED'
+ * 'MAILBOX_FLAG_IGNORE_ACLS'
+ * 'MAILBOX_FLAG_AUTO_CREATE'
+ * 'MAILBOX_FLAG_AUTO_SUBSCRIBE'
+ * 'MAILBOX_SYNC_FLAG_FULL_READ'
+ * 'MAILBOX_SYNC_FLAG_FULL_WRITE'
+ * 'MAILBOX_SYNC_FLAG_FAST'
+ * 'MAILBOX_SYNC_FLAG_NO_EXPUNGES'
+ * 'MAILBOX_SYNC_FLAG_FIX_INCONSISTENT'
+ * 'MAILBOX_SYNC_FLAG_EXPUNGE'
+ * 'MAILBOX_SYNC_FLAG_FORCE_RESYNC'
+
+object mail_user
+----------------
+
+Meta:
+
+ * has tostring
+ * is comparable (by username)
+
+Functions:
+
+ * 'plugin_getenv(key)' - returns key from user plugin settings or userdb
+   environment
+ * 'var_expand(template)' - expands mail user variables (see <Variables.txt>)
+ * 'mailbox(name, flags)' - allocates a mailbox, flags optional
+
+Variables:
+
+ * 'home' - home directory (if available)
+ * 'username' - user's name
+ * 'uid' - system uid
+ * 'gid' - system gid
+ * 'service' - IMAP/POP3/LMTP/LDA/...
+ * 'session_id' - Current session ID
+ * 'session_create_time' - When session was created
+ * 'nonexistent' - If user does not really exist
+ * 'anonymous' - If user is anonymous
+ * 'autocreated' - If user was automatically created internally for some
+   operation
+ * 'mail_debug' - If debugging is turned on
+ * 'fuzzy_search' - FIXME: Undocumented
+ * 'dsyncing' - If user is being dsync'd
+ * 'session_restored' - If this is a restored session
+
+object mailbox
+--------------
+
+Meta:
+
+ * has tostring
+ * is comparable (by full mailbox name)
+
+Functions:
+
+ * 'open()' - opens the mailbox
+ * 'close()' - closes the mailbox
+ * 'free()' - releases mailbox (must be done)
+ * 'sync(flags)' - synchronizes the mailbox (should usually be done, flags
+   optional)
+ * 'status(item,item,item...)' - returns requested mailbox status items as
+   table
+
+Variables:
+
+ * 'vname' - Full mailbox name
+ * 'name' - Mailbox name
+
+table mailbox status
+--------------------
+
+Variables:
+
+ * 'mailbox' - full name of mailbox
+ * 'messages' - number of messages
+ * 'recent' - number of \Recent messages
+ * 'unseen' - number of \Unseen messages
+ * 'uidvalidity' - current UID validity
+ * 'uidnext' - next UID
+ * 'first_unseen_seq' - first seqno of unseen mail
+ * 'first_recent_uid' - first UID of unseen mail
+ * 'highest_modseq' - highest modification sequence
+ * 'highest_pvt_modseq' - highest private modification sequence
+ * 'permanent_flags' - supported permanent flags as a bitmask
+ * 'flags' - supported flags as a bitmask
+ * 'permanent_keywords' - if permanent keywords are supported
+ * 'allow_new_keywords' - if new keywords can be added
+ * 'nonpermanent_modseqs' - whether non-permanent keywords are allowed
+ * 'no_modseq_tracking' - no modification sequence tracking
+ * 'have_guids' - whether GUIDs exist
+ * 'have_save_guids' - whether GUIDs can be saved
+ * 'have_only_guid128' - whether GUIDs are 128 bit always
+ * 'keywords' - table of current keywords
+
+object mail
+-----------
+
+Meta:
+
+ * has tostring
+ * is comparable (within same mailbox, by UID)
+
+Functions:
+
+ * None yet
+
+Variables:
+
+ * 'mailbox' - mailbox object
+ * 'seq' - Sequence number (can change)
+ * 'uid' - UID number (immutable)
+
+(This file was created from the wiki on 2019-06-19 12:42)