philiprehberger-header_kit 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7515c78405c89a2690d8a4fc48b802bdf9c5b79dd9deae14fe07de8a8673d2df
-  data.tar.gz: ca05991394f985b4b5b0148a6db2c826bc9101eb04787b6f6adf9c4d2839ab1b
+  metadata.gz: 255a0f1f4321e63ae82d6acaf028cddb9a041d4f1594b16dcbb8f2a51f54a286
+  data.tar.gz: 1a0ea312d1937e9e17c7cabe31f7822345d0de02f4627d09c597c5a71a5b7715
 SHA512:
-  metadata.gz: 02ce3113575c5c98db4e4b010138861a983488db0e888b09644dfe6162b48af2864190b815f82d33d1e0b6cbf5855eed176b1ec6bd30fdd73966f7be59b538b1
-  data.tar.gz: 387dd665c493e2d308e3cb76581733691d231d2160e3c6ad6cee724a818470f3fb31e089dd607206680738508b204f5630c0c48fae4f1c05ed89ed97c2bd4057
+  metadata.gz: ee48374d55f01e11ae5b499c31556037801082a6631ed60306d544109897715bf5510eff7403675e2e94795257903efe289469bd790181cc2c32fef70e65a975
+  data.tar.gz: 40cf00b3c4d3d9f88d50ab21f08fc2dfb2d75b9ee13e879f985d59b28a14e81c600376d13d8f13f9bafb4edd3ff9350d6c4f6d5766abf20e9dd94bd2fd9e706c

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-23
+
+### Added
+- `HeaderKit.build_accept_encoding(encodings)` for constructing Accept-Encoding headers from an array of `{encoding:, quality:}` hashes, mirroring the existing `build_accept` builder
+
+## [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

@@ -66,6 +66,17 @@ Philiprehberger::HeaderKit.parse_accept_encoding("gzip, deflate;q=0.5, br;q=0.8"
 # => [{encoding: "gzip", quality: 1.0}, {encoding: "br", quality: 0.8}, {encoding: "deflate", quality: 0.5}]
 ```
 
+### Build Accept-Encoding
+
+```ruby
+Philiprehberger::HeaderKit.build_accept_encoding([
+  {encoding: "gzip"},
+  {encoding: "br", quality: 0.9},
+  {encoding: "deflate", quality: 0.5}
+])
+# => "gzip, br;q=0.9, deflate;q=0.5"
+```
+
 ### Parse Authorization
 
 ```ruby
@@ -181,6 +192,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
@@ -200,6 +227,7 @@ Philiprehberger::HeaderKit.parse_retry_after("Fri, 04 Apr 2026 12:00:00 GMT")
 | `HeaderKit.parse_accept_language(header)` | Parse Accept-Language into sorted entries |
 | `HeaderKit.negotiate_language(header, available)` | Language negotiation, returns best match or nil |
 | `HeaderKit.parse_accept_encoding(header)` | Parse Accept-Encoding into sorted entries |
+| `HeaderKit.build_accept_encoding(encodings)` | Build Accept-Encoding header string from encoding array |
 | `HeaderKit.parse_authorization(header)` | Parse Authorization header (Bearer, Basic, Digest) |
 | `HeaderKit.parse_cache_control(header)` | Parse Cache-Control into directive hash |
 | `HeaderKit.build_cache_control(directives)` | Build Cache-Control string from hash |
@@ -215,6 +243,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/accept_encoding.rb

@@ -50,7 +50,37 @@ module Philiprehberger
         value.to_f.clamp(0.0, 1.0)
       end
 
-      private_class_method :parse_entry, :parse_quality
+      # Build an Accept-Encoding header string from an array of encoding hashes.
+      #
+      # @param encodings [Array<Hash>] each with :encoding and optional :quality
+      # @return [String] formatted Accept-Encoding header value
+      def self.build(encodings)
+        return '' if encodings.nil? || encodings.empty?
+
+        parts = encodings.map do |entry|
+          encoding = entry[:encoding]
+          quality = entry[:quality]
+
+          if quality && quality < 1.0
+            "#{encoding};q=#{format_quality(quality)}"
+          else
+            encoding
+          end
+        end
+
+        parts.join(', ')
+      end
+
+      # Format a quality value, removing trailing zeros.
+      #
+      # @param quality [Float] the quality value
+      # @return [String] formatted quality string
+      def self.format_quality(quality)
+        formatted = format('%.3f', quality)
+        formatted.sub(/0+\z/, '').sub(/\.\z/, '.0')
+      end
+
+      private_class_method :parse_entry, :parse_quality, :format_quality
     end
   end
 end

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.6.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'
@@ -44,6 +45,14 @@ module Philiprehberger
       AcceptEncoding.parse(header)
     end
 
+    # Build an Accept-Encoding header string from an array of encoding hashes.
+    #
+    # @param encodings [Array<Hash>] each with :encoding and optional :quality
+    # @return [String] formatted Accept-Encoding header value
+    def self.build_accept_encoding(encodings)
+      AcceptEncoding.build(encodings)
+    end
+
     # Parse an Accept-Language header into structured entries sorted by quality.
     #
     # @param header [String] the Accept-Language header value
@@ -176,6 +185,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.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-05 00:00:00.000000000 Z
+date: 2026-04-24 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