module

type Check interface {
	// CheckStateForMsg initializes the "internal" check state required for
	// processing of the new message.
	//
	// NOTE: Returned CheckState object must be hashable (usable as a map key).
	// This is used to deduplicate Check* calls, the easiest way to achieve
	// this is to have CheckState as a pointer to some struct, all pointers
	// are hashable.
	CheckStateForMsg(ctx context.Context, msgMeta *MsgMetadata) (CheckState, error)
}

type CheckResult struct {
	// Reason is the error that is reported to the message source
	// if check decided that the message should be rejected.
	Reason error

	// Reject is the flag that specifies that the message
	// should be rejected.
	Reject bool

	// Quarantine is the flag that specifies that the message
	// is considered "possibly malicious" and should be
	// put into Junk mailbox.
	//
	// This value is copied into MsgMetadata by the msgpipeline.
	Quarantine bool

	// AuthResult is the information that is supposed to
	// be included in Authentication-Results header.
	AuthResult []authres.Result

	// Header is the header fields that should be
	// added to the header after all checks.
	Header textproto.Header
}

type CheckState interface {
	// CheckConnection is executed once when client sends a new message.
	//
	// Result may be cached for the whole client connection so this function
	// may not be called sometimes.
	CheckConnection(ctx context.Context) CheckResult

	// CheckSender is executed once when client sends the message sender
	// information (e.g. on the MAIL FROM command).
	CheckSender(ctx context.Context, mailFrom string) CheckResult

	// CheckRcpt is executed for each recipient when its address is received
	// from the client (e.g. on the RCPT TO command).
	CheckRcpt(ctx context.Context, rcptTo string) CheckResult

	// CheckBody is executed once after the message body is received and
	// buffered in memory or on disk.
	//
	// Check code should use passed mutex when working with the message header.
	// Body can be read without locking it since it is read-only.
	CheckBody(ctx context.Context, header textproto.Header, body buffer.Buffer) CheckResult

	// Close is called after the message processing ends, even if any of the
	// Check* functions return an error.
	Close() error
}

type ConnState struct {
	// IANA name (ESMTP, ESMTPS, etc) of the protocol message was received
	// over. If the message was generated locally, this field is empty.
	Proto string

	// Information about the SMTP connection, including HELO hostname and
	// source IP. Valid only if Proto refers the SMTP protocol or its variant
	// (e.g. LMTP).
	smtp.ConnectionState

	// The RDNSName field contains the result of Reverse DNS lookup on the
	// client IP.
	//
	// The underlying type is the string or untyped nil value. It is the
	// message source responsibility to populate this field.
	//
	// Valid values of this field consumers need to be aware of:
	// RDNSName = nil
	//   The reverse DNS lookup is not applicable for that message source.
	//   Typically the case for messages generated locally.
	// RDNSName != nil, but Get returns nil
	//   The reverse DNS lookup was attempted, but resulted in an error.
	//   Consumers should assume that the PTR record doesn't exist.
	RDNSName *future.Future

	// If the client successfully authenticated using a username/password pair.
	// This field contains the username.
	AuthUser string

	// If the client successfully authenticated using a username/password pair.
	// This field should be cleaned if the ConnState object is serialized
	AuthPassword string
}

type Delivery interface {
	// AddRcpt adds the target address for the message.
	//
	// The domain part of the address is assumed to be U-labels with NFC normalization
	// and case-folding applied. The message source should ensure that by
	// calling address.CleanDomain if necessary.
	//
	// Implementation should assume that no case-folding or deduplication was
	// done by caller code. Its implementation responsibility to do so if it is
	// necessary. It is not recommended to reject duplicated recipients,
	// however. They should be silently ignored.
	//
	// Implementation should do as much checks as possible here and reject
	// recipients that can't be used.  Note: MsgMetadata object passed to Start
	// contains BodyLength field. If it is non-zero, it can be used to check
	// storage quota for the user before Body.
	AddRcpt(ctx context.Context, rcptTo string) error

	// Body sets the body and header contents for the message.
	// If this method fails, message is assumed to be undeliverable
	// to all recipients.
	//
	// Implementation should avoid doing any persistent changes to the
	// underlying storage until Commit is called. If that is not possible,
	// Abort should (attempt to) rollback any such changes.
	//
	// If Body can't be implemented without per-recipient failures,
	// then delivery object should also implement PartialDelivery interface
	// for use by message sources that are able to make sense of per-recipient
	// errors.
	//
	// Here is the example of possible implementation for maildir-based
	// storage:
	// Calling Body creates a file in tmp/ directory.
	// Commit moves the created file to new/ directory.
	// Abort removes the created file.
	Body(ctx context.Context, header textproto.Header, body buffer.Buffer) error

	// Abort cancels message delivery.
	//
	// All changes made to the underlying storage should be aborted at this
	// point, if possible.
	Abort(ctx context.Context) error

	// Commit completes message delivery.
	//
	// It generally should never fail, since failures here jeopardize
	// atomicity of the delivery if multiple targets are used.
	Commit(ctx context.Context) error
}

type DeliveryTarget interface {
	// Start starts the delivery of a new message.
	//
	// The domain part of the MAIL FROM address is assumed to be U-labels with
	// NFC normalization and case-folding applied. The message source should
	// ensure that by calling address.CleanDomain if necessary.
	Start(ctx context.Context, msgMeta *MsgMetadata, mailFrom string) (Delivery, error)
}

type Dummy struct {
	// contains filtered or unexported fields
}

type EarlyCheck interface {
	CheckConnection(ctx context.Context, state *smtp.ConnectionState) error
}

type FuncNewEndpoint func(modName string, addrs []string) (Module, error)

type FuncNewModule func(modName, instName string, aliases, inlineArgs []string) (Module, error)

