dmarcator 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4c6e25ca7a0fc2d77204c72ebb01906fce1ac4b537b1e011e505ed2938dda2b
-  data.tar.gz: 36f390d4c0e42c5e938df0345e9d412de2b09aed29da9ca83a424414090b88f1
+  metadata.gz: 689cd037f395f7803f4157fd148305f1d9d6c3dbb19fd42b61311b8e37d57124
+  data.tar.gz: 80518a23a140cb7102cb4d20a5fa896852ca8b104a3047939bcf4ba018e89699
 SHA512:
-  metadata.gz: 8f3db5da3231a84613e3a938d3e294f01da16df7aee2e633ba321e0002a8278ec28755accb08a1db2e6c72f2d0424cb34ea019b3168b32872503f59dddb6eaa4
-  data.tar.gz: 28d72632daef6199571fd1cd461c112610ebd14bd45a03b48c6b9127f571e82f8431ad35331e4c05d52482b2b5d085bb973a51aa37a888ede498b8b7a85f4eac
+  metadata.gz: c3b5f59702e05d0ffeeec17c9c3e7f8c1bd078448ba029fd4cf6bc8e6cbd8107dbda2e3633c228d1706f09832023a8a64b9806d6ee843b1fe13d449b19379e0c
+  data.tar.gz: de98c5111a0eb8023fa10807c7227d18bead12e17f2f43d084d8c5e3d27a2b1a4e86212c0c075fa2e75a97e5710e738de2baad45b833c31249d54a1abec80bb2

data/ChangeLog.md

@@ -1,3 +1,27 @@
+### 0.11.0 / 2026-10-29
+
+* Add `DMARCator.configure` for process-wide defaults, so a resolver can be set from code instead of only through the `DMARCATOR_DNS` environment variables. A configured resolver takes precedence over the environment, and `DMARCator.reset_configuration!` discards it.
+* A configured resolver may be a callable, in which case it is invoked for each lookup. This lets threaded applications use one resolver per lookup instead of sharing a `Resolv::DNS`, which does not serialise concurrent lookups.
+* Run CI on macOS 15 as well as Ubuntu 24.04, covering the Socket/OpenSSL and Net::HTTP paths used by the DoT and DoH transports.
+
+### 0.10.0 / 2026-10-29
+
+Breaking changes, taken before 1.0 so the release does not carry them:
+
+* Add `DMARCator::Error` as the base class for every error the library raises. `InvalidRecord`, `InvalidReport` and `ResolutionError` inherit from it, so one `rescue DMARCator::Error` catches all three.
+* `InvalidRecord` no longer inherits from `Parslet::ParseFailed`, removing the parser implementation from the public exception contract. Parse failures still expose the underlying parser error as their `cause`.
+* Remove the deprecated `DMARCator.query` and `DMARCator::Record.query` aliases. Use `DMARCator.dmarc` and `DMARCator::Record.lookup`.
+* Rename `DMARCator::Report::Record` to `DMARCator::Report::Row`, so aggregate rows are not confused with `DMARCator::Record`, the parsed DMARC TXT record.
+
+Migration:
+
+| Before | After |
+|---|---|
+| `DMARCator.query(domain)` | `DMARCator.dmarc(domain)` |
+| `DMARCator::Record.query(domain)` | `DMARCator::Record.lookup(domain)` |
+| `DMARCator::Report::Record` | `DMARCator::Report::Row` |
+| `rescue Parslet::ParseFailed` | `rescue DMARCator::Error` |
+
 ### 0.9.0 / 2026-10-29
 
 * Add `DMARCator.txt_records`, which returns the TXT resource records instead of strings, so callers that cache lookups can read each record's `ttl`. `DMARCator.txt` is now defined in terms of it and behaves the same.

data/README.md

@@ -177,6 +177,47 @@ more than the lookup on a fast resolver); `Resolv::DNS` does not lock per query,
 so use one resolver per thread when parallelising; and DoT/DoH open a new TLS
 connection per lookup, so plaintext is the better choice for bulk work.
 
