mailfilter

type Connect struct {
	Host   string        // The host name the MTA figured out for the remote client.
	Family milter.Family // Unknown, UNIX or TCP
	Unix   string        // If Family "unix", the path to the unix socket, else empty.
	Port   uint16        // If Family is TCP, the remote TCP port of the client connecting to the MTA
	Addr   netip.Addr    // If TCP, the IPv4 or IPv6 address of the remote client connecting to the MTA
	IfName string        // The Name of the network interface the MTA connection was accepted at. Might be empty.
	IfAddr string        // The IP address of the network interface the MTA connection was accepted at. Might be empty.
}

type Decision interface {
	// String returns the decision as an SMTP response string.
	// This is useful for testing/logging.
	String() string
	// Equal returns true if the decision is semantically equal to the provided decision.
	// This is useful for testing.
	// As a special case, a QuarantineResponse is equal to Accept.
	Equal(Decision) bool
}

type DecisionAt int

type DecisionModificationFunc func(ctx context.Context, trx Trx) (decision Decision, err error)

type ErrorHandling int

type Helo struct {
	Name        string // The HELO/EHLO hostname the client provided
	TlsVersion  string // TLSv1.3, TLSv1.2, ... or empty when no STARTTLS was used. Might even be empty when STARTTLS was used (when the MTA does not support the corresponding macro – almost all do).
	Cipher      string // The Cipher that the client and MTA negotiated.
	CipherBits  string // The bits of the cipher used. E.g., 256. Might be "RSA equivalent" bits for e.g., elliptic curve ciphers.
	CertSubject string // If MutualTLS was used for the connection between the client and MTA, this holds the subject of the validated client certificate.
	CertIssuer  string // If MutualTLS was used for the connection between the client and MTA, this holds the subject of the issuer of the client certificate (CA or Sub-CA).
}

type MTA struct {
	Version string // value of [milter.MacroMTAVersion] macro
	FQDN    string // value of [milter.MacroMTAFQDN] macro
	Daemon  string // value of [milter.MacroDaemonName] macro
}

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

type MaxAction int

type Option func(opt *options)

type RcptToValidationInput struct {
	// MTA holds information about the connecting MTA
	MTA *MTA
	// Connect holds the [Connect] information of this transaction.
	Connect *Connect
	// Helo holds the [Helo] information of this transaction.
	Helo *Helo
	// MailFrom holds the [addr.MailFrom] of this transaction.
	MailFrom *addr.MailFrom
	// RcptTo is the recipient address that needs to be validated
	RcptTo *addr.RcptTo
}

type RcptToValidator func(ctx context.Context, in *RcptToValidationInput) (Decision, error)

type Trx interface {
	// MTA holds information about the connecting MTA
	MTA() *MTA
	// Connect holds the [Connect] information of this transaction.
	Connect() *Connect
	// Helo holds the [Helo] information of this transaction.
	//
	// Only populated if [WithDecisionAt] is bigger than [DecisionAtConnect].
	Helo() *Helo

	// MailFrom holds the [addr.MailFrom] of this transaction.
	// Your changes to this pointer's Addr and Args values get send back to the MTA.
	//
	// Only populated if [WithDecisionAt] is bigger than [DecisionAtHelo].
	MailFrom() *addr.MailFrom
	// ChangeMailFrom changes the MailFrom Addr and Args.
	// This is just a convenience method, you could also directly change the MailFrom.
	//
	// When your filter should work with Sendmail you should set esmtpArgs to the empty string
	// since Sendmail validates the provided esmtpArgs and also rejects valid values like `SIZE=20`.
	ChangeMailFrom(from string, esmtpArgs string)

	// RcptTos holds the [RcptTo] recipient slice of this transaction.
	// Your changes to Addr and/or Args values of the elements of this slice get sent back to the MTA.
	// But you should use DelRcptTo and AddRcptTo
	//
	// Only populated if [WithDecisionAt] is bigger than [DecisionAtMailFrom].
	RcptTos() []*addr.RcptTo
	// HasRcptTo returns true when rcptTo is in the list of recipients.
	//
	// rcptTo get compared to the existing recipients IDNA address aware.
	HasRcptTo(rcptTo string) bool
	// AddRcptTo adds the rcptTo (without angles) to the list of recipients with the ESMTP arguments esmtpArgs.
	// If rcptTo is already in the list of recipients, only the esmtpArgs of this recipient get updated.
	//
	// rcptTo get compared to the existing recipients IDNA address aware.
	//
	// When your filter should work with Sendmail you should set esmtpArgs to the empty string
	// since Sendmail validates the provided esmtpArgs and also rejects valid values like `BODY=8BITMIME`.
	AddRcptTo(rcptTo string, esmtpArgs string)
	// DelRcptTo deletes the rcptTo (without angles) from the list of recipients.
	//
	// rcptTo get compared to the existing recipients IDNA address aware.
	DelRcptTo(rcptTo string)

	// Headers are the [Header] fields of this message.
	// You can use methods of [Header] to change the header fields of the current message.
	//
	// Only populated if [WithDecisionAt] is bigger than [DecisionAtData].
	Headers() header.Header
	// HeadersEnforceOrder activates a workaround for Sendmail to ensure that the header ordering of the resulting email
	// is exactly the same as the order in Headers. To ensure that, we delete all existing headers and add all headers
	// as new headers. This is, of course, a significant overhead, so you should only call this method when you really need
	// to enforce a specific header order.
	//
	// Sendmail may re-fold your header values (newline characters you inserted might get removed).
	//
	// For other MTAs this method does not do anything (since there we can ensure correct header ordering without this workaround).
	HeadersEnforceOrder()

	// Body gets you a [io.ReadSeeker] of the body.
	// The reader gets seeked to the start of the body whenever you call this method.
	//
	// This method returns nil when you used [WithDecisionAt] with anything other than [DecisionAtEndOfMessage]
	// or you used [WithoutBody].
	Body() io.ReadSeeker
	// ReplaceBody replaces the body of the current message with the contents of the [io.Reader] r.
	// The reader will only get read once, but it might get buffered when you call [Data] on the transaction.
	// When the reader implements the [io.Closer] interface, the milter will call [io.Closer.Close] on the reader when it is done with it.
	ReplaceBody(r io.Reader)

	// QueueId is the queue ID the MTA assigned for this transaction.
	// You cannot change this value.
	//
	// Only populated if [WithDecisionAt] is bigger than [DecisionAtMailFrom].
	QueueId() string

	// Data returns the full email data (headers and body) of the current message.
	// It includes any modifications you made to the Headers and either uses Body or ReplaceBody as the body of the message.
	// If you set WithoutBody, WithDecisionAt is not DecisionAtEndOfMessage, or the body is bigger than the configured maximum body size, Data will be the same as [header.Header.Reader].
	// A call to Data might re-use the Body io.ReadSeeker. Using Data and Body at the same time is not supported.
	Data() io.Reader
}