refactor: address review feedback (IntegrityError, single algorithm map, README reorg)

Per review from @grosser:

- Add CssParser::IntegrityError < RemoteFileError, raised specifically on
  an SRI mismatch, so callers can distinguish it from other fetch
  failures (404, SSRF rejection, timeout) while remaining catchable by
  existing `rescue RemoteFileError` code. Required a small fix to the
  method's catch-all rescue, which previously downgraded any exception
  raised inside it (including the new IntegrityError) back to a plain
  RemoteFileError -- now only IntegrityError specifically is let through
  unchanged, preserving existing behavior/tests for other error paths.
- Merge INTEGRITY_ALGORITHM_PRIORITY and the inline digest-class lookup
  into one INTEGRITY_ALGORITHMS hash (algorithm => Digest class, ordered
  strongest first), so there's a single structure to keep in sync instead
  of two.
- Move the Subresource Integrity usage examples out of the main Usage
  code block into their own README section, since it's a less-common,
  advanced option.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: JLLeitschuh

README.md

@@ -23,26 +23,6 @@ parser.load_uri!('file://home/user/styles/style.css')
 # load a remote file, setting the base_uri and media_types
 parser.load_uri!('../style.css', {base_uri: 'http://example.com/styles/inc/', media_types: [:screen, :handheld]})
 
-# load a remote file, verifying it against a Subresource Integrity value
-# (https://www.w3.org/TR/SRI/) before parsing -- e.g. the value of an
-# HTML <link integrity="..."> attribute. Raises CssParser::RemoteFileError
-# (or, with io_exceptions: false, loads nothing) when the fetched body
-# doesn't match.
-parser.load_uri!('http://example.com/styles/style.css', integrity: 'sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC')
-
-# `integrity:` also accepts several space-separated values, exactly like the
-# HTML attribute does. When more than one hash algorithm is present, only the
-# strongest one is checked (sha512 > sha384 > sha256) and every weaker value is
-# ignored; multiple values for that same strongest algorithm are treated as
-# alternatives -- matching any one of them is enough.
-parser.load_uri!(
-  'http://example.com/styles/style.css',
-  integrity: 'sha256-Br6tO8uuFyBAw2O0eUNdXVyuS/POLb5jpHxXaxIq6Q0= sha384-0gCPKBW0n+VzQzZu5gzP+YMxy9QTLyn1y/O/TMvLTpVajzRKAx6d7TiPB5W7DnDn'
-)
-# ^ only the sha384 value is actually checked here; the sha256 one is present
-# (e.g. for browsers/tools that only understand sha256) but ignored by this
-# library since a stronger algorithm is also listed.
-
 # load a local file, setting the base_dir and media_types
 parser.load_file!('print.css', '~/styles/', :print)
 
