queue

Documentation

Overview

Package queue is in charge of outgoing messages, queueing them when submitted, attempting a first delivery over SMTP, retrying with backoff and sending DSNs for delayed or failed deliveries.

Index

• Constants
• Variables
• func Add(ctx context.Context, log mlog.Log, senderAccount string, msgFile *os.File, ...) error
• func ConnectionCounter() int64
• func Count(ctx context.Context) (int, error)
• func Drop(ctx context.Context, log mlog.Log, ID int64, toDomain string, recipient string) (int, error)
• func Init() error
• func Kick(ctx context.Context, ID int64, toDomain, recipient string, transport *string) (int, error)
• func SaveRequireTLS(ctx context.Context, id int64, requireTLS *bool) error
• func Shutdown()
• func Start(resolver dns.Resolver, done chan struct{}) error
• type Msg
  • func List(ctx context.Context) ([]Msg, error)
  • func MakeMsg(sender, recipient smtp.Path, has8bit, smtputf8 bool, size int64, ...) Msg
  • func (m Msg) MessagePath() string
  • func (m Msg) Recipient() smtp.Path
  • func (m Msg) Sender() smtp.Path
• type ReadReaderAtCloser
  • func OpenMessage(ctx context.Context, id int64) (ReadReaderAtCloser, error)

Constants

const FutureReleaseIntervalMax = 60 * 24 * time.Hour

Allow requesting delivery starting from up to this interval from time of submission.

Variables

var DB *bstore.DB // Exported for making backups.

var DBTypes = []any{Msg{}} // Types stored in DB.

var Localserve bool

Set for mox localserve, to prevent queueing.

Functions

func Add

func Add(ctx context.Context, log mlog.Log, senderAccount string, msgFile *os.File, qml ...Msg) error

Add one or more new messages to the queue. They'll get the same BaseID, so they can be delivered in a single SMTP transaction, with a single DATA command, but may be split into multiple transactions if errors/limits are encountered. The queue is kicked immediately to start a first delivery attempt.

ID of the messagse must be 0 and will be set after inserting in the queue.

Add sets derived fields like RecipientDomainStr, and fields related to queueing, such as Queued, NextAttempt, LastAttempt, LastError.

func ConnectionCounter

func ConnectionCounter() int64

func Count

func Count(ctx context.Context) (int, error)

Count returns the number of messages in the delivery queue.

func Drop

func Drop(ctx context.Context, log mlog.Log, ID int64, toDomain string, recipient string) (int, error)

Drop removes messages from the queue that match all nonzero parameters. If all parameters are zero, all messages are removed. Returns number of messages removed.

func Init

func Init() error

Init opens the queue database without starting delivery.

func Kick

func Kick(ctx context.Context, ID int64, toDomain, recipient string, transport *string) (int, error)

Kick sets the NextAttempt for messages matching all filter parameters (ID, toDomain, recipient) that are nonzero, and kicks the queue, attempting delivery of those messages. If all parameters are zero, all messages are kicked. If transport is set, the delivery attempts for the matching messages will use the transport. An empty string is the default transport, i.e. direct delivery. Returns number of messages queued for immediate delivery.

func SaveRequireTLS

func SaveRequireTLS(ctx context.Context, id int64, requireTLS *bool) error

SaveRequireTLS updates the RequireTLS field of the message with id.

func Shutdown

func Shutdown()

Shutdown closes the queue database. The delivery process isn't stopped. For tests only.

func Start

func Start(resolver dns.Resolver, done chan struct{}) error

Start opens the database by calling Init, then starts the delivery process.

Types

type Msg

