backend

Documentation

Overview

IMAP server backend interface.

Index

• 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

Functions

func DoneUpdate

func DoneUpdate(u *Update)

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 {
	// Authenticate a user.
	Login(username, password string) (User, error)
}

An IMAP server backend. A backend operation always deals with users.

type ExpungeUpdate

type ExpungeUpdate struct {
	Update
	SeqNum uint32
}

An expunge update.

type Mailbox

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

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

	// Get this mailbox status.
	// See RFC 3501 section 6.3.10 for a list of items that can be requested.
	Status(items []string) (*imap.MailboxStatus, error)

	// Add the mailbox to the server's set of "active" or "subscribed" mailboxes.
	Subscribe() error

	// Remove the mailbox to the server's set of "active" or "subscribed"
	// mailboxes.
	Unsubscribe() error

	// 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

	// Get 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

	// Search messages.
	SearchMessages(uid bool, criteria *imap.SearchCriteria) ([]uint32, error)

	// Append 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 []byte) error

	// Alter 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

	// Copy 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

	// 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
}

A mailbox update.

type MessageUpdate

type MessageUpdate struct {
	Update
	*imap.Message
}

A message update.

type StatusUpdate

type StatusUpdate struct {
	Update
	*imap.StatusResp
}

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{}
}

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
}

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 {
	// Get this user's username.
	Username() string

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

	// Get a mailbox.
	GetMailbox(name string) (Mailbox, error)

	// Create 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

	// 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

	// Change 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.