digest_fields 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea76394e2f56ef9da13f17ae08ee86e8f85f157fdf8b10dbb7cd2eb69256e47b
-  data.tar.gz: e0ba82e591f64ab9a12c0003a1b224cbe242e71816e5ac6f42f089a168af39bf
+  metadata.gz: 724411f2f670ec2fae3f43d2d84cbfbab3ff9fce8625e2acef870a9c7fc94ec5
+  data.tar.gz: ceb6a28e84a21e6014dfa64cda9d12736783a5ad6cc33b5c65fa009c9db4e8dd
 SHA512:
-  metadata.gz: 809b925c68acdb80c3a178889970bcb3bf8d8e9b72cae9eea48c46554424d9b476109491e0020a4b9c10eb53fdadcff7e2336b26c46e9b2fe37cb4ea7a1f1ebf
-  data.tar.gz: a32ea12572fb2c7bc6fe3f2006910b2cd604dd81d71c2736ab8cf4f936fc1c5793b2f554487b176abebcd23f99645c8363f7108e615921cf6ae913959874d859
+  metadata.gz: f9c6c4624221fe9a21dc9d1d28463e3218c0ecfbb7b5c81d777858a29e28397097c02362300c705079d382a9f45c6a256e6db23f622c5dab536b97b09e659175
+  data.tar.gz: b84c7ecdc1888dca1ff176bc235b5edaa69145cf5fc029146e26f58b0e67de76aaae8fc260e185521670e58da54ce818b82bf75d19f5ee5bf4d80781866371de

data/README.md

@@ -4,19 +4,87 @@
 
 Support for `Content-Digest` and `Repl-Digest` header digests that follows the [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html) specification.
 
-> [!WARNING]
-> This library currently only offers low-level primitives, and does not interact with Rack, does not set headers or trailers, or decide what consistitues content to digest. This is currently an exercise left to the user.
-
 ## Usage
 
