uri-smtp 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49438452c14eb40d2d16d01c4f709e2ee1d40bfb664899befcd95099a7db451a
-  data.tar.gz: e98c9f37a0aa540895a32e428ca8d54277ff07a272349e438d8679113d679ca2
+  metadata.gz: 70ec42fc77da96a4bf7e8766406f110edbbd0de008148a7b62ad64b90137515e
+  data.tar.gz: def1342386b5d4ef7599f09750fd2dea8a709f06c452459c4f174374de4f48de
 SHA512:
-  metadata.gz: 46b9d9c3af1a9125c4eb6bfaa6b6d64d7f8b43c50dbecb6d4c077b577c94d04c110814b32cf2edaac085481c6cae80ef22336aa3dda56a4f0ac05681ed50fa1c
-  data.tar.gz: 6f291f3faacc6b8b01a87b6789b7b04308613b863b61f6343287c0c23583a8e8e3a65ce065f83a6d8a5214ac8d10cda7875f417ea905bd938bb0027596dece84
+  metadata.gz: 1eeb8f2e3f8debbc08271ae35c9a55cadbd2b2d7380a86d174cfa91461012b4986e1e9489c6fde38eedf018d1e5e8601807e6ba23fb6ed1aab3d0a755d82e628
+  data.tar.gz: d450be99efefaa24c20c2c6315a4d7b0a406d9ba043b558e6742a9bbe510670e0b6d076c5a1584ace1270ce650d73b9fd7549d93dd0853365b938b97713affe4

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
-## [0.1.0] - 2025-07-15
+## [0.4.0] - 2025-07-23
 
-- Initial release
+- FIX: correct settings for action_mailer using mail v2.8.1
+
+## [0.3.0] - 2025-07-23
+
+- FIX: Kernel.URI should accept URI's
+
+## [0.2.0] - 2025-07-18
+
+- Feature complete

data/README.md

