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)