gluon

README

Gluon

An IMAP4rev1 library focusing on correctness, stability and performance.

Demo

The demo server can be started with:

$ GLUON_LOG_LEVEL=trace go run demo/demo.go
DEBU[0000] Applying update                               update="MailboxCreated: Mailbox.ID = 0, Mailbox.Name = INBOX" user-id=ac8970c5-cdb7-4043-ad85-ad9b9defcfb8
DEBU[0000] Applying update                               update="MessagesCreated: MessageCount=0 Messages=[]" user-id=ac8970c5-cdb7-4043-ad85-ad9b9defcfb8
INFO[0000] User added to server                          userID=ac8970c5-cdb7-4043-ad85-ad9b9defcfb8
DEBU[0000] Applying update                               update="MailboxCreated: Mailbox.ID = 0, Mailbox.Name = INBOX" user-id=a51fad46-9bde-462a-a467-6c30f9a40a63
DEBU[0000] Applying update                               update="MessagesCreated: MessageCount=0 Messages=[]" user-id=a51fad46-9bde-462a-a467-6c30f9a40a63
INFO[0000] User added to server                          userID=a51fad46-9bde-462a-a467-6c30f9a40a63
INFO[0000] Server is listening on 127.0.0.1:1143

By default, the demo server includes two demo users, both with password pass. The first has addresses user1@example.com and alias1@example.com. The second has addresses user2@example.com and alias2@example.com.

Once started, connect to the demo server with an email client (e.g. thunderbird) or via telnet:

$ telnet 127.0.0.1 1143
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
* OK [CAPABILITY IDLE IMAP4rev1 MOVE UIDPLUS UNSELECT]  00.00.00 - gluon session ID 2
tag login user1@example.com pass
tag OK [CAPABILITY IDLE IMAP4rev1 MOVE UIDPLUS UNSELECT] Logged in
tag append inbox (\Seen) {14}
+ Ready
To: user@pm.me
tag OK [APPENDUID 1 1] APPEND
tag select inbox
* FLAGS (\Answered \Deleted \Flagged \Seen)
* 1 EXISTS
* 1 RECENT
* OK [PERMANENTFLAGS (\Answered \Deleted \Flagged \Seen)] Flags permitted
* OK [UIDNEXT 2] Predicted next UID
* OK [UIDVALIDITY 1] UIDs valid
tag OK [READ-WRITE] SELECT
tag fetch 1:* (UID BODY.PEEK[])
* 1 FETCH (UID 1 BODY[] {32}
X-Pm-Gluon-Id: 1
To: user@pm.me)
tag OK command completed in 1.030958ms

Changing DB schema

Do not forget to re-generate ent code after changing the DB schema in ./internal/db/ent/schema.

pushd ./internal/db/ent && go generate . && popd

Documentation

Overview

Package gluon implements an IMAP4rev1 (+ extensions) mailserver.

Package gluon implements an IMAP4rev1 (+ extensions) mailserver.

Index

• func IsNoSuchMailbox(err error) bool
• func IsNoSuchMessage(err error) bool
• type Option
  • func WithCmdProfiler(builder profiling.CmdProfilerBuilder) Option
  • func WithDBClient(ci db.ClientInterface) Option
  • func WithDataDir(path string) Option
  • func WithDatabaseDir(path string) Option
  • func WithDelimiter(delimiter string) Option
  • func WithDisableParallelism() Option
  • func WithIMAPLimits(limits limits2.IMAP) Option
  • func WithIdleBulkTime(idleBulkTime time.Duration) Option
  • func WithLogger(in, out io.Writer) Option
  • func WithLoginJailTime(loginJailTime time.Duration) Option
  • func WithPanicHandler(panicHandler async.PanicHandler) Option
  • func WithReporter(reporter reporter.Reporter) Option
  • func WithStoreBuilder(builder store.Builder) Option
  • func WithTLS(cfg *tls.Config) Option
  • func WithUIDValidityGenerator(generator imap.UIDValidityGenerator) Option
  • func WithVersionInfo(vmajor, vminor, vpatch int, name, vendor, supportURL string) Option
