storage/imapsql: Rename and clarify docs

See #212.

cmd/maddyctl/sql.go

@@ -2,13 +2,13 @@ package main
 
 import (
 	"github.com/foxcpp/maddy/internal/config"
-	"github.com/foxcpp/maddy/internal/storage/sql"
+	"github.com/foxcpp/maddy/internal/storage/imapsql"
 
 	_ "github.com/go-sql-driver/mysql"
 	_ "github.com/lib/pq"
 )
 
-func sqlFromCfgBlock(root, node config.Node) (*sql.Storage, error) {
+func sqlFromCfgBlock(root, node config.Node) (*imapsql.Storage, error) {
 	// Global variables relevant for sql module.
 	globals := config.NewMap(nil, root)
 	// None now...
@@ -23,7 +23,7 @@ func sqlFromCfgBlock(root, node config.Node) (*sql.Storage, error) {
 		instName = node.Args[0]
 	}
 
-	mod, err := sql.New("sql", instName, nil, nil)
+	mod, err := imapsql.New("sql", instName, nil, nil)
 	if err != nil {
 		return nil, err
 	}
@@ -31,5 +31,5 @@ func sqlFromCfgBlock(root, node config.Node) (*sql.Storage, error) {
 		return nil, err
 	}
 
-	return mod.(*sql.Storage), nil
+	return mod.(*imapsql.Storage), nil
 }

docs/man/maddy-storage.5.scd

@@ -9,30 +9,34 @@ flags, message UIDs, etc defined as in RFC 3501.
 This man page lists supported storage backends along with supported
 configuration directives for each.
 
-Most likely, you are going to modules listed here in 'storage' directive for
+Most likely, you are going to use modules listed here in 'storage' directive
-IMAP endpoint module (see *maddy-imap*(5)).
+for IMAP endpoint module (see *maddy-imap*(5)).
 
-# SQL-based database module (sql)
+# SQL-based database module (imapsql)
 
-Module that stores message metadata and indexes in a SQL-based relational
+The 'imapsql' module implements unified database for IMAP index and the user
-database.
+credentials using SQL-based relational database. This allows easier management
+as there is no storage accounts and no authentication accounts. There are just
+accounts that can be created and removed using 'maddyctl' command.
 
 Message contents are stored in an "external store", currently the only
 supported "external store" is a filesystem directory, used by default.
-All messages are stored in StateDirectory/messages under random IDs.
+By default, all messages are stored in StateDirectory/messages under random IDs.
 
 Supported RDBMS:
 - SQLite 3.25.0
 - PostgreSQL 9.6 or newer
 
-Can be used as a storage backend (for IMAP), authentication backend (IMAP &
-SMTP) or delivery target (SMTP).
-
 Account names are required to have the form of a email address and are
 case-insensitive. UTF-8 names are supported with restrictions defined in the
 PRECIS UsernameCaseMapped profile.
 
-The database can be managed using the maddyctl utility.
+```
+imapsql {
+	driver sqlite3
+	dsn imapsql.db
+}
+```
 
 ## Arguments
 

internal/storage/imapsql/bench_test.go

@@ -1,4 +1,4 @@
-package sql
+package imapsql
 
 import (
 	"flag"

internal/storage/imapsql/imapsql.go

@@ -1,11 +1,11 @@
-// Package sql implements SQL-based storage module
+// Package imapsql implements SQL-based storage module
 // using go-imap-sql library (github.com/foxcpp/go-imap-sql).
 //
 // Interfaces implemented:
 // - module.StorageBackend
 // - module.PlainAuth
 // - module.DeliveryTarget
-package sql
+package imapsql
 
 import (
 	"context"
@@ -187,12 +187,12 @@ func (store *Storage) InstanceName() string {
 func New(_, instName string, _, inlineArgs []string) (module.Module, error) {
 	store := &Storage{
 		instName: instName,
-		Log:      log.Logger{Name: "sql"},
+		Log:      log.Logger{Name: "imapsql"},
 		resolver: dns.DefaultResolver(),
 	}
 	if len(inlineArgs) != 0 {
 		if len(inlineArgs) == 1 {
-			return nil, errors.New("sql: expected at least 2 arguments")
+			return nil, errors.New("imapsql: expected at least 2 arguments")
 		}
 
 		store.driver = inlineArgs[0]
@@ -238,10 +238,10 @@ func (store *Storage) Init(cfg *config.Map) error {
 	}
 
 	if dsn == nil {
-		return errors.New("sql: dsn is required")
+		return errors.New("imapsql: dsn is required")
 	}
 	if driver == "" {
-		return errors.New("sql: driver is required")
+		return errors.New("imapsql: driver is required")
 	}
 
 	opts.Log = &store.Log
@@ -252,7 +252,7 @@ func (store *Storage) Init(cfg *config.Map) error {
 		// int is 32-bit on some platforms, so cut off values we can't actually
 		// use.
 		if int(uint32(appendlimitVal)) != appendlimitVal {
-			return errors.New("sql: appendlimit value is too big")
+			return errors.New("imapsql: appendlimit value is too big")
 		}
 		opts.MaxMsgBytes = new(uint32)
 		*opts.MaxMsgBytes = uint32(appendlimitVal)
@@ -273,24 +273,24 @@ func (store *Storage) Init(cfg *config.Map) error {
 			if len(compression) == 2 {
 				opts.CompressAlgoParams = compression[1]
 				if _, err := strconv.Atoi(compression[1]); err != nil {
-					return errors.New("sql: first argument for lz4 and zstd is compression level")
+					return errors.New("imapsql: first argument for lz4 and zstd is compression level")
 				}
 			}
 			if len(compression) > 2 {
-				return errors.New("sql: expected at most 2 arguments")
+				return errors.New("imapsql: expected at most 2 arguments")
 			}
 		case "off":
 			if len(compression) > 1 {
-				return errors.New("sql: expected at most 1 arguments")
+				return errors.New("imapsql: expected at most 1 arguments")
 			}
 		default:
-			return errors.New("sql: unknown compression algorithm")
+			return errors.New("imapsql: unknown compression algorithm")
 		}
 	}
 
 	store.Back, err = imapsql.New(driver, dsnStr, extStore, opts)
 	if err != nil {
-		return fmt.Errorf("sql: %s", err)
+		return fmt.Errorf("imapsql: %s", err)
 	}
 
 	store.Log.Debugln("go-imap-sql version", imapsql.VersionStr)
@@ -306,7 +306,7 @@ func (store *Storage) EnableUpdatePipe(mode updatepipe.BackendMode) error {
 		return nil
 	}
 	if store.updates != nil {
-		panic("sql: EnableUpdatePipe called after Updates")
+		panic("imapsql: EnableUpdatePipe called after Updates")
 	}
 
 	upds := store.Back.Updates()
@@ -321,7 +321,7 @@ func (store *Storage) EnableUpdatePipe(mode updatepipe.BackendMode) error {
 			Log: log.Logger{Name: "sql/updpipe", Debug: store.Log.Debug},
 		}
 	default:
-		return errors.New("sql: driver does not have an update pipe implementation")
+		return errors.New("imapsql: driver does not have an update pipe implementation")
 	}
 
 	wrapped := make(chan backend.Update, cap(upds)*2)
@@ -397,7 +397,7 @@ func (store *Storage) EnableChildrenExt() bool {
 func prepareUsername(username string) (string, error) {
 	mbox, domain, err := address.Split(username)
 	if err != nil {
-		return "", fmt.Errorf("sql: username prepare: %w", err)
+		return "", fmt.Errorf("imapsql: username prepare: %w", err)
 	}
 
 	// PRECIS is not included in the regular address.ForLookup since it reduces
@@ -409,12 +409,12 @@ func prepareUsername(username string) (string, error) {
 	// CompareKey and String.
 	mbox, err = precis.UsernameCaseMapped.CompareKey(mbox)
 	if err != nil {
-		return "", fmt.Errorf("sql: username prepare: %w", err)
+		return "", fmt.Errorf("imapsql: username prepare: %w", err)
 	}
 
 	domain, err = dns.ForLookup(domain)
 	if err != nil {
-		return "", fmt.Errorf("sql: username prepare: %w", err)
+		return "", fmt.Errorf("imapsql: username prepare: %w", err)
 	}
 
 	return mbox + "@" + domain, nil
@@ -422,7 +422,7 @@ func prepareUsername(username string) (string, error) {
 
 func (store *Storage) AuthPlain(username, password string) error {
 	// TODO: Pass session context there.
-	defer trace.StartRegion(context.Background(), "sql/AuthPlain").End()
+	defer trace.StartRegion(context.Background(), "imapsql/AuthPlain").End()
 
 	accountName, err := prepareUsername(username)
 	if err != nil {
@@ -468,5 +468,5 @@ func (store *Storage) Close() error {
 }
 
 func init() {
-	module.Register("sql", New)
+	module.Register("imapsql", New)
 }

internal/storage/imapsql/maddyctl.go

@@ -1,4 +1,4 @@
-package sql
+package imapsql
 
 import (
 	"errors"

internal/storage/imapsql/sqlite3.go

@@ -1,5 +1,5 @@
 // +build !nosqlite3,cgo
 
-package sql
+package imapsql
 
 import _ "github.com/mattn/go-sqlite3"

maddy.conf

@@ -1,4 +1,4 @@
-## maddy 0.1 - default configuration file (2020-02-15T12:39Z)
+## maddy 0.2 - default configuration file (2020-03-05)
 # Suitable for small-scale deployments. Uses its own format for local users DB,
 # should be managed via maddyctl utility.
 #
@@ -21,9 +21,13 @@ tls /etc/maddy/certs/$(hostname)/fullchain.pem \
 # ----------------------------------------------------------------------------
 # Local storage & authentication
 
-sql local_mailboxes local_authdb {
+# imapsql modules provides unified database that is used both for user
+# credentials and IMAP index. Use 'maddyctl users' utility to manage accounts
+# and 'maddyctl imap-*' commands to inspect stored messages.
+
+imapsql local_mailboxes local_authdb {
     driver sqlite3
-    dsn all.db
+    dsn imapsql.db
 }
 
 # ----------------------------------------------------------------------------

maddy.go

@@ -34,7 +34,7 @@ import (
 	_ "github.com/foxcpp/maddy/internal/endpoint/smtp"
 	_ "github.com/foxcpp/maddy/internal/modify"
 	_ "github.com/foxcpp/maddy/internal/modify/dkim"
-	_ "github.com/foxcpp/maddy/internal/storage/sql"
+	_ "github.com/foxcpp/maddy/internal/storage/imapsql"
 	_ "github.com/foxcpp/maddy/internal/table"
 	_ "github.com/foxcpp/maddy/internal/target/queue"
 	_ "github.com/foxcpp/maddy/internal/target/remote"