findxpand 0.1.0

data/lib/findxpand.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+# Findxpand origin middleware — server-side SEO remediation in your own stack.
+#
+#     RUBYOPT="-rfindxpand/auto" bundle exec puma
+#
+# One deploy. After that, approved fixes arrive as a manifest pushed to
+# `/__findxpand/manifest` and no further release is needed — which is the reason
+# this gem exists rather than a JSON file in the repository.
+#
+# The corrected bytes are produced on the server, before anything leaves the
+# process. No JavaScript is involved anywhere, because AI crawlers do not run it
+# (§3 rule 1) — a title injected on the client is not a remediation path.
+#
+# ## What is in here
+#
+#     rewrite.rb     the rewrite: pure, shared semantics, no I/O
+#     store.rb       the manifest, the counters, the cache file, the verdict
+#     signature.rb   HMAC over `timestamp.body`, constant time, 300s window
+#     admin.rb       the two endpoints, and the only branches that fail closed
+#     middleware.rb  the Rack middleware
+#     encoding.rb    accept-encoding negotiation, and gzip on the way out
+#     auto.rb        the zero-code attach
+#     railtie.rb     Rails, at position 0
+#     cli.rb         init / doctor / status
+#
+# Requiring this file is inert: it defines the classes and, if Rails is already
+# loaded, registers the Railtie — which is what a Gemfile entry does and what a
+# Rails developer expects a gem to do. It patches nothing. `findxpand/auto` is
+# the file that attaches, and it has to be asked for by name.
+#
+# **Zero runtime dependencies, deliberately.** This runs inside somebody else's
+# application, and a middleware that drags in a dependency tree is a middleware
+# that can break their build. It is a Rack middleware that does not require Rack:
+# nothing here needs more of Rack than the calling convention.
+#
+# Frozen string literals: on, in every file of this gem.
+
+require 'findxpand/rewrite'
+require 'findxpand/store'
+require 'findxpand/signature'
+require 'findxpand/encoding'
+require 'findxpand/admin'
+require 'findxpand/middleware'
+
+module Findxpand
+  VERSION = '0.1.0'
+
+  # Not published to RubyGems, and nothing in this gem may claim otherwise.
+  #
+  # Mirrors `engine.fix.origin.PUBLISHED_TO_REGISTRIES`, which was written on
+  # 31 Aug 2026 after checking npm and PyPI and finding that three surfaces had
+  # been printing `npm install @findxpand/middleware` — a command that answers
+  # 404, and the first thing a customer would learn about us. There is no publish
+  # workflow in this tree for any of the three packages, so `gem install
+  # findxpand` fails the same way. The CLI and the README ask here.
+  PUBLISHED_TO_REGISTRIES = false
+
+  # Said once, wherever an install instruction appears, for as long as the gem is
+  # unpublished. Without it the command reads as a mistake.
+  UNPUBLISHED_NOTE =
+    'We send you this file - the gem is not on RubyGems yet, so there is nothing to ' \
+    'install by name. Keep it somewhere your build can reach; the version in the ' \
+    'filename is what a support conversation refers to.'
+
+  def self.install_command
+    return 'gem install findxpand' if PUBLISHED_TO_REGISTRIES
+
+    # Versioned deliberately: `gem install ./findxpand.gem` would install
+    # whatever happens to be in the client's download folder, and the version is
+    # the only thing tying a support conversation to a build.
+    "gem install ./findxpand-#{VERSION}.gem"
+  end
+
+  # How this gem attaches without the customer editing anything.
+  #
+  # Mirrors the `node` and `python` rows of `engine.fix.origin._ATTACH`, which
+  # has no `ruby` row yet — see the README.
+  ATTACH = 'RUBYOPT="-rfindxpand/auto"'
+
+  @store = nil
+  @store_lock = Mutex.new
+  @store_paths = nil
+  @path_conflict = nil
+
+  # The one manifest this process serves.
+  #
+  # Memoised, because Ruby has three attach points and two of them can be live at
+  # once: the builder prepend wraps what `config.ru` builds and the Railtie sits
+  # at position 0 inside it. Two `Store` objects would mean two
+  # manifests in one process — a push landing in the instance that happens to own
+  # `/__findxpand/manifest` and a rewrite reading the other one, which is a fix
+  # that reports as stored and never appears on a page. §20.1 rule 2: one
+  # implementation of "what are this process's rules", and as many readers as the
+  # stack needs.
+  #
+  # **What used to be written here was false, and it was the worst defect in the
+  # gem.** It said: "the first caller's paths win — that is the `RUBYOPT` attach
+  # in practice, since it runs before the application's first line". On Rails the
+  # first caller is *always the Railtie*, because Rails builds and instantiates
+  # its middleware stack during `require config/environment`, before `config.ru`
+  # reaches `to_app`. And until 2 Sep 2026 `Findxpand.options_from_env` had
+  # exactly one caller in the whole gem (`auto.rb`), so the Railtie and the
+  # documented hand mount both arrived here with `cache_file: nil` — whatever
+  # `FINDXPAND_CACHE_FILE` said. The memoised store was therefore the one that
+  # could not persist: `Store#write_cache` returned at its first line, a push
+  # answered `{"ok":true,"version":"…"}`, pages were rewritten, and `/status`
+  # reported health. The next restart reverted the site. Worse,
+  # `OriginMiddleware.apply` then read an empty deployed
+  # manifest and merged the next fix into `{}`, so every previously approved fix
+  # vanished with no error anywhere.
+  #
+  # The repair is in `Middleware#initialize`, which now resolves **every** option
+  # from the environment on every construction path, matching
+  # `middleware/php/src/Middleware.php:97-106` (`$options = array_merge(
+  # Auto::options(), $options )` — "defaults come from the environment, so a
+  # container binding with no arguments behaves like the bootstrap"). Once every
+  # caller resolves the same environment, every caller asks for the same paths
+  # and the memoisation has nothing left to lose.
+  #
+  # What is left here is the case that survives that: somebody passing an
+  # explicit path in code from a second mount point. First caller still wins — a
+  # second store would split the manifest, which is what this memoisation exists
+  # to prevent — but the discarded value is now *observed*, so it is reported
+  # rather than dropped on the floor (§20.1 rule 3). Once, on stderr, naming both.
+  def self.store(cache_file: nil, manifest_file: nil, clock: nil)
+    wanted = [cache_file, manifest_file]
+    @store_lock.synchronize do
+      if @store.nil?
+        @store_paths = wanted
+        @store = Store.new(cache_file: cache_file, manifest_file: manifest_file, clock: clock)
+      elsif wanted != @store_paths && @path_conflict.nil?
+        @path_conflict = "serving #{@store_paths.inspect}; #{wanted.inspect} was ignored"
+        warn_stderr('two mount points asked for different manifest paths - ' \
+                    "#{@path_conflict}. One process serves one manifest: set " \
+                    'FINDXPAND_CACHE_FILE and pass no paths in code.')
+      end
+      @store
+    end
+  end
+
+  # For the suite only. A process that discarded its store mid-flight would lose
+  # every rule until the next push.
+  def self.reset_store!
+    @store_lock.synchronize do
+      @store = nil
+      @store_paths = nil
+      @path_conflict = nil
+    end
+  end
+
+  # How this gem talks to stderr, in one place.
+  #
+  # `Auto.warn_stderr` delegates here rather than carrying its own copy: two
+  # spellings of the prefix is the §20.1 rule 2 shape at its smallest, and the
+  # prefix is what a customer greps their boot log for. `$stderr.write` rather
+  # than `Kernel#warn` because `warn` is silenced by `-W0` and by
+  # `Warning[:deprecated] = false`-style configuration in somebody else's
+  # application, and this is not a deprecation notice — it is the only channel an
+  # attach that did not attach has.
+  def self.warn_stderr(message)
+    $stderr.write("findxpand: #{message}\n")
+  end
+
+  # What attached in this process, for `GET /__findxpand/status`.
+  #
+  # Additive keys. The engine spreads whatever the endpoint answers
+  # (`engine.fix.origin.status`, `{"ok": True, "installed": True, **payload}`), and
+  # `middleware/php/src/Store.php`'s `runtime`/`reach_reason` block is the
+  # precedent: a package reports the failures only its own runtime can have,
+  # named for what they mean rather than squeezed into a shared key.
+  #
+  # This answers the question the builder prepend could not. The total failure —
+  # `findxpand/auto` ran and nothing of ours was ever constructed — cannot be
+  # reported *here*, because there is then no middleware in the path to answer
+  # `/status` at all; that one goes to stderr from `Auto`. What is reported here
+  # is the partial case, which is the one a monitor can actually reach:
+  # `/status` answers because the Railtie mounted, `builders` names only
+  # `Rack::Builder`, and `built` is 0 — meaning the server parsed `config.ru`
+  # with its own vendored builder and the `RUBYOPT` attach never fired. That was
+  # the shipped behaviour under Puma until 2 Sep 2026 (`auto.rb`).
+  #
+  # `middlewares` is `Middleware.constructed`, and it is here rather than in
+  # `Auto` because it is true of the process however the middleware got there —
+  # the Railtie and a hand-written `use` move it too.
+  def self.attach_report
+    report = { 'auto' => defined?(Auto) ? true : false,
+               'middlewares' => Middleware.constructed }
+    report['store_conflict'] = @path_conflict unless @path_conflict.nil?
+    begin
+      report.merge!(Auto.report) if defined?(Auto)
+    rescue StandardError => e
+      # `/status` is the one endpoint that reports whether anything is wrong, and
+      # the engine's `verify` reads it. Raising here would take the health check
+      # down over the *reporting* of health, which is the tail wagging the dog —
+      # so the failure becomes a field instead of a 500. Named rather than
+      # swallowed: an absent `attach` block would read as "nothing to say", and
+      # this is "we could not look" (§20.1 rule 3).
+      report['attach_error'] = "#{e.class}: #{e.message}"
+    end
+    report
+  end
+
+  # `Findxpand.middleware(app, **options)` — the explicit mount, for anybody who
+  # would rather see it in their `config.ru` than trust a hook.
+  #
+  #     use Findxpand::Middleware
+  #     # or
+  #     run Findxpand.middleware(MyApp, token: ENV['FINDXPAND_TOKEN'])
+  #
+  # Mount it **first**, which in Rack is the first `use` in the file, and read
+  # `encoding.rb` before deciding that is enough: it is enough only because this
+  # middleware takes over the encoding negotiation on the paths it rewrites.
+  def self.middleware(app, **options)
+    Middleware.new(app, **options)
+  end
+
+  # `false`, `0`, `no` and `off` are off; anything else present is on.
+  #
+  # Written out because `ENV['X'] ? true : false` makes the string "false" true,
+  # and an operator who sets `FINDXPAND_ENABLED=false` to turn the gem off and
+  # finds it still running has no reason to suspect the flag.
+  def self.flag(name, fallback)
+    raw = ENV[name]
+    return fallback if raw.nil? || raw.empty?
+
+    !/\A(?:false|0|no|off)\z/i.match?(raw.strip)
+  end
+
+  # Middleware options from the environment, in one place.
+  def self.options_from_env
+    settings = {
+      token: ENV['FINDXPAND_TOKEN'].to_s,
+      cache_file: env_path('FINDXPAND_CACHE_FILE'),
+      manifest_file: env_path('FINDXPAND_MANIFEST_FILE'),
+      enabled: flag('FINDXPAND_ENABLED', true),
+      require_signature: flag('FINDXPAND_REQUIRE_SIGNATURE', true),
+      recompress: flag('FINDXPAND_RECOMPRESS', true)
+    }
+    raw = ENV['FINDXPAND_MAX_BYTES'].to_s
+    settings[:max_bytes] = raw.to_i if /\A\d+\z/.match?(raw) && raw.to_i.positive?
+    settings
+  end
+
+  def self.env_path(name)
+    value = ENV[name].to_s
+    value.empty? ? nil : value
+  end
+end
+
+# Registered here rather than in `auto.rb` because a Railtie is the shape a Rails
+# developer expects a gem to have, and because `auto.rb` is loaded by `RUBYOPT`
+# *before* Rails exists — at which point there is no `Rails::Railtie` to subclass.
+# A Gemfile entry loads this file after Rails, which is when this line is true.
+require 'findxpand/railtie' if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: findxpand
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nextoria
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-09-02 00:00:00.000000000 Z
+dependencies: []
+description: One deploy. After that, approved fixes arrive as a manifest pushed to
+  your own origin and no further release is needed. The corrected HTML is produced
+  on the server, so crawlers that do not run JavaScript still see it. Zero runtime
+  dependencies; it never makes an outbound request.
+email:
+executables:
+- findxpand
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/findxpand
+- findxpand.gemspec
+- lib/findxpand.rb
+- lib/findxpand/admin.rb
+- lib/findxpand/auto.rb
+- lib/findxpand/cli.rb
+- lib/findxpand/encoding.rb
+- lib/findxpand/middleware.rb
+- lib/findxpand/railtie.rb
+- lib/findxpand/rewrite.rb
+- lib/findxpand/signature.rb
+- lib/findxpand/store.rb
+homepage: https://nextoria.ae/findxpand
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://nextoria.ae/findxpand
+  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.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Server-side SEO remediation at your origin, for Rack, Rails, Sinatra and
+  Hanami.
+test_files: []