philiprehberger-header_kit 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b397e499d587d20070ad785372aa81dc6574f583de2663cb105598ba229f3b52
-  data.tar.gz: cf8de787ddaa0f5cf2c95efa89f17e8db64d0368262bdd691b29c029fc0587fe
+  metadata.gz: d06951b5686f64b328c573fc16904e84eddfc61424ab8491fc2da817c7241fca
+  data.tar.gz: 9bdc24a4fc3dabc8d34ccdc105564e5669e9024ada60869c09317fdc11f1c1d6
 SHA512:
-  metadata.gz: 600588c8096d75b8b8559a2aa0d9477025a7e02706e3906f7c57297999f303083078f8dd7dfe75c70a56a2ddb6e424d88c69e94b11cfee8a9038eb1c1e7bc275
-  data.tar.gz: 9984feba85757ee07365321359798fe91a87c0f44902c65c81f52bb1885683c0971ea78590eee5db427e952afe72bbc1dceee4eba39478ca90e24e04622bcb97
+  metadata.gz: 82e06b0e3e146393f17782091fd76c5813be7c46df09c6366d9e892d40a4d05e652655b0017c2cd8242a8812961b428f853cb771e74721e08c46b778911dd124
+  data.tar.gz: f9970a177aa61fa120ea97eceeeda50f19d9517c143b2d91c4bce924a26466c13de2ca88f2a5e00375cadebae0cf2f804436ace824ac0fa3a53d00dbf8f4efec

data/CHANGELOG.md

@@ -7,6 +7,17 @@ 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
+
+- `parse_retry_after` for parsing Retry-After headers (numeric seconds or HTTP date)
+
 ## [0.3.1] - 2026-03-31
 
 ### Changed

data/README.md

@@ -181,6 +181,32 @@ 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
+Philiprehberger::HeaderKit.parse_retry_after("120")
+# => {seconds: 120}
+
+Philiprehberger::HeaderKit.parse_retry_after("Fri, 04 Apr 2026 12:00:00 GMT")
+# => {date: 2026-04-04 12:00:00 UTC}
+```
+
 ## API
 
 | Method | Description |
@@ -204,6 +230,8 @@ Philiprehberger::HeaderKit.parse_via('1.1 vegur, 1.0 fred')
 | `HeaderKit.security_headers(**options)` | Generate recommended security headers |
 | `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/retry_after.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Philiprehberger
+  module HeaderKit
+    module RetryAfter
+      module_function
+
+      def parse(header)
+        return nil if header.nil? || header.empty?
+
+        if header.match?(/\A\d+\z/)
+          { seconds: header.to_i }
+        else
+          { date: Time.httpdate(header) }
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/header_kit/version.rb

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

data/lib/philiprehberger/header_kit.rb

@@ -9,11 +9,13 @@ 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'
 require_relative 'header_kit/security'
 require_relative 'header_kit/forwarded'
+require_relative 'header_kit/retry_after'
 
 module Philiprehberger
   module HeaderKit
@@ -174,5 +176,29 @@ module Philiprehberger
     def self.parse_via(header)
       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,
+    # or :date (Time) for HTTP date values. Returns nil for nil/empty input.
+    #
+    # @param header [String] the Retry-After header value
+    # @return [Hash, nil] hash with :seconds or :date key, or nil
+    def self.parse_retry_after(header)
+      RetryAfter.parse(header)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-header_kit
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 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,9 +32,11 @@ 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
+- lib/philiprehberger/header_kit/retry_after.rb
 - lib/philiprehberger/header_kit/security.rb
 - lib/philiprehberger/header_kit/version.rb
 homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-header_kit