backend

Documentation

Overview

Package backend defines an IMAP server backend interface.

Index

• Variables
• type Backend
• type BackendUpdater
• type ExpungeUpdate
• type Mailbox
• type MailboxPoller
• type MailboxUpdate
• type MessageUpdate
• type StatusUpdate
• type Update
  • func NewUpdate(username, mailbox string) Update
• type User

Variables

var (
	// ErrNoSuchMailbox is returned by User.GetMailbox, User.DeleteMailbox and
	// User.RenameMailbox when retrieving, deleting or renaming a mailbox that
	// doesn't exist.
	ErrNoSuchMailbox = errors.New("No such mailbox")
	// ErrMailboxAlreadyExists is returned by User.CreateMailbox and
	// User.RenameMailbox when creating or renaming mailbox that already exists.
	ErrMailboxAlreadyExists = errors.New("Mailbox already exists")
)

var ErrInvalidCredentials = errors.New("Invalid credentials")

ErrInvalidCredentials is returned by Backend.Login when a username or a password is incorrect.

Types

type Backend

type Backend interface {
	// Login authenticates a user. If the username or the password is incorrect,
	// it returns ErrInvalidCredentials.
	Login(username, password string) (User, error)
}

Backend is an IMAP server backend. A backend operation always deals with users.

type BackendUpdater

type BackendUpdater interface {
	// Updates returns a set of channels where updates are sent to.
	Updates() <-chan Update
}

BackendUpdater is a Backend that implements Updater is able to send unilateral backend updates. Backends not implementing this interface don't correctly send unilateral updates, for instance if a user logs in from two connections and deletes a message from one of them, the over is not aware that such a mesage has been deleted. More importantly, backends implementing Updater can notify the user for external updates such as new message notifications.

type ExpungeUpdate

type ExpungeUpdate struct {
	Update
	SeqNum uint32
}

ExpungeUpdate is an expunge update.

type Mailbox

type Mailbox interface {
	// Name returns this mailbox name.
	Name() string

	// Info returns this mailbox info.
	Info() (*imap.MailboxInfo, error)

	// Status returns this mailbox status. The fields Name, Flags, PermanentFlags
	// and UnseenSeqNum in the returned MailboxStatus must be always populated.
	// This function does not affect the state of any messages in the mailbox. See
	// RFC 3501 section 6.3.10 for a list of items that can be requested.
	Status(items []imap.StatusItem) (*imap.MailboxStatus, error)

	// SetSubscribed adds or removes the mailbox to the server's set of "active"
	// or "subscribed" mailboxes.
	SetSubscribed(subscribed bool) error

	// Check requests a checkpoint of the currently selected mailbox. A checkpoint
	// refers to any implementation-dependent housekeeping associated with the
	// mailbox (e.g., resolving the server's in-memory state of the mailbox with
	// the state on its disk). A checkpoint MAY take a non-instantaneous amount of
	// real time to complete. If a server implementation has no such housekeeping
	// considerations, CHECK is equivalent to NOOP.
	Check() error

	// ListMessages returns a list of messages. seqset must be interpreted as UIDs
	// if uid is set to true and as message sequence numbers otherwise. See RFC
	// 3501 section 6.4.5 for a list of items that can be requested.
	//
	// Messages must be sent to ch. When the function returns, ch must be closed.
	ListMessages(uid bool, seqset *imap.SeqSet, items []imap.FetchItem, ch chan<- *imap.Message) error

	// SearchMessages searches messages. The returned list must contain UIDs if
	// uid is set to true, or sequence numbers otherwise.
	SearchMessages(uid bool, criteria *imap.SearchCriteria) ([]uint32, error)

	// CreateMessage appends a new message to this mailbox. The \Recent flag will
	// be added no matter flags is empty or not. If date is nil, the current time
	// will be used.
	//
	// If the Backend implements Updater, it must notify the client immediately
	// via a mailbox update.
	CreateMessage(flags []string, date time.Time, body imap.Literal) error

	// UpdateMessagesFlags alters flags for the specified message(s).
	//
	// If the Backend implements Updater, it must notify the client immediately
	// via a message update.
	UpdateMessagesFlags(uid bool, seqset *imap.SeqSet, operation imap.FlagsOp, flags []string) error

	// CopyMessages copies the specified message(s) to the end of the specified
	// destination mailbox. The flags and internal date of the message(s) SHOULD
	// be preserved, and the Recent flag SHOULD be set, in the copy.
	//
	// If the destination mailbox does not exist, a server SHOULD return an error.
	// It SHOULD NOT automatically create the mailbox.
	//
	// If the Backend implements Updater, it must notify the client immediately
	// via a mailbox update.
	CopyMessages(uid bool, seqset *imap.SeqSet, dest string) error

	// Expunge permanently removes all messages that have the \Deleted flag set
	// from the currently selected mailbox.
	//
	// If the Backend implements Updater, it must notify the client immediately
	// via an expunge update.
	Expunge() error
}

