Config smtp-delivery via url

Author: eval

CHANGELOG.rdoc

@@ -11,6 +11,7 @@ Features:
 
 * Updated README to improve around sending multipart mail @kapfenho
 * Add delivery_interceptors method to Mail class to fetch registered interceptors @ghousemohamed
+* Configure smtp-delivery using a url @eval
 
 Code Improvements:
 

README.md

@@ -277,6 +277,8 @@ mail.delivery_method :sendmail
 mail.deliver
 ```
 
+#### Sending via SMTP
+
 Sending via smtp (for example to [mailcatcher](https://github.com/sj26/mailcatcher))
 ```ruby
 
@@ -285,6 +287,43 @@ Mail.defaults do
 end
 ```
 
+A url is also accepted:
+```ruby
+Mail.defaults do
+  # The following (note the URL-encoded userinfo)...:
+  delivery_method :smtp, url: 'smtp://user%40gmail.com:[email protected]'
+
+  # ...would be equivalent to:
+  delivery_method :smtp, { :address              => 'smtp.gmail.com',
+                           :port                 => 587,
+                           :user_name            => '[email protected]',
+                           :password             => 'app-password',
+                           :tls                  => false,
+                           :enable_starttls      => :always }
+
+  # Provide additional settings or overrides via the query string of the url:
+  delivery_method :smtp, url: '<above-url>?enable_starttls=auto&authentication=login'
+
+  # For localhost (or 127.0.0.1) it assumes no tls, nor starttls.
+  # So the following would work using [mailcatcher](https://github.com/sj26/mailcatcher):
+  delivery_method :smtp, url: 'smtp://127.0.0.1:1025'
+
+  # Scheme 'smtps' enables `tls` and uses port 465:
+  delivery_method :smtp, url: 'smtps://user%40gmail.com:[email protected]'
+
+  # Attributes provided via the url take precedence over other provided attributes.
+  # So in the following example, `address` will be set to 'smtp.gmail.com',
+  # and `authentication` will be set to 'login':
+  delivery_method :smtp, url: 'smtps://user%40gmail.com:[email protected]',
+                         address: 'ignored.org',
+                         authentication: 'login'
+
+  # Typically you would provide the url via an environment variable:
+  delivery_method :smtp, url: ENV["MY_APP_SMTP_URL"]
+end
+```
+
+#### Sending via Exim
 
 Exim requires its own delivery manager, and can be used like so:
 
@@ -294,6 +333,8 @@ mail.delivery_method :exim, :location => "/usr/bin/exim"
 mail.deliver
 ```
 
