module: Allow config blocks to have more than one name

This allows more readable configuration files without additional
explanations in cases where a single module is used for multiple
purposes.

Also cleans up certain problems with modules that rely on block
names having certain semantics (e.g. endpoint modules).

check_test.go

@@ -59,7 +59,7 @@ func (tcs *testCheckState) Close() error {
 }
 
 func init() {
-	module.Register("test_check", func(modName, instanceName string) (module.Module, error) {
+	module.Register("test_check", func(modName, instanceName string, aliases []string) (module.Module, error) {
 		return &testCheck{}, nil
 	})
 	module.RegisterInstance(&testCheck{}, nil)

config.go

@@ -16,11 +16,7 @@ Config matchers for module interfaces.
 */
 
 // createInlineModule is a helper function for config matchers that can create inline modules.
-func createInlineModule(modName, instName string) (module.Module, error) {
-	if instName != "" && module.HasInstance(instName) {
-		return nil, fmt.Errorf("module instance named %s already exists", instName)
-	}
-
+func createInlineModule(modName, instName string, aliases []string) (module.Module, error) {
 	newMod := module.Get(modName)
 	if newMod == nil {
 		return nil, fmt.Errorf("unknown module: %s", modName)
@@ -28,7 +24,7 @@ func createInlineModule(modName, instName string) (module.Module, error) {
 
 	log.Debugln("module create", modName, instName, "(inline)")
 
-	return newMod(modName, instName)
+	return newMod(modName, instName, aliases)
 }
 
 // initInlineModule constructs "faked" config tree and passes it to module
@@ -37,13 +33,7 @@ func createInlineModule(modName, instName string) (module.Module, error) {
 // args must contain at least one argument, otherwise initInlineModule panics.
 func initInlineModule(modObj module.Module, globals map[string]interface{}, args []string, block *config.Node) error {
 	log.Debugln("module init", modObj.Name(), modObj.InstanceName(), "(inline)")
-	return modObj.Init(config.NewMap(globals, &config.Node{
-		Name:     args[0],
-		Args:     args[1:],
-		Children: block.Children,
-		File:     block.File,
-		Line:     block.Line,
-	}))
+	return modObj.Init(config.NewMap(globals, block))
 }
 
 // moduleFromNode does all work to create or get existing module object with a certain type.
@@ -53,8 +43,8 @@ func initInlineModule(modObj module.Module, globals map[string]interface{}, args
 // inlineCfg should contain configuration directives for inline declarations.
 // args should contain values that are used to create module.
 // It should be either module name + instance name or just module name. Further extensions
-// may add other string arguments (currently, they can be accessed by module code using
-// Values field of config.Map passed to Init).
+// may add other string arguments (currently, they can be accessed by module instances
+// as aliases argument to constructor).
 //
 // It checks using reflection whether it is possible to store a module object into modObj
 // pointer (e.g. it implements all necessary interfaces) and stores it if everything is fine.
@@ -80,15 +70,17 @@ func moduleFromNode(args []string, inlineCfg *config.Node, globals map[string]in
 	if inlineCfg.Children != nil {
 		modName := args[0]
 
+		modAliases := args[1:]
 		instName := ""
 		if len(args) == 2 {
+			modAliases = args[2:]
 			instName = args[1]
 		}
 
-		modObj, err = createInlineModule(modName, instName)
+		modObj, err = createInlineModule(modName, instName, modAliases)
 	} else {
 		if len(args) != 1 {
-			return config.NodeErr(inlineCfg, "exactly one argument is required")
+			return config.NodeErr(inlineCfg, "exactly one argument is required for reference to existing module")
 		}
 		modObj, err = module.GetInstance(args[0])
 	}

externalauth.go

@@ -25,7 +25,7 @@ type ExternalAuth struct {
 	Log log.Logger
 }
 
-func NewExternalAuth(modName, instName string) (module.Module, error) {
+func NewExternalAuth(modName, instName string, _ []string) (module.Module, error) {
 	ea := &ExternalAuth{
 		modName:  modName,
 		instName: instName,

imap.go

@@ -27,6 +27,7 @@ import (
 
 type IMAPEndpoint struct {
 	name      string
+	aliases   []string
 	serv      *imapserver.Server
 	listeners []net.Listener
 	Auth      module.AuthProvider
@@ -39,9 +40,10 @@ type IMAPEndpoint struct {
 	Log log.Logger
 }
 
-func NewIMAPEndpoint(_, instName string) (module.Module, error) {
+func NewIMAPEndpoint(_, instName string, aliases []string) (module.Module, error) {
 	endp := &IMAPEndpoint{
 		name:    instName,
+		aliases: aliases,
 		Log:     log.Logger{Name: "imap"},
 	}
 	endp.name = instName
@@ -71,8 +73,9 @@ func (endp *IMAPEndpoint) Init(cfg *config.Map) error {
 		return fmt.Errorf("imap: storage module %T does not implement imapbackend.BackendUpdater", endp.Store)
 	}
 
-	addresses := make([]Address, 0, len(cfg.Block.Args))
-	for _, addr := range cfg.Block.Args {
+	args := append([]string{endp.name}, endp.aliases...)
+	addresses := make([]Address, 0, len(args))
+	for _, addr := range args {
 		saddr, err := standardizeAddress(addr)
 		if err != nil {
 			return fmt.Errorf("imap: invalid address: %s", endp.name)

maddy.conf

@@ -11,7 +11,7 @@ auth_domains example.org
 
 # Create and initialize sql module, it provides simple authentication and
 # storage backend using one database for everything.
-sql {
+sql local_mailboxes local_authdb {
     driver sqlite3
     dsn /var/lib/maddy/all.db
 }
@@ -25,7 +25,7 @@ smtp smtp://0.0.0.0:25 {
     # All messages for the recipients at example.org should be
     # delivered to local mailboxes.
     destination example.org {
-        deliver_to sql
+        deliver_to local_mailboxes
     }
 
     # Other recipients are rejected because we are not an open relay.
@@ -36,21 +36,21 @@ smtp smtp://0.0.0.0:25 {
 
 submission smtps://0.0.0.0:465 smtp://0.0.0.0:587 {
     # Use sql module for authentication.
-    auth sql
+    auth local_auth
 
     # All messages for the recipients at example.org should be
     # delivered to local mailboxes directly.
     destination example.org {
-        deliver_to sql
+        deliver_to local_mailboxes
     }
 
     # Remaining recipients are scheduled for remote delivery.
     default_destination {
-        deliver_to out_queue
+        deliver_to remote_queue
     }
 }
 
-queue out_queue {
+queue remote_queue {
     # Try to deliver message up to 8 tries. Note that this counter is not per
     # recipient, but for entire message.
     max_tries 8
@@ -67,8 +67,6 @@ queue out_queue {
 remote { }
 
 imap imaps://0.0.0.0:993 imap://0.0.0.0:143 {
-    # Use sql module for authentication.
-    auth sql
-    # And also for storage.
-    storage sql
+    auth local_authdb
+    storage local_mailboxes
 }

maddy.conf.5.scd

@@ -174,13 +174,15 @@ module2 config2 {
 Generic syntax for module configuration block is as follows:
 
 ```
-module_name config_block_name {
+module_name config_block_name optional_aliases... {
     configuration
     directives
     for_this
     module
 }
 ```
+If you specify more than one config_block_name, they all will be usable.
+Basically, they will be aliased to the first name.
 
 If config_block_name is omitted, it will be the same as module_name.
 Configuration block name must be unique across all configuration.

maddy.go

@@ -36,10 +36,12 @@ func Start(cfg []config.Node) error {
 
 	for _, block := range unmatched {
 		var instName string
+		var modAliases []string
 		if len(block.Args) == 0 {
 			instName = block.Name
 		} else {
 			instName = block.Args[0]
+			modAliases = block.Args[1:]
 		}
 
 		modName := block.Name
@@ -54,13 +56,20 @@ func Start(cfg []config.Node) error {
 		}
 
 		log.Debugln("module create", modName, instName)
-		inst, err := factory(modName, instName)
+		inst, err := factory(modName, instName, modAliases)
 		if err != nil {
 			return err
 		}
 
 		block := block
 		module.RegisterInstance(inst, config.NewMap(globals.Values, &block))
+		for _, alias := range modAliases {
+			if module.HasInstance(alias) {
+				return config.NodeErr(&block, "module instance named %s already exists", alias)
+			}
+			module.RegisterAlias(alias, instName)
+			log.Debugln("module alias", alias, "->", instName)
+		}
 		instances[instName] = modInfo{instance: inst, cfg: block}
 	}
 

module/instances.go

@@ -12,13 +12,14 @@ var (
 		mod Module
 		cfg *config.Map
 	})
+	aliases = make(map[string]string)
 
 	Initialized = make(map[string]bool)
 )
 
-// Register adds module instance to the global registry.
+// RegisterInstance adds module instance to the global registry.
 //
-// Instnace name must be unique. Second RegisterInstance with same instance
+// Instance name must be unique. Second RegisterInstance with same instance
 // name will replace previous.
 func RegisterInstance(inst Module, cfg *config.Map) {
 	instances[inst.InstanceName()] = struct {
@@ -27,7 +28,20 @@ func RegisterInstance(inst Module, cfg *config.Map) {
 	}{inst, cfg}
 }
 
+// RegisterAlias creates an association between a certain name and instance name.
+//
+// After RegisterAlias, module.GetInstance(aliasName) will return the same
+// result as module.GetInstance(instName).
+func RegisterAlias(aliasName, instName string) {
+	aliases[aliasName] = instName
+}
+
 func HasInstance(name string) bool {
+	aliasedName := aliases[name]
+	if aliasedName != "" {
+		name = aliasedName
+	}
+
 	_, ok := instances[name]
 	return ok
 }
@@ -38,6 +52,11 @@ func HasInstance(name string) bool {
 // Error is returned if module initialization fails or module instance does not
 // exists.
 func GetInstance(name string) (Module, error) {
+	aliasedName := aliases[name]
+	if aliasedName != "" {
+		name = aliasedName
+	}
+
 	mod, ok := instances[name]
 	if !ok {
 		return nil, fmt.Errorf("unknown module instance: %s", name)

module/module.go

@@ -46,5 +46,22 @@ type Module interface {
 }
 
 // FuncNewModule is function that creates new instance of module with specified name.
-// Note that this function should not do any form of initialization.
-type FuncNewModule func(modName, instanceName string) (Module, error)
+//
+// Module.InstanceName() of the returned module object should return instName.
+// aliases slice contains other names that can be used to reference created
+// module instance. Here is the example of top-level declarations and the
+// corresponding arguments passed to module constructor:
+//
+// modname { }
+// Arguments: "modname", "modname", nil.
+//
+// modname instname { }
+// Arguments: "modname", "instname", nil
+//
+// modname instname secondname1 secondname2 { }
+// Arguments: "modname", "instname", []string{"secondname1", "secondname2"}
+//
+// Note modules are allowed to attach additional meaning to used names.
+// For example, endpoint modules use instance name and aliases as addresses
+// to listen on.
+type FuncNewModule func(modName, instName string, aliases []string) (Module, error)

queue.go

@@ -91,7 +91,7 @@ type QueueMetadata struct {
 	LastAttempt time.Time
 }
 
-func NewQueue(_, instName string) (module.Module, error) {
+func NewQueue(_, instName string, _ []string) (module.Module, error) {
 	return &Queue{
 		name:             instName,
 		initialRetryTime: 15 * time.Minute,

queue_test.go

@@ -38,7 +38,7 @@ func cleanQueue(t *testing.T, q *Queue) {
 }
 
 func newTestQueueDir(t *testing.T, target module.DeliveryTarget, dir string) *Queue {
-	mod, _ := NewQueue("", "queue")
+	mod, _ := NewQueue("", "queue", nil)
 	q := mod.(*Queue)
 	q.Log = testLogger(t, "queue")
 	q.initialRetryTime = 0

remote.go

@@ -41,7 +41,7 @@ type RemoteTarget struct {
 
 var _ module.DeliveryTarget = &RemoteTarget{}
 
-func NewRemoteTarget(_, instName string) (module.Module, error) {
+func NewRemoteTarget(_, instName string, _ []string) (module.Module, error) {
 	return &RemoteTarget{
 		name:        instName,
 		resolver:    net.DefaultResolver,

smtp.go

@@ -138,6 +138,7 @@ type SMTPEndpoint struct {
 	Auth       module.AuthProvider
 	serv       *smtp.Server
 	name       string
+	aliases    []string
 	listeners  []net.Listener
 	dispatcher *Dispatcher
 
@@ -158,9 +159,10 @@ func (endp *SMTPEndpoint) InstanceName() string {
 	return endp.name
 }
 
-func NewSMTPEndpoint(modName, instName string) (module.Module, error) {
+func NewSMTPEndpoint(modName, instName string, aliases []string) (module.Module, error) {
 	endp := &SMTPEndpoint{
 		name:       instName,
+		aliases:    aliases,
 		submission: modName == "submission",
 		Log:        log.Logger{Name: "smtp"},
 	}
@@ -177,8 +179,9 @@ func (endp *SMTPEndpoint) Init(cfg *config.Map) error {
 		endp.Log.Debugf("authentication provider: %s %s", endp.Auth.(module.Module).Name(), endp.Auth.(module.Module).InstanceName())
 	}
 
-	addresses := make([]Address, 0, len(cfg.Block.Args))
-	for _, addr := range cfg.Block.Args {
+	args := append([]string{endp.name}, endp.aliases...)
+	addresses := make([]Address, 0, len(args))
+	for _, addr := range args {
 		saddr, err := standardizeAddress(addr)
 		if err != nil {
 			return fmt.Errorf("smtp: invalid address: %s", addr)

sql.go

@@ -152,7 +152,7 @@ func (sqlm *SQLStorage) InstanceName() string {
 	return sqlm.instName
 }
 
-func NewSQLStorage(_, instName string) (module.Module, error) {
+func NewSQLStorage(_, instName string, _ []string) (module.Module, error) {
 	return &SQLStorage{
 		instName: instName,
 		Log:      log.Logger{Name: "sql"},

stateless_check.go

@@ -145,7 +145,7 @@ func (c *statelessCheck) InstanceName() string {
 // It creates the module and its instance with the specified name that implement module.Check interface
 // and runs passed functions when corresponding module.CheckState methods are called.
 func RegisterStatelessCheck(name string, connCheck FuncConnCheck, senderCheck FuncSenderCheck, rcptCheck FuncRcptCheck, bodyCheck FuncBodyCheck) {
-	module.Register(name, func(modName, instName string) (module.Module, error) {
+	module.Register(name, func(modName, instName string, aliases []string) (module.Module, error) {
 		return &statelessCheck{
 			modName:  modName,
 			instName: instName,