uri-smtp 0.5.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 457b3741b5ef4678c7f1c6e19574f24d68d5f515ef58c6879f64516c8d472049
-  data.tar.gz: ecd3d5e89df1874095936cd804fd4241feefed5f2e8f6eb0f3015906d1f63cf6
+  metadata.gz: 19f134f7a4dd627d1493c292572328eba64155e9b1ec07e870aa647d54fa4ef2
+  data.tar.gz: ba12895246eb404221548ae749d5661ef8218d3ac3b0bf2b811b0b20253123ff
 SHA512:
-  metadata.gz: 98b76dad4efd9c9c53f674ef06139844f8845415592bb9927ad90a7d903c62ef388a944779f55987d219035fac120e67247f50251228016db86c346e4d3bc8d3
-  data.tar.gz: 530215f54f3c2e1e1c78d99f476b30c11438136e1313d6abc26e7e830ee885f999c0dc90ce3e4874ac9ca11c7e45c3606a156e236ccf676bba33917b58534e18
+  metadata.gz: 3ac0a82ee28bb827f44a7a74aa44215a428e6dda59f9821e59d3a7422b02aaed6e1fd9195537878e3cf9beeff919c6ef0bbdfbde905c6e5a51f89645c8f9b9b6
+  data.tar.gz: e824027c3c9aa864e6e34e5299ea75d0fee6af4641293ee10999c7c4aa43f330b7014e1624272ccb9fbbe499b510e565d0d1b4f6234e183386c2bfb3451a6874

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,13 @@
 ## [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`  

data/README.md

@@ -1,4 +1,4 @@
-# URI::SMTP
+# URI::SMTP [![Gem Version](https://badge.fury.io/rb/uri-smtp.svg)](https://badge.fury.io/rb/uri-smtp) [![API Docs](https://img.shields.io/badge/API%20Docs-YARD-red?style=flat-square&logo=ruby)](https://eval.github.io/uri-smtp/)
 
 Extends Ruby's `URI` with support for SMTP-uri's.  
 This allows for more concise SMTP-config:
@@ -48,7 +48,7 @@ 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_userinfo #=> "user@gmail.com:p@ss"
 url.decoded_user     #=> "user@gmail.com"
 url.user             #=> "user%40gmail.com"
 url.decoded_password #=> "p@ss"
@@ -74,7 +74,7 @@ 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)
 #=>
@@ -87,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
@@ -116,12 +118,12 @@ There's no official specification for SMTP-URIs. There's some prior work though.
 
 ### 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.
@@ -158,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.5.0"
+    VERSION = "0.7.1"
   end
 end

data/lib/uri/smtp.rb

@@ -3,20 +3,13 @@
 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?
@@ -25,9 +18,36 @@ module URI
       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
@@ -35,29 +55,35 @@ module URI
       "plain"
     end
 
-    # all formats: return nil when userinfo == nil.
+    # 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
     #
-    # format: :array
-    # Never contains empty strings (as opposed to [#user, #password]).
-    # Example:
-    # Given #<URI::SMTP smtps://:token@smtp.gmail.com>
-    # Then:
-    # [uri.user, uri.password] #=> ["", "token"]
-    # uri.decoded_userinfo     #=> [nil, "token"]
+    # @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"]
     #
-    # format: :hash
-    # Keys are absent when value would be `nil`.
-    # Example:
-    # Given #<URI::SMTP smtps://:token@smtp.gmail.com>
-    # Then:
-    # uri.decoded_userinfo(format: :array) #=> [nil, "token"]
-    # uri.decoded_userinfo(format: :to_h) #=> {password: "token"}
+    # @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].compact.join(":")
+        [decoded_user, decoded_password].join(":")
       when :array
         [string_presence(decoded_user), string_presence(decoded_password)]
       when :hash
@@ -71,18 +97,36 @@ module URI
       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"] || fragment
     end
 
+    # @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")
@@ -91,21 +135,44 @@ module URI
 
       :always
     end
-    alias_method :starttls?, :starttls
 
+    # @return [Boolean] whether or not `scheme` starts with `"smtps"`.
     def tls
       !!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
         .delete_if { |_k, v| !string_presence(v) }
@@ -121,6 +188,41 @@ module URI
         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
@@ -168,6 +270,11 @@ 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
@@ -175,12 +282,21 @@ module URI
     private
 
     def scheme_auth
-      scheme[/.*(?:\+(.+))/, 1]
+      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
@@ -189,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.5.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Gert Goet
@@ -17,13 +17,16 @@ 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
+- tmp/.gitkeep
 homepage: https://github.com/eval/uri-smtp
 licenses:
 - MIT
@@ -31,6 +34,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