philiprehberger-header_kit 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7515c78405c89a2690d8a4fc48b802bdf9c5b79dd9deae14fe07de8a8673d2df
-  data.tar.gz: ca05991394f985b4b5b0148a6db2c826bc9101eb04787b6f6adf9c4d2839ab1b
+  metadata.gz: d06951b5686f64b328c573fc16904e84eddfc61424ab8491fc2da817c7241fca
+  data.tar.gz: 9bdc24a4fc3dabc8d34ccdc105564e5669e9024ada60869c09317fdc11f1c1d6
 SHA512:
-  metadata.gz: 02ce3113575c5c98db4e4b010138861a983488db0e888b09644dfe6162b48af2864190b815f82d33d1e0b6cbf5855eed176b1ec6bd30fdd73966f7be59b538b1
-  data.tar.gz: 387dd665c493e2d308e3cb76581733691d231d2160e3c6ad6cee724a818470f3fb31e089dd607206680738508b204f5630c0c48fae4f1c05ed89ed97c2bd4057
+  metadata.gz: 82e06b0e3e146393f17782091fd76c5813be7c46df09c6366d9e892d40a4d05e652655b0017c2cd8242a8812961b428f853cb771e74721e08c46b778911dd124
+  data.tar.gz: f9970a177aa61fa120ea97eceeeda50f19d9517c143b2d91c4bce924a26466c13de2ca88f2a5e00375cadebae0cf2f804436ace824ac0fa3a53d00dbf8f4efec

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-17
+
+### Added
+- `HeaderKit.etag_match?(header_value, resource_etag)` for If-None-Match / If-Match evaluation with list, weak-prefix, and `*` wildcard support
+
 ## [0.4.0] - 2026-04-04
 
 ### Added

data/README.md

@@ -181,6 +181,22 @@ Philiprehberger::HeaderKit.parse_via('1.1 vegur, 1.0 fred')
 # => [{protocol: "1.1", host: "vegur"}, {protocol: "1.0", host: "fred"}]
 ```
 
+### Conditional-request matching
+
+```ruby
+Philiprehberger::HeaderKit.etag_match?('"abc"', 'abc')
+# => true
+
+Philiprehberger::HeaderKit.etag_match?('W/"abc", W/"xyz"', 'xyz')
+# => true
+
+Philiprehberger::HeaderKit.etag_match?('*', 'anything')
+# => true
+
+Philiprehberger::HeaderKit.etag_match?('"abc"', 'nope')
+# => false
+```
+
 ### Parse Retry-After
 
 ```ruby
@@ -215,6 +231,7 @@ Philiprehberger::HeaderKit.parse_retry_after("Fri, 04 Apr 2026 12:00:00 GMT")
 | `HeaderKit.parse_forwarded(header)` | Parse RFC 7239 Forwarded header |
 | `HeaderKit.parse_via(header)` | Parse Via header into structured entries |
 | `HeaderKit.parse_retry_after(header)` | Parse Retry-After header (seconds or HTTP date) |
+| `HeaderKit.etag_match?(header_value, resource_etag)` | Check If-None-Match / If-Match against a resource ETag (list, `W/` weak prefix, `*` wildcard) |
 
 ## Development
 

