uri-smtp 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8bf2f07b31cf5111ff58301d72dd91f186b890d417e0c22ab8d353c541ea763
-  data.tar.gz: e4b9f677a881051408f03e11a90a01095269c533cfc6cb34972c10fa358390b1
+  metadata.gz: 534a3148493353560954ff1399ed0bcc5972fb84a0a72f95389827e9b2e59c66
+  data.tar.gz: 0701b94ea526034678a4cd2cdd72996ca3e21e8e2a91d1ce4ea120a4ccc09c7b
 SHA512:
-  metadata.gz: 020ece2e1fc267c79ac9a28b5d74f57e448696676419c5eb6393e9db3f96a39abc7c1a11555000b793ae659013d2e8634bbdcd1d97199589a50704cdf51516d3
-  data.tar.gz: 7bcfcd9a669f90c42abe78f5a96c0af16ba4593ade3d42c3b90b43f8d8a620a464c96e4e836d4f8a4424bb08ac0c30ca0a1ffc88ee57ed49d761e809bfc9f7fd
+  metadata.gz: 59430a383a5a47c243dfe487d51f5749c0a58ffd1ba836c6fe1fb53c3b51927fed39329ba83f5a7853456a0f48abe13e7402cf33d182c6ed7d9881c53606366b
+  data.tar.gz: ab4b650b59960e5d6b1859ec78ea266fa1b50b4cc3d01c592662be8f3562bfc40a7ca70e4296a7b5a4fba9e1df5f6797b79851236223c9fcfec23d5f409d2345

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
-## [0.1.0] - 2025-07-15
+## [0.3.0] - 2025-07-23
 
-- Initial release
+- 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.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/uri/smtp.rb

@@ -6,8 +6,124 @@ require_relative "smtp/version"
 module URI
   class SMTP < URI::Generic
     class Error < StandardError; end
+
+    def initialize(scheme,
+      userinfo, host, port, registry,
+      path, opaque,
+      query,
+      fragment,
+      parser = DEFAULT_PARSER,
+      arg_check = false)
+      super
+    end
+
+    def port
+      return @port if @port
+      return 25 if host_local?
+      return 465 if tls?
+      587
+    end
+
+    def auth
+      # net-smtp: passing authtype without user/pw raises error
+      return nil unless userinfo
+      return parsed_query["auth"] if parsed_query.has_key?("auth")
+      return nil if scheme_auth == "none"
+      return scheme_auth if scheme_auth
+      "plain"
+    end
+
+    def domain
+      parsed_query["domain"]
+    end
+
+    def scheme_auth
+      scheme[/.*(?:\+(.+))/, 1]
+    end
+
+    def starttls
+      return false if tls?
+      return parsed_query["starttls"] if parsed_query.has_key?("starttls")
+      return false if host_local?
+      return false if insecure?
+      :always
+    end
+    alias_method :starttls?, :starttls
+
+    def tls
+      scheme == "smtps"
+    end
+    alias_method :tls?, :tls
+
+    def insecure?
+      scheme == "smtp+insecure"
+    end
+
+    def host_local?
+      %w[127.0.0.1 localhost].include?(host)
+    end
+
+    def parsed_query
+      @parsed_query ||= URI.decode_www_form(query.to_s).to_h.tap do
+        _1["starttls"] &&= case _1["starttls"]
+        when "always", "auto" then _1["starttls"].to_sym
+        when "false" then false
+        else
+          :always
+        end
+      end
+    end
+
+    def to_h(format: nil)
+      case format
+      when :am, :action_mailer
+        {
+          address: host,
+          authentication: auth,
+          domain:,
+          enable_starttls: starttls,
+          port:
+        }.tap do
+          unless _1[:authentication].nil?
+            _1[:user_name] = decoded_user
+            _1[:password] = decoded_password
+          end
+        end.delete_if { |_k, v| v.nil? }
+      else
+        {
+          auth:,
+          domain:,
+          host:,
+          port:,
+          scheme:,
+          starttls:,
+          tls:
+        }.tap do
+          unless _1[:auth].nil?
+            _1[:user] = decoded_user
+            _1[:password] = decoded_password
+          end
+        end.delete_if { |_k, v| v.nil? }
+      end
+    end
+
+    def self.parse(uri)
+      new(*URI.split(uri))
+    end
   end
 
   register_scheme "SMTP", SMTP
   register_scheme "SMTPS", SMTP
 end
+
+module UriSmtpExtensions
+  def parse(uri)
+    if uri.is_a?(String) && uri.start_with?("smtp")
+      return URI::SMTP.parse(uri)
+    end
+
+    super
+  end
+end
+
+URI.singleton_class.prepend(UriSmtpExtensions)

metadata

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