backend

Documentation

Overview

Package backend defines an IMAP server backend interface.

Index

• Variables
• func DoneUpdate(u *Update)
• func WaitUpdates(updates ...interface{}) <-chan struct{}
• type Backend
• type ExpungeUpdate
• type Mailbox
• type MailboxUpdate
• type MessageUpdate
• type StatusUpdate
• type Update
  • func (u *Update) Done() <-chan struct{}
• type Updater
• type UpdaterMailbox
• 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.

Functions

func DoneUpdate

func DoneUpdate(u *Update)

DoneUpdate marks an update as done. TODO: remove this function

func WaitUpdates

func WaitUpdates(updates ...interface{}) <-chan struct{}

WaitUpdates returns a channel that's closed when all provided updates have been dispatched to all clients. It panics if one of the provided value is not an update.

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 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 and
	// PermanentFlags 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 []string) (*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 []string, 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 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 struct {
	// 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
	// contains filtered or unexported fields
}

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

func (*Update) Done

func (u *Update) Done() <-chan struct{}

Done returns a channel that is closed when the update has been broadcast to all clients.

type Updater

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

Updater 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 UpdaterMailbox

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

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

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.