findxpand 0.1.0

data/lib/findxpand/middleware.rb

@@ -0,0 +1,597 @@
+# frozen_string_literal: true
+
+# The Rack middleware — Rails, Sinatra, Hanami, Roda, or a bare `->(env){}`.
+#
+#     use Findxpand::Middleware
+#
+# One deploy. After that, approved fixes arrive as a pushed manifest and no
+# further release is needed — which is the reason this exists rather than a JSON
+# file in the repository.
+#
+# **Prefer `findxpand/auto`. Do not mount this by hand.** `use` is exported and
+# correct, and it still asks somebody to place a middleware correctly in a stack
+# we cannot see. `auto.rb` removes the question by wrapping whatever
+# builder the server built the application with - its own vendored one
+# included, which is what Puma has - and by owning the encoding negotiation so
+# that being outermost is finally the right place to be. See `encoding.rb` for
+# the measurement that killed the old instruction, and `auto.rb` for why one
+# class name was not enough.
+#
+# **It never fails a request it does not understand.** Every branch either
+# handles the response or passes it through untouched, and the rewrite itself is
+# wrapped so that an exception serves the original bytes. Being able to 500 a
+# client's homepage in exchange for a meta description is not a trade anyone
+# agreed to. §3 rule 7 fails writes, credentials and budgets closed — it does not
+# ask us to stop a page rendering.
+#
+# ## Two things this does to the request, and only on a path with a rule
+#
+# 1. `Accept-Encoding` becomes `identity`, so nothing below us gzips a body we
+#    are about to rewrite. `encoding.rb` has the measurement.
+# 2. `If-None-Match` and `If-Modified-Since` are dropped, so nothing below us
+#    answers `304 Not Modified` for a page whose bytes we are changing. Without
+#    it a returning visitor — and a crawler with our page already in its cache —
+#    is served the *old* document from its own cache indefinitely, while
+#    `/status` counts the fix as applied for everybody else. That is a fix
+#    verified as deployed and not delivered, which §3 rule 4 says must never
+#    read as success. **This has no counterpart in the Node or Python packages
+#    and should be promoted into all three.**
+#
+# Every other path keeps its own headers exactly as they arrived, which is what
+# keeps the cost of turning this on at zero.
+#
+# ## Every visitor gets identical bytes
+#
+# There is no user-agent branch anywhere in this gem. Serving crawlers something
+# different is cloaking, and the whole point of a server-side rewrite is that it
+# needs no such trick (§12).
+#
+# Frozen string literals: on. Buffered chunks are joined, never appended to a
+# literal, and the header hash is duplicated before it is written to because a
+# Rack application is entitled to return a frozen one.
+
+require 'json'
+
+module Findxpand
+  class Middleware
+    # Set on every HTML response this middleware handled. Deliberately not the
+    # edge worker's `x-findxpand-edge`: a site can run both, and a verification
+    # that could not tell which layer served the value would report the wrong
+    # thing as deployed. Mirrors `engine.fix.origin.ORIGIN_HEADER`.
+    ORIGIN_HEADER = 'x-findxpand-origin-mw'
+    VERSION_HEADER = 'x-findxpand-rules'
+
+    DEFAULT_MAX_BYTES = 2 * 1024 * 1024
+
+    # Mirrors `engine.fix.origin.STATUS_CODES`. Nothing 2xx or 3xx: a move is a
+    # redirect, and forcing 200 would mean inventing a body.
+    ALLOWED_STATUS = [404, 410, 451].freeze
+    STATUS_BODY = { 404 => 'Not Found', 410 => 'Gone', 451 => 'Unavailable' }.freeze
+
+    # Marks the request as already ours, so a second instance in the same stack
+    # passes straight through.
+    #
+    # Ruby has three attach points and two of them can be live at once — the
+    # builder prepend wraps the app that `config.ru` builds, and the Railtie
+    # inserts at position 0 of the Rails stack *inside* that. Nesting is
+    # therefore the normal case rather than a misconfiguration, and two live
+    # instances would rewrite an already-rewritten page and gzip an
+    # already-gzipped one. Marked on the request rather than on the app object
+    # because the app object may be frozen, may be a lambda, and may be built
+    # lazily on the first request (Sinatra) — the env is the one thing every
+    # instance in a stack is guaranteed to share.
+    SEEN_KEY = 'findxpand.seen'
+
+    # Dropped from the request on a ruled path. See the header.
+    CONDITIONAL_ENV = %w[HTTP_IF_NONE_MATCH HTTP_IF_MODIFIED_SINCE].freeze
+
+    # The four statuses a manifest redirect may carry, matching
+    # `middleware/php/src/Store.php:391`. Anything else is served as a 301
+    # rather than passed through: a 418 with a `location` is not a redirect any
+    # client follows, and a manifest that reached us with one is a manifest we
+    # do not trust to have meant it.
+    REDIRECT_STATUS = [301, 302, 307, 308].freeze
+
+    attr_reader :store
+
+    # How many of these have been built in this process, ever.
+    #
+    # **The only evidence that the attach reached anything.** `Auto.install`
+    # returning true says a hook was placed; it does not say the hook ran, and
+    # until 2 Sep 2026 it did not run on Puma at all — Puma parses `config.ru`
+    # with its own vendored builder, and the prepend was on `Rack::Builder`
+    # alone (see `auto.rb`, which now attaches by shape as well as by name). A
+    # count kept here, in the object that is the whole point of attaching, is
+    # the one fact that cannot be true while the attach is a no-op. Read by
+    # `Findxpand.attach_report` for `/status` and by `Auto.attach_problem` for
+    # the sentence that names which half failed, so neither of them has to infer
+    # it from a hook it placed (§20.1 rule 3: report what was observed, not what
+    # was arranged).
+    @constructed = 0
+    @constructed_lock = Mutex.new
+
+    class << self
+      attr_reader :constructed
+    end
+
+    def self.count_construction
+      @constructed_lock.synchronize { @constructed += 1 }
+    end
+
+    # For the suite only.
+    def self.reset_constructed!
+      @constructed_lock.synchronize { @constructed = 0 }
+    end
+
+    # Options resolve **explicit keyword, then environment, then default** — on
+    # every construction path, which is the whole of this change.
+    #
+    # `use Findxpand::Middleware` with no arguments is advertised as a complete
+    # install and the Railtie's `insert_before 0, Findxpand::Middleware` gives
+    # Rails no way to pass one. Until 2 Sep 2026 only `token` fell back to the
+    # environment here; `cache_file`, `manifest_file`, `max_bytes`,
+    # `require_signature`, `recompress` and `enabled` did not, and
+    # `Findxpand.options_from_env` had exactly one caller in the whole gem
+    # (`auto.rb`). So every install that was not the `RUBYOPT` attach — which on
+    # Rails is *every* install, because the Railtie runs first — built a store
+    # with `cache_file: nil` while `FINDXPAND_CACHE_FILE` was set in the
+    # environment beside it. That store persisted nothing, adopted no sibling
+    # worker's push, and reported itself healthy; `Findxpand.store` has the full
+    # account of what that costs, and it is the worst outcome in the system
+    # because it silently destroys work the customer approved. The same hole
+    # swallowed `FINDXPAND_ENABLED=false` on those paths — the off switch the
+    # README promises, ignored by two of the three ways in.
+    #
+    # Matched to `middleware/php/src/Middleware.php:97-106`, the sibling package
+    # with the same three-ways-in problem, which resolves it in one line:
+    # `$options = array_merge( Auto::options(), $options )`, docblocked as
+    # "defaults come from the environment, so a container binding with no
+    # arguments behaves like the bootstrap". §20.1 rule 2 — one reading of the
+    # environment, and as many callers as the gem has entry points.
+    #
+    # **`nil` is the sentinel for "not given" on the three flags**, rather than
+    # `true`. An explicit `enabled: false` from a caller has to beat
+    # `FINDXPAND_ENABLED=1`, and a keyword defaulting to `true` cannot tell the
+    # two apart. `token: ''` is preserved as empty for the same reason (`'' ||
+    # x` is `''` in Ruby, since an empty String is truthy) — a caller can shut
+    # the admin endpoints without unsetting the environment.
+    #
+    # An empty token leaves those endpoints answering 401 to everybody, which is
+    # the safe direction: the alternative is an unauthenticated manifest
+    # endpoint on a customer's origin.
+    #
+    # `store:` and `rewriter:` are seams for the suite, not options. The rewriter
+    # exists because a `rescue` nothing can reach is a `rescue` nobody has tested
+    # — §20.1 rule 3 applied to our own error handling — and the only way to
+    # reach this one is to hand the middleware something that raises.
+    def initialize(app, token: nil, cache_file: nil, manifest_file: nil,
+                   enabled: nil, max_bytes: nil, require_signature: nil,
+                   recompress: nil, store: nil, rewriter: Rewrite, clock: nil)
+      settings = Findxpand.options_from_env
+      @app = app
+      @token = (token || settings[:token]).to_s
+      @enabled = enabled.nil? ? settings[:enabled] : enabled
+      # `options_from_env` omits `:max_bytes` when the variable is absent or
+      # unparseable, so the default lands here and a garbled `FINDXPAND_MAX_BYTES`
+      # cannot silently set the ceiling to zero and skip every page as too large.
+      @max_bytes = (max_bytes || settings[:max_bytes] || DEFAULT_MAX_BYTES).to_i
+      # The escape hatch exists for one case: an intermediary that rewrites or
+      # re-encodes request bodies, which invalidates any signature over them.
+      # Turn it off there and nowhere else — an unsigned push is authenticated
+      # by the bearer token alone, and a bearer token is replayable.
+      @require_signature = require_signature.nil? ? settings[:require_signature] : require_signature
+      # Ask the application for uncompressed HTML on the pages we rewrite, and
+      # compress them again on the way out. Off is for an intermediary that has
+      # already taken over the negotiation.
+      @recompress = recompress.nil? ? settings[:recompress] : recompress
+      @rewriter = rewriter
+      @store = store || Findxpand.store(cache_file: cache_file || settings[:cache_file],
+                                        manifest_file: manifest_file || settings[:manifest_file],
+                                        clock: clock)
+      @admin = Admin.new(store: @store, token: @token, max_bytes: @max_bytes,
+                         require_signature: @require_signature, clock: clock)
+      # Counted last, so a constructor that raised is not counted as an attach
+      # that worked.
+      self.class.count_construction
+    end
+
+    def call(env)
+      path = env['PATH_INFO'].to_s
+      path = '/' if path.empty?
+
+      # A second instance of this gem is already in the stack and has already
+      # decided what happens to this response. Leaving now is what makes the
+      # Railtie and the builder prepend safe to have on at the same time.
+      return @app.call(env) if env[SEEN_KEY]
+
+      env[SEEN_KEY] = true
+
+      # Has a sibling worker been pushed a manifest this process has not seen?
+      # Throttled to once a second inside the store; on a server that does not
+      # fork and on one with no cache file it does nothing at all. Asked before
+      # the admin branch as well, so a monitor polling `/status` on worker three
+      # is told what worker one was pushed.
+      @store.reload_if_stale
+
+      return @admin.call(env, path) if Admin.admin_path?(path)
+
+      # Counted before any decision about this request, and never for the admin
+      # surface. See `Store#saw_request`: a probe that answers its own question
+      # is an auditor that cannot fail.
+      @store.saw_request
+
+      return @app.call(env) unless @enabled
+
+      redirect = @store.redirect_for(path)
+      return serve_redirect(redirect) if redirect
+
+      manifest = @store.get
+      return serve_robots(manifest) if path == '/robots.txt' && present?(manifest['robots_txt'])
+
+      rule = @store.rule_for(path)
+      if rule.nil?
+        # Counted here and nowhere else: this is the "the manifest does not name
+        # this path" branch, and it is the third value that makes `considered:
+        # 0` readable. A manifest whose keys match nothing produces exactly the
+        # same counters as a middleware nobody has sent a request to yet, which
+        # is how the `normalise_path` disagreement stayed invisible for a
+        # fortnight while `/status` reported healthy. Ported from
+        # `middleware/node/src/index.ts:238-256` and `manifest.ts:274-284`,
+        # counter and semantics unchanged, because an operator alerting on
+        # `counters.unmatched > 0 && counters.considered == 0` — the condition
+        # the engine's own `degraded_reason` docstring names as the honest
+        # detector — was evaluating `nil > 0` against a Ruby origin.
+        #
+        # A request, not a response, and that is the honest reading: we leave
+        # before the application is called, so nothing here knows whether the
+        # response would have been HTML. Images, CSS and favicons are counted
+        # alongside pages, exactly as they are in Node.
+        @store.miss
+        return @app.call(env)
+      end
+
+      # A status rule answers before the application is reached. That is the
+      # point: the page still exists and still renders, and answering 200 is
+      # exactly the defect being corrected.
+      code = rule['status_code']
+      return serve_status(code) if code.is_a?(Integer) && ALLOWED_STATUS.include?(code)
+
+      # From here the response is ours to rewrite, so it is ours to encode — and
+      # ours to make sure the application actually produces. Only on this branch:
+      # every path above either never reaches the application or is not a page we
+      # touch, and those keep the application's own compression and conditional
+      # handling exactly as they were.
+      coding = ''
+      if @recompress
+        coding = Encoding.negotiate(env['HTTP_ACCEPT_ENCODING'])
+        env['HTTP_ACCEPT_ENCODING'] = 'identity' unless coding.empty?
+      end
+      CONDITIONAL_ENV.each { |key| env.delete(key) }
+
+      rewrite(env, rule, coding)
+    end
+
+    private
+
+    def present?(value)
+      value.is_a?(String) && !value.empty?
+    end
+
+    # `redirect['to']` is a non-empty String or this method is never reached:
+    # `Store#redirect_for` skips an entry that does not carry one, matching
+    # `middleware/php/src/Store.php:333-356`. Written without a `.to_s` on
+    # purpose, so the guarantee is visible here rather than papered over — a
+    # `.to_s` was what turned `{"from":"/old-beans","to":null}` into a live 301
+    # to nowhere, serving a dead page where the application would have rendered
+    # a working one and counting it as a healthy `redirect`. §3 rule 7's closed
+    # direction for a malformed manifest is "serve the page unchanged"; it is
+    # not "emit a redirect to an empty location". Python raises on
+    # `str(redirect["to"])` and Node throws `ERR_HTTP_INVALID_HEADER_VALUE`, so
+    # both of them failed loudly where this failed silently — the one direction
+    # this package is not allowed to differ in.
+    def serve_redirect(redirect)
+      status = redirect['status']
+      status = 301 unless REDIRECT_STATUS.include?(status)
+      @store.record('redirect')
+      [status,
+       { 'location' => redirect['to'],
+         'content-length' => '0',
+         ORIGIN_HEADER => 'redirect' },
+       []]
+    end
+
+    def serve_robots(manifest)
+      sitemap = manifest['sitemap']
+      text = manifest['robots_txt'].to_s
+      text += "\nSitemap: #{sitemap}\n" if present?(sitemap)
+      @store.record('1')
+      [200,
+       { 'content-type' => 'text/plain; charset=utf-8',
+         'content-length' => text.bytesize.to_s,
+         ORIGIN_HEADER => '1',
+         VERSION_HEADER => manifest['version'].to_s },
+       [text]]
+    end
+
+    def serve_status(code)
+      body = STATUS_BODY.fetch(code)
+      @store.record('status')
+      [code,
+       { 'content-type' => 'text/plain; charset=utf-8',
+         'content-length' => body.bytesize.to_s,
+         ORIGIN_HEADER => 'status',
+         VERSION_HEADER => @store.get['version'].to_s },
+       [body]]
+    end
+
+    def rewrite(env, rule, coding)
+      status, headers, body = @app.call(env)
+      # A Rack application may return a frozen header hash, and Rack 3 says the
+      # caller owns what it is given. Duplicated once, here, so no branch below
+      # has to remember.
+      headers = headers.nil? ? {} : headers.dup
+
+      # A 404's title is not ours to correct, and a 500 is not a page to decorate
+      # while somebody is trying to debug it.
+      return passthrough(status, headers, body, '', coding) unless status.to_i == 200
+      return passthrough(status, headers, body, '', coding) unless html?(headers)
+
+      # Something already compressed this despite our asking for identity.
+      # Rewriting encoded bytes produces a broken page.
+      if present?(header(headers, 'content-encoding'))
+        return passthrough(status, headers, body, 'skip-encoded', coding)
+      end
+
+      declared = header(headers, 'content-length').to_s
+      if !declared.empty? && declared.to_i > @max_bytes
+        return passthrough(status, headers, body, 'skip-large', coding)
+      end
+
+      # A Rack 3 streaming body — one that responds to `call` and not to `each` —
+      # cannot be buffered without changing what streaming means, so it is served
+      # exactly as it arrived. Marked `skip-large` rather than given a marker of
+      # its own: the two mean the same thing to a reader ("we declined to hold
+      # this response"), and a Ruby-only counter key would put a field in
+      # `/status` that the engine's parser and the other two packages have never
+      # seen.
+      unless body.respond_to?(:each)
+        return passthrough(status, headers, body, 'skip-large', coding)
+      end
+
+      chunks, rest, size = buffer(body)
+      if !rest.nil? || size > @max_bytes
+        # Too large to hold. Served whole rather than truncated: what was already
+        # pulled off the body is yielded first and the remainder streams on. The
+        # size is re-checked here as well as inside `buffer` because a body that
+        # answered `to_ary` was whole before we ever looked at it, so nothing in
+        # the loop ever ran — and most Ruby applications return exactly that.
+        return passthrough(status, headers, Remainder.new(chunks, rest, body), 'skip-large', coding)
+      end
+
+      # Joined as bytes. `['<html>'.b, 'مرحبا'].join` raises
+      # `Encoding::CompatibilityError` on a body whose chunks came from different
+      # places — a template fragment read off a socket beside one built in
+      # memory — and a raise here is a 500 on the customer's homepage rather than
+      # a page we declined to rewrite. Bytes have no compatibility question.
+      original = chunks.map { |chunk| chunk.to_s.b }.join
+      text = original.dup.force_encoding('UTF-8')
+      # A page we cannot decode is a page we do not touch. Node cannot reach this
+      # branch — `Buffer.toString('utf8')` substitutes replacement characters
+      # rather than reporting — which is why its counter table has eight keys and
+      # ours has nine.
+      unless text.valid_encoding?
+        held = Remainder.new(chunks, nil, body)
+        return passthrough(status, headers, held, 'skip-encoding', coding)
+      end
+
+      begin
+        out = @rewriter.transform(text, rule)
+      rescue StandardError
+        # A rewrite that raises serves the original bytes. This is the whole
+        # safety argument for buffering: the client's page is never lost to a bug
+        # of ours. Marked `error` rather than left to read as `pass` — those are
+        # the same bytes and opposite problems, and reporting a crashing rewrite
+        # as a clean no-op is exactly the invisible failure the counters exist to
+        # end.
+        return passthrough(status, headers, Remainder.new(chunks, nil, body), 'error', coding)
+      end
+
+      finish(status, headers, body, original, out, coding)
+    end
+
+    # Send what the rewrite produced.
+    #
+    # `marker` is decided from the text, before anything is compressed, so
+    # `x-findxpand-origin-mw` describes what we did to the *page* rather than
+    # what we did to the bytes.
+    def finish(status, headers, body, original, out, coding)
+      # Both sides binary before they are compared. `String#==` is false for two
+      # strings that hold the same bytes under different encodings once either
+      # leaves ASCII, so comparing the UTF-8 rewrite against the binary original
+      # would answer "changed" for every Arabic page we did not change — a `1`
+      # marker, an `applied` counter and an `applied_age` on a rewrite that did
+      # nothing (§14 again).
+      bytes = out.to_s.b
+      marker = bytes == original ? 'pass' : '1'
+
+      delete_header(headers, 'content-length')
+      # Nothing downstream is chunking a body we have already buffered whole.
+      delete_header(headers, 'transfer-encoding')
+      if marker == '1'
+        # The application computed this over the document it produced, and the
+        # document that leaves here is a different one. A stale validator is not
+        # a cosmetic problem: a cache or a browser holding the old page would go
+        # on being told it is current, so the fix would be live for new visitors
+        # and invisible to returning ones. Dropped rather than recomputed —
+        # revalidating costs a request, serving the wrong page costs the fix.
+        delete_header(headers, 'etag')
+      end
+
+      unless coding.empty?
+        add_vary(headers)
+        unless Encoding.no_transform?(header(headers, 'cache-control'))
+          packed = Encoding.encode(bytes, coding)
+          unless packed.nil?
+            bytes = packed
+            headers['content-encoding'] = coding
+          end
+        end
+      end
+
+      # **`bytesize`, never `length`.** `length` counts characters, so on the
+      # Arabic pages this product exists to fix (§14) a content-length taken from
+      # it is roughly half the bytes actually sent, and the client is served a
+      # truncated document — valid-looking HTML that simply stops. The rewrite
+      # layer counts in characters throughout and the HTTP layer counts in bytes
+      # throughout; this line is the boundary between the two.
+      headers['content-length'] = bytes.bytesize.to_s
+      headers[ORIGIN_HEADER] = marker
+      headers[VERSION_HEADER] = @store.get['version'].to_s
+      @store.record(marker)
+      close(body)
+      [status, headers, [bytes]]
+    end
+
+    def passthrough(status, headers, body, marker, coding)
+      unless marker.empty?
+        headers[ORIGIN_HEADER] = marker
+        @store.record(marker)
+      end
+      # We asked for identity on this request, so the response varies by what the
+      # client sent even though we did not compress it.
+      add_vary(headers) unless coding.empty?
+      [status, headers, body]
+    end
+
+    # `[chunks, remainder_or_nil, size]`.
+    #
+    # A body that answers `to_ary` is already whole in memory, so there is
+    # nothing to stream and no `Enumerator` to build. Everything else is pulled
+    # one chunk at a time through `to_enum(:each)`, which is the only construct
+    # in Ruby with the pull semantics this needs: `each` is a push, so a
+    # middleware that discovers halfway through that a body is too large has no
+    # way to hand the rest back unless it is holding an enumerator over it.
+    #
+    # The ceiling is checked inside the loop *and* against `content-length`
+    # before we get here, because most Ruby applications return their whole page
+    # as one chunk and would never reach the second iteration.
+    #
+    # ## What this costs, stated rather than fixed
+    #
+    # `to_enum(:each)` plus `next` is external iteration, and Ruby implements it
+    # with a **Fiber**. If the `Remainder` we hand back is never drained — a
+    # client that disconnects after the first chunk of a 3 MB export — that Fiber
+    # stays suspended for good, and a Fiber that is garbage collected without
+    # being resumed to completion does **not** run the `ensure` blocks inside the
+    # `each` it was in the middle of. Python's equivalent (`wsgi.py`'s `_chain`)
+    # has no such hazard: it is a plain generator over an already-`iter()`ed
+    # iterable.
+    #
+    # It is left as it is, and three things bound it:
+    #
+    # 1. `close` **is** forwarded (`Remainder#close`), and Rack's own contract is
+    #    that a body releases what it holds in `close` — the server is required
+    #    to call it and is not required to finish iterating. A body that does its
+    #    cleanup only in an `ensure` inside `each` is already outside that
+    #    contract; on Rails the executor and the database connection go back
+    #    through `Rack::BodyProxy#close`, which we do call.
+    # 2. Nothing gets here unless the response declared no `content-length` **and**
+    #    exceeded the ceiling, which is the chunked-and-large case alone.
+    # 3. Every alternative is worse. Draining the remainder inside `close` would
+    #    run those `ensure` blocks — and would hang for ever on an endless body
+    #    (`ActionController::Live`, Server-Sent Events), which is a hung worker
+    #    rather than an unreleased object. Buffering past the ceiling is the
+    #    ceiling deleted. Not handing the rest back at all truncates the
+    #    customer's page, which is the one thing this whole path exists to
+    #    prevent.
+    #
+    # **Unverified: no Ruby on the machine this was written on.** The Fiber
+    # semantics above are from the language documentation, not from a run.
+    def buffer(body)
+      if body.respond_to?(:to_ary)
+        # Asked once. `to_ary` is a conversion, not a reader, and a body entitled
+        # to build its array on demand would build two.
+        whole = body.to_ary
+        return [whole, nil, whole.sum { |chunk| chunk.to_s.bytesize }]
+      end
+
+      chunks = []
+      size = 0
+      enum = body.to_enum(:each)
+      loop do
+        chunk = enum.next.to_s
+        chunks << chunk
+        size += chunk.bytesize
+        return [chunks, enum, size] if size > @max_bytes
+      end
+      [chunks, nil, size]
+    end
+
+    # What was buffered, then whatever is left, then close what we borrowed.
+    #
+    # Rack calls `close` on the body it is given and never on the one we took it
+    # from, so the original's `close` has to be forwarded — on Rails that is
+    # where the executor hands back the database connection.
+    class Remainder
+      def initialize(chunks, rest, original)
+        @chunks = chunks
+        @rest = rest
+        @original = original
+      end
+
+      def each
+        @chunks.each { |chunk| yield chunk }
+        return if @rest.nil?
+
+        loop { yield @rest.next }
+      end
+
+      def close
+        @original.close if @original.respond_to?(:close)
+      end
+    end
+
+    def close(body)
+      body.close if body.respond_to?(:close)
+    end
+
+    def html?(headers)
+      header(headers, 'content-type').to_s.include?('text/html')
+    end
+
+    # Read a header without caring how the application spelled it.
+    #
+    # Rack 3 requires lower case, Rack 2 conventionally uses `Content-Type`, and
+    # a Rack 2 app may hand back a `Rack::Utils::HeaderHash`, which is already
+    # case-insensitive. A plain `headers['content-type']` is correct under
+    # exactly one of those three and silently wrong under the others: it reads an
+    # empty content type, decides the response is not HTML, and every page on
+    # that app is served untouched, uncounted and unmarked — health with the
+    # lights off, which is the failure the Node package shipped for `writeHead`.
+    def header(headers, name)
+      value = headers[name]
+      if value.nil?
+        key = headers.keys.find { |candidate| candidate.to_s.downcase == name }
+        value = key.nil? ? nil : headers[key]
+      end
+      # Some Rack 2 servers accept an Array of values for a repeated header.
+      value.is_a?(Array) ? value.join(', ') : value
+    end
+
+    def delete_header(headers, name)
+      headers.delete(name)
+      key = headers.keys.find { |candidate| candidate.to_s.downcase == name }
+      headers.delete(key) unless key.nil?
+    end
+
+    # `Vary: Accept-Encoding`, spliced in under whatever casing is already there.
+    def add_vary(headers)
+      existing = header(headers, 'vary')
+      wanted = Encoding.vary_value(existing)
+      return if wanted.empty?
+
+      key = headers.keys.find { |candidate| candidate.to_s.downcase == 'vary' } || 'vary'
+      headers[key] = wanted
+    end
+  end
+end

