uri-smtp 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70ec42fc77da96a4bf7e8766406f110edbbd0de008148a7b62ad64b90137515e
-  data.tar.gz: def1342386b5d4ef7599f09750fd2dea8a709f06c452459c4f174374de4f48de
+  metadata.gz: 9aa4d8b92e611c33b96e27f740ed87ecabb90dd69c454828d8246e3c405b9ba5
+  data.tar.gz: 476ad95a2ef969f89fb9bf1b56f278686091bb99ad9de8c5ab379e1bcb10aaf6
 SHA512:
-  metadata.gz: 1eeb8f2e3f8debbc08271ae35c9a55cadbd2b2d7380a86d174cfa91461012b4986e1e9489c6fde38eedf018d1e5e8601807e6ba23fb6ed1aab3d0a755d82e628
-  data.tar.gz: d450be99efefaa24c20c2c6315a4d7b0a406d9ba043b558e6742a9bbe510670e0b6d076c5a1584ace1270ce650d73b9fd7549d93dd0853365b938b97713affe4
+  metadata.gz: 63b77eee5fd37f45f1f270bf956ab2ff6f5ae4699907e3b86ebf249dc3b4d7228f6ff95bbf7f36aff748b3d80a0d124162808a2a034ea9c721f361eab0f0ee0e
+  data.tar.gz: 031a0988bc86f82cfb8dd6998fbe3f188f0957e25bd80845bc80f5f4bc7ff06e33df30bbe1a0e57a77d7614f6cb2979424b974e2bfa40a51ca21c9713a1ba488

data/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--title 'URI::SMTP Documentation'
+--charset utf-8
+--markup markdown
+--markup-provider redcarpet
+'lib/**/*.rb' - '*.md'

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 ## [Unreleased]
 
+## [0.6.0] - 2025-07-27
+
+- Add: API-docs at https://eval.github.io/uri-smtp/  
+- Fix: "smtp+insecure+foo://..." not considered `#insecure?`  
+- Fix: "smtp://foo.org?auth=none" being ignored  
+- Fix: "smtp+insecure://..." having auth "insecure"  
+- Remove: `#starttls?`  
+
+## [0.5.0] - 2025-07-25
+
+- Add: `uri#read_timeout`, `uri#open_timeout`  
+  Coerced integers from query:
+  ```ruby
+  URI("smtp://foo?read_timeout=1").read_timeout #=> 1
+  ```
+  Included in `to_h`.
+- Add: `uri.decoded_userinfo(format: ...)`  
+  `:format` can be one of `[:string :array :hash]`
+- Add: domain can appear in fragment
+  ```ruby
+  URI("smtp://foo.org#sender.org").domain #=> "sender.org"
+  ```
+  NOTE Any domain from the query takes precedence.
+- Fix: "smtps+foo://..." having no tls
+
 ## [0.4.0] - 2025-07-23
 
 - FIX: correct settings for action_mailer using mail v2.8.1
@@ -11,3 +36,4 @@
 ## [0.2.0] - 2025-07-18
 
 - Feature complete
+

data/README.md

@@ -1,6 +1,25 @@
 # URI::SMTP
 
-This library allows for parsing SMTP-URIs.
+Extends Ruby's `URI` with support for SMTP-uri's.  
+This allows for more concise SMTP-config:
+```diff
+# config/environments/production.rb
+config.action_mailer.delivery_method = :smtp
+- config.action_mailer.smtp_settings = {
+-   address:         "smtp.gmail.com",
+-   port:            587,
+-   domain:          "example.com",
+-   user_name:       Rails.application.credentials.dig(:smtp, :user_name),
+-   password:        Rails.application.credentials.dig(:smtp, :password),
+-   authentication:  "plain",
+-   enable_starttls: true,
+-   open_timeout:    5,
+-   read_timeout:    5
+- }
+# given ENV["SMPT_URL"]:
+# "smtp://user_name:password@smtp.gmail.com?open_timeout=5&read_timeout=5#example.com"
++ config.action_mailer.smtp_settings = URI(ENV.fetch("SMTP_URL")).to_h(format: :am)
+```
 
 ## Installation
 
@@ -21,27 +40,29 @@ gem install uri-smtp
 ### parse
 
 ```ruby
-u = URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com?domain=sender.org")
+u = URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com#sender.org")
 
 url.scheme           #=> "smtps+login"
 url.auth             #=> "login"
 url.starttls         #=> false
+url.starttls?        #=> false
 url.tls?             #=> true
 url.userinfo         #=> "user%40gmail.com:p%40ss"
+url.decoded_userinfo #=> "user@gmail.com:p@ss"
 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"
+url.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",
@@ -53,9 +74,10 @@ URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com?domain=sender.org").to
  password: "p@ss"}
 ```
 