Mailbox represents a mailbox belonging to a user in the mail storage system. A mailbox operation always deals with messages.

type MailboxPoller

type MailboxPoller interface {
	// Poll requests mailbox updates.
	Poll() error
}

MailboxPoller is a Mailbox that is able to poll updates for new messages or message status updates during a period of inactivity.

type MailboxUpdate

type MailboxUpdate struct {
	Update
	*imap.MailboxStatus
}

MailboxUpdate is a mailbox update.

type MessageUpdate

type MessageUpdate struct {
	Update
	*imap.Message
}

MessageUpdate is a message update.

type StatusUpdate

type StatusUpdate struct {
	Update
	*imap.StatusResp
}

StatusUpdate is a status update. See RFC 3501 section 7.1 for a list of status responses.

type Update

type Update interface {
	// The user targeted by this update. If empty, all connected users will
	// be notified.
	Username() string
	// The mailbox targeted by this update. If empty, the update targets all
	// mailboxes.
	Mailbox() string
	// Done returns a channel that is closed when the update has been broadcast to
	// all clients.
	Done() chan struct{}
}

Update contains user and mailbox information about an unilateral backend update.

func NewUpdate

func NewUpdate(username, mailbox string) Update

NewUpdate creates a new update.

type User

type User interface {
	// Username returns this user's username.
	Username() string

	// ListMailboxes returns a list of mailboxes belonging to this user. If
	// subscribed is set to true, only returns subscribed mailboxes.
	ListMailboxes(subscribed bool) ([]Mailbox, error)

	// GetMailbox returns a mailbox. If it doesn't exist, it returns
	// ErrNoSuchMailbox.
	GetMailbox(name string) (Mailbox, error)

	// CreateMailbox creates a new mailbox.
	//
	// If the mailbox already exists, an error must be returned. If the mailbox
	// name is suffixed with the server's hierarchy separator character, this is a
	// declaration that the client intends to create mailbox names under this name
	// in the hierarchy.
	//
	// If the server's hierarchy separator character appears elsewhere in the
	// name, the server SHOULD create any superior hierarchical names that are
	// needed for the CREATE command to be successfully completed.  In other
	// words, an attempt to create "foo/bar/zap" on a server in which "/" is the
	// hierarchy separator character SHOULD create foo/ and foo/bar/ if they do
	// not already exist.
	//
	// If a new mailbox is created with the same name as a mailbox which was
	// deleted, its unique identifiers MUST be greater than any unique identifiers
	// used in the previous incarnation of the mailbox UNLESS the new incarnation
	// has a different unique identifier validity value.
	CreateMailbox(name string) error

	// DeleteMailbox permanently remove the mailbox with the given name. It is an
	// error to // attempt to delete INBOX or a mailbox name that does not exist.
	//
	// The DELETE command MUST NOT remove inferior hierarchical names. For
	// example, if a mailbox "foo" has an inferior "foo.bar" (assuming "." is the
	// hierarchy delimiter character), removing "foo" MUST NOT remove "foo.bar".
	//
	// The value of the highest-used unique identifier of the deleted mailbox MUST
	// be preserved so that a new mailbox created with the same name will not
	// reuse the identifiers of the former incarnation, UNLESS the new incarnation
	// has a different unique identifier validity value.
	DeleteMailbox(name string) error

	// RenameMailbox changes the name of a mailbox. It is an error to attempt to
	// rename from a mailbox name that does not exist or to a mailbox name that
	// already exists.
	//
	// If the name has inferior hierarchical names, then the inferior hierarchical
	// names MUST also be renamed.  For example, a rename of "foo" to "zap" will
	// rename "foo/bar" (assuming "/" is the hierarchy delimiter character) to
	// "zap/bar".
	//
	// If the server's hierarchy separator character appears in the name, the
	// server SHOULD create any superior hierarchical names that are needed for
	// the RENAME command to complete successfully.  In other words, an attempt to
	// rename "foo/bar/zap" to baz/rag/zowie on a server in which "/" is the
	// hierarchy separator character SHOULD create baz/ and baz/rag/ if they do
	// not already exist.
	//
	// The value of the highest-used unique identifier of the old mailbox name
	// MUST be preserved so that a new mailbox created with the same name will not
	// reuse the identifiers of the former incarnation, UNLESS the new incarnation
	// has a different unique identifier validity value.
	//
	// Renaming INBOX is permitted, and has special behavior.  It moves all
	// messages in INBOX to a new mailbox with the given name, leaving INBOX
	// empty.  If the server implementation supports inferior hierarchical names
	// of INBOX, these are unaffected by a rename of INBOX.
	RenameMailbox(existingName, newName string) error

	// Logout is called when this User will no longer be used, likely because the
	// client closed the connection.
	Logout() error
}

User represents a user in the mail storage system. A user operation always deals with mailboxes.