type Msg struct {
	ID int64

	// A message for multiple recipients will get a BaseID that is identical to the
	// first Msg.ID queued. The message contents will be identical for each recipient,
	// including MsgPrefix. If other properties are identical too, including recipient
	// domain, multiple Msgs may be delivered in a single SMTP transaction. For
	// messages with a single recipient, this field will be 0.
	BaseID int64 `bstore:"index"`

	Queued             time.Time      `bstore:"default now"`
	SenderAccount      string         // Failures are delivered back to this local account. Also used for routing.
	SenderLocalpart    smtp.Localpart // Should be a local user and domain.
	SenderDomain       dns.IPDomain
	RecipientLocalpart smtp.Localpart // Typically a remote user and domain.
	RecipientDomain    dns.IPDomain
	RecipientDomainStr string              // For filtering.
	Attempts           int                 // Next attempt is based on last attempt and exponential back off based on attempts.
	MaxAttempts        int                 // Max number of attempts before giving up. If 0, then the default of 8 attempts is used instead.
	DialedIPs          map[string][]net.IP // For each host, the IPs that were dialed. Used for IP selection for later attempts.
	NextAttempt        time.Time           // For scheduling.
	LastAttempt        *time.Time
	LastError          string

	Has8bit       bool   // Whether message contains bytes with high bit set, determines whether 8BITMIME SMTP extension is needed.
	SMTPUTF8      bool   // Whether message requires use of SMTPUTF8.
	IsDMARCReport bool   // Delivery failures for DMARC reports are handled differently.
	IsTLSReport   bool   // Delivery failures for TLS reports are handled differently.
	Size          int64  // Full size of message, combined MsgPrefix with contents of message file.
	MessageID     string // Used when composing a DSN, in its References header.
	MsgPrefix     []byte

	// If set, this message is a DSN and this is a version using utf-8, for the case
	// the remote MTA supports smtputf8. In this case, Size and MsgPrefix are not
	// relevant.
	DSNUTF8 []byte

	// If non-empty, the transport to use for this message. Can be set through cli or
	// admin interface. If empty (the default for a submitted message), regular routing
	// rules apply.
	Transport string

	// RequireTLS influences TLS verification during delivery.
	//
	// If nil, the recipient domain policy is followed (MTA-STS and/or DANE), falling
	// back to optional opportunistic non-verified STARTTLS.
	//
	// If RequireTLS is true (through SMTP REQUIRETLS extension or webmail submit),
	// MTA-STS or DANE is required, as well as REQUIRETLS support by the next hop
	// server.
	//
	// If RequireTLS is false (through messag header "TLS-Required: No"), the recipient
	// domain's policy is ignored if it does not lead to a successful TLS connection,
	// i.e. falling back to SMTP delivery with unverified STARTTLS or plain text.
	RequireTLS *bool

	// For DSNs, where the original FUTURERELEASE value must be included as per-message
	// field. This field should be of the form "for;" plus interval, or "until;" plus
	// utc date-time.
	FutureReleaseRequest string
}

Msg is a message in the queue.

Use MakeMsg to make a message with fields that Add needs. Add will further set queueing related fields.

func List

func List(ctx context.Context) ([]Msg, error)

List returns all messages in the delivery queue. Ordered by earliest delivery attempt first.

func MakeMsg

func MakeMsg(sender, recipient smtp.Path, has8bit, smtputf8 bool, size int64, messageID string, prefix []byte, requireTLS *bool, next time.Time) Msg

MakeMsg is a convenience function that sets the commonly used fields for a Msg.

func (Msg) MessagePath

func (m Msg) MessagePath() string

MessagePath returns the path where the message is stored.

func (Msg) Recipient

func (m Msg) Recipient() smtp.Path

Recipient of message as used in RCPT TO.

func (Msg) Sender

func (m Msg) Sender() smtp.Path

Sender of message as used in MAIL FROM.

type ReadReaderAtCloser

type ReadReaderAtCloser interface {
	io.ReadCloser
	io.ReaderAt
}

func OpenMessage

func OpenMessage(ctx context.Context, id int64) (ReadReaderAtCloser, error)

OpenMessage opens a message present in the queue.