1package backend
2
3import "errors"
4
5var (
6	// ErrNoSuchMailbox is returned by User.GetMailbox, User.DeleteMailbox and
7	// User.RenameMailbox when retrieving, deleting or renaming a mailbox that
8	// doesn't exist.
9	ErrNoSuchMailbox = errors.New("No such mailbox")
10	// ErrMailboxAlreadyExists is returned by User.CreateMailbox and
11	// User.RenameMailbox when creating or renaming mailbox that already exists.
12	ErrMailboxAlreadyExists = errors.New("Mailbox already exists")
13)
14
15// User represents a user in the mail storage system. A user operation always
16// deals with mailboxes.
17type User interface {
18	// Username returns this user's username.
19	Username() string
20
21	// ListMailboxes returns a list of mailboxes belonging to this user. If
22	// subscribed is set to true, only returns subscribed mailboxes.
23	ListMailboxes(subscribed bool) ([]Mailbox, error)
24
25	// GetMailbox returns a mailbox. If it doesn't exist, it returns
26	// ErrNoSuchMailbox.
27	GetMailbox(name string) (Mailbox, error)
28
29	// CreateMailbox creates a new mailbox.
30	//
31	// If the mailbox already exists, an error must be returned. If the mailbox
32	// name is suffixed with the server's hierarchy separator character, this is a
33	// declaration that the client intends to create mailbox names under this name
34	// in the hierarchy.
35	//
36	// If the server's hierarchy separator character appears elsewhere in the
37	// name, the server SHOULD create any superior hierarchical names that are
38	// needed for the CREATE command to be successfully completed.  In other
39	// words, an attempt to create "foo/bar/zap" on a server in which "/" is the
40	// hierarchy separator character SHOULD create foo/ and foo/bar/ if they do
41	// not already exist.
42	//
43	// If a new mailbox is created with the same name as a mailbox which was
44	// deleted, its unique identifiers MUST be greater than any unique identifiers
45	// used in the previous incarnation of the mailbox UNLESS the new incarnation
46	// has a different unique identifier validity value.
47	CreateMailbox(name string) error
48
49	// DeleteMailbox permanently remove the mailbox with the given name. It is an
50	// error to // attempt to delete INBOX or a mailbox name that does not exist.
51	//
52	// The DELETE command MUST NOT remove inferior hierarchical names. For
53	// example, if a mailbox "foo" has an inferior "foo.bar" (assuming "." is the
54	// hierarchy delimiter character), removing "foo" MUST NOT remove "foo.bar".
55	//
56	// The value of the highest-used unique identifier of the deleted mailbox MUST
57	// be preserved so that a new mailbox created with the same name will not
58	// reuse the identifiers of the former incarnation, UNLESS the new incarnation
59	// has a different unique identifier validity value.
60	DeleteMailbox(name string) error
61
62	// RenameMailbox changes the name of a mailbox. It is an error to attempt to
63	// rename from a mailbox name that does not exist or to a mailbox name that
64	// already exists.
65	//
66	// If the name has inferior hierarchical names, then the inferior hierarchical
67	// names MUST also be renamed.  For example, a rename of "foo" to "zap" will
68	// rename "foo/bar" (assuming "/" is the hierarchy delimiter character) to
69	// "zap/bar".
70	//
71	// If the server's hierarchy separator character appears in the name, the
72	// server SHOULD create any superior hierarchical names that are needed for
73	// the RENAME command to complete successfully.  In other words, an attempt to
74	// rename "foo/bar/zap" to baz/rag/zowie on a server in which "/" is the
75	// hierarchy separator character SHOULD create baz/ and baz/rag/ if they do
76	// not already exist.
77	//
78	// The value of the highest-used unique identifier of the old mailbox name
79	// MUST be preserved so that a new mailbox created with the same name will not
80	// reuse the identifiers of the former incarnation, UNLESS the new incarnation
81	// has a different unique identifier validity value.
82	//
83	// Renaming INBOX is permitted, and has special behavior.  It moves all
84	// messages in INBOX to a new mailbox with the given name, leaving INBOX
85	// empty.  If the server implementation supports inferior hierarchical names
86	// of INBOX, these are unaffected by a rename of INBOX.
87	RenameMailbox(existingName, newName string) error
88
89	// Logout is called when this User will no longer be used, likely because the
90	// client closed the connection.
91	Logout() error
92}
93