Sieve implementation for Dovecot (1.1)

################################################################################
                                 !! WARNING !!
  
 This sieve implementation is highly experimental. In addition to the usual GPL 
   disclaimer you are advised not to use this for any important mail just yet!
     
      	The current status of this project is outlined in the TODO file.
  
################################################################################

Compiling and Configuring
-------------------------

Refer to INSTALL file.

Using
-----

The main purpose of this package is to replace the existing cmusieve plugin that 
is currently available for Dovecot's deliver. With this respect it is currently 
not very different from the cmusieve plugin implementation. 

Unlike cmusieve, this sieve module logs runtime errors to <scriptfile>.log if it 
can and not '<scriptfile>.err'. It appends new timestamped log entries to the 
end of the logfile. I currently didn't bother to implement log rotation, so keep 
this in mind. Some development-related debug output is sent to stderr/stdout at 
all times, this will be removed when this project matures. 

The cmusieve plugin compiled the script into a file with an appended c, e.g. 
'test.sievec'. This new implementation recognizes scripts to have the .sieve 
extension. The binary is (by default) written to a file with extension .svbin. 
This means that the default .dovecot.sieve is compiled into .dovecot.svbin. 
Included scripts are currently always compiled into the main binary, meaning 
that no other files are written and no permission to do so is necessary for the 
global script directories. 

To test the sieve engine outside deliver it is useful to execute the binaries 
that exist in the src/sieve-bin/ directory of this package. After installation, 
these scripts are available in the dovecot lib directory. The following commands
are available:

--

sievec [-d] <sieve-file> <out-file>

Compiles the script and produces a sieve binary. However, when the -d option is
provided, a code dump is written to the output file. When the output file is '-'
the dump output is written to stdout (only if -d is specified). 

--

sieved <bin-file> [<dump-file>]

Reads a sieve binary and produces a code dump. The optional dump-file parameter
provides the means to specify a file to which the dump is to be written. 
Otherwise, the dump is printed to stdout. 

-- 

sieve-test [-r <recipient address>][-s <envelope sender>]
           [-m <mailbox>][-d <dump filename>][-c] <scriptfile> <mailfile>

Reads mail message from the specified mailfile and executes the specified sieve 
script to produce a verdict. This prints an execution dump with the instructions 
encountered during execution and finally it prints a list of actions that would 
have been performed on this message.

Options:
  -r  envelope recipient address
  -s  envelope sender
  -m  the mailbox where the keep action should store
  -d  causes a dump of the generated code to be written to the specified
      file. Using - as filename causes the dump to be written to stdout
  -c  force compilation (ignore any existing binary)

--

sieve-exec

Currently undocumented (will be merged with sieve-test).

--

Various example scripts are bundled in the directory 'sieve'. 

Authors
-------

Refer to AUTHORS file.

Features
--------

* Well-structured 3-stage compiler: uses dovecot framework and avoids using
  lex/yucc. Compiler doesn't bail on first error, but tries to find more.
* Highly extendable with new sieve capabilities: This keeps the possibility of 
  plugins in mind. It should eventually provide the necessary infrastructure for 
  at least all currently known (proposed) extensions. The goal is to keep the
  extension interface provided by sieve engine as generic as possible, i.e. 
  without explicit support for specific extensions. New similar extensions can
  then use the same interface methods without changes to the sieve engine code.

What works:
* Scripts can be parsed, the grammar is fully supported. 
* Script validation (contextual analysis) works almost completely. However, 
  outgoing mail addresses are not verified yet as required. 
* Script code generation works for all core commands. Comparators, match-types 
  and address-part modifiers work as required.
* Interpreter runs core commands and tests. Comparators, match-types and 
  address-part modifiers have the desired effect. 
* The interpreter produces a result containing a set of actions to execute.
  Duplicate actions can be avoided and conflicts can be detected. Multiple 
  scripts could be executed in succession on the result object although no 
  support to do so is currently available.
* Execution of the result is supported for all core action commands and all
  fully implemented extensions (see list below).  
* Compiled binary code can be saved to and loaded back from disk. The binary 
  is structured as a set of data blocks, which can contain extension-dependent
  extra data. For example, the include extension uses this to store the 
  compiled included scripts (no external inclusion of binaries supported yet).
* This sieve implementation is available as an alternative plugin to  
  dovecot's deliver. It is not completely useful yet, but hopefully this will 
  soon be able to replace the current cmusieve implementation.

Base tests and their implementation status:
  false, true: trivial, full
  address: full
  header: full 
  exists: full
  size: full 	 
  not, anyof, allof: full

Base commands and their implementation status:
  require: full
  if,elsif,else: full
  discard: full
  keep: full
  redirect: full 
  stop: trivial, full
	
Extensions and their implementation status:

  Base specification (RFC5228):
    fileinto: full
    reject: full
    envelope: full
    encoded-character: full

  Other RFCs/drafts:
    subaddress: full
    comparator-i;ascii-numeric: full
    relational: full 
    copy: full
    regex: full, but suboptimal and no UTF-8
    body: full, but text body-transform implementation is simple
    include: almost full; needs some more work (no external binaries)
    vacation: almost full; no support for required References header
    imapflags: flag management works, but flags are not stored (no variables)
    variables: largely untested core functionality present; need to provide 
               suppor other extensions that depend on this one

  Low priority:
    notify: planned, first mailto only 
    editheader: planned, needs additional support from Dovecot though.
    mimeloop: planned

All implemented extensions are like the engine itself currently very much 
experimental. A status of 'full' does not mean that the extension is bug-free 
or even fully RFC-compliant. Other extensions will be added as soon as the 
necessary infrastructure is available. Extensions already supported by cmusieve
have priority.

Contact Info
------------

Stephan Bosch <stephan at rename-it dot nl>
IRC: Freenode, #dovecot, S[r]us

Please use the Dovecot mailing list <dovecot at dovecot.org> for questions about 
this package. You can post to the list without subscribing, the mail then waits 
in a moderator queue for a while. See http://dovecot.org/mailinglists.html