philiprehberger-header_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0483e3f7557d6bc4a5d455fa7fcfbee3808118f120f17427f73c1b763cdfa4dd'
+  data.tar.gz: f2834acace689c8b78da5e7af771348efa97918bf7eb71434e6317708ef9da62
+SHA512:
+  metadata.gz: cbc23f4ecb68a3c80815a21f09de5156ccef17e9d9cc15a2d420409209f06119491d059ccfc9d3de26f268029cb78b910db12d88c56cf0918a14dea45d11f75e
+  data.tar.gz: 6c792d9fbff457ce2377ab95e641bce5626bb3a8ce5a01df1f0062cee51b9be05c0e9ecdc91e978938842213c5c76e9847cb521f1c91031d06f766b75be5df88

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-26
+
+### Added
+- Initial release
+- Parse Accept headers with quality values and parameters
+- Parse and build Cache-Control directives
+- Parse Content-Type with charset and boundary
+- Parse and build Link headers (RFC 8288)
+- Content negotiation matching Accept against available types

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+# philiprehberger-header_kit
+
+[![Tests](https://github.com/philiprehberger/rb-header-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-header-kit/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-header_kit.svg)](https://rubygems.org/gems/philiprehberger-header_kit)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-header-kit)](LICENSE)
+[![Sponsor](https://img.shields.io/badge/sponsor-philiprehberger-pink?logo=githubsponsors)](https://github.com/sponsors/philiprehberger)
+
+HTTP header parsing, construction, and content negotiation
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-header_kit"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-header_kit
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/header_kit"
+```
+
+### Parse Accept
+
+```ruby
+Philiprehberger::HeaderKit.parse_accept("text/html;q=0.9, application/json")
+# => [{type: "application/json", quality: 1.0, params: {}},
+#     {type: "text/html", quality: 0.9, params: {}}]
+```
+
+### Parse Cache-Control
+
+```ruby
+Philiprehberger::HeaderKit.parse_cache_control("public, max-age=3600, must-revalidate")
+# => {public: true, max_age: 3600, must_revalidate: true}
+```
+
+### Build Cache-Control
+
+```ruby
+Philiprehberger::HeaderKit.build_cache_control(public: true, max_age: 3600)
+# => "public, max-age=3600"
+```
+
+### Parse Content-Type
+
+```ruby
+Philiprehberger::HeaderKit.parse_content_type("text/html; charset=utf-8")
+# => {media_type: "text/html", charset: "utf-8", boundary: nil}
+```
+
+### Parse Link
+
+```ruby
+Philiprehberger::HeaderKit.parse_link('<https://example.com/2>; rel="next"')
+# => [{uri: "https://example.com/2", rel: "next", type: nil, title: nil}]
+```
+
+### Build Link
+
+```ruby
+Philiprehberger::HeaderKit.build_link([{uri: "https://example.com/2", rel: "next"}])
+# => '<https://example.com/2>; rel="next"'
+```
+
+### Content Negotiation
+
+```ruby
+Philiprehberger::HeaderKit.negotiate("text/html;q=0.9, application/json", ["text/html", "application/json"])
+# => "application/json"
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `HeaderKit.parse_accept(header)` | Parse Accept header into sorted entries |
+| `HeaderKit.parse_cache_control(header)` | Parse Cache-Control into directive hash |
+| `HeaderKit.build_cache_control(directives)` | Build Cache-Control string from hash |
+| `HeaderKit.parse_content_type(header)` | Parse Content-Type into components |
+| `HeaderKit.parse_link(header)` | Parse Link header into entry array |
+| `HeaderKit.build_link(links)` | Build Link header from array of hashes |
+| `HeaderKit.negotiate(accept_header, available)` | Content negotiation, returns best match or nil |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/header_kit/accept.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HeaderKit
+    # Parses Accept headers into structured media type entries with quality values.
+    #
+    # Each entry contains the media type, a quality factor (0.0-1.0), and any
+    # additional parameters from the header.
+    module Accept
+      QUALITY_PATTERN = /\Aq\z/i
+
+      # Parse an Accept header string.
+      #
+      # @param header [String] the Accept header value
+      # @return [Array<Hash>] sorted by quality descending, each with :type, :quality, :params
+      def self.parse(header)
+        return [] if header.nil? || header.strip.empty?
+
+        entries = header.split(',').map { |entry| parse_entry(entry.strip) }
+        entries.compact.sort_by { |e| [-e[:quality], entries.index(e)] }
+      end
+
+      # Parse a single media type entry from an Accept header.
+      #
+      # @param entry [String] a single media type with optional parameters
+      # @return [Hash, nil] parsed entry or nil if invalid
+      def self.parse_entry(entry)
+        return nil if entry.empty?
+
+        parts = entry.split(';').map(&:strip)
+        type = parts.shift
+        return nil if type.nil? || type.empty?
+
+        quality = 1.0
+        params = {}
+
+        parts.each do |param|
+          key, value = param.split('=', 2).map(&:strip)
+          next if key.nil? || key.empty?
+
+          if QUALITY_PATTERN.match?(key)
+            quality = parse_quality(value)
+          else
+            params[key] = value
+          end
+        end
+
+        { type: type, quality: quality, params: params }
+      end
+
+      # Parse a quality value, clamping to [0.0, 1.0].
+      #
+      # @param value [String, nil] the quality string
+      # @return [Float] parsed quality value
+      def self.parse_quality(value)
+        return 1.0 if value.nil? || value.empty?
+
+        q = value.to_f
+        q.clamp(0.0, 1.0)
+      end
+
+      private_class_method :parse_entry, :parse_quality
+    end
+  end
+end

data/lib/philiprehberger/header_kit/cache_control.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HeaderKit
+    # Parses and builds Cache-Control header values.
+    #
+    # Supports common directives: max-age, s-maxage, no-cache, no-store,
+    # public, private, must-revalidate, proxy-revalidate, no-transform, immutable.
+    module CacheControl
+      VALUE_DIRECTIVES = %w[max-age s-maxage max-stale min-fresh stale-while-revalidate stale-if-error].freeze
+
+      # Parse a Cache-Control header string into a directive hash.
+      #
+      # Boolean directives become `true`. Value directives are converted to integers.
+      # Keys are symbolized with hyphens replaced by underscores.
+      #
+      # @param header [String] the Cache-Control header value
+      # @return [Hash{Symbol => true, Integer, String}] parsed directives
+      def self.parse(header)
+        return {} if header.nil? || header.strip.empty?
+
+        directives = {}
+
+        header.split(',').each do |part|
+          part = part.strip
+          next if part.empty?
+
+          key, value = part.split('=', 2)
+          key = key.strip.downcase
+          sym = key.tr('-', '_').to_sym
+
+          if value
+            value = value.strip.delete('"')
+            directives[sym] = VALUE_DIRECTIVES.include?(key) ? value.to_i : value
+          else
+            directives[sym] = true
+          end
+        end
+
+        directives
+      end
+
+      # Build a Cache-Control header string from a directive hash.
+      #
+      # @param directives [Hash{Symbol => true, Integer, String}] directive hash
+      # @return [String] formatted Cache-Control header value
+      def self.build(directives)
+        return '' if directives.nil? || directives.empty?
+
+        parts = directives.map do |key, value|
+          directive = key.to_s.tr('_', '-')
+          value == true ? directive : "#{directive}=#{value}"
+        end
+
+        parts.join(', ')
+      end
+    end
+  end
+end

data/lib/philiprehberger/header_kit/content_type.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HeaderKit
+    # Parses Content-Type header values into media type, charset, and boundary components.
+    module ContentType
+      # Parse a Content-Type header string.
+      #
+      # @param header [String] the Content-Type header value
+      # @return [Hash] with :media_type, :charset, :boundary keys
+      def self.parse(header)
+        result = { media_type: nil, charset: nil, boundary: nil }
+        return result if header.nil? || header.strip.empty?
+
+        parts = header.split(';').map(&:strip)
+        result[:media_type] = parts.shift&.downcase
+
+        parts.each do |param|
+          key, value = param.split('=', 2).map(&:strip)
+          next if key.nil? || key.empty?
+
+          value = unquote(value) if value
+
+          case key.downcase
+          when 'charset'
+            result[:charset] = value
+          when 'boundary'
+            result[:boundary] = value
+          end
+        end
+
+        result
+      end
+
+      # Remove surrounding double quotes from a value.
+      #
+      # @param value [String, nil] the value to unquote
+      # @return [String, nil] unquoted value
+      def self.unquote(value)
+        return value if value.nil?
+
+        value = value.strip
+        if value.start_with?('"') && value.end_with?('"')
+          value[1..-2]
+        else
+          value
+        end
+      end
+
+      private_class_method :unquote
+    end
+  end
+end

data/lib/philiprehberger/header_kit/link.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HeaderKit
+    # Parses and builds RFC 8288 Link header values.
+    #
+    # Each link entry contains a URI and optional parameters such as rel, type, and title.
+    module Link
+      URI_PATTERN = /<([^>]*)>/
+
+      # Parse a Link header string into an array of link entries.
+      #
+      # @param header [String] the Link header value
+      # @return [Array<Hash>] each with :uri, :rel, :type, :title keys
+      def self.parse(header)
+        return [] if header.nil? || header.strip.empty?
+
+        header.split(/,(?=\s*<)/).map { |entry| parse_entry(entry.strip) }.compact
+      end
+
+      # Build a Link header string from an array of link hashes.
+      #
+      # @param links [Array<Hash>] each with :uri and optional :rel, :type, :title
+      # @return [String] formatted Link header value
+      def self.build(links)
+        return '' if links.nil? || links.empty?
+
+        parts = links.map do |link|
+          entry = "<#{link[:uri]}>"
+          entry += "; rel=\"#{link[:rel]}\"" if link[:rel]
+          entry += "; type=\"#{link[:type]}\"" if link[:type]
+          entry += "; title=\"#{link[:title]}\"" if link[:title]
+          entry
+        end
+
+        parts.join(', ')
+      end
+
+      # Parse a single Link entry.
+      #
+      # @param entry [String] a single link entry
+      # @return [Hash, nil] parsed link or nil if invalid
+      def self.parse_entry(entry)
+        match = URI_PATTERN.match(entry)
+        return nil unless match
+
+        uri = match[1]
+        result = { uri: uri, rel: nil, type: nil, title: nil }
+
+        params_str = entry[match.end(0)..]
+        return result if params_str.nil? || params_str.strip.empty?
+
+        params_str.split(';').each do |param|
+          param = param.strip
+          next if param.empty?
+
+          key, value = param.split('=', 2).map(&:strip)
+          next if key.nil? || key.empty? || value.nil?
+
+          value = unquote(value)
+
+          case key.downcase
+          when 'rel'
+            result[:rel] = value
+          when 'type'
+            result[:type] = value
+          when 'title'
+            result[:title] = value
+          end
+        end
+
+        result
+      end
+
+      # Remove surrounding double quotes from a value.
+      #
+      # @param value [String, nil] the value to unquote
+      # @return [String, nil] unquoted value
+      def self.unquote(value)
+        return value if value.nil?
+
+        value = value.strip
+        if value.start_with?('"') && value.end_with?('"')
+          value[1..-2]
+        else
+          value
+        end
+      end
+
+      private_class_method :parse_entry, :unquote
+    end
+  end
+end

data/lib/philiprehberger/header_kit/negotiation.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HeaderKit
+    # Content negotiation logic for matching Accept headers against available media types.
+    module Negotiation
+      # Find the best matching media type from available types based on an Accept header.
+      #
+      # Matching rules (RFC 7231):
+      # 1. Exact type match
+      # 2. Subtype wildcard (e.g., text/* matches text/html)
+      # 3. Full wildcard (*/*) matches anything
+      #
+      # @param accept_header [String] the Accept header value
+      # @param available [Array<String>] list of available media types
+      # @return [String, nil] the best matching type, or nil if no match
+      def self.negotiate(accept_header, available)
+        return nil if available.nil? || available.empty?
+        return available.first if accept_header.nil? || accept_header.strip.empty?
+
+        accepted = Accept.parse(accept_header)
+        return nil if accepted.empty?
+
+        best_match = nil
+        best_quality = -1.0
+        best_specificity = -1
+
+        accepted.each do |entry|
+          available.each do |candidate|
+            specificity = match_specificity(entry[:type], candidate)
+            next unless specificity >= 0
+            next unless entry[:quality] > best_quality ||
+                        (entry[:quality] == best_quality && specificity > best_specificity)
+
+            best_match = candidate
+            best_quality = entry[:quality]
+            best_specificity = specificity
+          end
+        end
+
+        best_quality > 0.0 ? best_match : nil
+      end
+
+      # Calculate match specificity between an accept type pattern and a candidate.
+      #
+      # @param pattern [String] the accept type (may include wildcards)
+      # @param candidate [String] the available media type
+      # @return [Integer] specificity score (-1 = no match, 0 = */*, 1 = type/*, 2 = exact)
+      def self.match_specificity(pattern, candidate)
+        return 0 if pattern == '*/*'
+
+        pattern_type, pattern_sub = pattern.downcase.split('/', 2)
+        candidate_type, candidate_sub = candidate.downcase.split('/', 2)
+
+        return -1 unless pattern_type == candidate_type || pattern_type == '*'
+
+        if pattern_sub == '*'
+          1
+        elsif pattern_sub == candidate_sub
+          2
+        else
+          -1
+        end
+      end
+
+      private_class_method :match_specificity
+    end
+  end
+end

data/lib/philiprehberger/header_kit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HeaderKit
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/header_kit.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative 'header_kit/version'
+require_relative 'header_kit/accept'
+require_relative 'header_kit/cache_control'
+require_relative 'header_kit/content_type'
+require_relative 'header_kit/link'
+require_relative 'header_kit/negotiation'
+
+module Philiprehberger
+  module HeaderKit
+    class Error < StandardError; end
+
+    # Parse an Accept header into structured entries sorted by quality.
+    #
+    # @param header [String] the Accept header value
+    # @return [Array<Hash>] entries with :type, :quality, :params keys
+    def self.parse_accept(header)
+      Accept.parse(header)
+    end
+
+    # Parse a Cache-Control header into a directive hash.
+    #
+    # @param header [String] the Cache-Control header value
+    # @return [Hash{Symbol => true, Integer, String}] parsed directives
+    def self.parse_cache_control(header)
+      CacheControl.parse(header)
+    end
+
+    # Build a Cache-Control header string from a directive hash.
+    #
+    # @param directives [Hash{Symbol => true, Integer, String}] directive hash
+    # @return [String] formatted Cache-Control header value
+    def self.build_cache_control(directives)
+      CacheControl.build(directives)
+    end
+
+    # Parse a Content-Type header into its components.
+    #
+    # @param header [String] the Content-Type header value
+    # @return [Hash] with :media_type, :charset, :boundary keys
+    def self.parse_content_type(header)
+      ContentType.parse(header)
+    end
+
+    # Parse a Link header into an array of link entries.
+    #
+    # @param header [String] the Link header value
+    # @return [Array<Hash>] entries with :uri, :rel, :type, :title keys
+    def self.parse_link(header)
+      Link.parse(header)
+    end
+
+    # Build a Link header string from an array of link hashes.
+    #
+    # @param links [Array<Hash>] each with :uri and optional :rel, :type, :title
+    # @return [String] formatted Link header value
+    def self.build_link(links)
+      Link.build(links)
+    end
+
+    # Find the best matching media type via content negotiation.
+    #
+    # @param accept_header [String] the Accept header value
+    # @param available [Array<String>] list of available media types
+    # @return [String, nil] the best matching type, or nil if no match
+    def self.negotiate(accept_header, available)
+      Negotiation.negotiate(accept_header, available)
+    end
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-header_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-27 00:00:00.000000000 Z
+dependencies: []
+description: Parse and build Accept, Cache-Control, Content-Type, and Link HTTP headers.
+  Includes content negotiation for selecting the best response type.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/header_kit.rb
+- lib/philiprehberger/header_kit/accept.rb
+- lib/philiprehberger/header_kit/cache_control.rb
+- lib/philiprehberger/header_kit/content_type.rb
+- lib/philiprehberger/header_kit/link.rb
+- lib/philiprehberger/header_kit/negotiation.rb
+- lib/philiprehberger/header_kit/version.rb
+homepage: https://github.com/philiprehberger/rb-header-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-header-kit
+  source_code_uri: https://github.com/philiprehberger/rb-header-kit
+  changelog_uri: https://github.com/philiprehberger/rb-header-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-header-kit/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: HTTP header parsing, construction, and content negotiation
+test_files: []