wneessen/go-mail
1
1
Fork 0
mirror of https://github.com/wneessen/go-mail.git synced 2024-11-15 02:12:55 +01:00
Code Issues Projects Releases Packages Wiki Activity

Refine method documentation in client.go

Browse source 
Correct typos and enhance clarity in method descriptions. Provide additional context for default values and behavior, and specify consequences for security settings in client configurations.
This commit is contained in:
Winni Neessen 2024-10-04 22:23:18 +02:00
parent eeaee3f60a
commit d900f5403e
Signed by: wneessen
GPG key ID: 385AC9889632126E
1 changed files with 42 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
client.go
View file

@ -311,7 +311,7 @@ func WithSSLPort(fallback bool) Option {
} }
} }
// WithDebugLog neables debug logging for the Client. The debug logger will log incoming and outgoing // WithDebugLog enables debug logging for the Client. The debug logger will log incoming and outgoing
// communication between the Client and the server to os.StdErr. // communication between the Client and the server to os.StdErr.
// //
// Note: The SMTP communication might include unencrypted authentication data, depending if you are // Note: The SMTP communication might include unencrypted authentication data, depending if you are
@ -492,8 +492,10 @@ func WithDSNRcptNotifyType(opts ...DSNRcptNotifyOption) Option {
} }
} }
// WithoutNoop disables the Client Noop check during connections. This is primarily for servers which delay responses // WithoutNoop indicates that the Client should skip the "NOOP" command during the dial.
// to SMTP commands that are not the AUTH command. For example Microsoft Exchange's Tarpit. //
// This is useful for servers which delay potentially unwanted clients when they perform commands
// other than AUTH. For example Microsoft Exchange's Tarpit.
func WithoutNoop() Option { func WithoutNoop() Option {
return func(c *Client) error { return func(c *Client) error {
c.noNoop = true c.noNoop = true
@ -501,7 +503,8 @@ func WithoutNoop() Option {
} }
} }
// WithDialContextFunc overrides the default DialContext for connecting SMTP server // WithDialContextFunc sets the provided DialContextFunc as DialContext and overrides the default DialContext for
// connecting to the SMTP server
func WithDialContextFunc(dialCtxFunc DialContextFunc) Option { func WithDialContextFunc(dialCtxFunc DialContextFunc) Option {
return func(c *Client) error { return func(c *Client) error {
c.dialContextFunc = dialCtxFunc c.dialContextFunc = dialCtxFunc
@ -509,34 +512,35 @@ func WithDialContextFunc(dialCtxFunc DialContextFunc) Option {
} }
} }
// TLSPolicy returns the currently set TLSPolicy as string // TLSPolicy returns the TLSPolicy that is currently set on the Client as string
func (c *Client) TLSPolicy() string { func (c *Client) TLSPolicy() string {
return c.tlspolicy.String() return c.tlspolicy.String()
} }
// ServerAddr returns the currently set combination of hostname and port // ServerAddr returns the server address that is currently set on the Client in the format "host:port".
func (c *Client) ServerAddr() string { func (c *Client) ServerAddr() string {
return fmt.Sprintf("%s:%d", c.host, c.port) return fmt.Sprintf("%s:%d", c.host, c.port)
} }
// SetTLSPolicy overrides the current TLSPolicy with the given TLSPolicy value // SetTLSPolicy sets or overrides the TLSPolicy that is currently set on the Client with the given
// TLSPolicy.
// //
// Note: To follow best-practices for SMTP TLS connections, it is recommended // Note: To follow best-practices for SMTP TLS connections, it is recommended to use SetTLSPortPolicy
// to use SetTLSPortPolicy instead. // instead.
func (c *Client) SetTLSPolicy(policy TLSPolicy) { func (c *Client) SetTLSPolicy(policy TLSPolicy) {
c.tlspolicy = policy c.tlspolicy = policy
} }
// SetTLSPortPolicy overrides the current TLSPolicy with the given TLSPolicy // SetTLSPortPolicy sets or overrides the TLSPolicy that is currently set on the Client with the given
// value. The correct port is automatically set. // TLSPolicy. The correct port is automatically set.
// //
// Port 587 is used for TLSMandatory and TLSOpportunistic. // If TLSMandatory or TLSOpportunistic are provided as TLSPolicy, port 587 will be used for the connection.
// If the connection fails with TLSOpportunistic, a plaintext connection is // If the connection fails with TLSOpportunistic, the Client will attempt to connect on port 25 using
// attempted on port 25 as a fallback. // using an unencrypted connection as a fallback. If NoTLS is provided, the Client will always use port 25.
// NoTLS will allways use port 25.
// //
// Note: If a different port has already been set otherwise, the port-choosing // Note: If a different port has already been set otherwise using WithPort, the selected port has higher
// and fallback automatism will be skipped. // precedence and is used to establish the SSL/TLS connection. In this case the authmatic fallback
// mechanism is skipped at all.
func (c *Client) SetTLSPortPolicy(policy TLSPolicy) { func (c *Client) SetTLSPortPolicy(policy TLSPolicy) {
if c.port == DefaultPort { if c.port == DefaultPort {
c.port = DefaultPortTLS c.port = DefaultPortTLS
@ -552,21 +556,21 @@ func (c *Client) SetTLSPortPolicy(policy TLSPolicy) {
c.tlspolicy = policy c.tlspolicy = policy
} }
// SetSSL tells the Client wether to use SSL or not // SetSSL sets or overrides wether the Client should use implicit SSL/TLS.
func (c *Client) SetSSL(ssl bool) { func (c *Client) SetSSL(ssl bool) {
c.useSSL = ssl c.useSSL = ssl
} }
// SetSSLPort tells the Client wether or not to use SSL and fallback. // SetSSLPort sets or overrides wether the Client should use implicit SSL/TLS with optional fallback. The
// The correct port is automatically set. // correct port is automatically set.
// //
// Port 465 is used when SSL set (true). // If ssl is set to true, the default port 25 will be overriden with port 465. If fallback is set to true
// Port 25 is used when SSL is unset (false). // and the SSL/TLS connection fails, the Client will attempt to connect on port 25 using using an
// When the SSL connection fails and fb is set to true, // unencrypted connection.
// the client will attempt to connect on port 25 using plaintext.
// //
// Note: If a different port has already been set otherwise, the port-choosing // Note: If a different port has already been set otherwise using WithPort, the selected port has higher
// and fallback automatism will be skipped. // precedence and is used to establish the SSL/TLS connection. In this case the authmatic fallback
// mechanism is skipped at all.
func (c *Client) SetSSLPort(ssl bool, fallback bool) { func (c *Client) SetSSLPort(ssl bool, fallback bool) {
if c.port == DefaultPort { if c.port == DefaultPort {
if ssl { if ssl {
@ -582,7 +586,12 @@ func (c *Client) SetSSLPort(ssl bool, fallback bool) {
c.useSSL = ssl c.useSSL = ssl
} }
// SetDebugLog tells the Client whether debug logging is enabled or not // SetDebugLog sets or overrides wether the Client is using debug logging. The debug logger will log
// incoming and outgoing communication between the Client and the server to os.StdErr.
//
// Note: The SMTP communication might include unencrypted authentication data, depending if you are
// using SMTP authentication and the type of authentication mechanism. This could pose a data
// protection problem. Use debug logging with care.
func (c *Client) SetDebugLog(val bool) { func (c *Client) SetDebugLog(val bool) {
c.useDebugLog = val c.useDebugLog = val
if c.smtpClient != nil { if c.smtpClient != nil {
@ -590,7 +599,10 @@ func (c *Client) SetDebugLog(val bool) {
} }
} }
// SetLogger tells the Client which log.Logger to use // SetLogger sets of overrides the custom logger currently set for the Client. The logger has to satisfy
// the log.Logger interface and is only used when debug logging is enabled on the Client.
//
// By default we use log.Stdlog.
func (c *Client) SetLogger(logger log.Logger) { func (c *Client) SetLogger(logger log.Logger) {
c.logger = logger c.logger = logger
if c.smtpClient != nil { if c.smtpClient != nil {
@ -598,7 +610,8 @@ func (c *Client) SetLogger(logger log.Logger) {
} }
} }
// SetTLSConfig overrides the current *tls.Config with the given *tls.Config value // SetTLSConfig sets or overrides the tls.Config that is currently set for the Client with the given value.
// An error is returned if the provided tls.Config is invalid.
func (c *Client) SetTLSConfig(tlsconfig *tls.Config) error { func (c *Client) SetTLSConfig(tlsconfig *tls.Config) error {
c.mutex.Lock() c.mutex.Lock()
defer c.mutex.Unlock() defer c.mutex.Unlock()