+### SPF and DKIM
+
+The TXT primitives also cover the other two records a checker needs. There is
+no record-type-specific API, because the semantics belong to the caller:
+
+```ruby
+DMARCator.txt("example.com")                # SPF (RFC 7208)
+DMARCator.txt("s1._domainkey.example.com")  # DKIM (RFC 6376)
+```
+
+Both need the raw list rather than a single value: more than one SPF record is
+a `permerror`, and DKIM keys can be duplicated, rotated or revoked (`p=`). A
+helper returning "the" record would hide exactly those conditions. DKIM is also
+per-selector and selectors cannot be enumerated, so any convenience method would
+have to take a selector and would only build the name above.
+
+## Configuration
+
+Process-wide defaults can be set from code, and take precedence over the
+`DMARCATOR_DNS` environment variables:
+
+```ruby
+DMARCator.configure do |config|
+  config.resolver = DMARCator::Resolver::DoH.new(url: "https://dns.example/dns-query")
+end
+```
+
+A resolver object is shared by every thread, and `Resolv::DNS` does not
+serialise concurrent lookups, so threaded applications should configure a
+factory instead:
+
+```ruby
+DMARCator.configure do |config|
+  config.resolver = -> { Resolv::DNS.new }
+end
+```
+
+`DMARCator.reset_configuration!` discards configured values, which is useful in
+tests. Passing `resolver:` to a lookup still overrides both the configured
+default and the environment.
+
 ## Strict parsing
 
 By default, unknown tags and tags with invalid values are ignored. Pass

data/lib/dmarcator/config.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module DMARCator
+  #
+  # Process-wide defaults.
+  #
+  # @since 0.11.0
+  #
+  class Config
+    #
+    # The default resolver used when a lookup is not given one.
+    #
+    # Either a resolver ({Resolv::DNS}, {Resolver::DoH}, {Resolver::DoT}) or a
+    # callable returning one. Prefer a callable in threaded applications: a
+    # resolver object is shared by every thread, and `Resolv::DNS` does not
+    # serialise concurrent lookups.
+    #
+    # @return [Object, #call, nil]
+    #
+    attr_accessor :resolver
+  end
+
+  #
+  # The process-wide configuration.
+  #
+  # @return [Config]
+  #
+  # @since 0.11.0
+  #
+  def self.config
+    @config ||= Config.new
+  end
+
+  #
+  # Configures process-wide defaults.
+  #
+  #   DMARCator.configure do |config|
+  #     config.resolver = -> { Resolv::DNS.new }
+  #   end
+  #
+  # When set, a configured resolver takes precedence over `DMARCATOR_DNS` and
+  # is used by {txt}, {txt_records}, {dmarc} and {Record.lookup} whenever no
+  # resolver is passed explicitly.
+  #
+  # @yieldparam [Config] config
+  #
+  # @return [Config]
+  #
+  # @since 0.11.0
+  #
+  def self.configure
+    yield config if block_given?
+    config
+  end
+
+  #
+  # Discards any configured defaults.
+  #
+  # @return [Config]
+  #
+  # @since 0.11.0
+  #
+  def self.reset_configuration!
+    @config = Config.new
+  end
+end

data/lib/dmarcator/exceptions.rb

@@ -1,30 +1,41 @@
 # frozen_string_literal: true
 
-require 'parslet'
-
 module DMARCator
+  #
+  # Base class for every error raised by this library.
+  #
+  # Rescuing this catches parse failures, report failures and DNS lookup
+  # failures alike.
+  #
+  # @since 0.10.0
+  #
+  class Error < StandardError
+  end
+
   #
   # Raised when a DMARC record cannot be parsed.
   #
   # @since 0.2.0
   #
-  class InvalidRecord < Parslet::ParseFailed
+  class InvalidRecord < Error
   end
 
   #
   # Raised when a DMARC XML report cannot be parsed.
   #
-  class InvalidReport < StandardError
+  # @since 0.3.0
+  #
+  class InvalidReport < Error
   end
 
   #
-  # Raised when an encrypted DNS transport fails to return a usable answer.
+  # Raised when a DNS transport fails to return a usable answer.
   #
   # This is deliberately distinct from a missing record: a failed lookup must
   # not be mistaken for a domain without a DMARC policy.
   #
   # @since 0.6.0
   #
