uri-imap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25097a74ef0a79401bd63d4b871d3a45b2ede02d37309b9cea0f09e0b6ce991c
+  data.tar.gz: a279ba051e0704d83064af1345573ca7684943c68c6a699e0563c14315c821e3
+SHA512:
+  metadata.gz: 1b1c3ef70dc59b0bd4c76fc52efc2e1c482053a7d905b4de76445071bbde7f05c7355504092b489d3be7abf39511ef372ce6e5b2ce147d41276814204e1256f0
+  data.tar.gz: 26b6a6b4d8c0ded40a397f9b6f2c26c1bbf8c37e64f9180754c9534ad1e32bd0b391bd78101c6bf94cef70b107a2091183aeb23fd0274f17958f72104b9592e0

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

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

@@ -0,0 +1,13 @@
+Changes can be:
+
+* ✨ Features
+* ⚠️ Breaking
+* 🐛 Bug Fixes
+* 🛠️ Developer
+
+## [Unreleased]
+
+## [0.1.0] - 2025-08-11
+
+- ✨ Initial release
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Gert Goet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# URI::IMAP [![Gem Version](https://badge.fury.io/rb/uri-imap.svg)](https://badge.fury.io/rb/uri-imap) [![API Docs](https://img.shields.io/badge/API%20Docs-YARD-red?style=flat-square&logo=ruby)](https://eval.github.io/uri-imap/)
+
+Extends Ruby's `URI` with support for IMAP-uri's.  
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add uri-imap
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install uri-imap
+```
+
+## Usage
+
+### parse
+
+```ruby
+u = URI("imaps+plain://user%40gmail.com:p%40ss@imap.gmail.com")
+
+url.scheme           #=> "imaps+plain"
+url.auth             #=> "plain"
+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             #=> "imap.gmail.com"
+url.port             #=> 993
+```
+
+### to_h
+
+```ruby
+URI("imaps+login://user%40gmail.com:p%40ss@imap.gmail.com").to_h
+#=>
+{auth: "login",
+ host: "imap.gmail.com",
+ port: 993,
+ scheme: "imaps+login",
+ starttls: false,
+ tls: true,
+ user: "user@gmail.com",
+ password: "p@ss"}
+```
+
+## IMAP-URI
+
+There's no official specification for IMAP-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-imap.5.scd).  
+
+`<scheme>[+<auth>]://[<user>[:<password>]@]<host>[:<port>][?<query>]`
+
+### scheme
+
+- `imap`  
+  IMAP with STARTTLS (i.e. `url.starttls #=> :always`).
+- `imap+insecure`  
+  IMAP without STARTTLS (i.e. `url.starttls #=> false`)..
+- `imaps`  
+  IMAP with TLS.
+
+
+### auth
+
+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 when no authentication is provided.
+
+> [!NOTE]
+> any query's value for `auth` takes precedence.
+
+### Examples
+
+TBD
+
+## 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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/eval/uri-imap.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/uri/imap/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module URI
+  class IMAP < URI::Generic
+    VERSION = "0.1.0"
+  end
+end