+### Rack middleware
+
+`Rack::DigestFields` automatically computes and injects `Unencoded-Digest` response headers.
+
+#### Why `Unencoded-Digest` and not `Content-Digest` or `Repr-Digest`?
+
+[RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html) defines two similar headers:
+
+- **`Content-Digest`** — digest of the bytes as transferred on the wire, after any content-encoding (e.g. gzip) is applied.
+- **`Repr-Digest`** — digest of the full selected representation, which also varies with content-encoding.
+
+Both require the middleware to know the final encoded bytes. In a typical deployment, content-encoding is applied *downstream* of the Ruby process — by nginx, a CDN, or `Rack::Deflater` positioned later in the stack. The app never sees those bytes, so it cannot correctly compute either header.
+
+`Unencoded-Digest` is the digest of the body *before* any content-encoding. A Rack middleware always has these bytes, so it can produce the header reliably regardless of what happens downstream.
+
+> [!NOTE]
+> `Unencoded-Digest` is defined in an IETF draft ([draft-ietf-httpbis-unencoded-digest](https://datatracker.ietf.org/doc/draft-ietf-httpbis-unencoded-digest/)) that has not yet been standardised. Breaking changes to the header name, wire format, or semantics are unlikely — current feedback on the draft focuses on security considerations rather than the core design — but it is possible before the RFC is finalised.
+
+```ruby
+# config.ru
+require "digest_fields/rack"
+
+use Rack::DigestFields,
+  on_partial_content: :raise,  # required: :raise | :warn | :skip
+  unencoded_digest: true        # uses default algorithms (sha-256, sha-512)
+```
+
+With algorithm override:
+
+```ruby
+use Rack::DigestFields,
+  on_partial_content: :skip,
+  unencoded_digest: {
+    algorithms: %w[sha-256],
+    on_partial_content: :warn  # overrides global for this header
+  }
+```
+
+In Rails, insert before `Rack::Sendfile` to ensure the middleware sees the raw response body before any transformation:
+
+```ruby
+config.middleware.insert_before Rack::Sendfile, Rack::DigestFields,
+  on_partial_content: :raise,
+  unencoded_digest: true
+```
+
+`on_partial_content` is required with no default — `206 Partial Content` responses cannot correctly produce `Unencoded-Digest` (it requires the full unencoded representation). The three behaviours are:
+
+| Value | Behaviour |
+|---|---|
+| `:raise` | Raise `Rack::DigestFields::PartialContentError` |
+| `:warn` | Emit a warning and omit the header |
+| `:skip` | Omit the header silently |
+
 ### Library
 
 ```ruby
-digest = DigestFields.digest(body)
-digest.to_s # => "sha-256=:X48E9qOok...:, sha-512=:jas48SD...:"
+DigestFields.digest(body)
+# => "sha-256=:X48E9qOok...:, sha-512=:jas48SD...:"
+
+DigestFields.digest(body, algorithms: "sha-256")
+# => "sha-256=:X48E9qOok...:
+
+DigestFields.digest(body, algorithms: %w[sha-256 sha-512])
+# => "sha-256=:X48E9qOok...:, sha-512=:jas48SD...:"
+```
+
+### Custom Algorithms
+
+`sha-512` and `sha-256` are supported.
+
+The spec's [deprecated hash algorithms](https://www.iana.org/assignments/http-digest-hash-alg/http-digest-hash-alg.xhtml) are intentionally not supported, but you can add your own support if you need to:
+
+```ruby
+# Register a custom algorithm
+DigestFields.algorithms.add("md5", ->(body) { Digest::MD5.base64digest(body) })
 
-digest = DigestFields.digest(body, algorithms: [:sha256])
-digest.to_s # => "sha-256=:X48E9qOok...:
+DigestFields.digest(body, algorithms: %w[md5 sha-512])
+# => "md5=:...:, sha-512=:...:, "
 ```
 
 ## Installation

data/lib/digest_fields/algorithms.rb

@@ -0,0 +1,27 @@
+module DigestFields
+  class Algorithms
+    def initialize
+      reset!
+    end
+
+    def add(key, callable)
+      @registry[key] = callable
+    end
+
+    def reset!
+      @registry = {}
+      add("sha-256", ->(body) { Digest::SHA256.base64digest(body) })
+      add("sha-512", ->(body) { Digest::SHA512.base64digest(body) })
+    end
+
+    def keys
+      @registry.keys
+    end
+
+    def fetch(key)
+      @registry.fetch(key) do
+        raise ArgumentError, "#{key.inspect} not available (try one of: #{@registry.keys.join(", ")})"
+      end
+    end
+  end
+end

data/lib/digest_fields/digestion.rb

@@ -1,24 +1,9 @@
 module DigestFields::Digestion
-  ALGORITHMS = {
-    sha256: ->(body) { Digest::SHA256.base64digest(body) },
-    sha512: ->(body) { Digest::SHA512.base64digest(body) }
-  }
-
   module_function
 
-  def compute(body, algorithms: %i[sha256 sha512])
-    algorithms = [algorithms].flatten
-
-    algorithms.map do |algorithm|
-      key = algorithm.to_s.sub(/(\d+)$/, '-\1')
-
-      algorithm = ALGORITHMS.fetch(algorithm) do
-        raise ArgumentError, "#{algorithm.inspect} not available (try one of: #{ALGORITHMS.keys.join(", ")})"
-      end
-
-      digest = algorithm.call(body)
-
-      "#{key}=:#{digest}:"
+  def compute(body, registry:, algorithms:)
+    [algorithms].flatten.map do |key|
+      "#{key}=:#{registry.fetch(key).call(body)}:"
     end.join(", ")
   end
 end

data/lib/digest_fields/rack.rb

@@ -0,0 +1,97 @@
+require "rack"
+require "digest_fields"
+
+module Rack
+  class DigestFields
+    class PartialContentError < StandardError; end
+
+    VALID_ON_PARTIAL_CONTENT = %i[skip warn raise].freeze
+    RECOGNISED_HEADER_KEYS = %i[unencoded_digest].freeze
+    KNOWN_OPTION_KEYS = (RECOGNISED_HEADER_KEYS + [:on_partial_content]).freeze
+
+    def initialize(app, **options)
+      @app = app
+      validate_options!(options)
+      @on_partial_content = options.fetch(:on_partial_content)
+      @unencoded_digest = parse_unencoded_digest(options[:unencoded_digest])
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+
+      if status == 206
+        mode = @unencoded_digest[:on_partial_content] || @on_partial_content
+        case mode
+        when :skip
+          return [status, headers, body]
+        when :warn
+          Kernel.warn("Rack::DigestFields: Unencoded-Digest cannot be computed for 206 Partial Content")
+          return [status, headers, body]
+        when :raise
+          raise PartialContentError, "Rack::DigestFields: Unencoded-Digest cannot be computed for 206 Partial Content"
+        end
+      end
+
+      chunks = []
+      body.each { |chunk| chunks << chunk }
+      body.close if body.respond_to?(:close)
+      buffered = chunks.join
+
+      digest = ::DigestFields.digest(buffered, algorithms: @unencoded_digest[:algorithms])
+      headers = headers.merge("Unencoded-Digest" => digest)
+
+      [status, headers, [buffered]]
+    end
+
+    private
+
+    def validate_options!(options)
+      unknown = options.keys - KNOWN_OPTION_KEYS
+      raise ArgumentError, "Unrecognised options: #{unknown.map(&:inspect).join(", ")}" if unknown.any?
+
+      unless (options.keys & RECOGNISED_HEADER_KEYS).any?
+        raise ArgumentError, "No digest headers configured. Provide at least one of: #{RECOGNISED_HEADER_KEYS.join(", ")}"
+      end
+
+      unless options.key?(:on_partial_content)
+        raise ArgumentError, "on_partial_content is required (choose: :skip, :warn, or :raise)"
+      end
+
+      validate_on_partial_content!(options[:on_partial_content], context: "global")
+
+      if options.key?(:unencoded_digest)
+        config = options[:unencoded_digest]
+        unless config == true || config.is_a?(Hash)
+          raise ArgumentError, "unencoded_digest must be true or a Hash, got #{config.inspect}"
+        end
+      end
+
+      return unless options[:unencoded_digest].is_a?(Hash)
+
+      if options[:unencoded_digest].key?(:on_partial_content)
+        validate_on_partial_content!(options[:unencoded_digest][:on_partial_content], context: "unencoded_digest")
+      end
+
+      if options[:unencoded_digest][:algorithms] == []
+        raise ArgumentError, "algorithms cannot be empty"
+      end
+    end
+
+    def validate_on_partial_content!(value, context:)
+      return if VALID_ON_PARTIAL_CONTENT.include?(value)
+      raise ArgumentError, "Invalid on_partial_content #{value.inspect} for #{context} (choose: :skip, :warn, or :raise)"
+    end
+
+    def parse_unencoded_digest(config)
+      # Algorithms are snapshotted from the registry at middleware init time.
+      # Changes to DigestFields.algorithms after initialization are not reflected.
+      base_algorithms = ::DigestFields.algorithms.keys
+      return {algorithms: base_algorithms} if config == true || config.nil? || config == {}
+
+      {
+        algorithms: config[:algorithms] || base_algorithms,
+        on_partial_content: config[:on_partial_content]
+      }
+    end
+  end
+end

data/lib/digest_fields/version.rb

@@ -1,3 +1,3 @@
 module DigestFields
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/digest_fields.rb

@@ -1,12 +1,15 @@
 require "digest"
 
 module DigestFields
-  module_function
+  def self.algorithms
+    @algorithms ||= Algorithms.new
+  end
 
-  def digest(*, **)
-    Digestion.compute(*, **)
+  def self.digest(body, algorithms: self.algorithms.keys)
+    Digestion.compute(body, registry: self.algorithms, algorithms: algorithms)
   end
 end
 
 require_relative "digest_fields/version"
+require_relative "digest_fields/algorithms"
 require_relative "digest_fields/digestion"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: digest_fields
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pete Nicholls
@@ -49,7 +49,9 @@ files:
 - Rakefile
 - certs/aupajo.pem
 - lib/digest_fields.rb
+- lib/digest_fields/algorithms.rb
 - lib/digest_fields/digestion.rb
+- lib/digest_fields/rack.rb
 - lib/digest_fields/version.rb
 homepage: https://github.com/aupajo/digest_fields
 licenses: