maddy

 1/*
 2Maddy Mail Server - Composable all-in-one email server.
 3Copyright © 2019-2020 Max Mazurov <fox.cpp@disroot.org>, Maddy Mail Server contributors
 4
 5This program is free software: you can redistribute it and/or modify
 6it under the terms of the GNU General Public License as published by
 7the Free Software Foundation, either version 3 of the License, or
 8(at your option) any later version.
 9
10This program is distributed in the hope that it will be useful,
11but WITHOUT ANY WARRANTY; without even the implied warranty of
12MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13GNU General Public License for more details.
14
15You should have received a copy of the GNU General Public License
16along with this program.  If not, see <https://www.gnu.org/licenses/>.
17*/
18
19// Package module contains modules registry and interfaces implemented
20// by modules.
21//
22// Interfaces are placed here to prevent circular dependencies.
23//
24// Each interface required by maddy for operation is provided by some object
25// called "module".  This includes authentication, storage backends, DKIM,
26// email filters, etc.  Each module may serve multiple functions. I.e. it can
27// be IMAP storage backend, SMTP downstream and authentication provider at the
28// same moment.
29//
30// Each module gets its own unique name (sql for go-imap-sql, proxy for
31// proxy module, local for local delivery perhaps, etc). Each module instance
32// also can have its own unique name can be used to refer to it in
33// configuration.
34package module
35
36import (
37	"github.com/foxcpp/maddy/framework/config"
38)
39
40// Module is the interface implemented by all maddy module instances.
41//
42// It defines basic methods used to identify instances.
43//
44// Additionally, module can implement io.Closer if it needs to perform clean-up
45// on shutdown. If module starts long-lived goroutines - they should be stopped
46// *before* Close method returns to ensure graceful shutdown.
47type Module interface {
48	// Init performs actual initialization of the module.
49	//
50	// It is not done in FuncNewModule so all module instances are
51	// registered at time of initialization, thus initialization does not
52	// depends on ordering of configuration blocks and modules can reference
53	// each other without any problems.
54	//
55	// Module can use passed config.Map to read its configuration variables.
56	Init(*config.Map) error
57
58	// Name method reports module name.
59	//
60	// It is used to reference module in the configuration and in logs.
61	Name() string
62
63	// InstanceName method reports unique name of this module instance or empty
64	// string if module instance is unnamed.
65	InstanceName() string
66}
67
68// FuncNewModule is function that creates new instance of module with specified name.
69//
70// Module.InstanceName() of the returned module object should return instName.
71// aliases slice contains other names that can be used to reference created
72// module instance.
73//
74// If module is defined inline, instName will be empty and all values
75// specified after module name in configuration will be in inlineArgs.
76type FuncNewModule func(modName, instName string, aliases, inlineArgs []string) (Module, error)
77
78// FuncNewEndpoint is a function that creates new instance of endpoint
79// module.
80//
81// Compared to regular modules, endpoint module instances are:
82// - Not registered in the global registry.
83// - Can't be defined inline.
84// - Don't have an unique name
85// - All config arguments are always passed as an 'addrs' slice and not used as
86// names.
87//
88// As a consequence of having no per-instance name, InstanceName of the module
89// object always returns the same value as Name.
90type FuncNewEndpoint func(modName string, addrs []string) (Module, error)