data/lib/uri/imap.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "imap/version"
+
+# See https://docs.ruby-lang.org/en/master/URI.html
+module URI
+  # Class that adds imap(s)-scheme to the standard URI-module.
+  class IMAP < URI::Generic
+    class Error < StandardError; end
+
+    # @return [Integer]
+    def port
+      return @port if @port
+      return 993 if tls?
+
+      143
+    end
+
+    # Return mechanism of authentication (default `"plain"`).
+    #
+    # Only returns value when {URI::imap#userinfo} is provided and authentication is not `"none"`.
+    #
+    # Authentication can be provided via scheme (e.g. `"imap+login://..."`) or via
+    # query-params (e.g. `"imap://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("imap://foo.org").auth #=> nil
+    #
+    #   # "none"
+    #   URI("imap+none://user@foo.org").auth #=> nil
+    #
+    #   # default value
+    #   URI("imap://user@foo.org").auth #=> "plain"
+    #
+    #   # query takes precedence
+    #   URI("imap+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. `"imap://foo.org?auth=none"`.
+    # @return [String] 'auth via query' when present.
+    # @return [nil] if 'auth via scheme' is `"none"`, e.g. `"imap+none://foo.org"`.
+    # @return [String] 'auth via scheme' when present, e.g. `"imap+login://foo.org"`.
+    # @return [String] else `"plain"`
+    def auth
+      # net-imap: 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("imap://foo.org").decoded_userinfo #=> nil
+    #   URI("imap://foo.org").decoded_userinfo(format: :array) #=> nil
+    #   URI("imap://foo.org").decoded_userinfo(format: :hash) #=> nil
+    #
+    # @example format `:array`
+    #   # absent user/password is `nil`
+    #   URI("imap://user@foo.org").decoded_userinfo(format: :array) #=> ["user", nil]
+    #   URI("imap://:pw@foo.org").decoded_userinfo(format: :array) #=> [nil, "pw"]
+    #   # decoded values
+    #   URI("imap://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("imap://user%40gmail.com@foo.org").decoded_userinfo(format: :hash) #=> {user: "user@gmail.com"}
+    #   URI("imap://: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
+
+    # @return [Integer]
+    def idle_timeout
+      parsed_query["idle_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-imap net-imap} 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. `"imap://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 `"imap+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
+
+    # @return [Boolean] whether or not `scheme` starts with `"imaps"`.
+    def tls
+      !!scheme[/^imaps/]
+    end
+    alias_method :tls?, :tls
+
+    # Whether or not the scheme indicates to skip STARTTLS.
+    #
+    # @see #starttls
+    #
+    # @example
+    #   URI("imap+insecure://foo.org").insecure? #=> true
+    #   # This is equivalent (though shorter and more descriptive) to
+    #   URI("imap://foo.org?starttls=false")
+    #
+    #   # combine with authentication
+    #   URI("imap+insecure+login://user:pw@foo.org").insecure? #=> true
+    # @return [Boolean] whether `scheme` starts with `"imap+insecure"`.
+    def insecure?
+      scheme.start_with?("imap+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("imap://127.0.0.1:1025").host_local? #=> true
+    #
+    #   URI("imap://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`, `idle_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) }
+        .tap do
+        _1["idle_timeout"] &&= _1["idle_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
+
+    # 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("imaps+login://user%40gmail.com:p%40ss@imap.gmail.com#sender.org").to_h
+    #   # =>
+    #   # {auth: "login",
+    #   #  host: "imap.gmail.com",
+    #   #  port: 465,
+    #   #  scheme: "imaps+login",
+    #   #  starttls: false,
+    #   #  tls: true,
+    #   #  user: "user@gmail.com",
+    #   #  password: "p@ss"}
+    # @return [Hash]
+    def to_h
+      {
+        auth:,
+        host:,
+        idle_timeout:,
+        open_timeout:,
+        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
+
+    # Parse `uri` and instantiate instance of URI::imap.
+    # @example
+    #   URI::imap.parse("imaps+plain://user:pw@foo.org#sender.org")
+    #   #=> #<URI::imap imaps+plain://user:pw@foo.org#sender.org>
+    # @return [URI::imap] URI::imap instance from `uri`.
+    def self.parse(uri)
+      new(*URI.split(uri))
+    end
+
+    private
+
+    def scheme_auth
+      string_absense_in(scheme.split("+").last, %w[imap imaps 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 "IMAP", IMAP
+  register_scheme "IMAPS", IMAP
+end
+
+module UriImapExtensions
+  def parse(uri)
+    # Ensure 'plus schemes' (e.g., `imap+login://`, `imap+oauth://`) are parsed as URI::imap
+    # instead of URI::Generic objects.
+    return URI::IMAP.parse(uri) if uri.is_a?(String) && uri.start_with?("imap")
+
+    super
+  end
+end
+
+URI.singleton_class.prepend(UriImapExtensions)

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

data/sig/uri/imap.rbs

@@ -0,0 +1,6 @@
+module URI
+  class IMAP
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: uri-imap
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gert Goet
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email:
+- gert@thinkcreate.dk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/uri/imap.rb
+- lib/uri/imap/version.rb
+- rakelib/yard.rake
+- sig/uri/imap.rbs
+- tmp/.gitkeep
+homepage: https://github.com/eval/uri-imap
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/eval/uri-imap
+  source_code_uri: https://github.com/eval/uri-imap
+  changelog_uri: https://github.com/eval/uri-imap/blob/main/CHANGELOG.md
+  documentation_uri: https://eval.github.io/uri-imap/
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'URI-IMAP: address IMAP-servers as URI'
+test_files: []