Add rack.early_hints to SPEC

This is already de facto spec as both Unicorn and Puma
implement it. The changes to SPEC are compatible with
both implementations.

Fixes #1692
Fixes #1695

Co-authored-by: Jeremy Evans <code@jeremyevans.net>

CHANGELOG.md

@@ -17,6 +17,7 @@ All notable changes to this project will be documented in this file. For info on
 - Response header keys can no longer include uppercase characters.
 - Response body can now respond to #call instead of #each, for the equivalent of response hijacking in previous versions.
 - Middleware must no longer call #each on the body, but they can call #to_ary on the body if it responds to #to_ary.
+- rack.early_hints is now officially supported as an optional feature (already implemented by Unicorn, Puma, and Falcon).
 
 ### Removed
 

SPEC.rdoc

@@ -129,6 +129,7 @@ There are the following restrictions:
 * There must be a valid input stream in <tt>rack.input</tt>.
 * There must be a valid error stream in <tt>rack.errors</tt>.
 * There may be a valid hijack stream in <tt>rack.hijack_io</tt>
+* There may be a valid early hints callback in <tt>rack.early_hints</tt>
 * The <tt>REQUEST_METHOD</tt> must be a valid token.
 * The <tt>SCRIPT_NAME</tt>, if non-empty, must start with <tt>/</tt>
 * The <tt>PATH_INFO</tt>, if non-empty, must start with <tt>/</tt>
@@ -241,6 +242,15 @@ if the request env has <tt>rack.hijack?</tt> <tt>true</tt>.
 * Middleware should not wrap the IO object for the request pattern. The
   request pattern is intended to provide the hijacker with "raw tcp".
 
+=== Early Hints
+
+The application or any middleware may call the <tt>rack.early_hints</tt>
+with an object which would be valid as the headers of a Rack response.
+
+If <tt>rack.early_hints</tt> is present, it must respond to #call.
+If <tt>rack.early_hints</tt> is called, it must be called with
+valid Rack response headers.
+
 == The Response
 
 === The Status

lib/rack/constants.rb

@@ -39,6 +39,7 @@ module Rack
   # Rack environment variables
   RACK_VERSION                        = 'rack.version'
   RACK_TEMPFILES                      = 'rack.tempfiles'
+  RACK_EARLY_HINTS                    = 'rack.early_hints'
   RACK_ERRORS                         = 'rack.errors'
   RACK_LOGGER                         = 'rack.logger'
   RACK_INPUT                          = 'rack.input'

lib/rack/lint.rb

@@ -330,6 +330,8 @@ def check_environment(env)
         check_error env[RACK_ERRORS]
         ## * There may be a valid hijack stream in <tt>rack.hijack_io</tt>
         check_hijack env
+        ## * There may be a valid early hints callback in <tt>rack.early_hints</tt>
+        check_early_hints env
 
         ## * The <tt>REQUEST_METHOD</tt> must be a valid token.
         unless env[REQUEST_METHOD] =~ /\A[0-9A-Za-z!\#$%&'*+.^_`|~-]+\z/
@@ -628,8 +630,31 @@ def check_hijack_response(headers, env)
       ## * Middleware may wrap the IO object for the response pattern.
       ## * Middleware should not wrap the IO object for the request pattern. The
       ##   request pattern is intended to provide the hijacker with "raw tcp".
+
+      ##
+      ## === Early Hints
       ##
+      ## The application or any middleware may call the <tt>rack.early_hints</tt>
+      ## with an object which would be valid as the headers of a Rack response.
+      def check_early_hints(env)
+        if env[RACK_EARLY_HINTS]
+          ##
+          ## If <tt>rack.early_hints</tt> is present, it must respond to #call.
+          unless env[RACK_EARLY_HINTS].respond_to?(:call)
+            raise LintError, "rack.early_hints must respond to call"
+          end
 
+          original_callback = env[RACK_EARLY_HINTS]
+          env[RACK_EARLY_HINTS] = lambda do |headers|
+            ## If <tt>rack.early_hints</tt> is called, it must be called with
+            ## valid Rack response headers.
+            check_headers(headers)
+            original_callback.call(headers)
+          end
+        end
+      end
+
+      ##
       ## == The Response
       ##
       ## === The Status

test/spec_lint.rb

@@ -383,6 +383,58 @@ def obj.each; end
 
   end
 
+  it "notice rack.early_hints errors" do
+    def self.env(arg={})
+      super(arg.merge("rack.early_hints" => proc{}))
+    end
+    def self.app(value)
+      app = Rack::Lint.new(lambda { |env|
+                             env['rack.early_hints'].call(value)
+                             [200, {}, []]
+                           })
+      lambda { app.call(env) }
+    end
+
+    app(Object.new).must_raise(Rack::Lint::LintError).
+      message.must_equal "headers object should be a hash, but isn't (got Object as headers)"
+
+    app({}.freeze).must_raise(Rack::Lint::LintError).
+      message.must_equal "headers object should not be frozen, but is"
+
+    app(true => false).must_raise(Rack::Lint::LintError).
+      message.must_equal "header key must be a string, was TrueClass"
+
+    app("status" => "404").must_raise(Rack::Lint::LintError).
+      message.must_match(/must not contain status/)
+
+    invalid_headers = 0.upto(31).map(&:chr) + %W<( ) , / : ; < = > ? @ [ \\ ] { } \x7F>
+    invalid_headers.each do |invalid_header|
+      app(invalid_header => "text/plain").
+        must_raise(Rack::Lint::LintError, "on invalid header: #{invalid_header}").
+        message.must_equal("invalid header name: #{invalid_header}")
+    end
+
+    ('A'..'Z').each do |invalid_header|
+      app(invalid_header => "text/plain").
+        must_raise(Rack::Lint::LintError, "on invalid header: #{invalid_header}").
+        message.must_equal("uppercase character in header name: #{invalid_header}")
+    end
+
+    valid_headers = 0.upto(127).map(&:chr) - invalid_headers - ('A'..'Z').to_a
+    valid_headers.each do |valid_header|
+      app(valid_header => "text/plain").call.first.must_equal 200
+    end
+
+    app("foo" => Object.new).must_raise(Rack::Lint::LintError).
+      message.must_equal "a header value must be a String or Array of Strings, but the value of 'foo' is a Object"
+
+    app("foo-bar" => "text\000plain").must_raise(Rack::Lint::LintError).
+      message.must_match(/invalid header/)
+
+    app([%w(content-type text/plain), %w(content-length 0)]).must_raise(Rack::Lint::LintError).
+      message.must_equal "headers object should be a hash, but isn't (got Array as headers)"
+  end
+
   it "notice content-type errors" do
     # lambda {
     #   Rack::Lint.new(lambda { |env|