-Formatting for action_mailer configuration, use `to_h(format: :am)`:
+For [ActionMailer configuration](https://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration), use `format: :action_mailer` (or `: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",
@@ -65,6 +87,8 @@ URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com?domain=sender.org").to
  password: "p@ss"}
 ```
 
+Besides renaming some keys, this also works around a quirk in `v2.8.1` of the mail-gem (e.g. `tls: false` [skips setting up STARTTLS](https://github.com/mikel/mail/blob/2.8.1/lib/mail/network/delivery_methods/smtp.rb#L115)).
+
 
 Full Rails config:
 ```ruby
@@ -89,17 +113,17 @@ There's no official specification for SMTP-URIs. There's some prior work though.
   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`).
+> to get `url.starttls #=> :auto`, provide it in the query: `smtp://user:pw@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:
+Any value for auth that passes the URI-parser is acceptable. 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.
+  Authenticate with a username and password using AUTH PLAIN. This is the default behavior when no authentication is provided.
 
 > [!NOTE]
 > any query's value for `auth` takes precedence.
@@ -136,6 +160,7 @@ There's no restriction to the value of auth. Though the following values have sp
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Use `bin/yard server --reload` when working on documentation.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/lib/uri/smtp/version.rb

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

data/lib/uri/smtp.rb

@@ -3,77 +3,226 @@
 require "uri"
 require_relative "smtp/version"
 
+# See https://docs.ruby-lang.org/en/master/URI.html
 module URI
+  # Class that adds smtp(s)-scheme to the standard URI-module.
   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
-
+    # @return [Integer]
     def port
       return @port if @port
       return 25 if host_local?
       return 465 if tls?
+
       587
     end
 
+    # Return mechanism of authentication (default `"plain"`).
+    #
+    # Only returns value when {URI::SMTP#userinfo} is provided and authentication is not `"none"`.
+    #
+    # Authentication can be provided via scheme (e.g. `"smtp+login://..."`) or via
+    # query-params (e.g. `"smtp://foo.org?auth=cram-md5"`). The latter takes precedence when both are provided.
+    # A provided value of `"none"` results in `nil`. Other values are returned as is.
+    # @example
+    #   # no userinfo
+    #   URI("smtp://foo.org").auth #=> nil
+    #
+    #   # "none"
+    #   URI("smtp+none://user@foo.org").auth #=> nil
+    #
+    #   # default value
+    #   URI("smtp://user@foo.org").auth #=> "plain"
+    #
+    #   # query takes precedence
+    #   URI("smtp+login://user@foo.org?auth=cram-md5").auth #=> "cram-md5"
+    # @return [String, nil] mechanism of authentication or `nil`:
+    # @return [nil] when there's no `userinfo`.
+    # @return [nil] if 'auth via query' is `"none"`, e.g. `"smtp://foo.org?auth=none"`.
+    # @return [String] 'auth via query' when present.
+    # @return [nil] if 'auth via scheme' is `"none"`, e.g. `"smtp+none://foo.org"`.
+    # @return [String] 'auth via scheme' when present, e.g. `"smtp+login://foo.org"`.
+    # @return [String] else `"plain"`
     def auth
       # net-smtp: passing authtype without user/pw raises error
       return nil unless userinfo
+      return nil if parsed_query["auth"] == "none"
       return parsed_query["auth"] if parsed_query.has_key?("auth")
       return nil if scheme_auth == "none"
       return scheme_auth if scheme_auth
+
       "plain"
     end
 
+    # Decoded userinfo formatted as String, Array or Hash.
+    #
+    # **NOTE** not provided user or password result in `nil` (format: :array) or absent keys (format: :hash).
+    #
+    # @example no userinfo => `nil`
+    #   URI("smtp://foo.org").decoded_userinfo #=> nil
+    #   URI("smtp://foo.org").decoded_userinfo(format: :array) #=> nil
+    #   URI("smtp://foo.org").decoded_userinfo(format: :hash) #=> nil
+    #
+    # @example format `:array`
+    #   # absent user/password is `nil`
+    #   URI("smtp://user@foo.org").decoded_userinfo(format: :array) #=> ["user", nil]
+    #   URI("smtp://:pw@foo.org").decoded_userinfo(format: :array) #=> [nil, "pw"]
+    #   # decoded values
+    #   URI("smtp://user%40gmail.com:p%40ss@foo.org").decoded_userinfo(format: :array) #=> ["user@gmail.com", "p@ss"]
+    #
+    # @example format `:hash`
+    #   # absent user/password is left out
+    #   URI("smtp://user%40gmail.com@foo.org").decoded_userinfo(format: :hash) #=> {user: "user@gmail.com"}
+    #   URI("smtp://:p%40ss@foo.org").decoded_userinfo(format: :hash) #=> {password: "p@ss"}
+    #
+    # @param format [Symbol] the format type, `:string` (default), `:array` or `:hash`.
+    # @return [String, Array, Hash] Decoded userinfo formatted as String, Array or Hash.
+    def decoded_userinfo(format: :string)
+      return if userinfo.nil?
+
+      case format
+      when :string
+        [decoded_user, decoded_password].join(":")
+      when :array
+        [string_presence(decoded_user), string_presence(decoded_password)]
+      when :hash
+        {
+          user: string_presence(decoded_user),
+          password: string_presence(decoded_password)
+        }.delete_if { |_k, v| v.nil? }
+      else
+        raise ArgumentError,
+          "Unknown format #{format.inspect}. Should be one of #{%i[string array hash].inspect}."
+      end
+    end
+
+    # The host to send mail from, i.e. the `HELO` domain.
+    # @return [String] the query-key `domain` when present, e.g. `"smtp://foo.org?domain=sender.org"`.
+    # @return [String] the `fragment` when present, e.g. `"smtp://foo.org#sender.org"`.
+    # @return [nil] otherwise
     def domain
-      parsed_query["domain"]
+      parsed_query["domain"] || fragment
     end
 
-    def scheme_auth
-      scheme[/.*(?:\+(.+))/, 1]
+    # @return [Integer]
+    def read_timeout
+      parsed_query["read_timeout"]
     end
 
+    # @return [Integer]
+    def open_timeout
+      parsed_query["open_timeout"]
+    end
+
+    # Whether or not to use `STARTTLS`.
+    #
+    # The possible return values (i.e. `:always`, `:auto` and `false`) map to what {https://github.com/ruby/net-smtp net-smtp} uses:
+    # - `:always` use `STARTTLS` or disconnect when server does not support it.
+    # - `:auto` use `STARTTLS` when supported, otherwise continue unencrypted.
+    # - `false` don't use `STARTTLS`.
+    #
+    # @return [false] when `tls?`.
+    # @return [:always, :auto, false] when query-key `starttls` is present, e.g. `"smtp://foo.org?starttls=auto"`.
+    # @return [false] when `host_local?` (the host is considered one for local development).
+    # @return [false] when `insecure?` (i.e. `scheme` starts with `"smtp+insecure"`).
+    # @return [:always] otherwise.
     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
 
+    # @return [Boolean] whether or not `scheme` starts with `"smtps"`.
     def tls
-      scheme == "smtps"
+      !!scheme[/^smtps/]
     end
     alias_method :tls?, :tls
 
+    # Whether or not the scheme indicates to skip STARTTLS.
+    #
+    # @see #starttls
+    #
+    # @example
+    #   URI("smtp+insecure://foo.org").insecure? #=> true
+    #   # This is equivalent (though shorter and more descriptive) to
+    #   URI("smtp://foo.org?starttls=false")
+    #
+    #   # combine with authentication
+    #   URI("smtp+insecure+login://user:pw@foo.org").insecure? #=> true
+    # @return [Boolean] whether `scheme` starts with `"smtp+insecure"`.
     def insecure?
-      scheme == "smtp+insecure"
+      scheme.start_with?("smtp+insecure")
     end
 
+    # Whether or not `host` is considered local.
+    #
+    # Hostnames that are considered local have certain defaults (i.e. port `25` and no `STARTTLS`).
+    # @example
+    #   # Point to mailcatcher (https://github.com/sj26/mailcatcher)
+    #   URI("smtp://127.0.0.1:1025").host_local? #=> true
+    #
+    #   URI("smtp://localhost").host_local? #=> true
+    # @return [Boolean] whether or not `host` is considered local.
     def host_local?
       %w[127.0.0.1 localhost].include?(host)
     end
 
+    # `query` as Hash with values `starttls`, `read_timeout` and `open_timeout` coerced.
+    # @return [Hash] `query` parsed.
     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
+      @parsed_query ||= URI.decode_www_form(query.to_s).to_h
+        .delete_if { |_k, v| !string_presence(v) }
+        .tap do
+          _1["read_timeout"] &&= _1["read_timeout"].to_i
+          _1["open_timeout"] &&= _1["open_timeout"].to_i
+          _1["starttls"] &&= case _1["starttls"]
+          when "always", "auto" then _1["starttls"].to_sym
+          when "false" then false
+          else
+            :always
+          end
         end
-      end
     end
 
