mailresolver 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 12a1881f2f511ee3179b481e2b0edfd43f79bfed4fdc9f7d96ce94a4fb511650
+  data.tar.gz: a1f1aadf2ecfbe335cba1c5ddd33daeba467760ad7b0d1ec070905f9622d4120
+SHA512:
+  metadata.gz: 9ee55c2b9fefb4afd0d576e7469804e9c969c653a4b285f1beb77b80efad56dbe77f12397568dba54c17bea7e37c20fa34326c988407fd3a4e3d7d8cc659a847
+  data.tar.gz: 3a6ef2bbe9788425d1e65c8ac21364218eac4d67a0db34bdafc2918030bcf7f5557625410b9497a7095b272e55d5043b9f60a74e15b994409ab62a64e15f47db

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.5.1
+
+- Re-release: 0.5.0
+
+## 0.5.0
+
+- Initial public release.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Lev
+
+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,170 @@
+# mailresolver
+
+🔍 DNS resolution for mail, in Ruby.
+
+**mailresolver** is a small, injectable DNS client for mail libraries — TXT, A/AAAA, MX, PTR, and CNAME lookups.
+
+For mail libraries and the apps that use them: SPF/DKIM/DMARC/MTA-STS checks that need a missing record told apart from a server that couldn't answer, apps running several mail libraries that want one shared resolver instead of one apiece, test suites that want to fake DNS without touching a network.
+
+**mailresolver** handles:
+
+- TXT, A, AAAA, MX, PTR, and CNAME lookups, plus a merged `addresses` for A+AAAA
+- a three-way error taxonomy — `NotFound`, `ServerFailure`, `Timeout` — instead of collapsing every failure into an empty answer
+- one shared resolver across every mail library in your app, multiplexed over dnsruby's single I/O thread
+- configurable retry/timeout schedule
+- DNSSEC validation and answer caching off, unconditionally, for callers that have no way to act on either
+- test doubles — a hash-backed fake and a real loopback nameserver — so a suite never needs the network
+
+> Not a general-purpose DNS client — five record types and three errors, built for what mail authentication needs.
+
+## Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [The Error Taxonomy](#the-error-taxonomy)
+- [Why This Distinction Exists](#why-this-distinction-exists)
+- [One Resolver, Shared](#one-resolver-shared)
+- [Configuration](#configuration)
+- [Custom Resolvers](#custom-resolvers)
+- [Test Doubles](#test-doubles)
+- [Testing](#testing)
+- [History](#history)
+- [Contributing](#contributing)
+- [Acknowledgments](#acknowledgments)
+- [License](#license)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "mailresolver"
+```
+
+Requires Ruby >= 3.4
+
+## Usage
+
+```ruby
+require "mailresolver"
+
+resolver = MailResolver::Resolver.new
+
+resolver.txt("example.com")           # => ["v=spf1 -all"]
+resolver.a("example.com")             # => ["203.0.113.10"]
+resolver.aaaa("example.com")          # => ["2001:db8::1"]
+resolver.addresses("example.com")     # => ["203.0.113.10", "2001:db8::1"]
+resolver.mx("example.com")            # => ["mx1.example.com", "mx2.example.com"], sorted by preference
+resolver.ptr("203.0.113.10")          # => ["mail.example.com"]
+resolver.cname("www.example.com")     # => ["example.com"]
+```
+
+`addresses` merges A and AAAA. A family the name doesn't publish contributes nothing to it rather than ending the lookup — but a name that doesn't exist at all raises `NoSuchName`, and a nameserver that couldn't answer still raises, same as every other method here.
+
+IPv6 addresses come back lower case: dnsruby renders them upper case, and RFC 5952 §4.3 asks for lower.
+
+## The Error Taxonomy
+
+Every method raises one of three errors instead of guessing:
+
+- `MailResolver::NotFound` — the server said there is nothing there: NXDOMAIN, or NOERROR with no records of the type asked for. NXDOMAIN specifically raises the subclass `MailResolver::NoSuchName`, for the callers — implicit MX, for one — to whom "the name doesn't exist" means something different from "the name has no records of this type"
+- `MailResolver::ServerFailure` — the server didn't say: SERVFAIL, REFUSED, or a transport failure (a connect that failed, a socket dnsruby couldn't open, an address that wouldn't resolve)
+- `MailResolver::Timeout` — no answer arrived in time
+
+All of them descend from `MailResolver::Error`. Malformed input is the caller's bug, not a DNS answer, and raises `ArgumentError` instead — `ptr("not an ip")`, for instance.
+
+## Why This Distinction Exists
+
+`NotFound` and `ServerFailure` look interchangeable from a distance — both mean "I don't have an answer for you" — but they mean opposite things to the caller, and mail authentication is built on the difference.
+
+SPF (RFC 7208) counts a void lookup — a `NotFound` — against its ten-lookup budget and keeps evaluating. It abandons evaluation entirely on a `ServerFailure` or a `Timeout`, returning `temperror` rather than pretending the record said nothing. Collapse the two, the way `Resolv` does, and a nameserver having a bad minute reads as a domain that designates no senders — SPF fails a message that should have deferred, and a forged one passes for the same reason a legitimate one would have failed.
+
+The same shape recurs in DKIM, DMARC, and MTA-STS: a missing record is a policy decision the domain made; a server that couldn't answer is not.
+
+## One Resolver, Shared
+
+Build one `MailResolver::Resolver` and hand it to every mail library your app uses:
+
+```ruby
+resolver = MailResolver::Resolver.new
+
+MailAuth.authenticate(raw, ip: ip, resolver: resolver)
+MtaSts.lookup(domain, known: nil, resolver: resolver)
+```
+
+dnsruby multiplexes concurrent queries over a single I/O thread, and can only do that if callers share one `Dnsruby::Resolver`. Handing each library its own `MailResolver::Resolver` — rather than one instance shared across them — buys nothing and costs an I/O thread apiece.
+
+## Configuration
+
+```ruby
+MailResolver::Resolver.new(timeouts: [5, 3, 3])
+```
+
+`timeouts` is one attempt per element: the first element is how long the first packet gets before the first retry, dnsruby doubles the interval for each retry after that, and the sum is the hard deadline. The default sends packets at 0, 5, and 10 seconds and gives the whole query 11 seconds before raising `Timeout`.
+
+DNSSEC validation and dnsruby's answer cache are both off, unconditionally. DNSSEC costs a round trip that most callers of this gem have no way to act on — MTA-STS, for one, trusts the certificate on the policy host rather than the DNS answer. Caching is dnsruby's own concern to have off: its cache is process-global, so a nameserver that starts failing would otherwise keep serving its last good answer to every caller in the process.
+
+## Custom Resolvers
+
+Anything that responds to `txt`, `a`, `aaaa`, `addresses`, `mx`, `ptr`, and `cname` — raising the three errors above — is a drop-in replacement. You don't have to write one: see [Test Doubles](#test-doubles).
+
+## Test Doubles
+
+`MailResolver::Testing` ships what every caller's suite would otherwise hand-roll. It isn't loaded with the gem:
+
+```ruby
+require "mailresolver/testing"
+```
+
+`FakeResolver` stands a hash in for a zone, no network involved:
+
+```ruby
+resolver = MailResolver::Testing::FakeResolver.new(
+  "example.com"  => { txt: [ "v=spf1 -all" ], a: [ "192.0.2.1" ] },
+  "broken.example.com" => { txt: :servfail }
+)
+
+resolver.txt("example.com")          # => ["v=spf1 -all"]
+resolver.mx("example.com")           # raises NotFound — the name is here, MX isn't
+resolver.txt("absent.example.com")   # raises NoSuchName — the name isn't here at all
+resolver.txt("broken.example.com")   # raises ServerFailure
+resolver.queries                     # => [["example.com", :txt], ...]
+```
+
+The sentinels `:timeout`, `:servfail`, and `:nxdomain` stand where records would, for the failures a zone can't otherwise express. PTR is keyed by the address itself rather than its reverse name.
+
+`LocalNameserver` goes a layer lower, for the cases a double can only assert by decree — what dnsruby actually raises per rcode. It binds a UDP socket on loopback, answers every query with the rcode you name, and hands you a `Resolver` pointed at it:
+
+```ruby
+MailResolver::Testing::LocalNameserver.answering(:servfail) do |resolver|
+  assert_raises(MailResolver::ServerFailure) { resolver.txt("example.com") }
+end
+```
+
+`:noerror`, `:servfail`, `:nxdomain`, and `:refused` are the rcodes; `nil` never replies, which is what a timeout looks like from the client. Pass `records:` to answer a `:noerror` query.
+
+## Testing
+
+```sh
+bundle install
+rake
+```
+
+The suite stubs `Dnsruby::Resolver`'s query path throughout.
+
+## History
+
+View the [changelog](CHANGELOG.md).
+
+## Contributing
+
+Everyone is encouraged to help improve this project:
+
+- [Report bugs](https://github.com/mailpiece/mailresolver/issues)
+- Fix bugs and submit pull requests
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/mailresolver/resolver.rb

@@ -0,0 +1,136 @@
+require "dnsruby"
+require "ipaddr"
+
+module MailResolver
+  class Error < StandardError; end
+  # NXDOMAIN, or NOERROR with no records of the type asked for.
+  class NotFound < Error; end
+  # NXDOMAIN: the name itself doesn't exist, not just records of that type.
+  class NoSuchName < NotFound; end
+  # No answer arrived in time.
+  class Timeout < Error; end
+  # SERVFAIL, REFUSED, or transport failure — distinct from NotFound's "nothing there".
+  class ServerFailure < Error; end
+
+  # DNS for mail. Built on dnsruby rather than Resolv, which collapses SERVFAIL/REFUSED into NXDOMAIN.
+  class Resolver
+    # One attempt per element; intervals double after the first, and the sum is the hard deadline.
+    # Default: attempts at 0s, 5s, and 10s, over at 11s.
+    TIMEOUTS = [ 5, 3, 3 ].freeze
+
+    def initialize(timeouts: TIMEOUTS)
+      @timeouts = timeouts
+      @lock = Mutex.new
+    end
+
+    # TXT character-strings are joined into one value (RFC 7208 §3.3).
+    def txt(name)
+      records("TXT", name).map { |record| record.strings.join }
+    end
+
+    def a(name)
+      records("A", name).map { |record| record.address.to_s }
+    end
+
+    # Dnsruby prints IPv6 in capitals; RFC 5952 §4.3 asks for lower case.
+    def aaaa(name)
+      records("AAAA", name).map { |record| record.address.to_s.downcase }
+    end
+
+    # A missing family contributes nothing; NXDOMAIN or nameserver failure still raises.
+    def addresses(name)
+      %w[ A AAAA ].flat_map { |type| family(type, name) }
+    end
+
+    # Equal preferences tie-break on the exchange name so callers always see the same order.
+    def mx(name)
+      records("MX", name).sort_by { |record| [ record.preference, record.exchange.to_s ] }
+        .map { |record| record.exchange.to_s }
+    end
+
+    # Dnsruby puts the question name in `name` and the host in `domainname`.
+    def ptr(address)
+      records("PTR", IPAddr.new(address.to_s).reverse).map { |record| record.domainname.to_s }
+    end
+
+    def cname(name)
+      records("CNAME", name).map { |record| record.domainname.to_s }
+    end
+
+    private
+      def family(type, name)
+        records(type, name).map { |record| record.address.to_s.downcase }
+      rescue NoSuchName
+        raise
+      rescue NotFound
+        []
+      end
+
+      # Filtered by type: a CNAME answer carries the alias beside the records it leads to.
+      def records(type, name)
+        answers = resolver.query(name.to_s, type).answer.select { |record| record.type == type }
+
+        if answers.any?
+          answers
+        else
+          raise NotFound, "no #{type} records for #{name}"
+        end
+      rescue Dnsruby::NXDomain
+        raise NoSuchName, "no such name #{name}"
+      rescue Dnsruby::ResolvTimeout
+        # Descends from Timeout::Error, not Dnsruby::ResolvError.
+        raise Timeout, "timed out resolving #{type} #{name}"
+      # Connect/send failures arrive as bare IOError/SocketError/SystemCallError from dnsruby's queue.
+      rescue Dnsruby::ResolvError, IOError, SocketError, SystemCallError => error
+        raise ServerFailure, "couldn't resolve #{type} #{name}: #{reason(error)}"
+      end
+
+      def reason(error)
+        if error.is_a?(Dnsruby::ResolvError)
+          rcode(error)
+        else
+          without_backtrace(error.message)
+        end
+      end
+
+      # Dnsruby rcode classes often carry no message, and `class.name` is nil on an anonymous class.
+      def rcode(error)
+        name = error.class.name&.split("::")&.last
+
+        case
+        when name.nil?                         then error.message
+        when error.message == error.class.name then name
+        else                                        "#{name}, #{error.message}"
+        end
+      end
+
+      # Transport error messages carry dnsruby's own backtrace inline.
+      def without_backtrace(message)
+        message.sub(/\s*\[".*\z/m, "")
+      end
+
+      # Built once and shared so concurrent queries multiplex over one I/O thread.
+      # Caching and DNSSEC are off — the former is process-global, the latter unused by callers.
+      def resolver
+        @lock.synchronize do
+          @resolver ||= Dnsruby::Resolver.new(**options).tap do |dns|
+            dns.dnssec = false
+            dns.do_caching = false
+            dns.query_timeout = @timeouts.sum
+            dns.packet_timeout = @timeouts.first
+            dns.retry_times = @timeouts.size
+            # Dnsruby fires attempt n at 2^(n-1) times this; halving the first element lands the schedule.
+            dns.retry_delay = @timeouts.first / 2.0
+          end
+        end
+      rescue ArgumentError => error
+        # Dnsruby raises this when no configured nameserver is usable.
+        raise ServerFailure, "no usable nameserver: #{error.message}"
+      end
+
+      # Overridden by MailResolver::Testing::LocalNameserver to point at a loopback nameserver.
+      def options
+        {}
+      end
+  end
+end

data/lib/mailresolver/testing.rb

@@ -0,0 +1,170 @@
+require "socket"
+require "resolv"
+
+module MailResolver
+  # Doubles for tests that need DNS to misbehave. Require from your test helper:
+  #
+  #   require "mailresolver/testing"
+  module Testing
+    # A zone in a hash: missing names raise NoSuchName, missing types raise NotFound,
+    # and :timeout/:servfail/:nxdomain stand in for misbehavior. PTR is keyed by address.
+    #
+    #   FakeResolver.new("example.com" => { txt: [ "v=spf1 -all" ], mx: :servfail })
+    class FakeResolver
+      attr_reader :queries
+
+      def initialize(zone = {})
+        @zone = zone.transform_keys { |name| normalized(name) }
+        @queries = []
+      end
+
+      def txt(name)
+        lookup(name, :txt)
+      end
+
+      def a(name)
+        lookup(name, :a)
+      end
+
+      def aaaa(name)
+        lookup(name, :aaaa)
+      end
+
+      # A missing family contributes nothing; NXDOMAIN or nameserver failure still raises.
+      def addresses(name)
+        %i[ a aaaa ].flat_map { |type| family(type, name) }
+      end
+
+      def mx(name)
+        lookup(name, :mx)
+      end
+
+      def ptr(address)
+        lookup(address, :ptr)
+      end
+
+      def cname(name)
+        lookup(name, :cname)
+      end
+
+      private
+        def family(type, name)
+          lookup(name, type)
+        rescue NoSuchName
+          raise
+        rescue NotFound
+          []
+        end
+
+        def lookup(name, type)
+          key = normalized(name)
+          @queries << [ key, type ]
+
+          case records = @zone.dig(key, type)
+          when :timeout  then raise Timeout, "timed out resolving #{type.upcase} #{key}"
+          when :servfail then raise ServerFailure, "server failure resolving #{type.upcase} #{key}"
+          when :nxdomain then raise NoSuchName, "no such name #{key}"
+          when nil, []   then raise absence(key, type)
+          else records
+          end
+        end
+
+        # A name the zone never mentions doesn't exist; one there without this type does.
+        def absence(key, type)
+          if @zone.key?(key)
+            NotFound.new("no #{type.upcase} records for #{key}")
+          else
+            NoSuchName.new("no such name #{key}")
+          end
+        end
+
+        def normalized(name)
+          name.to_s.downcase.chomp(".")
+        end
+    end
+
+    # A loopback nameserver for one rcode (records for :noerror, [name, record]
+    # for an alias, nil for a timeout), with replies encoded via Resolv.
+    #
+    #   LocalNameserver.answering(:servfail) do |resolver|
+    #     assert_raises(MailResolver::ServerFailure) { resolver.txt("example.com") }
+    #   end
+    class LocalNameserver
+      RCODES = { noerror: 0, servfail: 2, nxdomain: 3, refused: 5 }.freeze
+      TIMEOUTS = [ 0.5 ].freeze
+
+      def self.answering(rcode, records: [], timeouts: TIMEOUTS)
+        nameserver = new(rcode, records: records)
+        yield nameserver.resolver(timeouts: timeouts)
+      ensure
+        nameserver&.close
+      end
+
+      def initialize(rcode, records: [])
+        @rcode, @records = rcode, records
+        @socket = UDPSocket.new
+        @socket.bind("127.0.0.1", 0)
+        @thread = Thread.new { serve }
+      end
+
+      def port
+        @socket.addr[1]
+      end
+
+      def resolver(timeouts: TIMEOUTS)
+        LocalResolver.new(port, timeouts: timeouts)
+      end
+
+      def close
+        @thread.kill
+        @socket.close
+      end
+
+      # Overrides options so configuring a nameserver stays off the public API.
+      class LocalResolver < Resolver
+        def initialize(port, **options)
+          super(**options)
+          @port = port
+        end
+
+        private
+          def options
+            { nameserver: "127.0.0.1", port: @port }
+          end
+      end
+
+      private
+        def serve
+          loop do
+            message, sender = @socket.recvfrom(4096)
+            @socket.send(reply_to(message).encode, 0, sender[3], sender[1]) if @rcode
+          end
+        rescue IOError, Errno::EBADF
+          nil
+        end
+
+        def reply_to(message)
+          query = Resolv::DNS::Message.decode(message)
+          reply = Resolv::DNS::Message.new(query.id)
+          reply.qr = 1
+          reply.rd = query.rd
+          reply.ra = 1
+          reply.rcode = RCODES.fetch(@rcode)
+
+          query.each_question do |name, typeclass|
+            reply.add_question(name, typeclass)
+
+            @records.each do |record|
+              if record.is_a?(Array)
+                reply.add_answer(Resolv::DNS::Name.create(record.first), 60, record.last)
+              else
+                reply.add_answer(name, 60, record)
+              end
+            end
+          end
+
+          reply
+        end
+    end
+  end
+end

data/lib/mailresolver/version.rb

@@ -0,0 +1,3 @@
+module MailResolver
+  VERSION = "0.5.1"
+end

data/lib/mailresolver.rb

@@ -0,0 +1,6 @@
+require "mailresolver/version"
+require "mailresolver/resolver"
+
+# DNS for mail: what does DNS say, and if it didn't answer, why not?
+module MailResolver
+end

data/mailresolver.gemspec

@@ -0,0 +1,32 @@
+require_relative "lib/mailresolver/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "mailresolver"
+  spec.version = MailResolver::VERSION
+  spec.platform = Gem::Platform::RUBY
+  spec.required_ruby_version = ">= 3.4"
+  spec.authors = [ "Simon Lev" ]
+
+  spec.summary = "DNS resolution for mail, in Ruby."
+  spec.description = "DNS resolution for mail, in Ruby. **mailresolver** is a small, injectable DNS client for mail libraries — TXT, A/AAAA, MX, PTR, and CNAME lookups."
+
+  spec.homepage = "https://github.com/mailpiece/mailresolver"
+  spec.license = "MIT"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE",
+    "mailresolver.gemspec"
+  ]
+  spec.require_paths = [ "lib" ]
+
+  # Resolv collapses SERVFAIL/REFUSED into empty answers; dnsruby does not.
+  spec.add_dependency "dnsruby", "~> 1.74"
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: mailresolver
+version: !ruby/object:Gem::Version
+  version: 0.5.1
+platform: ruby
+authors:
+- Simon Lev
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dnsruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.74'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.74'
+description: DNS resolution for mail, in Ruby. **mailresolver** is a small, injectable
+  DNS client for mail libraries — TXT, A/AAAA, MX, PTR, and CNAME lookups.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mailresolver.rb
+- lib/mailresolver/resolver.rb
+- lib/mailresolver/testing.rb
+- lib/mailresolver/version.rb
+- mailresolver.gemspec
+homepage: https://github.com/mailpiece/mailresolver
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mailpiece/mailresolver
+  changelog_uri: https://github.com/mailpiece/mailresolver/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mailpiece/mailresolver/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: DNS resolution for mail, in Ruby.
+test_files: []