data/lib/philiprehberger/header_kit/etag.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HeaderKit
+    # Evaluates If-None-Match / If-Match style header values against a
+    # resource ETag.
+    #
+    # Accepts single ETags, comma-separated lists, weak-prefixed values
+    # (e.g. `W/"abc"`), and the `*` wildcard. Strong and weak semantics
+    # collapse to equality on the inner token — callers that need strict
+    # strong/weak differentiation should implement that separately.
+    module Etag
+      module_function
+
+      # Check whether a header value matches a resource ETag.
+      #
+      # @param header_value [String, nil] the raw If-None-Match / If-Match header
+      # @param resource_etag [String, nil] the resource ETag (unquoted, no `W/` prefix)
+      # @return [Boolean] true if any value in the header matches the resource
+      def match?(header_value, resource_etag)
+        return false if header_value.nil?
+
+        stripped = header_value.strip
+        return false if stripped.empty?
+
+        tokens = split_values(stripped)
+        return false if tokens.empty?
+
+        tokens.any? { |token| token_matches?(token, resource_etag) }
+      end
+
+      # Split a header value into individual ETag tokens.
+      #
+      # Quoted sections (including escaped characters) are preserved so commas
+      # inside a quoted ETag do not split the value.
+      #
+      # @param value [String] the header value to split
+      # @return [Array<String>] trimmed, non-empty tokens
+      def split_values(value)
+        tokens = []
+        buffer = +''
+        in_quotes = false
+        escaped = false
+
+        value.each_char do |char|
+          if escaped
+            buffer << char
+            escaped = false
+          elsif in_quotes && char == '\\'
+            buffer << char
+            escaped = true
+          elsif char == '"'
+            buffer << char
+            in_quotes = !in_quotes
+          elsif char == ',' && !in_quotes
+            tokens << buffer.strip unless buffer.strip.empty?
+            buffer = +''
+          else
+            buffer << char
+          end
+        end
+
+        tokens << buffer.strip unless buffer.strip.empty?
+        tokens
+      end
+
+      # Determine whether a single token matches the resource ETag.
+      #
+      # @param token [String] a single header token
+      # @param resource_etag [String, nil] the resource ETag
+      # @return [Boolean] true if the token matches
+      def token_matches?(token, resource_etag)
+        return !resource_etag.nil? if token == '*'
+        return false if resource_etag.nil?
+
+        unwrap(token) == resource_etag
+      end
+
+      # Strip weak prefix and surrounding quotes from an ETag token.
+      #
+      # Backslash-escaped characters inside the quoted value are unescaped.
+      #
+      # @param token [String] a single ETag token
+      # @return [String] the inner ETag value
+      def unwrap(token)
+        value = token.sub(%r{\AW/}i, '')
+
+        return value unless value.start_with?('"') && value.end_with?('"') && value.length >= 2
+
+        inner = value[1..-2]
+        inner.gsub(/\\(.)/, '\1')
+      end
+    end
+  end
+end

data/lib/philiprehberger/header_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module HeaderKit
-    VERSION = '0.4.0'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/header_kit.rb

@@ -9,6 +9,7 @@ require_relative 'header_kit/authorization'
 require_relative 'header_kit/cache_control'
 require_relative 'header_kit/content_type'
 require_relative 'header_kit/cookie'
+require_relative 'header_kit/etag'
 require_relative 'header_kit/link'
 require_relative 'header_kit/negotiation'
 require_relative 'header_kit/cors'
@@ -176,6 +177,19 @@ module Philiprehberger
       Forwarded.parse_via(header)
     end
 
+    # Check whether an If-None-Match / If-Match header matches a resource ETag.
+    #
+    # Accepts a single ETag, comma-separated list, weak-prefixed values
+    # (e.g. `W/"abc"`), or the `*` wildcard. Weak and strong ETags collapse
+    # to equality on the inner token.
+    #
+    # @param header_value [String, nil] the raw header value
+    # @param resource_etag [String, nil] the resource ETag (unquoted, no `W/` prefix)
+    # @return [Boolean] true if any value in the header matches the resource
+    def self.etag_match?(header_value, resource_etag)
+      Etag.match?(header_value, resource_etag)
+    end
+
     # Parse a Retry-After header.
     #
     # Returns a hash with :seconds (Integer) for numeric values,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-header_kit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-05 00:00:00.000000000 Z
+date: 2026-04-18 00:00:00.000000000 Z
 dependencies: []
 description: Parse and build Accept, Accept-Language, Accept-Encoding, Authorization,
   Cache-Control, Content-Type, Cookie, Link, CORS, Forwarded, and Via HTTP headers.
@@ -32,6 +32,7 @@ files:
 - lib/philiprehberger/header_kit/content_type.rb
 - lib/philiprehberger/header_kit/cookie.rb
 - lib/philiprehberger/header_kit/cors.rb
+- lib/philiprehberger/header_kit/etag.rb
 - lib/philiprehberger/header_kit/forwarded.rb
 - lib/philiprehberger/header_kit/link.rb
 - lib/philiprehberger/header_kit/negotiation.rb