Dovecot Lua support

Since v2.3.0 dovecot supports Lua scripting. Dovecot supports lua 5.0 or newer.

See also:

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

void dlua_register_dovecot(struct dlua_script *script)

Register dovecot variable. This item can also be extended by context specific tables, like authentication database adds dovecot.auth.

void dlua_push_event(struct event *event)

Pushes an Dovecot Event to stack.

Lua API

Event functions are available from

New in version v2.3.4.

object event

Note

object event_passthrough has same API, except the passthrough_event method is not present.

Functions:

mail-lua

New in version v2.3.4.

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

void dlua_register_mail_storage(struct dlua_script *script)

Register storage Lua interface to script context

Parameters
  • scriptdlua_script to add mail storage

bool mail_lua_plugin_get_script(struct mail_user *user, struct dlua_script **script_r)

Returns script context if available. If FALSE is returned, no Lua script has been loaded, and you should optionally deal this yourself.

Parameters
  • usermail_user

  • scriptdlua_script

void dlua_push_mail_user(struct dlua_script *script, struct mail_user *user)

Pushes a mail user on top of stack.

Parameters
  • scriptdlua_script

  • usermail_user

void dlua_push_mailbox(struct dlua_script *script, struct mailbox *box)

Pushes a mailbox on top of stack.

Parameters
  • scriptdlua_script

  • boxmailbox

void dlua_push_mail(struct dlua_script *script, struct mail *mail)

Pushes a mail on top of stack.

Parameters
  • scriptdlua_script

  • boxmail

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:

enum STATUS_MESSAGES
enum STATUS_RECENT
enum STATUS_UIDNEXT
enum STATUS_UIDVALIDITY
enum STATUS_UNSEEN
enum STATUS_FIRST_UNSEEN_SEQ
enum STATUS_KEYWORDS
enum STATUS_HIGHESTMODSEQ
enum STATUS_PERMANENT_FLAGS
enum STATUS_FIRST_RECENT_UID
enum STATUS_HIGHESTPVTMODSEQ
enum MAILBOX_FLAG_READONLY
enum MAILBOX_FLAG_SAVEONLY
enum MAILBOX_FLAG_DROP_RECENT
enum MAILBOX_FLAG_NO_INDEX_FILES
enum MAILBOX_FLAG_KEEP_LOCKED
enum MAILBOX_FLAG_IGNORE_ACLS
enum MAILBOX_FLAG_AUTO_CREATE
enum MAILBOX_FLAG_AUTO_SUBSCRIBE
enum MAILBOX_SYNC_FLAG_FULL_READ
enum MAILBOX_SYNC_FLAG_FULL_WRITE
enum MAILBOX_SYNC_FLAG_FAST
enum MAILBOX_SYNC_FLAG_NO_EXPUNGES
enum MAILBOX_SYNC_FLAG_FIX_INCONSISTENT
enum MAILBOX_SYNC_FLAG_EXPUNGE
enum MAILBOX_SYNC_FLAG_FORCE_RESYNC
enum MAILBOX_ATTRIBUTE_PREFIX_DOVECOT

String constant vendor/vendor.dovecot/

New in version 2.3.7.

enum MAILBOX_ATTRIBUTE_PREFIX_DOVECOT_PVT

String constant vendor/vendor.dovecot/pvt/

New in version 2.3.7.

enum MAILBOX_ATTRIBUTE_PREFIX_DOVECOT_PVT_SERVER

String constant vendor/vendor.dovecot/pvt/server/

New in version 2.3.7.

object mail_user

Meta

  • has tostring

  • is comparable (by username)

Functions

New in version 2.3.7.

New in version 2.3.7.

New in version 2.3.7.

New in version 2.3.7.

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

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

New in version 2.3.7.

New in version 2.3.7.

New in version 2.3.7.

New in version 2.3.7.

Variables

vname

Full mailbox name

Mailbox 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)