@@ -91,6 +71,39 @@ content_rule.offset
 #=> 0..21
 ```
 
+# Subresource Integrity
+
+`Parser#load_uri!` accepts an `integrity:` option that verifies a fetched remote stylesheet
+against a [Subresource Integrity](https://www.w3.org/TR/SRI/) value before it's parsed -- the
+same value an HTML `<link integrity="...">` attribute carries.
+
+```Ruby
+parser.load_uri!(
+  'http://example.com/styles/style.css',
+  integrity: 'sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC'
+)
+```
+
+When the fetched body doesn't match, `CssParser::IntegrityError` (a subclass of
+`CssParser::RemoteFileError`, so existing `rescue RemoteFileError` code is unaffected) is
+raised if `io_exceptions` is enabled, or nothing is loaded otherwise.
+
+`integrity:` also accepts several space-separated values, exactly like the HTML attribute
+does. When more than one hash algorithm is present, only the strongest one is checked
+(sha512 > sha384 > sha256) and every weaker value is ignored; multiple values for that same
+strongest algorithm are treated as alternatives -- matching any one of them is enough (useful
+during a stylesheet rotation, when a CDN may still serve the old version for a while):
+
+```Ruby
+parser.load_uri!(
+  'http://example.com/styles/style.css',
+  integrity: 'sha256-Br6tO8uuFyBAw2O0eUNdXVyuS/POLb5jpHxXaxIq6Q0= sha384-0gCPKBW0n+VzQzZu5gzP+YMxy9QTLyn1y/O/TMvLTpVajzRKAx6d7TiPB5W7DnDn'
+)
+# only the sha384 value is actually checked here; the sha256 one is present
+# (e.g. for browsers/tools that only understand sha256) but ignored by this
+# library since a stronger algorithm is also listed.
+```
+
 # Testing
 
 ```Bash

lib/css_parser/parser.rb

@@ -8,6 +8,13 @@ module CssParser
   # Exception class used for any errors encountered while downloading remote files.
   class RemoteFileError < IOError; end
 
+  # Exception class used when a fetched remote file fails Subresource Integrity
+  # verification (see the `:integrity` option on `Parser#load_uri!`). A subclass of
+  # `RemoteFileError` so existing `rescue RemoteFileError` callers are unaffected;
+  # callers that want to distinguish an integrity failure from other fetch failures
+  # (404, SSRF rejection, timeout, etc.) can rescue this class specifically.
+  class IntegrityError < RemoteFileError; end
+
   # Exception class used if a request is made to load a CSS file more than once.
   class CircularReferenceError < StandardError; end
 
@@ -42,12 +49,17 @@ class Parser
     # was GHSA-9pmc-p236-855h.
     REMOTE_ALLOWED_SCHEMES = %w[http https].freeze
 
-    # Subresource Integrity hash algorithms this library can verify,
-    # strongest first. Mirrors the SRI spec's "agility" rule
-    # (https://www.w3.org/TR/SRI/#agility): when a caller-supplied
-    # `integrity` value lists more than one algorithm, only the
-    # strongest one present is checked.
-    INTEGRITY_ALGORITHM_PRIORITY = %w[sha512 sha384 sha256].freeze
+    # Subresource Integrity hash algorithms this library can verify, mapped to their
+    # Digest class, ordered strongest first. A single structure (rather than a
+    # separate priority list and digest-class lookup) so the two can't drift out of
+    # sync. Mirrors the SRI spec's "agility" rule (https://www.w3.org/TR/SRI/#agility):
+    # when a caller-supplied `integrity` value lists more than one algorithm, only
+    # the strongest one present is checked.
+    INTEGRITY_ALGORITHMS = {
+      'sha512' => Digest::SHA512,
+      'sha384' => Digest::SHA384,
+      'sha256' => Digest::SHA256
+    }.freeze
 
     # Array of CSS files that have been loaded.
     attr_reader :loaded_uris
@@ -508,8 +520,9 @@ def parse_block_into_rule_sets!(block, options = {}) # :nodoc:
     # Subresource Integrity value (https://www.w3.org/TR/SRI/) -- e.g. the value of an
     # HTML <tt><link integrity="..."></tt> attribute -- and, for http(s) URIs, verifies the
     # fetched response body against it before the CSS is parsed. When the digest does not
-    # match, the fetch is treated as a failure: an exception is raised if <tt>io_exceptions</tt>
-    # is enabled, otherwise nothing is loaded. Ignored for <tt>file://</tt> URIs.
+    # match, <tt>CssParser::IntegrityError</tt> (a subclass of <tt>RemoteFileError</tt>) is
+    # raised if <tt>io_exceptions</tt> is enabled, otherwise nothing is loaded. Ignored for
+    # <tt>file://</tt> URIs.
     #
     # Deprecated: originally accepted three params: `uri`, `base_uri` and `media_types`
     def load_uri!(uri, options = {}, deprecated = nil)
@@ -733,7 +746,7 @@ def read_remote_file(uri, integrity: nil) # :nodoc:
         end
 
         if integrity && !integrity_matches?(res.body, integrity)
-          raise RemoteFileError, uri.to_s if @options[:io_exceptions]
+          raise IntegrityError, uri.to_s if @options[:io_exceptions]
 
           return nil, nil
         end