type ManageableStorage interface {
	Storage

	ListIMAPAccts() ([]string, error)
	CreateIMAPAcct(username string) error
	DeleteIMAPAcct(username string) error
}

type Modifier interface {
	// ModStateForMsg initializes modifier "internal" state
	// required for processing of the message.
	ModStateForMsg(ctx context.Context, msgMeta *MsgMetadata) (ModifierState, error)
}

type ModifierState interface {
	// RewriteSender allows modifier to replace MAIL FROM value.
	// If no changes are required, this method returns its
	// argument, otherwise it returns a new value.
	//
	// Note that per-source/per-destination modifiers are executed
	// after routing decision is made so changed value will have no
	// effect on it.
	//
	// Also note that MsgMeta.OriginalFrom will still contain the original value
	// for purposes of tracing. It should not be modified by this method.
	RewriteSender(ctx context.Context, mailFrom string) (string, error)

	// RewriteRcpt replaces RCPT TO value.
	// If no changed are required, this method returns its argument, otherwise
	// it returns a new value.
	//
	// MsgPipeline will take of populating MsgMeta.OriginalRcpts. RewriteRcpt
	// doesn't do it.
	RewriteRcpt(ctx context.Context, rcptTo string) (string, error)

	// RewriteBody modifies passed Header argument and may optionally
	// inspect the passed body buffer to make a decision on new header field values.
	//
	// There is no way to modify the body and RewriteBody should avoid
	// removing existing header fields and changing their values.
	RewriteBody(ctx context.Context, h *textproto.Header, body buffer.Buffer) error

	// Close is called after the message processing ends, even if any of the
	// Rewrite* functions return an error.
	Close() error
}

type Module interface {
	// Init performs actual initialization of the module.
	//
	// It is not done in FuncNewModule so all module instances are
	// registered at time of initialization, thus initialization does not
	// depends on ordering of configuration blocks and modules can reference
	// each other without any problems.
	//
	// Module can use passed config.Map to read its configuration variables.
	Init(*config.Map) error

	// Name method reports module name.
	//
	// It is used to reference module in the configuration and in logs.
	Name() string

	// InstanceName method reports unique name of this module instance or empty
	// string if module instance is unnamed.
	InstanceName() string
}

type MsgMetadata struct {
	// Unique identifier for this message. Randomly generated by the
	// message source module.
	ID string

	// Original message sender address as it was received by the message source.
	//
	// Note that this field is meant for use for tracing purposes.
	// All routing and other decisions should be made based on the sender address
	// passed separately (for example, mailFrom argument for CheckSender function)
	// Note that addresses may contain unescaped Unicode characters.
	OriginalFrom string

	// If set - no SrcHostname and SrcAddr will be added to Received
	// header. These fields are still written to the server log.
	DontTraceSender bool

	// Quarantine is a message flag that is should be set if message is
	// considered "suspicious" and should be put into "Junk" folder
	// in the storage.
	//
	// This field should not be modified by the checks that verify
	// the message. It is set only by the message pipeline.
	Quarantine bool

	// OriginalRcpts contains the mapping from the final recipient to the
	// recipient that was presented by the client.
	//
	// MsgPipeline will update that field when recipient modifiers
	// are executed.
	//
	// It should be used when reporting information back to client (via DSN,
	// for example) to prevent disclosing information about aliases
	// which is usually unwanted.
	OriginalRcpts map[string]string

	// SMTPOpts contains the SMTP MAIL FROM command arguments, if the message
	// was accepted over SMTP or SMTP-like protocol (such as LMTP).
	//
	// Note that the Size field should not be used as source of information about
	// the body size. Especially since it counts the header too whereas
	// Buffer.Len does not.
	SMTPOpts smtp.MailOptions

	// Conn contains the information about the underlying protocol connection
	// that was used to accept this message. The referenced instance may be shared
	// between multiple messages.
	//
	// It can be nil for locally generated messages.
	Conn *ConnState
}

type MutableTable interface {
	Table
	Keys() ([]string, error)
	RemoveKey(k string) error
	SetKey(k, v string) error
}

type PartialDelivery interface {
	// BodyNonAtomic is similar to Body method of the regular Delivery interface
	// with the except that it allows target to reject the body only for some
	// recipients by setting statuses using passed collector object.
	//
	// This interface is preferred by the LMTP endpoint and queue implementation
	// to ensure correct handling of partial failures.
	BodyNonAtomic(ctx context.Context, c StatusCollector, header textproto.Header, body buffer.Buffer)
}

type PlainAuth interface {
	AuthPlain(username, password string) error
}

type PlainUserDB interface {
	PlainAuth
	ListUsers() ([]string, error)
	CreateUser(username, password string) error
	SetUserPassword(username, password string) error
	DeleteUser(username string) error
}

type StatusCollector interface {
	// SetStatus sets the error associated with the recipient.
	//
	// rcptTo should match exactly the value that was passed to the
	// AddRcpt, i.e. if any translations was made by the target,
	// they should not affect the rcptTo argument here.
	//
	// It should not be called multiple times for the same
	// value of rcptTo. It also should not be called
	// after BodyNonAtomic returns.
	//
	// SetStatus is goroutine-safe. Implementations
	// provide necessary serialization.
	SetStatus(rcptTo string, err error)
}

type Storage interface {
	// GetOrCreateIMAPAcct returns User associated with storage account specified by
	// the name.
	//
	// If it doesn't exists - it should be created.
	GetOrCreateIMAPAcct(username string) (imapbackend.User, error)
	GetIMAPAcct(username string) (imapbackend.User, error)

	// Extensions returns list of IMAP extensions supported by backend.
	IMAPExtensions() []string
}

type Table interface {
	Lookup(s string) (string, bool, error)
}