wneessen/go-mail
1
1
Fork 0
mirror of https://github.com/wneessen/go-mail.git synced 2024-10-06 02:05:57 +02:00
Code Issues Projects Releases Packages Wiki Activity

Improve client option documentation for clarity and validation

Browse source 
Enhanced the documentation for NewClient and related option functions to provide clearer descriptions. Added validation details for WithPort and WithTimeout, and improved explanations for SSL/TLS settings.
This commit is contained in:
Winni Neessen 2024-10-04 21:26:29 +02:00
parent 779a3f3942
commit a34f400a05
Signed by: wneessen
GPG key ID: 385AC9889632126E
1 changed files with 17 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
client.go
View file

@ -225,7 +225,11 @@ var (
"combined with any of SUCCESS, FAILURE or DELAY")
)
// NewClient returns a new Session client object
// NewClient creates a new Client instance with the provided host and optional configuration Option functions.
// It initializes default values for connection timeout, port, TLS settings, and HELO/EHLO hostname.
// Option functions, if provided, override default values.
//
// Returns an error if critical defaults are unset.
func NewClient(host string, opts ...Option) (*Client, error) {
c := &Client{
connTimeout: DefaultTimeout,
@ -258,7 +262,8 @@ func NewClient(host string, opts ...Option) (*Client, error) {
return c, nil
}
// WithPort overrides the default connection port
// WithPort sets the port number for the Client and overrides the default port. It validates the port number to
// ensure it is between 1 and 65535. An error is returned if the provided port number is invalid.
func WithPort(port int) Option {
return func(c *Client) error {
if port < 1 || port > 65535 {
@ -269,7 +274,8 @@ func WithPort(port int) Option {
}
}
// WithTimeout overrides the default connection timeout
// WithTimeout sets the connection timeout for the Client to the provided duration and overrides the default
// timeout. An error is returned if the provided timeout is invalid.
func WithTimeout(timeout time.Duration) Option {
return func(c *Client) error {
if timeout <= 0 {
@ -280,7 +286,7 @@ func WithTimeout(timeout time.Duration) Option {
}
}
// WithSSL tells the client to use a SSL/TLS connection
// WithSSL enables implicit SSL/TLS for the Client.
func WithSSL() Option {
return func(c *Client) error {
c.useSSL = true
@ -288,16 +294,16 @@ func WithSSL() Option {
}
}
// WithSSLPort tells the Client wether or not to use SSL and fallback.
// WithSSLPort enables implicit SSL/TLS with an optional fallback for the Client.
// The correct port is automatically set.
//
// Port 465 is used when SSL set (true).
// Port 25 is used when SSL is unset (false).
// When the SSL connection fails and fb is set to true,
// the client will attempt to connect on port 25 using plaintext.
// If this option is used with NewClient, the default port 25 will be overriden
// with port 465. If fallback is set to true and the SSL/TLS connection fails,
// the Client will attempt to connect on port 25 using plaintext.
//
// Note: If a different port has already been set otherwise, the port-choosing
// and fallback automatism will be skipped.
// Note: If a different port has already been set otherwise using WithPort, the
// selected port has higher precedence and is used to establish the SSL/TLS
// connection. In this case the authmatic fallback mechanism is skipped at all.
func WithSSLPort(fallback bool) Option {
return func(c *Client) error {
c.SetSSLPort(true, fallback)