+#### Logging
+
 Mail may be "delivered" to a logfile, too, for development and testing:
 
 ```ruby

lib/mail/network/delivery_methods/smtp.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 require 'mail/smtp_envelope'
+require 'mail/utilities'
 
 module Mail
   # == Sending Email with SMTP
@@ -35,8 +36,21 @@ module Mail
   #                              :password             => '<password>',
   #                              :authentication       => 'plain',
   #                              :enable_starttls_auto => true  }
+  #
+  #     # ...or using the url-attribute (note the trailing 's' in the scheme
+  #     # to set `tls`, also note the URL-encoded userinfo):
+  #     delivery_method :smtp,
+  #        { :url => 'smtps://user%40gmail.com:[email protected]' }
   #   end
   #
+  # === Sending via Fastmail
+  #
+  #   Mail.defaults do
+  #     delivery_method :smtp,
+  #       { :url => 'smtps://user%40fastmail.fm:[email protected]' }
+  #   end
+  #
+  #
   # === Certificate verification
   #
   # When using TLS, some mail servers provide certificates that are self-signed
@@ -74,6 +88,84 @@ module Mail
   #
   #   mail.deliver!
   class SMTP
+    class UrlResolver
+
+      DEFAULTS = {
+        "smtp" => Hash.new({
+          :port => 587,
+          :tls => false,
+          :enable_starttls => :always
+        }).merge({
+          "localhost" => {
+            :port => 25,
+            :tls => false,
+            :enable_starttls => false
+          },
+          "127.0.0.1" => {
+            :port => 25,
+            :tls => false,
+            :enable_starttls => false
+          }}),
+        "smtps" => Hash.new({
+          :port => 465,
+          :tls => true,
+          :enable_starttls => false
+        })
+      }
+
+      def initialize(url)
+        @uri = url.is_a?(URI) ? url : uri_parser.parse(url)
+        unless DEFAULTS.has_key?(@uri.scheme)
+          raise ArgumentError, "#{url} is not a valid SMTP-url. Required format: smtp(s)://host?domain=sender.org"
+        end
+        @query = uri.query
+      end
+
+      def to_hash
+        config = raw_config
+        config.map { |key, value| config[key] = uri_parser.unescape(value) if value.is_a? String }
+        config
+      end
+
+      private
+        attr_reader :uri
+
+        def raw_config
+          scheme_defaults.merge(query_hash).merge({
+              :address              => uri.host,
+              :port                 => uri.port,
+              :user_name            => uri.user,
+              :password             => uri.password
+          }.delete_if {|_key, value| Utilities.blank?(value) })
+        end
+
+        def uri_parser
+          Utilities.uri_parser
+        end
+
+        def query_hash
+          @query_hash = begin
+            result = Hash[(@query || "").split("&").map { |pair| k,v = pair.split("="); [k.to_sym, v] }]
+
+            result[:open_timeout] &&= result[:open_timeout].to_i
+            result[:read_timeout] &&= result[:read_timeout].to_i
+            result[:enable_starttls] &&= begin
+              case result[:enable_starttls]
+              when "always", "auto" then result[:enable_starttls].to_sym
+              else
+                result[:enable_starttls] != "false"
+              end
+            end
+            result[:enable_starttls_auto] &&= result[:enable_starttls_auto] != 'false'
+            result
+          end
+        end
+
+        def scheme_defaults
+          DEFAULTS[uri.scheme][uri.host]
+        end
+    end
+
     attr_accessor :settings
 
     DEFAULTS = {
@@ -92,8 +184,13 @@ class SMTP
       :read_timeout         => 5
     }
 
-    def initialize(values)
-      self.settings = DEFAULTS.merge(values)
+    def initialize(config)
+      settings = DEFAULTS.merge(config)
+
+      if config.has_key?(:url)
+        settings = settings.merge(UrlResolver.new(config.delete(:url)).to_hash)
+      end
+      self.settings = settings
     end
 
     def deliver!(mail)

spec/mail/network/delivery_methods/smtp_spec.rb

@@ -11,6 +11,72 @@
     Mail.defaults { delivery_method :smtp, {} }
   end
 
+  describe 'settings via url' do
+    def smtp_delivery_settings_for_url(url, options = {})
+      Mail.defaults { delivery_method :smtp, {:url => url}.merge(options) }
+
+      Mail.delivery_method.settings
+    end
+
+    it 'provides smtp defaults for localhost' do
+      expect(smtp_delivery_settings_for_url('smtp://localhost')).to \
+        include(:port                 => 25,
+                :tls                  => false,
+                :enable_starttls      => false)
+    end
+
+    it 'provides smtp defaults for non-localhost' do
+      expect(smtp_delivery_settings_for_url('smtp://gmail.com')).to \
+        include(:port                 => 587,
+                :enable_starttls      => :always)
+    end
+
+    it 'provides smtps defaults' do
+      expect(smtp_delivery_settings_for_url('smtps://gmail.com')).to \
+        include(:port                 => 465,
+                :tls                  => true,
+                :enable_starttls      => false)
+    end
+
+    it 'parses the url correctly and coerces where needed' do
+      url = 'smtp://mailer.org:12345?domain=sender.org&authentication=login&openssl_verify_mode=peer&open_timeout=1&read_timeout=2&enable_starttls=always&enable_starttls_auto=true'
+      expect(smtp_delivery_settings_for_url(url)).to \
+        include(:address              => 'mailer.org',
+                :port                 => 12345,
+                :domain               => 'sender.org',
+                :authentication       => 'login',
+                :openssl_verify_mode  => 'peer',
+                :tls                  => false,
+                :open_timeout         => 1,
+                :read_timeout         => 2,
+                :enable_starttls      => :always,
+                :enable_starttls_auto => true)
+    end
+
+    it 'gives precedence to attributes from the url' do
+      config = {:address => 'ignored', :domain => 'ignored'}
+      expect(smtp_delivery_settings_for_url('smtp://user:pw@real-host?domain=real-domain.org', config)).not_to \
+        include(config)
+    end
+
+    it 'unescapes credentials' do
+      expect(smtp_delivery_settings_for_url('smtps://user%40host:pw-with-%[email protected]')).to \
+        include(:user_name => 'user@host',
+                :password => 'pw-with-/')
+    end
+
+    it 'accepts an URI' do
+      expect(smtp_delivery_settings_for_url(URI.parse('smtp://host?enable_starttls=auto'))).to \
+        include(:address => 'host', :enable_starttls => :auto)
+    end
+
+    it 'should raise an error for url without smtp(s) scheme' do
+      expect {
+        smtp_delivery_settings_for_url('foo://host')
+      }.to raise_error(/is not a valid SMTP-url/)
+    end
+  end
+
   describe "general usage" do
     it "should send emails from given settings" do