maddy

 1# Modules introduction
 2
 3maddy is built of many small components called "modules". Each module does one
 4certain well-defined task. Modules can be connected to each other in arbitrary
 5ways to achieve wanted functionality. Default configuration file defines
 6set of modules that together implement typical email server stack.
 7
 8To specify the module that should be used by another module for something, look
 9for configuration directives with "module reference" argument. Then
10put the module name as an argument for it. Optionally, if referenced module
11needs that, put additional arguments after the name. You can also put a
12configuration block with additional directives specifing the module
13configuration.
14
15Here are some examples:
16
17```
18smtp ... {
19    # Deliver messages to the 'dummy' module with the default configuration.
20    deliver_to dummy
21
22    # Deliver messages to the 'target.smtp' module with
23    # 'tcp://127.0.0.1:1125' argument as a configuration.
24    deliver_to smtp tcp://127.0.0.1:1125
25
26    # Deliver messages to the 'queue' module with the specified configuration.
27    deliver_to queue {
28        target ...
29        max_tries 10
30    }
31}
32```
33
34Additionally, module configuration can be placed in a separate named block
35at the top-level and referenced by its name where it is needed.
36
37Here is the example:
38```
39storage.imapsql local_mailboxes {
40    driver sqlite3
41    dsn all.db
42}
43
44smtp ... {
45    deliver_to &local_mailboxes
46}
47```
48
49It is recommended to use this syntax for modules that are 'expensive' to
50initialize such as storage backends and authentication providers.
51
52For top-level configuration block definition, syntax is as follows:
53```
54namespace.module_name config_block_name... {
55    module_configuration
56}
57```
58If config\_block\_name is omitted, it will be the same as module\_name. Multiple
59names can be specified. All names must be unique.
60
61Note the "storage." prefix. This is the actual module name and includes
62"namespace". It is a little cheating to make more concise names and can
63be omitted when you reference the module where it is used since it can
64be implied (e.g. putting module reference in "check{}" likely means you want
65something with "check." prefix)
66
67Usual module arguments can't be specified when using this syntax, however,
68modules usually provide explicit directives that allow to specify the needed
69values. For example 'sql sqlite3 all.db' is equivalent to
70```
71storage.imapsql {
72    driver sqlite3
73    dsn all.db
74}
75```
76