-  class ResolutionError < StandardError
+  class ResolutionError < Error
   end
 end

data/lib/dmarcator/query.rb

@@ -3,6 +3,7 @@
 require 'resolv'
 require 'rubygems'
 
+require_relative 'config'
 require_relative 'resolver'
 
 module DMARCator
@@ -125,7 +126,11 @@ module DMARCator
   end
 
   #
-  # Builds the resolver configured by the environment.
+  # The default resolver: a {configure}d one, or one built from the
+  # environment.
+  #
+  # A configured resolver may be an object or a callable; a callable is called
+  # for each lookup, which is what threaded applications should use.
   #
   # @return [Resolv::DNS, Resolver::DoH, Resolver::DoT]
   #
@@ -135,7 +140,11 @@ module DMARCator
   # @since 0.6.0
   #
   def self.default_resolver
-    Resolver.build
+    configured = config.resolver
+
+    return configured.call if configured.respond_to?(:call)
+
+    configured || Resolver.build
   end
 
   #
@@ -246,16 +255,6 @@ module DMARCator
     dmarc_records.first if dmarc_records.one?
   end
 
-  #
-  # @deprecated Use {dmarc}, which names what it returns. Kept for
-  #   compatibility; it will be removed in a future release.
-  #
-  # @see dmarc
-  #
-  def self.query(domain,resolver=default_resolver)
-    dmarc(domain, resolver: resolver)
-  end
-
   #
   # Looks up the TXT records at an already-validated name.
   #

data/lib/dmarcator/record.rb

@@ -285,7 +285,8 @@ module DMARCator
 
       new(attributes)
     rescue Parslet::ParseFailed => error
-      raise InvalidRecord.new(truncate_error_message(error.message), error.cause)
+      # Raising inside the rescue sets this error as the cause automatically.
+      raise InvalidRecord, truncate_error_message(error.message)
     end
 
     # Maximum length of error messages echoed from parsing untrusted input.
@@ -342,16 +343,6 @@ module DMARCator
       end
     end
 
-    #
-    # @deprecated Use {lookup}, which names what it returns. Kept for
-    #   compatibility; it will be removed in a future release.
-    #
-    # @see lookup
-    #
-    def self.query(domain,resolver=DMARCator.default_resolver)
-      lookup(domain, resolver: resolver)
-    end
-
     #
     # Converts the record to a Hash.
     #

data/lib/dmarcator/report/{record.rb → row.rb}

@@ -9,7 +9,10 @@ module DMARCator
     #
     # Represents a single `record` element of a DMARC XML report.
     #
-    class Record
+    # Named `Row` so it is not confused with {DMARCator::Record}, the parsed
+    # DMARC TXT record.
+    #
+    class Row
       include XmlHelper
 
       # Attribute names exposed by this class.

data/lib/dmarcator/report.rb

@@ -8,7 +8,7 @@ require_relative 'xml_helper'
 require_relative 'exceptions'
 require_relative 'report/metadata'
 require_relative 'report/policy'
-require_relative 'report/record'
+require_relative 'report/row'
 
 module DMARCator
   #
@@ -114,11 +114,11 @@ module DMARCator
     #
     # The report records.
     #
-    # @return [Array<Report::Record>]
+    # @return [Array<Report::Row>]
     #
     def records
       @records ||= @node.xpath('feedback/record').map do |node|
-        Record.new(node)
+        Row.new(node)
       end
     end
   end

data/lib/dmarcator/version.rb

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '0.9.0'
+  VERSION = '0.11.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Noah Berman
@@ -69,6 +69,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/dmarcator.rb
+- lib/dmarcator/config.rb
 - lib/dmarcator/exceptions.rb
 - lib/dmarcator/parser.rb
 - lib/dmarcator/query.rb
@@ -78,7 +79,7 @@ files:
 - lib/dmarcator/report/metadata.rb
 - lib/dmarcator/report/policy.rb
 - lib/dmarcator/report/reason.rb
-- lib/dmarcator/report/record.rb
+- lib/dmarcator/report/row.rb
 - lib/dmarcator/resolver.rb
 - lib/dmarcator/resolver/doh.rb
 - lib/dmarcator/resolver/dot.rb