• type Server
  • func New(withOpt ...Option) (*Server, error)
  • func (s *Server) AddUser(ctx context.Context, conn connector.Connector, passphrase []byte) (string, error)
  • func (s *Server) AddWatcher(ofType ...events.Event) <-chan events.Event
  • func (s *Server) Close(ctx context.Context) error
  • func (s *Server) GetDataPath() string
  • func (s *Server) GetDatabasePath() string
  • func (s *Server) GetErrorCh() <-chan error
  • func (s *Server) GetVersionInfo() version.Info
  • func (s *Server) LoadUser(ctx context.Context, conn connector.Connector, userID string, ...) (bool, error)
  • func (s *Server) RemoveUser(ctx context.Context, userID string, removeFiles bool) error
  • func (s *Server) Serve(ctx context.Context, l net.Listener) error

Functions

func IsNoSuchMailbox

func IsNoSuchMailbox(err error) bool

IsNoSuchMailbox returns true if the error is ErrNoSuchMailbox.

func IsNoSuchMessage

func IsNoSuchMessage(err error) bool

IsNoSuchMessage returns true if the error is ErrNoSuchMessage.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option represents a type that can be used to configure the server.

func WithCmdProfiler

func WithCmdProfiler(builder profiling.CmdProfilerBuilder) Option

WithCmdProfiler allows a specific CmdProfilerBuilder to be set for the server's execution.

func WithDBClient

func WithDBClient(ci db.ClientInterface) Option

func WithDataDir

func WithDataDir(path string) Option

func WithDatabaseDir

func WithDatabaseDir(path string) Option

func WithDelimiter

func WithDelimiter(delimiter string) Option

WithDelimiter instructs the server to use the given path delimiter instead of the default ('/').

func WithDisableParallelism

func WithDisableParallelism() Option

func WithIMAPLimits

func WithIMAPLimits(limits limits2.IMAP) Option

func WithIdleBulkTime

func WithIdleBulkTime(idleBulkTime time.Duration) Option

WithIdleBulkTime instructs the server to use the given IDLE bulk time.

func WithLogger

func WithLogger(in, out io.Writer) Option

WithLogger instructs the server to write incoming and outgoing IMAP communication to the given io.Writers.

func WithLoginJailTime

func WithLoginJailTime(loginJailTime time.Duration) Option

WithLoginJailTime instructs the server to use the given login jail time.

func WithPanicHandler

func WithPanicHandler(panicHandler async.PanicHandler) Option

func WithReporter

func WithReporter(reporter reporter.Reporter) Option

func WithStoreBuilder

func WithStoreBuilder(builder store.Builder) Option

func WithTLS

func WithTLS(cfg *tls.Config) Option

WithTLS instructs the server to use the given TLS config.

func WithUIDValidityGenerator

func WithUIDValidityGenerator(generator imap.UIDValidityGenerator) Option

func WithVersionInfo

func WithVersionInfo(
	vmajor, vminor, vpatch int,
	name, vendor, supportURL string,
) Option

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the gluon IMAP server.

func New

func New(withOpt ...Option) (*Server, error)

New creates a new server with the given options.

func (*Server) AddUser

func (s *Server) AddUser(ctx context.Context, conn connector.Connector, passphrase []byte) (string, error)

AddUser creates a new user and generates new unique ID for this user. If the user already exists, an error is returned (use LoadUser instead).

func (*Server) AddWatcher

func (s *Server) AddWatcher(ofType ...events.Event) <-chan events.Event

AddWatcher adds a new watcher which watches events of the given types. If no types are specified, the watcher watches all events.

func (*Server) Close

func (s *Server) Close(ctx context.Context) error

Close closes the server.

func (*Server) GetDataPath

func (s *Server) GetDataPath() string

GetDataPath returns the path in which gluon stores its data.

func (*Server) GetDatabasePath

func (s *Server) GetDatabasePath() string

GetDatabasePath returns the path in which gluon stores its data.

func (*Server) GetErrorCh

func (s *Server) GetErrorCh() <-chan error

GetErrorCh returns the error channel.

func (*Server) GetVersionInfo

func (s *Server) GetVersionInfo() version.Info

GetVersionInfo returns the version info.

func (*Server) LoadUser

func (s *Server) LoadUser(ctx context.Context, conn connector.Connector, userID string, passphrase []byte) (bool, error)

LoadUser adds an existing user using a previously crated unique user ID. It returns true if the user was newly created, false if it already existed.

func (*Server) RemoveUser

func (s *Server) RemoveUser(ctx context.Context, userID string, removeFiles bool) error

RemoveUser removes a user from gluon.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, l net.Listener) error

Serve serves connections accepted from the given listener. It stops serving when the context is canceled, the listener is closed, or the server is closed.