@@ -1,6 +1,6 @@
 # URI::SMTP
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/uri/smtp`. To experiment with that code, run `bin/console` for an interactive prompt.
+This library allows for parsing SMTP-URIs.
 
 ## Installation
 
@@ -18,6 +18,120 @@ gem install uri-smtp
 
 ## Usage
 
+### parse
+
+```ruby
+u = URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com?domain=sender.org")
+
+url.scheme           #=> "smtps+login"
+url.auth             #=> "login"
+url.starttls         #=> false
+url.tls?             #=> true
+url.userinfo         #=> "user%40gmail.com:p%40ss"
+url.decoded_user     #=> "user@gmail.com"
+url.user             #=> "user%40gmail.com"
+url.decoded_password #=> "p@ss"
+url.password         #=> "p%40ss"
+url.host             #=> "smtp.gmail.com"
+url.port             #=> 465
+url.domain           #=> s"ender.org"
+url.query            #=> "domain=sender.org"
+```
+
+### to_h
+
+```ruby
+URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com?domain=sender.org").to_h
+{auth: "login",
+ domain: "sender.org",
+ host: "smtp.gmail.com",
+ port: 587,
+ scheme: "smtps+login",
+ starttls: :always,
+ tls: false,
+ user: "user@gmail.com",
+ password: "p@ss"}
+```
+
+Formatting for action_mailer configuration, use `to_h(format: :am)`:
+```ruby
+URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com?domain=sender.org").to_h(format: :am)
+{address: "smtp.gmail.com",
+ authentication: "login",
+ domain: "sender.org",
+ enable_starttls: :always,
+ port: 587,
+ user_name: "user@gmail.com",
+ password: "p@ss"}
+```
+
+
+Full Rails config:
+```ruby
+    config.action_mailer.delivery_method = :smtp
+    # [mailcatcher](https://github.com/sj26/mailcatcher) fallback:
+    config.action_mailer.smtp_settings = URI(ENV.fetch("SMTP_URL", "smtp://127.0.0.1:1025")).to_h(format: :am)
+```
+
+## SMTP-URI
+
+There's no official specification for SMTP-URIs. There's some prior work though. This implementation is heavily inspired by [aerc](https://git.sr.ht/~rjarry/aerc/tree/master/item/doc/aerc-smtp.5.scd).  
+
+`<scheme>[+<auth>]://[<user>[:<password>]@]<host>[:<port>][?<query>][#<fragment>]`
+
+### scheme
+
+- `smtp`  
+  SMTP with STARTTLS (i.e. `url.starttls #=> :always`).
+- `smtp+insecure`  
+  SMTP without STARTTLS (i.e. `url.starttls #=> false`)..
+- `smtps`  
+  SMTP with TLS.
+
+> [!NOTE]
+> to get `url.starttls #=> :auto`, provide it in the query: `smtp://foo?auth=auto`. In that case `net-smtp` uses STARTTLS when the server supports it (but won't halt like when using `:always`).
+
+
+### auth
+
+There's no restriction to the value of auth. Though the following values have special meaning:
+
+- `none`  
+  No authentication is required.
+- `plain`  
+  Authenticate with a username and password using AUTH PLAIN. This is the default behavior.
+
+> [!NOTE]
+> any query's value for `auth` takes precedence.
+
+### Examples
+
+| SMTP URI | TLS? | Port | STARTTLS | Auth Method | Notes |
+|----------|---------|------|----------|-------------|-------|
+| `smtp://smtp.example.com` | ❌ | 587 | ⚡ | none | Standard submission with STARTTLS `:always` |
+| `smtp+insecure://smtp.example.com` | ❌ | 587 | ❌ | none | Standard submission without STARTTLS |
+| `smtp+insecure+login://user:pass@smtp.example.com` | ❌ | 587 | ❌ | login | Authenticate insecurely using LOGIN auth |
+| `smtp://smtp.example.com?starttls=auto` | ❌ | 587 | 🔄 | none | Standard submission with STARTTLS `:auto` |
+| `smtp://smtp.example.com:1025` | ❌ | 1025 | ⚡ | none | Standard submission with STARTTLS `:always` on custom port |
+| `smtp://user:pass@mail.example.com` | ❌ | 587 | ⚡ | plain | STARTTLS `:always` with (default) PLAIN auth |
+| `smtp+login://user:pass@mail.example.com` | ❌ | 587 | ⚡ | login | STARTTLS `:always` with LOGIN auth |
+| `smtp+none://mail.example.com` | ❌ | 587 | 🔄 | none | Explicit no authentication |
+| `smtps://mail.example.com` | ✅ | 465 | ❌ | none | Direct TLS connection |
+| `smtps://mail.example.com?domain=sender.org&read_timeout=5&open_timeout=5` | ✅ | 465 | ❌ | none | `domain`, `read_timeout` and `open_timeout` set |
+| `smtps+login://user@imap.gmail.com` | ✅ | 465 | ❌ | login | Direct TLS with LOGIN auth |
+| `smtps://user%40gmail.com:p%40ss@imap.gmail.com` | ✅ | 465 | ❌ | login | Direct TLS with encoded userinfo `user@gmail.com:p@ss` |
+| `smtp://localhost` | ❌ | 25 | ❌ | none | Local delivery (no encryption) |
+| `smtp://127.0.0.1` | ❌ | 25 | ❌ | none | Local delivery (no encryption) |
+
+**Legend**
+
+`STARTTLS`
+- ⚡ = `:always`  
+  Require STARTTLS (i.e. `net-smtp` aborts when server doesn't support STARTTLS).
+- 🔄 = `:auto`  
+  Use STARTTLS if supported by server.
+- ❌ = `false`  
+  No STARTTLS. This is always the case when using TLS.
 
 ## Development
 

data/lib/uri/smtp/version.rb

@@ -4,6 +4,6 @@ require "uri"
 
 module URI
   class SMTP < URI::Generic
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/uri/smtp.rb

@@ -81,13 +81,23 @@ module URI
           address: host,
           authentication: auth,
           domain:,
-          enable_starttls: starttls,
-          port:
+          enable_starttls: starttls == :always,
+          enable_starttls_auto: starttls == :auto,
+          port:,
+          tls:
         }.tap do
           unless _1[:authentication].nil?
             _1[:user_name] = decoded_user
             _1[:password] = decoded_password
           end
+          # mail 2.8.1 logic is faulty in that it shortcuts
+          # (start)tls-settings when they are false.
+          # So we delete these flags.
+          _1.delete(:tls) unless _1[:tls]
+          _1.delete(:enable_starttls) unless _1[:enable_starttls]
+          _1.delete(:enable_starttls) if _1[:tls]
+          _1.delete(:enable_starttls_auto) unless _1[:enable_starttls_auto]
+          _1.delete(:enable_starttls_auto) if _1[:tls]
         end.delete_if { |_k, v| v.nil? }
       else
         {
@@ -118,7 +128,7 @@ end
 
 module UriSmtpExtensions
   def parse(uri)
-    if uri.start_with?("smtp")
+    if uri.is_a?(String) && uri.start_with?("smtp")
       return URI::SMTP.parse(uri)
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uri-smtp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Gert Goet