@@ -743,6 +756,16 @@ def read_remote_file(uri, integrity: nil) # :nodoc:
         src.encode!('UTF-8', charset) if charset
 
         [src, charset]
+      rescue IntegrityError
+        # Let the IntegrityError raised above propagate with its specific
+        # class intact, rather than being downgraded to a generic
+        # RemoteFileError by the catch-all below. Other RemoteFileErrors
+        # raised within this method (e.g. from fetch_via_net_http on a
+        # cross-scheme redirect) are intentionally still caught by the
+        # catch-all: it discards their (potentially redirect-target-scoped)
+        # message in favor of this method's own `uri`, which several
+        # existing tests depend on.
+        raise
       rescue
         raise RemoteFileError, uri.to_s if @options[:io_exceptions]
 
@@ -761,18 +784,14 @@ def read_remote_file(uri, integrity: nil) # :nodoc:
     def integrity_matches?(body, integrity) # :nodoc:
       candidates = integrity.to_s.split.filter_map do |token|
         algorithm, value = token.split('-', 2)
-        [algorithm, value] if algorithm && value && INTEGRITY_ALGORITHM_PRIORITY.include?(algorithm)
+        [algorithm, value] if algorithm && value && INTEGRITY_ALGORITHMS.key?(algorithm)
       end
       return true if candidates.empty?
 
-      algorithm = candidates.map(&:first).min_by { |a| INTEGRITY_ALGORITHM_PRIORITY.index(a) }
+      algorithms_present = candidates.map(&:first)
+      algorithm = INTEGRITY_ALGORITHMS.each_key.find { |a| algorithms_present.include?(a) }
       expected_values = candidates.select { |a, _v| a == algorithm }.map { |_a, v| v }
-
-      digest_class = {
-        'sha512' => Digest::SHA512,
-        'sha384' => Digest::SHA384,
-        'sha256' => Digest::SHA256
-      }.fetch(algorithm)
+      digest_class = INTEGRITY_ALGORITHMS.fetch(algorithm)
 
       expected_values.include?(Base64.strict_encode64(digest_class.digest(body)))
     end

test/test_css_parser_integrity.rb

@@ -77,6 +77,15 @@ def test_matching_sha512_integrity_loads_normally
   end
 
   def test_mismatched_integrity_is_refused
+    tampered = "#{sha('sha384')[0, 15]}not-the-real-digest-at-all=="
+    assert_raises(CssParser::IntegrityError) do
+      cp.load_uri!("#{@uri_base}/simple.css", integrity: tampered)
+    end
+  end
+
+  def test_mismatched_integrity_raises_a_subclass_of_remote_file_error
+    # CssParser::IntegrityError must remain catchable by existing
+    # `rescue RemoteFileError` callers.
     tampered = "#{sha('sha384')[0, 15]}not-the-real-digest-at-all=="
     assert_raises(CssParser::RemoteFileError) do
       cp.load_uri!("#{@uri_base}/simple.css", integrity: tampered)
@@ -96,7 +105,7 @@ def test_strongest_algorithm_wins_when_multiple_present_and_it_fails
     # here) is authoritative, so a right-but-weaker value must not mask
     # a wrong-but-stronger one.
     value = "#{sha('sha256')} sha512-#{Base64.strict_encode64('not the real digest')}"
-    assert_raises(CssParser::RemoteFileError) do
+    assert_raises(CssParser::IntegrityError) do
       cp.load_uri!("#{@uri_base}/simple.css", integrity: value)
     end
   end
@@ -122,7 +131,7 @@ def test_multiple_values_for_the_same_algorithm_accepts_any_match
   end
 
   def test_unrecognized_algorithm_only_value_is_unverifiable_and_passes
-    # md5 is not in INTEGRITY_ALGORITHM_PRIORITY. A value naming only an
+    # md5 is not in INTEGRITY_ALGORITHMS. A value naming only an
     # unsupported algorithm can't be checked either way, so it's treated
     # as unverifiable rather than failing every such fetch.
     parser = cp