smtpconn

Documentation

Overview

The package smtpconn contains the code shared between target.smtp and remote modules.

It implements the wrapper over the SMTP connection (go-smtp.Client) object with the following features added: - Logging of certain errors (e.g. QUIT command errors) - Wrapping of returned errors using the exterrors package. - SMTPUTF8/IDNA support. - TLS support mode (don't use, attempt, require).

Index

• type C
  • func New() *C
  • func (c *C) Client() *smtp.Client
  • func (c *C) Close() error
  • func (c *C) Connect(ctx context.Context, endp config.Endpoint, starttls bool, ...) (didTLS bool, err error)
  • func (c *C) ConnectLMTP(ctx context.Context, endp config.Endpoint, starttls bool, ...) (didTLS bool, err error)
  • func (c *C) Data(ctx context.Context, hdr textproto.Header, body io.Reader) error
  • func (c *C) DirectClose() error
  • func (c *C) IsLMTP() bool
  • func (c *C) LMTPData(ctx context.Context, hdr textproto.Header, body io.Reader, ...) error
  • func (c *C) Mail(ctx context.Context, from string, opts smtp.MailOptions) error
  • func (c *C) Noop() error
  • func (c *C) Rcpt(ctx context.Context, to string) error
  • func (c *C) Rcpts() []string
  • func (c *C) ServerName() string
• type TLSError
  • func (err TLSError) Error() string
  • func (err TLSError) Unwrap() error

Types

type C

type C struct {
	// Dialer to use to estabilish new network connections. Set to net.Dialer
	// DialContext by New.
	Dialer func(ctx context.Context, network, addr string) (net.Conn, error)

	// Timeout for most session commands (EHLO, MAIL, RCPT, DATA, STARTTLS).
	// Set to 5 mins by New.
	CommandTimeout time.Duration

	// Timeout for the initial TCP connection establishment.
	ConnectTimeout time.Duration

	// Timeout for the final dot. Set to 12 mins by New.
	// (see go-smtp source for explanation of used defaults).
	SubmissionTimeout time.Duration

	// Hostname to sent in the EHLO/HELO command. Set to
	// 'localhost.localdomain' by New. Expected to be encoded in ACE form.
	Hostname string

	// tls.Config to use. Can be nil if no special changes are required.
	TLSConfig *tls.Config

	// Logger to use for debug log and certain errors.
	Log log.Logger

	// Include the remote server address in SMTP status messages in the form
	// "ADDRESS said: ..."
	AddrInSMTPMsg bool
	// contains filtered or unexported fields
}

The C object represents the SMTP connection and is a wrapper around go-smtp.Client with additional maddy-specific logic.

Currently, the C object represents one session and cannot be reused.

func New

func New() *C

New creates the new instance of the C object, populating the required fields with resonable default values.

func (*C) Client

func (c *C) Client() *smtp.Client

func (*C) Close

func (c *C) Close() error

Close sends the QUIT command, if it fail - it directly closes the connection.

func (*C) Connect

func (c *C) Connect(ctx context.Context, endp config.Endpoint, starttls bool, tlsConfig *tls.Config) (didTLS bool, err error)

Connect actually estabilishes the network connection with the remote host, executes HELO/EHLO and optionally STARTTLS command.

func (*C) ConnectLMTP

func (c *C) ConnectLMTP(ctx context.Context, endp config.Endpoint, starttls bool, tlsConfig *tls.Config) (didTLS bool, err error)

ConnectLMTP estabilishes the network connection with the remote host and sends LHLO command, negotiating LMTP use.

func (*C) Data

func (c *C) Data(ctx context.Context, hdr textproto.Header, body io.Reader) error

Data sends the DATA command to the remote server and then sends the message header and body.

If the Data command fails, the connection may be in a unclean state (e.g. in the middle of message data stream). It is not safe to continue using it.

func (*C) DirectClose

func (c *C) DirectClose() error

DirectClose closes the underlying connection without sending the QUIT command.

func (*C) IsLMTP

func (c *C) IsLMTP() bool

func (*C) LMTPData

func (c *C) LMTPData(ctx context.Context, hdr textproto.Header, body io.Reader, statusCb func(string, *smtp.SMTPError)) error

func (*C) Mail

func (c *C) Mail(ctx context.Context, from string, opts smtp.MailOptions) error

Mail sends the MAIL FROM command to the remote server.

SIZE and REQUIRETLS options are forwarded to the remote server as-is. SMTPUTF8 is forwarded if supported by the remote server, if it is not supported - attempt will be done to convert addresses to the ASCII form, if this is not possible, the corresponding method (Mail or Rcpt) will fail.

func (*C) Noop

func (c *C) Noop() error

func (*C) Rcpt

func (c *C) Rcpt(ctx context.Context, to string) error

Rcpt sends the RCPT TO command to the remote server.

If the address is non-ASCII and cannot be converted to ASCII and the remote server does not support SMTPUTF8, error will be returned.

func (*C) Rcpts

func (c *C) Rcpts() []string

Rcpts returns the list of recipients that were accepted by the remote server.

func (*C) ServerName

func (c *C) ServerName() string

type TLSError

type TLSError struct {
	Err error
}

TLSError is returned by Connect to indicate the error during STARTTLS command execution.

If the endpoint uses Implicit TLS, TLS errors are threated as connection errors and thus are not returned as TLSError.

func (TLSError) Error

func (err TLSError) Error() string

func (TLSError) Unwrap

func (err TLSError) Unwrap() error