+    # Return {Hash} representing the URI.
+    #
+    # `format` should be one of: `nil` or `:action_mailer` (or `:am`).
+    #
+    # Format `:action_mailer` matches how {https://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration ActionMailer} should be configured and works around some quirks in Mail v2.8.1.
+    #
+    # **NOTE** keys with nil-values are stripped.
+    # @example default format
+    #   URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com#sender.org").to_h
+    #   # =>
+    #   # {auth: "login",
+    #   #  domain: "sender.org",
+    #   #  host: "smtp.gmail.com",
+    #   #  port: 465,
+    #   #  scheme: "smtps+login",
+    #   #  starttls: false,
+    #   #  tls: true,
+    #   #  user: "user@gmail.com",
+    #   #  password: "p@ss"}
+    # @example format `:action_mailer`/`:am`, ActionMailer configuration
+    #   URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com#sender.org").to_h(format: :am)
+    #   # =>
+    #   # {address: "smtp.gmail.com",
+    #   #  authentication: "login",
+    #   #  domain: "sender.org",
+    #   #  port: 465,
+    #   #  tls: true,
+    #   #  user_name: "user@gmail.com",
+    #   #  password: "p@ss"}
+    # @example Rails configuration
+    #   # file: config/environments/development.rb
+    #   # Config via env-var SMTP_URL or fallback to mailcatcher.
+    #   config.action_mailer.smtp_settings = URI(ENV.fetch("SMTP_URL", "http://127.0.0.1:1025")).to_h(format: :am)
+    # @param format [Symbol] the format type, `nil` (default), `:action_mailer`/`:am`.
+    # @return [Hash]
     def to_h(format: nil)
       case format
       when :am, :action_mailer
@@ -83,7 +232,9 @@ module URI
           domain:,
           enable_starttls: starttls == :always,
           enable_starttls_auto: starttls == :auto,
+          open_timeout:,
           port:,
+          read_timeout:,
           tls:
         }.tap do
           unless _1[:authentication].nil?
@@ -104,7 +255,9 @@ module URI
           auth:,
           domain:,
           host:,
+          open_timeout:,
           port:,
+          read_timeout:,
           scheme:,
           starttls:,
           tls:
@@ -117,9 +270,33 @@ module URI
       end
     end
 
+    # Parse `uri` and instantiate instance of URI::SMTP.
+    # @example
+    #   URI::SMTP.parse("smtps+plain://user:pw@foo.org#sender.org")
+    #   #=> #<URI::SMTP smtps+plain://user:pw@foo.org#sender.org>
+    # @return [URI::SMTP] URI::SMTP instance from `uri`.
     def self.parse(uri)
       new(*URI.split(uri))
     end
+
+    private
+
+    def scheme_auth
+      string_absense_in(scheme.split("+").last, %w[smtp smtps insecure])
+    end
+
+    # string_presence("")   #=> nil
+    # string_presence("  ") #=> nil
+    # string_presence(" FOO ") #=> " FOO "
+    def string_presence(s)
+      s.to_s.strip.then { _1 unless _1.empty? }
+    end
+
+    # string_absense_in("foo", %w[bar baz]) #=> "foo"
+    # string_absense_in("bar", %w[bar baz]) #=> nil
+    def string_absense_in(s, array)
+      s unless array.include?(s)
+    end
   end
 
   register_scheme "SMTP", SMTP
@@ -128,6 +305,8 @@ end
 
 module UriSmtpExtensions
   def parse(uri)
+    # Ensure 'plus schemes' (e.g., `smtp+login://`, `smtp+oauth://`) are parsed as URI::SMTP
+    # instead of URI::Generic objects.
     if uri.is_a?(String) && uri.start_with?("smtp")
       return URI::SMTP.parse(uri)
     end

data/rakelib/yard.rake

@@ -0,0 +1,12 @@
+require "yard"
+
+YARD::Rake::YardocTask.new(:docs) do |t|
+  # Options defined in `.yardopts` are read first, then merged with
+  # options defined here.
+  #
+  # It's recommended to define options in `.yardopts` instead of here,
+  # as `.yardopts` can be read by external YARD tools, like the
+  # hot-reload YARD server `yard server --reload`.
+
+  # t.options += ['--title', "Something custom"]
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uri-smtp
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Gert Goet
@@ -17,12 +17,14 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".standard.yml"
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/uri/smtp.rb
 - lib/uri/smtp/version.rb
+- rakelib/yard.rake
 - sig/uri/smtp.rbs
 homepage: https://github.com/eval/uri-smtp
 licenses:
@@ -31,6 +33,7 @@ metadata:
   homepage_uri: https://github.com/eval/uri-smtp
   source_code_uri: https://github.com/eval/uri-smtp
   changelog_uri: https://github.com/eval/uri-smtp/blob/main/CHANGELOG.md
+  documentation_uri: https://eval.github.io/uri-smtp/
 rdoc_options: []
 require_paths:
 - lib