Skip to content

v0.5.0: Concurrency-safety, SCRAM-SHA, improved error handling and better GoDoc documentation // *POTENTIALLY BREAKING*

Compare
Choose a tag to compare
@wneessen wneessen released this 06 Oct 16:07
· 553 commits to main since this release
v0.5.0
a94e721
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.

Welcome to go-mail v0.5.0! This release is a big one, bringing new features and improvements to the go-mail codebase!

Goroutine-/thread-safety (Potentially breaking)

With #307 we've made go-mail goroutine-safe by introducing a sync.Mutex. Concurrency-safety was a much requested feature, now allowing you to dial your Client and then use that Client in different goroutines. While we've added a lot of new tests (including a test SMTP server to which we connect to in different goroutines), this feature has not been extensively tested in an production environment. Therefore we've marked this features (and respectively this release) as a potentially breaking release. If you plan to use go-mail in a concurrency scenario, please test properly and report back any issues.

SCRAM-SHA-1(-PLUS) / SCRAM-SHA-256(-PLUS) SMTP authentication support

With #310 we have introduced SMTP authentication functions for SCRAM-SHA-1(-PLUS) and SCRAM-SHA-256(-PLUS). Most of the ground work was contributed by @drakkan. @wneessen cleaned up the code a bit, added channel bindings support and added several test cases.

SCRAM-SHA-X(-PLUS) isn't commonly supported, yet but I've tested the code with Dovecot (no channel binding support) and mox (supports both) and the code seems to be working properly. Feedback from using SCRAM with other systems is appreciated!

Thanks again to @drakkan for the excellent WIP code.

Improved error handling

With #301 the error handling was refactored in accordance to #168. Errors are not nested into each other anymore. The send logic for a single message has been moved to the non-version-specific Client.go while the version-specific only handle multi-message handling and error combination. Error messages now also refer to a message ID of the message that failed (if present), for easier debugging.

Thanks to @mitar for pointing out the flaws in the old error handling system and for suggesting the improvements.

Enhanced SMTP LOGIN authentication handling

With #312 we've refactored the SMTP LOGIN auth handling, to improve compatibility with various server responses.

In detail: before, we were only roughly following the Microsoft Spec they defined for MS Outlook.
Meaning:

  • Sending AUTH LOGIN (server might responds with "Username:")
  • Sending the username (server might responds with "Password:")
  • Sending the password (server authenticates)

This is the common approach for most mail systems/providers and is the specified way by Microsoft in their MS-XLOGIN spec.

Yet, there is also an old IETF draft for SMTP AUTH LOGIN that states for clients:

The contents of both challenges SHOULD be ignored.

Since there is no official standard RFC and we've seen different implementations of this mechanism (sending "Username:", "Username", "username", "User name", etc.) we now follow the IETF-Draft instead and ignore any server challange to allow compatiblity with most mail servers/providers. This way it works with servers that follow the Microsoft way but also any other kind of implementation (like i. e. Mox).

Improved GoDoc documentation

With #324 we revises the GoDoc documenation comments for the whole package. It provides much more details for each method in a more standardised format, allowing users of the package to get better information on what does what. This is especially helpful for LSP implementations like gopls.

Simplified random number generation

The random methods for generating random numbers have been simplified and the use of crypto/rand has been replaced by math/rand or math/rand/v2 (depending on the used Go version). We've realized that for our use cases, math/rand will provide enough randomness. It simplies the randNum code a lot.

Dependencies (Potentially breaking)

So far, we were always commited to keep go-mail dependency-free, meaning only relying on the Go Stdlib. So far this has been working well and we believe that people appreciate that no further dependcies are added to their project, when they import go-mail. Yet, we've finally reached a point, where adding new features might require us to import some limited dependencies. This happened with the SCRAM support in #310. We've done a poll beforehand to see if the community is fine with this and the common agreement is, that people are ok with a limited, well curated list of external packages as long as the packages are still maintained and have a good security reputation. Therefore this release adds the first dependencies to go-mail - both from the Go extended library:

  • golang.org/x/crypto
  • golang.org/x/text

As your codebase might not allow for additional dependencies, this feature is also marked as Potentially breaking

We hope you like this release and a big thanks goes out the community that contributed to this release.

What's Changed

CI/CD maintenance changes

  • Bump step-security/harden-runner from 2.9.1 to 2.10.1 by @dependabot in #297
  • Bump github/codeql-action from 3.26.6 to 3.26.7 by @dependabot in #299
  • Bump github/codeql-action from 3.26.7 to 3.26.8 by @dependabot in #300
  • Bump sonarsource/sonarqube-scan-action from 0c0f3958d90fc466625f1d1af1f47bddd4cc6bd1 to f885e52a7572cf7943f28637e75730227df2dbf2 by @dependabot in #304
  • Bump github/codeql-action from 3.26.8 to 3.26.9 by @dependabot in #306
  • Bump sonarsource/sonarqube-scan-action from f885e52a7572cf7943f28637e75730227df2dbf2 to 884b79409bbd464b2a59edc326a4b77dc56b2195 by @dependabot in #305
  • Bump github/codeql-action from 3.26.9 to 3.26.10 by @dependabot in #309
  • Fix GitHub actions by @wneessen in #315
  • Bump golang/govulncheck-action from 1.0.3 to 1.0.4 by @dependabot in #314
  • Bump codecov/codecov-action from 4.5.0 to 4.6.0 by @dependabot in #313
  • Bump golangci/golangci-lint-action from 6.1.0 to 6.1.1 by @dependabot in #318
  • Bump github/codeql-action from 3.26.10 to 3.26.11 by @dependabot in #321
  • Update GH test workflows by @wneessen in #319
  • Update GitHub Actions paths for Go and workflow files by @wneessen in #322

Full Changelog: v0.4.4...v0.5.0

Contributors

wneessen, drakkan, and 2 other contributors
Assets 2
Loading
0 Join discussion