mailbox

type ACL []Entry

type AttrScope int

type Entry struct {
	Identifier Identifier
	Rights     Rights
	Negative   bool
}

type FlagsUpdate struct {
	Flags    []string
	Keywords []string
}

type Folder struct {
	ID            uint64
	Name          string
	UIDValidity   uint32
	NextUID       uint32
	Messages      uint32
	Unseen        uint32
	HighestModSeq uint64
	// GUID is a stable 16-byte identifier stamped at folder creation
	// time. Survives RENAME (unlike Name). Used as the key namespace
	// for per-folder metadata in pkg/dict (RFC 5464 METADATA) and as
	// the rename-stable handle for ACL state, quota counters, etc.
	GUID [16]byte
}

type Identifier struct {
	Type IdentifierType
	Name string // user=/group=/group-override= only
}

type IdentifierType int

type IndexBackend interface {
	OpenUser(*UserInfo) UserIndex
}

type Location struct {
	Driver string // "maildir", "sdbox" (alias: "dbox"), "mdbox"
	Path   string // expanded absolute path (varexpand applied)
}

type MailboxBackend interface {
	OpenUser(*UserInfo) UserMailbox
}

type MessageMeta struct {
	UID          uint32
	Filename     string // backend-specific filename returned by UserMailbox.Save
	Flags        []string
	Keywords     []string
	ModSeq       uint64
	Size         uint32
	VSize        uint32
	InternalDate time.Time
	GUID         [16]byte
	CacheOffset  uint32
	// AltTier is true when the message body resides in alt (cold) storage.
	// Stored as FlagBackend (0x40) in the on-disk index record so Fetch()
	// can open the correct tier without a wasted primary-tier syscall.
	// Only meaningful for mdbox; other drivers ignore it.
	AltTier bool
}

type Resolver struct {
	// Root is prepended to template-derived paths. Absolute override paths
	// from userdb skip Root entirely.
	Root string

	// HomeTemplate is the Dovecot-style template for users with no userdb
	// override. Default: "%d/%u" (virtual hosting layout).
	HomeTemplate string

	// DefaultQuotaRules are applied to every UserInfo produced by this
	// Resolver when the userdb lookup provides no per-user override.
	// Mirrors Dovecot's quota_rule setting at the global level.
	DefaultQuotaRules []string

	// DefaultVolatileDir is the cluster-wide VOLATILEDIR template applied
	// when no per-user override arrives from userdb. Supports the same
	// %u/%n/%d/%h variables as HomeTemplate. Empty disables volatile dir
	// (default). Mirrors Dovecot's VOLATILEDIR mail-location modifier at
	// the global config level.
	DefaultVolatileDir string

	// DefaultIndexDir is the cluster-wide INDEX= template applied when no
	// per-user override arrives from userdb. Supports %u/%n/%d/%h. Empty
	// keeps index files co-located with the mailbox (default). Mirrors
	// Dovecot's INDEX= mail-location modifier at the global config level.
	DefaultIndexDir string

	// DefaultControlDir is the cluster-wide CONTROL= template applied when
	// no per-user override arrives from userdb. Supports %u/%n/%d/%h.
	// Empty keeps control files co-located with the mailbox (default).
	// Mirrors Dovecot's CONTROL= mail-location modifier at the global
	// config level.
	DefaultControlDir string

	// DefaultAltDir is the cluster-wide ALT= template applied when no
	// per-user override arrives from userdb. Supports %u/%n/%d/%h.
	// Empty disables two-tier storage (default). Mirrors Dovecot's
	// ALT= mail-location modifier at the global config level.
	DefaultAltDir string
}

type Rights string

type ScanRecord struct {
	Filename     string
	GUID         [16]byte
	Size         uint32
	VSize        uint32
	InternalDate time.Time
	Flags        []string
}

type SeqRange struct {
	From, To uint32 // inclusive; To==0 means '*'
}

type SeqSet []SeqRange

