findxpand 0.1.0

data/lib/findxpand/auto.rb

@@ -0,0 +1,607 @@
+# frozen_string_literal: true
+
+# Attaching without editing the application.
+#
+#     RUBYOPT="-rfindxpand/auto" bundle exec puma
+#     RUBYOPT="-rfindxpand/auto" bundle exec rails server
+#     RUBYOPT="-rfindxpand/auto" bundle exec unicorn
+#
+# Ruby's `-r` is Node's `--require` and Python's `sitecustomize`: it runs before
+# the application's first line, which is the only place from which a middleware
+# can guarantee its own position.
+#
+# ## Why this exists, rather than one more line in the install guide
+#
+# `use Findxpand::Middleware` asks a customer to place a middleware correctly in
+# a stack we cannot see, and the instruction we shipped for doing it was **wrong
+# in every language it was written for**. Measured 31 Aug 2026:
+#
+#     Express + compression, findxpand first   marker `skip-encoded`, page
+#                                              unmodified, `/status` healthy
+#     Express + compression, findxpand last    2069 bytes of plain HTML on the
+#                                              wire under `content-encoding: gzip`
+#     Django 6.1 + GZipMiddleware, outermost    marker `skip-encoded`, original
+#                                              title served, `/status` healthy
+#
+# Rack has the same shape as the Django case and the same only-one-position:
+# `use Rack::Deflater` inside us hands us gzip, and there is nowhere else to
+# stand. This was never a step people were getting wrong — it is a step with no
+# right answer, which is why the answer is to delete the step. `encoding.rb`
+# takes over the negotiation so that outermost is finally the correct place, and
+# this file makes outermost happen without anybody typing anything.
+#
+# ## The hook: every builder, not one class
+#
+# **A Rack builder, prepended — whichever class the server actually uses.**
+#
+# What used to be written here was: "`Rack::Builder#to_app`, prepended. Every
+# Ruby web server that serves a Rack application builds it through that one
+# method." **That is false, and it was false on the server named in our own
+# headline install command.** Puma does not parse `config.ru` with
+# `Rack::Builder`. It carries a vendored copy — `Puma::Rack::Builder`, in
+# `puma/lib/puma/rack/builder.rb`, reached from `Puma::Configuration#load_rackup`
+# — whose `new_from_string` evaluates `Puma::Rack::Builder.new {...}.to_app`.
+# A prepend on `::Rack::Builder` is not on that class and never runs, so
+# `RUBYOPT="-rfindxpand/auto" bundle exec puma` placed a hook, warned about
+# nothing, and attached nothing. `/__findxpand/status` then 404s and the engine
+# reports `installed: false` for a package that is installed and did run: the
+# attach that silently does not attach, §20.1 rule 3, in the one place it costs
+# the most.
+#
+# **MEASURED 2 Sep 2026 on Ruby 3.4.10, Puma 8.0.2, rack 3.2.7 — and the claim
+# above is half right, in a way that matters.** Puma 8 does ship the vendored
+# copy: `puma/rack/builder.rb` is in the gem and `require "puma/rack/builder"`
+# defines `Puma::Rack::Builder`. But it is NOT loaded when the `rack` gem is
+# available, and with rack present Puma parses `config.ru` with the real
+# `::Rack::Builder`. Booting a bare non-Rails `config.ru` under
+# `RUBYOPT="-rfindxpand/auto" puma -b tcp://127.0.0.1:8782` gave
+# `attach_state: "attached", builders: ["Rack::Builder"], built: 1,
+# watching: false` — the by-name prepend caught it and the watcher never fired.
+# An approved title then landed in the served HTML and `origin-confirm` reported
+# `deployed: true`.
+#
+# So the vendored builder is Puma's rack-less FALLBACK rather than its normal
+# path, and the original finding overstated it. The watcher is still the thing
+# that covers that fallback, because the fallback is required lazily — after
+# `findxpand/auto` has already run, which is precisely the case a prepend by
+# name cannot reach. That half is measured too: loading the real
+# `Puma::Rack::Builder` after us and building an app through it returns a
+# `Findxpand::Middleware`, so the TracePoint catches Puma's own class by shape.
+#
+# Both mechanisms are therefore exercised, and neither is redundant:
+#
+# 1. **By name, for what is already loaded** (`BUILDER_CLASSES`). Cheap, exact,
+#    and enough for `rackup`, Unicorn, Thin and anything that reaches
+#    `Rack::Builder` before we run.
+# 2. **By shape, for what is defined afterwards** (`watch_for_builders`). A
+#    class that defines `to_app`, `use` and `run` *is* a Rack builder whatever it
+#    is called and whoever vendored it. This catches Puma without our being right
+#    about `Puma::Rack::Builder`, and it catches the next server that vendors
+#    one.
+#
+# `super` first in every case, so the application is built exactly as it would
+# have been and every `use` in the file is already inside what we are handed.
+#
+# ## Why a TracePoint now, when this file used to refuse one
+#
+# The rejected version was a `TracePoint` **waiting for `Rack::Builder` to be
+# defined**, so that Rack need not be loadable at the moment this file runs. That
+# is still refused, and for the reason written here before: `bundle exec`
+# prepends `-rbundler/setup` to `RUBYOPT`, so the load path is already the
+# Gemfile's by the time we run, and a Rack application's Gemfile contains Rack.
+# It bought a case that does not occur.
+#
+# The case this one buys **always** occurs: the server defines its own builder
+# *after* us, because the server is what `RUBYOPT` runs before. No amount of
+# looking at the moment we load can see a class that does not exist yet, and
+# requiring `puma/rack/builder` ourselves would mean loading a server's internals
+# out of order on the strength of a filename we cannot check from here.
+#
+# What it costs, and this is reasoning rather than a measurement — nothing in
+# this file has been executed: one Ruby-level callback per class or module body
+# that *closes* (`:end`), which is thousands during a Rails boot and rare
+# afterwards, doing an `is_a?` and up to three `method_defined?` calls. It is
+# disarmed the moment an application is built through us, which is the moment it
+# has nothing left to catch. If `TracePoint` cannot be enabled at all — another
+# Ruby, a sandbox — that is **said on stderr** rather than discovered by a
+# customer whose pages never changed.
+#
+# Three alternatives were considered and are not used alone:
+#
+# * **A Railtie inserting at position 0.** It is shipped (`railtie.rb`) and it is
+#   not sufficient: index 0 of the Rails stack is still *inside* whatever
+#   `config.ru` wrapped around `Rails.application`, and it reaches no Sinatra,
+#   Hanami or plain Rack application at all. It is the belt to this file's
+#   braces, and it matters in one real case — a Rails process where `RUBYOPT`
+#   never arrived but the Gemfile did.
+# * **Patching the server.** Puma, Unicorn, Passenger, Falcon and WEBrick share
+#   no request path, no configuration object and no naming convention; a hook per
+#   server is five hooks to maintain and five ways to silently miss. Node could
+#   do it in one place because every one of its servers emits `request` on an
+#   `http.Server`. Ruby has no such single seam below Rack — but every one of
+#   them does build through *a* builder, which is what the shape test uses.
+# * **Requiring the server's own builder file ourselves.** One line, and it
+#   depends on a path inside somebody else's gem being what we think it is, at
+#   the version they pinned, loadable in whatever order we ask for it. The shape
+#   test needs to be right about nothing.
+#
+# ## What it reaches, and what it does not
+#
+# Reached, through a builder's `to_app`:
+#
+# * anything booted from a `config.ru` — `rackup`, `puma`, `unicorn`, `thin`,
+#   `falcon`, Passenger, WEBrick;
+# * **Rails**, because `rails server` and every one of those servers loads
+#   `config.ru`, and the wrap therefore sits outside the Rails stack *and*
+#   outside anything `config.ru` itself `use`d;
+# * **Sinatra**, classic and modular, including `ruby app.rb` with no
+#   `config.ru`, because `Sinatra::Base.new` builds through `Rack::Builder`.
+#   Note what that does *not* mean: Sinatra builds through a builder of its own
+#   making, so we are outside everything `config.ru` used **and inside
+#   Sinatra's own `use` lines**. The claim that this is "strictly further out
+#   than any `use` line" holds for `config.ru` and does not hold for
+#   `Sinatra::Base.use`;
+# * **Hanami**, **Roda**, **Grape**, `Rack::URLMap`, and a bare lambda.
+#
+# Reached, through the Railtie, and only when the gem is in the Gemfile so that
+# it is required after Rails: the Rails middleware stack at position 0.
+#
+# **Not reached, and there is no point pretending otherwise:**
+#
+# * a server handed an app object in code rather than through a builder —
+#   `Puma::Server.new(MyApp).run`, `Rackup::Handler::WEBrick.run(MyApp)`;
+# * a builder that does not answer to `to_app`, `use` and `run` together. That
+#   is the whole of what the shape test recognises, and a server that invents a
+#   different DSL is a server we do not see. `attach_state` and `built` say so
+#   (see below) rather than leaving it to be guessed;
+# * anything that is not a Rack application: a bare `WEBrick::HTTPServer` with a
+#   servlet, `Async::HTTP::Server` used directly, gRPC, ActionCable's own socket
+#   path;
+# * a process that never receives `RUBYOPT` — a `bin/rails` wrapper that
+#   re-execs, a systemd unit with a scrubbed `Environment=`, a Dockerfile that
+#   sets `ENV` in a build stage the runtime stage does not inherit. On Rails the
+#   Railtie still catches this; on Sinatra and Hanami nothing does;
+# * **JRuby and TruffleRuby**, in the sense that the mechanism is ordinary Ruby
+#   and ought to work and has not been run there. If `TracePoint` is missing or
+#   refuses to enable, only the by-name half runs and stderr says so;
+# * **the other workers.** After `fork` — Puma in cluster mode, Unicorn, Passenger
+#   — each worker holds its own copy of the manifest, and a push arrives at
+#   exactly one of them. `Store#reload_if_stale` closes that by re-reading the
+#   cache file when it changes, which is why `FINDXPAND_CACHE_FILE` is not
+#   optional on a forking server.
+#
+# ## How you can tell, without trusting any of the above
+#
+# An attach that silently does not attach is the worst outcome of all (§20.1
+# rule 3), so nothing here reports on the strength of a hook it *placed*. Every
+# field is something this process *observed*:
+#
+#     attach_state   pending / no-token / disabled / no-builder / watching /
+#                    attached / failed  — modelled on
+#                    `middleware/php/src/Auto.php:135-155`, which made the same
+#                    change for the same reason: "`attached()` alone is a boolean
+#                    with four causes behind it"
+#     builders       the classes actually prepended, by name
+#     built          how many applications were built through one of them
+#     middlewares    how many `Findxpand::Middleware` objects exist
+#     attach_problem the sentence, when `built` or `middlewares` is zero
+#
+# They are reported by `GET /__findxpand/status` (`Findxpand.attach_report`,
+# merged in by `Admin`). `built: 0` there is the exact signature of the Puma
+# defect above: the Railtie mounted us, so the endpoint answers, and the
+# `RUBYOPT` hook never fired.
+#
+# **The one case this cannot report is the total one**, and it is named rather
+# than papered over: if nothing of ours was ever constructed there is no
+# middleware in the path to answer `/status` at all. Stderr is then the only
+# channel, and it carries every cause that can be observed at boot — no token,
+# no builder, a `TracePoint` that would not enable. What remains unobservable is
+# a process that boots cleanly and simply never builds an application through
+# anything we recognise; nothing in-process can distinguish that from a server
+# that has not finished booting, and inventing a timer that guessed would be a
+# monitor that cries wolf on every Puma master and every `rake` task.
+#
+# ## Failure direction
+#
+# Every path here degrades to *not attached*, never to *broken*. A missing token,
+# a Rack that cannot be loaded, a wrap that raises: the message goes to stderr
+# and the application runs exactly as it would have. This code executes before
+# the first line of somebody's site, and §3 rule 7's fail-closed rule is about
+# writes, credentials and budgets — not about refusing to let a homepage render.
+#
+# The one failure it cannot soften is a `LoadError` on `-rfindxpand/auto`
+# itself: Ruby exits before this file runs. That is why the README's first step
+# is the Gemfile and the second is the `RUBYOPT`.
+#
+# Frozen string literals: on.
+
+require 'findxpand'
+
+module Findxpand
+  module Auto
+    # The builder classes we prepend on sight, by name, without requiring any of
+    # them.
+    #
+    # Names rather than constants: this file loads before the application's first
+    # line, and `Puma::Rack::Builder` is a `NameError` at that point on every
+    # stack including Puma's own. Resolved one segment at a time through
+    # `const_defined?` so that a missing namespace is a `nil` rather than an
+    # exception, and so that nothing here can force a `require` of a gem the
+    # customer did not ask for.
+    #
+    # This list is a fast path and not the mechanism. Anything defined after us —
+    # which is every server's own copy, since the server loads after `RUBYOPT` —
+    # is caught by shape in `watch_for_builders`, so a name missing from here
+    # costs nothing but the microsecond the watcher takes to recognise it. A name
+    # in here that no gem defines costs nothing either: `resolve` answers `nil`
+    # and the row never appears in `builders`. `Rackup::Builder` is in the list on
+    # that basis — Rack 3 moved `Rack::Server` and `Rack::Handler` into the
+    # `rackup` gem, and whether `Builder` went with them could not be checked from
+    # this machine.
+    BUILDER_CLASSES = %w[
+      Rack::Builder
+      Rackup::Builder
+      Puma::Rack::Builder
+    ].freeze
+
+    # The three methods that make a class a Rack builder.
+    #
+    # `to_app` alone is not enough — `Rails::Application` and several test
+    # harnesses answer to it — and prepending to something that is not a builder
+    # would put our `super` call in front of a method that means something else.
+    # All three together are the `config.ru` DSL and nothing else has them.
+    BUILDER_METHODS = %i[to_app use run].freeze
+
+    # Guards against a second `-r`, a re-require under a different path, or a
+    # `require 'findxpand/auto'` in an initialiser on top of the `RUBYOPT`. Two
+    # prepends of the same module are harmless — Ruby ignores the second — but
+    # the warning would be printed twice and the answer to `installed?` would
+    # stop meaning anything.
+    @installed = false
+    # name => true, for every class we actually prepended. The keys are the
+    # report; the Hash is the idempotence check.
+    @attached = {}
+    # Applications built through a hook we placed. **The only evidence the hook
+    # ran**, as distinct from `@installed`, which says only that it was placed.
+    @built = 0
+    @built_lock = Mutex.new
+    @watch = nil
+    @watch_error = nil
+
+    # Why nothing is attached in this process, or `attached`.
+    #
+    # `pending`     `install` has not run — the file was required and nothing else
+    # `no-token`    FINDXPAND_TOKEN was empty, so we declined to attach
+    # `disabled`    FINDXPAND_ENABLED was off. Somebody meant this
+    # `no-builder`  no builder was loaded and none can be watched for
+    # `watching`    hooks placed; no application has been built through one yet
+    # `attached`    an application **was** built through a hook we placed
+    # `failed`      an exception during install; the application runs unchanged
+    #
+    # Six causes behind one boolean, which is the change
+    # `middleware/php/src/Auto.php:135-155` made after its Laravel provider read
+    # `attached() == false` as one particular cause and announced it on every
+    # `php artisan` command. `attached` here is a fact about the *hook* — an
+    # application came through it — and not a claim that a middleware resulted;
+    # `attach_problem` answers that, from `Middleware.constructed`.
+    @state = 'pending'
+
+    class << self
+      attr_reader :installed, :built, :state, :watch_error
+    end
+
+    # For the suite only. Does not un-prepend: a module prepended to a class is
+    # there for the life of the process, which is why the tests define a fresh
+    # class per case rather than reusing one.
+    def self.reset!
+      @installed = false
+      @attached = {}
+      @built = 0
+      @state = 'pending'
+      @watch_error = nil
+      @watch&.disable
+      @watch = nil
+    end
+
+    # Delegated rather than duplicated: two spellings of the `findxpand:` prefix
+    # is the §20.1 rule 2 shape at its smallest, and the prefix is what a
+    # customer greps their boot log for.
+    def self.warn_stderr(message)
+      Findxpand.warn_stderr(message)
+    end
+
+    # Wrap one built application, or hand it back with a reason.
+    #
+    # Never raises. This is called from inside somebody else's boot, and an
+    # exception here is a site that does not start.
+    def self.wrap(app)
+      return app if app.nil?
+      # `to_app` on a builder whose `run` was already our middleware. Harmless to
+      # wrap twice — `Middleware::SEEN_KEY` makes the inner one a no-op — but
+      # pointless, and one fewer object per request path is one fewer thing to
+      # explain in a stack trace.
+      return app if app.is_a?(Findxpand::Middleware)
+      # **Whatever this is, it is not a Rack application.** The safety net under
+      # the shape test: `builder_shape?` recognises a builder by three method
+      # names, and a class somewhere in a large application may carry all three
+      # and mean something else entirely by them. Wrapping *that* object's return
+      # value would hand its caller a `Findxpand::Middleware` where it expected
+      # its own type, which is a broken application rather than an unattached
+      # one — the direction this file is not allowed to fail in. A Rack
+      # application is exactly a thing that answers `call`, so that is the test.
+      return app unless app.respond_to?(:call)
+
+      settings = Findxpand.options_from_env
+      return app if settings[:token].empty?
+      return app unless settings[:enabled]
+
+      # Constructed with no options **on purpose**. `Middleware#initialize`
+      # resolves every option from this same environment on every construction
+      # path, so passing them here as well would be a second reading of one fact
+      # — the §20.1 rule 2 shape, and the exact shape that produced the defect
+      # this gem shipped: the `RUBYOPT` path read `FINDXPAND_CACHE_FILE` and the
+      # other two paths did not. What is read here is only the question *whether
+      # to attach at all*, which the constructor does not answer.
+      Findxpand::Middleware.new(app)
+    rescue StandardError => e
+      warn_stderr("could not attach (#{e.class}: #{e.message}); your application is running " \
+                'unchanged.')
+      app
+    end
+
+    # Prepended to every builder we find, which is the whole mechanism.
+    #
+    # `super` first, so the application is built exactly as it would have been
+    # and every `use` in the file is already inside what we are handed.
+    module Builder
+      def to_app
+        built = super
+        Findxpand::Auto.built!
+        Findxpand::Auto.wrap(built)
+      end
+    end
+
+    # One application was built through a hook we placed.
+    #
+    # Counted **before** `wrap` decides anything, because the two questions are
+    # different and were being answered by one number: "did the hook run" is
+    # this, and "did a middleware result" is `Middleware.constructed`. A hook
+    # that ran and declined (no token) reports differently from a hook that never
+    # ran at all, and the second is the Puma defect.
+    def self.built!
+      @built_lock.synchronize do
+        @built += 1
+        @state = 'attached'
+      end
+      # Disarmed here. An application has been built through us, so the class
+      # that builds applications in this process is one we are already on, and a
+      # watcher that goes on watching is a callback on every class body for the
+      # life of the process buying nothing.
+      #
+      # The trade, stated: if some *inner* builder builds first — a `map` block,
+      # a Sinatra sub-application — we disarm before the server's own outer
+      # builder is defined, and we are then attached but not outermost. That is a
+      # degradation (a `Rack::Deflater` outside us can hand us gzip, which we
+      # count as `skip-encoded` and report as degraded) rather than a silence,
+      # and `builders` names exactly what we got.
+      @watch&.disable
+    rescue StandardError
+      nil
+    end
+
+    # Prepend to every named builder class that is already defined.
+    #
+    # Idempotent, and safe to call again later: the Railtie calls it a second
+    # time, because by the time Rails runs its initializers Rack is certainly
+    # loaded even if it was not when `RUBYOPT` ran. Returns the names now
+    # attached.
+    #
+    # `names` is a seam for the suite, not an option. The list it defaults to is
+    # a constant because a customer has no business changing it, and a test
+    # cannot add `Rack::Builder` to a process that has no Rack in it.
+    def self.attach_builders(names = BUILDER_CLASSES)
+      names.each do |name|
+        next if @attached.key?(name)
+
+        klass = resolve(name)
+        next if klass.nil?
+
+        attach_class(klass, name)
+      end
+      @attached.keys
+    end
+
+    # Resolve `A::B::C` without raising and without requiring anything.
+    #
+    # `Object.const_defined?('Puma::Rack::Builder')` raises `NameError` when
+    # `Puma` is not defined rather than answering false, which on a non-Puma
+    # stack is every boot — so the path is walked a segment at a time. `false` as
+    # the second argument keeps the lookup off `Object`'s ancestors, so a
+    # `Builder` constant belonging to something else cannot be mistaken for this
+    # one.
+    def self.resolve(name)
+      name.split('::').reduce(Object) do |scope, segment|
+        return nil unless scope.is_a?(Module) && scope.const_defined?(segment, false)
+
+        scope.const_get(segment, false)
+      end
+    rescue StandardError
+      nil
+    end
+
+    # Prepend to one class, once.
+    #
+    # The idempotence check is `ancestors.include?`, not our own bookkeeping: a
+    # class reopened later, a subclass of one we already hold, and a second call
+    # from the Railtie all arrive here, and the ancestor chain is the fact while
+    # a Hash of names is only our record of it.
+    def self.attach_class(klass, name = nil)
+      return false unless klass.is_a?(Module)
+      return false if klass.ancestors.include?(Builder)
+
+      klass.prepend(Builder)
+      @attached[name || klass.name || klass.to_s] = true
+      true
+    rescue StandardError
+      # A frozen class, or a Module that refuses a prepend. Not a reason to stop
+      # a boot, and the name simply does not appear in `builders`.
+      false
+    end
+
+    # Is this a Rack builder, whatever it is called?
+    #
+    # Asked of every class body that closes after we install. See
+    # `BUILDER_METHODS` for why all three are required.
+    def self.builder_shape?(klass)
+      return false unless klass.is_a?(Module)
+
+      BUILDER_METHODS.all? { |method| klass.method_defined?(method) }
+    rescue StandardError
+      false
+    end
+
+    # Watch for a builder class defined after us — which is every server's own.
+    #
+    # `:end` rather than `:class`, so the body has finished and the methods we
+    # test for exist. (`prepend` would work at `:class` too, since `super` is
+    # resolved at call time, but then the shape test would answer false for every
+    # class in the process and this would be a watcher that never fires.)
+    #
+    # Returns whether the watch is armed. Never raises: a Ruby without
+    # `TracePoint`, or one that refuses to enable it, degrades to the by-name
+    # half and says so on stderr from `install`.
+    def self.watch_for_builders
+      return true unless @watch.nil?
+      return false unless defined?(::TracePoint)
+
+      watch = ::TracePoint.new(:end) do |point|
+        # Deliberately no Mutex. Taking one inside a trace callback deadlocks the
+        # first time a `require` runs while this file holds it — `Mutex` is not
+        # reentrant — and the work being protected is a `prepend` Ruby already
+        # makes idempotent plus one Hash write. `install` runs on the main thread
+        # before the application exists, so there is no second writer to race.
+        #
+        # Every line of it inside a `rescue`, because an exception raised in a
+        # trace handler propagates into whatever code happened to close a class —
+        # somebody else's `require`, at their boot. This file's one promise is
+        # that it degrades to *not attached* and never to *broken*, and a raise
+        # here is the one place that promise could be broken from.
+        begin
+          target = point.self
+          attach_class(target) if builder_shape?(target)
+        rescue StandardError
+          nil
+        end
+      end
+      watch.enable
+      @watch = watch
+      true
+    rescue StandardError, NotImplementedError => e
+      @watch = nil
+      @watch_error = "#{e.class}: #{e.message}"
+      false
+    end
+
+    # What this process observed about its own attach, for `/status`.
+    #
+    # Every value is a count or a name of something that happened. Nothing here
+    # is derived from configuration, and nothing reports health for a state it
+    # did not examine (§20.1 rule 3).
+    def self.report
+      {
+        'attach_state' => @state,
+        'builders' => @attached.keys.sort,
+        'built' => @built,
+        'watching' => !@watch.nil? && @watch.enabled?
+      }.tap do |report|
+        report['watch_error'] = @watch_error unless @watch_error.nil?
+        problem = attach_problem
+        report['attach_problem'] = problem unless problem.nil?
+      end
+    end
+
+    # The sentence for a `-rfindxpand/auto` that did not reach anything, or
+    # `nil` when there is nothing to report.
+    #
+    # `nil` is "we looked and there is nothing wrong", which is only sayable
+    # because both inputs are observations: an application was built through us,
+    # and a middleware exists. Neither can be true while the attach is a no-op.
+    def self.attach_problem
+      return nil unless @installed
+
+      if @built.zero?
+        return 'findxpand/auto ran and no application has been built through it. Hooks were ' \
+               "placed on #{@attached.keys.sort.inspect}; this server built its application " \
+               'some other way - it parses config.ru with its own builder class, or it was ' \
+               'handed an app object in code. If this endpoint is answering, the Rails ' \
+               'Railtie is what mounted us.'
+      end
+      if Findxpand::Middleware.constructed.zero?
+        return 'an application was built through findxpand/auto and no middleware was added ' \
+               'to it - FINDXPAND_TOKEN was empty, or FINDXPAND_ENABLED was off, at the ' \
+               'moment it was built.'
+      end
+
+      nil
+    end
+
+    # The whole of what a `-rfindxpand/auto` process does before its own first
+    # line.
+    def self.install
+      return false if @installed
+
+      if ENV['FINDXPAND_TOKEN'].to_s.empty?
+        @state = 'no-token'
+        warn_stderr('FINDXPAND_TOKEN is not set, so nothing was attached and this process ' \
+                  'serves your pages unchanged.')
+        return false
+      end
+      unless Findxpand.flag('FINDXPAND_ENABLED', true)
+        # Deliberately silent. Somebody set this on purpose.
+        @state = 'disabled'
+        return false
+      end
+
+      @installed = true
+      load_rack
+      attach_builders
+      watching = watch_for_builders
+      @state = 'watching'
+
+      if @attached.empty? && !watching
+        # Nothing to prepend and no way to notice one appearing. This process
+        # cannot attach, and the only channel it has is this line.
+        @state = 'no-builder'
+        warn_stderr('no Rack builder class is loaded and this Ruby will not let us watch for ' \
+                    "one (#{@watch_error}), so nothing was attached and this process serves " \
+                    'your pages unchanged.')
+      elsif !watching
+        # The by-name half is live and the by-shape half is not. Said out loud,
+        # because this is precisely the configuration in which a server that
+        # vendors its own builder — Puma does — attaches nothing and warns
+        # nothing, which is the defect this watch exists to end.
+        warn_stderr("watching for a server's own builder is unavailable here " \
+                    "(#{@watch_error}). Servers that parse config.ru with a vendored copy of " \
+                    'Rack::Builder - Puma is one - will not be reached. Check ' \
+                    '/__findxpand/status: `built: 0` means this happened.')
+      end
+      true
+    rescue StandardError => e
+      @state = 'failed'
+      warn_stderr("bootstrap skipped (#{e.class}: #{e.message}); running unchanged.")
+      false
+    end
+
+    # Rack, if this process has it. Not an error when it does not: the Railtie
+    # may still attach, the watch may still see a builder, and if nothing does,
+    # `/status` and stderr say so rather than implying health.
+    def self.load_rack
+      require 'rack'
+      true
+    rescue LoadError
+      false
+    end
+  end
+end
+
+Findxpand::Auto.install