data/lib/findxpand/railtie.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Rails, at position 0 of its own middleware stack.
+#
+# Loaded by `lib/findxpand.rb` when Rails is already defined, which is what a
+# Gemfile entry produces: Bundler requires the gems in Gemfile order, so `gem
+# 'findxpand'` after `gem 'rails'` lands here. Under `RUBYOPT="-rfindxpand/auto"`
+# it does *not* — that runs before Rails exists — and it does not need to, since
+# `auto.rb` attaches one layer further out.
+#
+# ## Why position 0 is enough on Rails
+#
+# `insert_before 0` is the outermost entry of the Rails stack: the stack is folded
+# from the end, so index 0 wraps everything after it, including a
+# `config.middleware.use Rack::Deflater`. What it does *not* wrap is anything
+# `config.ru` itself `use`d, which sits outside `Rails.application` — and that
+# turns out not to matter, because a `Rack::Deflater` out there sees the
+# `Accept-Encoding: identity` this middleware wrote into the env on its way down,
+# and declines a response that already carries a `content-encoding`. Either way
+# it stands aside, and the page it is handed is the corrected one.
+#
+# So a Rails application needs nothing but the Gemfile line. `RUBYOPT` is still
+# the recommended install because it is the same instruction for every framework
+# and because it survives a `config.ru` that does something unusual.
+#
+# ## Not a place to be clever
+#
+# This file patches no builder class. Adding a gem to a Gemfile should insert a
+# middleware — every Rails developer expects that — and should not monkey-patch
+# Rack behind their back; that is what asking for `findxpand/auto` by name
+# means. The one exception is re-arming a hook that
+# `auto.rb` already installed, which is a no-op unless `RUBYOPT` ran and Rack was
+# somehow not loadable at the time.
+#
+# Frozen string literals: on.
+
+# A top-level `return` in a required file, so that `require
+# 'findxpand/railtie'` by hand outside Rails is inert rather than a NameError.
+return unless defined?(::Rails::Railtie)
+
+require 'findxpand'
+
+module Findxpand
+  class Railtie < ::Rails::Railtie
+    initializer 'findxpand.middleware', before: :build_middleware_stack do |app|
+      # Only if `findxpand/auto` was loaded. Late, but not too late: Rails
+      # initializers run while `config.ru` is being read and before the builder
+      # calls `to_app`. Re-armed here because Rack is certainly loaded by now
+      # even if it was not when `RUBYOPT` ran; the shape watcher in `auto.rb`
+      # covers the builder a server defines for itself, which this cannot reach.
+      Findxpand::Auto.attach_builders if defined?(Findxpand::Auto)
+
+      if ENV['FINDXPAND_TOKEN'].to_s.empty?
+        # Silent rather than noisy. A Rails process boots this file in
+        # `rails console`, `rails runner`, `rake` and every CI job, and a gem
+        # that writes to stderr in all of them is a gem somebody removes.
+        # `auto.rb` warns instead, because a `RUBYOPT` was a deliberate act.
+        next
+      end
+      next unless Findxpand.flag('FINDXPAND_ENABLED', true)
+
+      begin
+        app.middleware.insert_before 0, Findxpand::Middleware
+      rescue StandardError
+        # `insert_before 0` is the documented spelling and `unshift` is the one
+        # older stacks answer to. Both mean outermost; neither is worth failing
+        # a boot over.
+        app.middleware.unshift Findxpand::Middleware
+      end
+    end
+  end
+end