type UserIndex interface {
	OpenFolder(folder string, uidValidity uint32) (*Folder, error)
	SaveFolder(f *Folder) error
	AppendMessage(folderID uint64, m *MessageMeta) error
	// AllocateUID atomically reserves and persists the folder's next UID
	// under the cross-process mailbox lock. The caller passes the UID to
	// UserMailbox.Save, then records the full MessageMeta via AppendMessage.
	//
	// If the caller fails between AllocateUID and AppendMessage the UID
	// is burnt — matches Dovecot's "uid hole" tolerance. Periodic rebuild
	// reconciles state by scanning the on-disk tree.
	AllocateUID(folderID uint64) (uint32, error)
	// AllocateUIDWithModSeq atomically reserves the folder's next UID and
	// pre-allocates the next modseq value in one lock/reload/flush cycle,
	// replacing the separate AllocateUID + NextModSeq calls in Append.
	AllocateUIDWithModSeq(folderID uint64) (uid uint32, modseq uint64, err error)
	// AllocateAndAppend assigns a UID and records the message in a single
	// lock/reload/flush cycle — the go-imap appendBytes pattern applied to
	// persistent storage. m.UID and m.ModSeq are filled in by the call;
	// all other fields must be set by the caller. m.Filename must already
	// be known (box.Save completes before this call). Replaces the two-step
	// AllocateUID(WithModSeq) + AppendMessage pattern that caused APPEND stalls.
	AllocateAndAppend(folderID uint64, m *MessageMeta) error
	UpdateFlags(folderID uint64, uid uint32, flags, keywords []string) error
	// UpdateFlagsMulti replaces flags+keywords for a batch of UIDs in a
	// single lock/reload/flush cycle. Returns the new modseq per UID.
	UpdateFlagsMulti(folderID uint64, updates map[uint32]FlagsUpdate) (map[uint32]uint64, error)
	// SetAltTier sets or clears the AltTier marker (FlagBackend) for every
	// message in folderID whose Filename matches one of the supplied names.
	// Called by the altmove API after physically relocating mdbox m.<N> files
	// so subsequent Fetch calls can skip the primary-tier open() attempt.
	// Operates under the cross-process mailbox lock for the folder.
	SetAltTier(folderID uint64, filenames []string, altTier bool) error
	GetMessages(folderID uint64, uids SeqSet) ([]*MessageMeta, error)
	ExpungeMessage(folderID uint64, uid uint32) error
	NextModSeq(folderID uint64) (uint64, error)
	// Vanished returns UIDs expunged from folderID with modseq strictly
	// greater than sinceModSeq. Drives QRESYNC (RFC 7162) SELECT and
	// UID FETCH (CHANGEDSINCE N VANISHED) responses.
	Vanished(folderID uint64, sinceModSeq uint64) ([]uint32, error)
	Keywords(folderID uint64) ([]string, error)
	// RenameFolder renames oldName to newName in the index.
	// Called by IMAP RENAME immediately after UserMailbox.Rename succeeds.
	RenameFolder(oldName, newName string) error
	// GetPOP3UIDLs loads saved POP3 UIDLs for a folder (uid → uidl string).
	// Returns an empty map when no saved UIDLs exist yet.
	GetPOP3UIDLs(folderID uint64) (map[uint32]string, error)
	// SavePOP3UIDLs persists POP3 UIDLs so subsequent sessions use stable values.
	SavePOP3UIDLs(folderID uint64, uidls map[uint32]string) error
	// ResetFolder atomically replaces the on-disk record set for
	// folderID with the supplied messages. Preserves UIDVALIDITY
	// and the folder GUID; bumps NextUID past max(records.UID);
	// HighestModSeq advances by one so QRESYNC clients invalidate
	// their caches. Drives the admin rebuild flow. Caller has
	// already taken the cross-process mailbox lock and made a
	// .bak of the old base file.
	ResetFolder(folderID uint64, records []*MessageMeta) error
	// OptimizeIndex compacts the .index.log overlay into the base
	// .index file. Returns a no-op nil when there is nothing to
	// compact. Takes the same X lock as a normal write.
	OptimizeIndex(folderID uint64) error
	Close() error
}

type UserInfo struct {
	// Username is the canonical login (typically full email). Used for
	// per-user concurrency counters, log lines, and message-ID Received
	// headers — never as a storage path on its own.
	Username string

	// Home is the absolute filesystem root for the user's mailbox tree.
	// Resolved from either userdb.home (override) or the storage.mail_home
	// template expanded against the username. See Resolver.
	Home string

	// VolatileDir, when non-empty, redirects volatile index artefacts
	// (Recreate tmp files) to a local path instead of the NFS-backed
	// index directory. Mirrors Dovecot's VOLATILEDIR mail-location
	// modifier. Template vars (%u/%n/%d/%h) are already expanded by the
	// time this field is populated.
	VolatileDir string

	// IndexDir, when non-empty, redirects all per-folder index files
	// (yarilo.index*, yarilo-acl) to a separate directory tree. The
	// mailbox data (Maildir cur/new/tmp) stays under Home; only index
	// state moves. Mirrors Dovecot's INDEX= mail-location modifier.
	// Template vars (%u/%n/%d/%h) are already expanded.
	IndexDir string

	// ControlDir, when non-empty, redirects per-folder control files
	// (yarilo-uidlist, subscriptions) to a separate directory tree.
	// The mailbox data and index files are unaffected. Mirrors Dovecot's
	// CONTROL= mail-location modifier.
	// Template vars (%u/%n/%d/%h) are already expanded.
	ControlDir string

	// AltDir, when non-empty, enables two-tier maildir storage. Messages
	// that have been cold-tiered (via altmove) live under AltDir instead
	// of Home. Reads check both primary (Home) and alt; writes always go
	// to the primary tier. Mirrors Dovecot's ALT= mail-location modifier.
	// Template vars (%u/%n/%d/%h) are already expanded.
	AltDir string

	// Groups is the list of supplementary groups the user belongs to,
	// sourced from the userdb `groups=` extra field (comma-separated).
	// ACL evaluation matches these against `group=<name>` and
	// `group-override=<name>` entries. Empty when not configured —
	// group= ACL entries have no effect in that case.
	Groups []string

	// QuotaRules is the list of per-user quota rules sourced from the
	// userdb `quota_rule=` extra field. Format: `*:storage=5G` or
	// `*:messages=100000`. Empty means no quota limit.
	QuotaRules []string

	// SessionID is the IMAP/POP3 session identifier assigned by the login
	// proxy. Included in the yarilo-locks owner string for BUSY diagnostics.
	// Empty for LMTP and other non-session contexts.
	SessionID string
}

type UserMailbox interface {
	Init() error
	Create(folder string) error
	Delete(folder string) error
	Rename(oldName, newName string) error
	Save(folder string, r io.Reader, uid uint32, size int64, flags []string) (string, error)
	// Fetch returns a reader for the message body. altTier hints that the
	// message lives in alt (cold) storage so the driver can open it directly
	// without trying the primary path first. The hint is set from
	// MessageMeta.AltTier which is persisted in the index as FlagBackend.
	Fetch(folder, filename string, altTier bool) (io.ReadCloser, error)
	Remove(folder, filename string) error
	List(folder string) ([]*MessageMeta, error)
	FolderExists(folder string) (bool, error)
	ListFolders() ([]string, error)
	// Scan walks the on-disk representation of folder and yields
	// every visible message as a ScanRecord. Used by the admin
	// rebuild flow to regenerate the fileindex independently of
	// whatever the index currently believes. Returns
	// (nil, fmt.Errorf("driver/scan: not yet implemented"))
	// from drivers that have not implemented disk-scan yet.
	Scan(folder string) ([]ScanRecord, error)
	Close() error
}