Extract several packages to form a public API

framework/module/msgmetadata.go

@@ -0,0 +1,133 @@
+package module
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"io"
+
+	"github.com/emersion/go-smtp"
+	"github.com/foxcpp/maddy/framework/future"
+)
+
+// ConnState structure holds the state information of the protocol used to
+// accept this message.
+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
+}
+
+// MsgMetadata structure contains all information about the origin of
+// the message and all associated flags indicating how it should be handled
+// by components.
+//
+// All fields should be considered read-only except when otherwise is noted.
+// Module instances should avoid keeping reference to the instance passed to it
+// and copy the structure using DeepCopy method instead.
+//
+// Compatibility with older values should be considered when changing this
+// structure since it is serialized to the disk by the queue module using
+// JSON. Modules should correctly handle missing or invalid values.
+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
+
+	// This is set by endpoint/smtp to indicate that body contains "TLS-Required: No"
+	// header. It is only meaningful if server has seen the body at least once
+	// (e.g. the message was passed via queue).
+	TLSRequireOverride bool
+}
+
+// DeepCopy creates a copy of the MsgMetadata structure, also
+// copying contents of the maps and slices.
+//
+// There are a few exceptions, however:
+// - SrcAddr is not copied and copy field references original value.
+func (msgMeta *MsgMetadata) DeepCopy() *MsgMetadata {
+	cpy := *msgMeta
+	// There is no good way to copy net.Addr, but it should not be
+	// modified by anything anyway so we are safe.
+	return &cpy
+}
+
+// GenerateMsgID generates a string usable as MsgID field in module.MsgMeta.
+func GenerateMsgID() (string, error) {
+	rawID := make([]byte, 4)
+	_, err := io.ReadFull(rand.Reader, rawID)
+	return hex.EncodeToString(rawID), err
+}