findxpand 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 756ce879fc1079faabc838210e35b0467f721dc3064b4c7f0032df2164ce8f0d
+  data.tar.gz: 28c91eb83f1f26942080772c18522cdb7a52fe7bd7c4c652dfa0aba58ac08735
+SHA512:
+  metadata.gz: 84a14740683127e6b8b76b3194c460e9e451f21f28f1d6b02ff81cf6e8d4e4249eb166cd9d4440997660bc5b8e1d78f64075af05557a2d78b849a11a7a25d920
+  data.tar.gz: b711ee022f7a8122ea6929a633bbee91ae98612641ee926210511db4ce53dc15761e978bd2a96560749961c6135c5ad60731b2675fc40cc3234edef331c25e0e

data/README.md

@@ -0,0 +1,325 @@
+# findxpand
+
+Server-side SEO remediation at your origin, for Rack, Rails, Sinatra, Hanami,
+Roda, Grape, or a bare lambda.
+
+```bash
+gem install ./findxpand-0.1.0.gem
+```
+
+> **Not on RubyGems yet.** We send you the `.gem` file; `findxpand` is not a
+> published name, so installing it by name fails. The version in the filename is
+> what a support conversation refers to.
+
+## The whole install
+
+```ruby
+# Gemfile
+gem 'findxpand'
+```
+
+```bash
+RUBYOPT="-rfindxpand/auto" bundle exec puma
+```
+
+Nothing in your application changes. `FINDXPAND_TOKEN` in the same environment is
+the only other thing needed.
+
+**The Gemfile line is not optional.** `bundle exec` restricts the load path to
+the Gemfile before `RUBYOPT` is processed, so without it Ruby answers
+`LoadError: cannot load such file -- findxpand/auto` and your server does not
+start at all. That is the one failure this gem cannot soften — every other one
+degrades to *not attached* — and it is why the Gemfile is step one.
+
+That is the only deploy. Approved fixes arrive afterwards as a manifest pushed to
+`/__findxpand/manifest`, and no further release is needed.
+
+### On Rails, the Gemfile line is enough on its own
+
+A Railtie inserts the middleware at position 0 of the Rails stack, which is
+outermost of everything Rails builds — ahead of a
+`config.middleware.use Rack::Deflater`, and ahead of the router. The `RUBYOPT` is
+still the recommended install because it is the same instruction for every
+framework and it survives a `config.ru` that does something unusual.
+
+### Why not `use Findxpand::Middleware`
+
+Because there is no position in a Rack stack that also uses `Rack::Deflater`
+where mounting by hand does the right thing, and the same measurement holds in
+three languages. 31 Aug 2026:
+
+| stack | mount | result |
+|---|---|---|
+| Express + `compression` | findxpand first | `skip-encoded` — page unmodified, `/status` healthy, the fix silently never lands |
+| Express + `compression` | compression first | 2069 bytes of plain HTML on the wire under `content-encoding: gzip` — undecodable |
+| Django 6.1 + `GZipMiddleware` | outermost | `skip-encoded`, original title served, `/status` healthy |
+
+In Rack, `use Rack::Deflater` *inside* you means the body you are handed has
+already been gzipped, and there is nowhere further out to stand. So the wrapper
+stops asking to be placed correctly and takes over the negotiation instead: on
+the handful of paths the manifest names, your application is asked for
+`Accept-Encoding: identity` and the rewritten page is compressed on the way out.
+A path with no rule is not touched at all, and your own compression still runs on
+the rest of the site exactly as before.
+
+`Findxpand::Middleware` is still exported for embedding, and is what `/auto`
+mounts.
+
+### What it reaches, and what it does not
+
+`findxpand/auto` prepends `to_app` on the class your server builds its Rack
+application with, and wraps what that returns.
+
+**Not `Rack::Builder` alone.** This page used to say "one method —
+`Rack::Builder#to_app` — which every Ruby web server calls", and that was wrong
+on the server in the command at the top of this page: Puma parses `config.ru`
+with its own vendored copy of the builder, so a prepend on `Rack::Builder` never
+ran and nothing said so. What attaches now is two things — every builder class
+already loaded, by name, and every class defined afterwards that carries the
+`config.ru` DSL (`to_app`, `use` and `run` together), which is what a server's
+vendored copy is. See `lib/findxpand/auto.rb`; that file also records that none
+of it has been run against a real Puma.
+
+**Reached:** anything booted from a `config.ru` (`rackup`, Puma, Unicorn, Thin,
+Falcon, Passenger, WEBrick); **Rails**, because `rails server` loads `config.ru`
+too, so the wrap sits outside the Rails stack *and* outside anything `config.ru`
+itself used; **Sinatra**, classic and modular, including `ruby app.rb` with no
+`config.ru` at all, because `Sinatra::Base.new` builds through a builder;
+**Hanami**, **Roda**, **Grape**, `Rack::URLMap`, and a plain lambda.
+
+**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`;
+- a builder that does not answer to `to_app`, `use` and `run` together — that is
+  the whole of what is recognised, and a server with a different DSL is a server
+  this does not see;
+- anything that is not a Rack application: a bare `WEBrick::HTTPServer` with a
+  servlet, `Async::HTTP::Server` used directly, gRPC;
+- 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,
+  ought to work, and has not been run there. Watching for a server's own builder
+  needs `TracePoint`; where that will not enable, the boot log says so in a
+  sentence rather than leaving it to be discovered.
+
+If it does not attach, `/__findxpand/status` says so rather than reporting
+health — `attach.built: 0` is a hook that was placed and never ran. See *It
+tells you when it is doing nothing*. The one case no endpoint can report is the
+total one: with no middleware anywhere there is nothing to answer `/status`, so
+that one is a line on stderr at boot.
+
+## Not a Ruby app, or not one of those? Run it as a sidecar
+
+The same behaviour, with a reverse proxy where your application would be. Nothing
+installs into your stack and it does not matter what your stack is. See
+`middleware/node/README.md` for the container; it is the route for PHP, Java,
+.NET, Go, and static files behind nginx.
+
+## Environment
+
+Two variables matter:
+
+| Variable | Meaning |
+|---|---|
+| `FINDXPAND_TOKEN` | **Required.** The shared secret we push manifests with, and the HMAC key. We generate it; nothing attaches without it. |
+| `FINDXPAND_CACHE_FILE` | **Required in practice.** Where a pushed manifest is persisted. Without it, every restart drops every rule until the next push — and on a forking server a push reaches one worker. |
+
+And five that have sensible defaults:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `FINDXPAND_MANIFEST_FILE` | — | A manifest committed to your repository, for the no-inbound-endpoint mode. Read at boot; a push overrides it. |
+| `FINDXPAND_ENABLED` | on | `false`, `0`, `no` or `off` leaves the gem installed and stops it touching responses. |
+| `FINDXPAND_MAX_BYTES` | 2 MB | Largest HTML body to buffer. Larger responses stream through untouched. |
+| `FINDXPAND_REQUIRE_SIGNATURE` | on | Verify the signature on every push. See below before turning this off. |
+| `FINDXPAND_RECOMPRESS` | on | On a path with a rule, ask your application for `identity` and gzip the rewritten page on the way out. Turn it **off** only where an intermediary has already taken over content negotiation. Off means a ruled page is served uncompressed. |
+
+**All seven are read on every way in** — the `RUBYOPT` attach, the Rails Railtie,
+and a hand-written `use Findxpand::Middleware`. Until 2 Sep 2026 only the first
+of those read them, so on Rails `FINDXPAND_CACHE_FILE` was silently ignored and
+nothing persisted while `/status` reported health.
+
+> **Pick a cache path that survives a restart, and that every worker can read.**
+> `/var/tmp` is fine on a VM and wrong on a container or a serverless platform,
+> where it is discarded. Use a mounted volume; if the platform has no durable
+> disk at all, say so — the manifest-in-the-repository mode exists for exactly
+> that and needs none.
+
+## Forking servers
+
+Puma in cluster mode, Unicorn and Passenger serve from forked workers, and a
+manifest pushed to `/__findxpand/manifest` arrives at **exactly one of them**.
+The worker that took the push writes the cache file; every other worker notices
+the change and adopts it within a second. That is the whole reason
+`FINDXPAND_CACHE_FILE` is listed as required rather than optional — without a
+shared cache file, three workers out of four go on serving the previous rules
+until the next deploy, and a fix verifies or fails to verify depending on which
+worker answers the re-fetch.
+
+No network is involved: a worker reads a local file its sibling wrote.
+
+That paragraph is true of every way in, and until 2 Sep 2026 it was true of one:
+`FINDXPAND_CACHE_FILE` was read only by the `RUBYOPT` attach, so a Rails app —
+where the Railtie is always the first to build the store — ran with no cache
+file at all whatever the environment said. Nothing was written, nothing was
+adopted, and `/status` reported health. If you are looking at a `/status` from
+before that, `persisted` is the field that would have shown it.
+
+## What it does to a response
+
+Only when the path has a rule, the status is 200, the content type is HTML, and
+nothing has already compressed it. Everything else is passed through and marked:
+
+| `x-findxpand-origin-mw` | Meaning |
+|---|---|
+| `1` | rewritten |
+| `pass` | a rule existed and changed nothing |
+| `error` | the rewrite raised; **your original bytes were served unchanged** |
+| `skip-encoded` | already compressed — something below us gzipped it |
+| `skip-large` | over `FINDXPAND_MAX_BYTES`, served whole rather than truncated |
+| `skip-encoding` | the body was not valid UTF-8, so it was not touched |
+| `redirect` | served from the manifest's redirect table |
+| `status` | a 404/410/451 rule answered before your app was reached |
+
+**On any exception, the original response is served.** The rewrite runs inside a
+`rescue` and the buffered bytes are sent untouched if it raises — that is the
+reason for buffering at all. A bug of ours cannot take down a page.
+
+Two things happen to the *request*, and only on a path with a rule:
+`Accept-Encoding` becomes `identity`, and `If-None-Match` / `If-Modified-Since`
+are dropped. The second is there because a `304 Not Modified` answered below us
+would leave a returning visitor — and a crawler with the page already cached —
+holding the *old* document indefinitely while the fix counted as applied for
+everybody else.
+
+**Every visitor gets identical bytes.** There is no user-agent branch anywhere in
+this gem. Serving crawlers something different is cloaking, and the point of a
+server-side rewrite is that it needs no such trick.
+
+## Endpoints
+
+Both require `Authorization: Bearer <token>`, are `no-store`, and carry
+`x-robots-tag: noindex, nofollow`.
+
+- `GET /__findxpand/status` — version, rule count, age, health, and the manifest
+- `POST /__findxpand/manifest` — replace the rules; echoes the stored version
+
+### It tells you when it is doing nothing
+
+`/__findxpand/status` reports `counters`, `requests_seen`, `applied_age`,
+`persisted`, `reach_reason`, `attach`, `degraded` and `degraded_reason` as well
+as the rule count. This is the failure worth monitoring: attached below
+compression, attached where no rule matches, unable to persist a push, or not
+attached at all, the middleware serves every page untouched and every other
+signal looks healthy.
+
+```json
+{
+  "degraded": true,
+  "degraded_reason": "12 response(s) arrived already compressed and could not be rewritten - the middleware is mounted after compression, and needs to be mounted before it",
+  "requests_seen": 12,
+  "persisted": true,
+  "counters": { "considered": 12, "applied": 0, "skip_encoded": 12, "unmatched": 0, "error": 0 },
+  "attach": { "attach_state": "attached", "builders": ["Rack::Builder"], "built": 1, "middlewares": 1 }
+}
+```
+
+Alert on `degraded`. `applied_age` is seconds since a rewrite last landed, or
+`null` if one never has. Four fields answer four different "is it really
+working" questions, and they are not interchangeable:
+
+- `counters.unmatched` — requests that reached the middleware on a path the
+  manifest does not name. Many of them with `considered: 0` means the manifest's
+  keys match nothing this site serves, or the middleware is mounted where the
+  pages do not go. It is the same counter the Node package reports, and this
+  package votes on it: **twenty unmatched requests, no match at all, and a
+  minute of uptime** puts the sentence in `degraded_reason`. One unmatched
+  request is a favicon, so it is counted and not voted on — if you alert on this
+  yourself, use the same floor rather than `> 0`, or your alert fires on the
+  first stylesheet of every deploy.
+- `requests_seen` — every non-admin request that reached the middleware, pages
+  and assets and health probes alike. Weaker than `unmatched` on purpose: one
+  `GET /api/health` moves it, so it answers "was I in *a* request path" and not
+  "was I in the one the pages go down". Up more than a minute with
+  `requests_seen: 0` is reported as degraded rather than healthy.
+- `persisted` — `true` a push was written to `FINDXPAND_CACHE_FILE`, `false` one
+  was taken and could not be, `null` nothing has been pushed here yet. `false`
+  is the expensive one: the rules are live in this process, a restart drops
+  them, and the other workers never saw them.
+- `attach.built` — how many applications were built through the `RUBYOPT` hook.
+  `0` with the endpoint answering means the Railtie mounted us and the hook
+  never fired.
+
+Asking `/status` does not count as a request; an auditor that satisfies its own
+question is not an auditor.
+
+## The CLI
+
+```bash
+findxpand init      # the lines to add, ready to paste
+findxpand doctor    # this machine's preconditions, and what it cannot check
+findxpand status    # the manifest cached on this machine
+```
+
+`doctor` runs in a different process from your server, so it cannot tell you
+whether the middleware is in the request path, and it says so instead of implying
+otherwise. It prints the `curl` line for `/status`, which is the thing that
+knows.
+
+Nothing in the CLI makes an HTTP request, to us or to localhost.
+
+## Pushes are signed, not merely authenticated
+
+Every manifest push carries `x-findxpand-signature` and `x-findxpand-timestamp`:
+HMAC-SHA256 over `timestamp.body`, keyed by your token, compared in constant
+time. Unsigned, altered or stale pushes are refused with **401**.
+
+The bearer token proves who sent a push and says nothing about what was in it.
+Anything holding it — a logging proxy, a mirrored request, an old CI secret —
+could otherwise replay a captured manifest indefinitely, or swap the manifest
+inside one. The timestamp is inside the digest, so a captured push expires; the
+window is 300 seconds, which means the clock on that host has to be roughly
+right.
+
+There is one supported reason to turn this off, and it is an intermediary that
+rewrites or re-encodes request bodies, since that invalidates any signature over
+them.
+
+## Why it never calls us
+
+It cannot. There is no outbound request anywhere in this gem. If Findxpand is
+unavailable, your site serves the last manifest it received, indefinitely.
+
+## Removing the gem removes the rules
+
+The corrected titles, descriptions, canonicals and alt text are produced by this
+middleware at request time. They are not written into your templates, your
+database or your CMS. Uninstall the gem, unset `RUBYOPT`, or set
+`FINDXPAND_ENABLED=false`, and your pages go back to exactly what your
+application renders — immediately, with no migration and nothing left behind.
+
+That is a property to know before you choose this route rather than a defect, and
+it cuts both ways: it is why a bad fix is one environment variable from being
+gone, and it is why a fix is not "in your codebase" once it is live. Where a
+change should persist in your own source instead, the pull-request route carries
+the same fields into your repository.
+
+## Development
+
+```bash
+ruby -Ilib -Itest test/conformance_test.rb   # the shared cross-language fixture
+ruby -Ilib -Itest test/rewrite_test.rb       # Ruby's own ways to get this wrong
+ruby -Ilib -Itest test/middleware_test.rb    # the Rack layer, end to end
+ruby -Ilib -Itest test/attach_test.rb        # the attach, the env, the store singleton
+```
+
+No Bundler and no `gem install`: minitest ships with Ruby and this gem has no
+dependencies, so its suite runs wherever the gem does.
+
+`test/conformance_test.rb` runs `middleware/conformance/cases.json`, which is
+generated by the engine and is the same file the Node and Python middlewares run.
+Four hand-written rewriters have to agree byte for byte, and one fixture with
+four consumers is the only thing that makes disagreement visible.

data/exe/findxpand

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The console script. Everything it does is in `lib/findxpand/cli.rb`.
+#
+# `exit` with the CLI's own return value, so that `findxpand doctor` can be the
+# last line of a deploy script and mean something. A tool that reports a failed
+# precondition and exits 0 is the §20.1 rule 3 shape from the outside.
+
+begin
+  require 'findxpand/cli'
+rescue LoadError
+  # Run straight out of a checkout rather than an installed gem. The rescue
+  # rather than an unconditional `$LOAD_PATH` push, so that an installed copy
+  # never quietly loads a different one that happens to be nearby.
+  $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+  require 'findxpand/cli'
+end
+
+exit(Findxpand::CLI.run(ARGV))

data/findxpand.gemspec

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# The gem, and its one unusual property: it has no dependencies at all.
+#
+# Not "few". None. This installs into somebody else's application, and a
+# middleware that drags in a dependency tree is a middleware that can break their
+# build or pin a version they cannot afford — so everything it needs comes out of
+# the standard library: `json`, `openssl`, `zlib`, `stringio`, `fileutils`,
+# `mutex_m`-free plain `Mutex`, and `minitest` for the suite, which ships with
+# Ruby. It is a **Rack** middleware that does not depend on Rack: nothing in it
+# needs more of Rack than the calling convention, and `findxpand/auto` only
+# touches `Rack::Builder` if the host application has already loaded it.
+#
+# `required_ruby_version >= 3.0` for three reasons that are all load-bearing:
+# `OpenSSL.secure_compare` (constant-time digest comparison) ships with the
+# openssl that comes with Ruby 3.0; `Enumerable#to_h` with a block builds the
+# pattern table; and `Hash#transform_keys` shapes the status JSON. None is worth
+# a compatibility shim for Ruby 2.
+
+# The version comes from the library rather than being written here as well: two
+# copies of one fact are two that drift, and the one somebody edits is never the
+# one the other reads (§20.1 rule 2).
+#
+# `$LOAD_PATH` rather than `require_relative 'lib/findxpand'`, because that file
+# requires its own siblings by name, and `lib/` is not on the path while a
+# gemspec is being evaluated.
+$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+require 'findxpand'
+
+Gem::Specification.new do |spec|
+  spec.name = 'findxpand'
+  spec.version = Findxpand::VERSION
+  spec.license = 'MIT'
+  spec.authors = ['Nextoria']
+  spec.summary = 'Server-side SEO remediation at your origin, for Rack, Rails, Sinatra and Hanami.'
+  spec.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.'
+  spec.homepage = 'https://nextoria.ae/findxpand'
+  spec.required_ruby_version = '>= 3.0'
+
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    # Deliberately absent: `allowed_push_host`. This gem is not published, and a
+    # push host in the metadata is the kind of line somebody trusts later.
+    # `Findxpand::PUBLISHED_TO_REGISTRIES` is the flag to flip when it is, and it
+    # moves the README, the CLI and the engine's install screen together.
+    'rubygems_mfa_required' => 'true'
+  }
+
+  # Listed with `Dir` rather than `git ls-files`, which is the usual line and
+  # needs git to be installed and the tree to be a checkout — neither is true of
+  # the tarball a customer builds from.
+  spec.files = Dir[
+    'lib/**/*.rb',
+    'exe/*',
+    'README.md',
+    'findxpand.gemspec'
+  ]
+  spec.bindir = 'exe'
+  spec.executables = ['findxpand']
+  spec.require_paths = ['lib']
+
+  # The suite is deliberately not in `spec.files`: it reads
+  # `middleware/conformance/cases.json`, which lives outside this directory
+  # because three other packages read the same file, and a gem that shipped a
+  # test it cannot run would be worse than one that ships none. Run it from the
+  # repository with `ruby -Ilib -Itest test/conformance_test.rb`.
+end

data/lib/findxpand/admin.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# The two endpoints, and nothing else about the request path.
+#
+#     GET  /__findxpand/status    bearer token
+#     POST /__findxpand/manifest  bearer token *and* HMAC-SHA256
+#
+# Split out of the middleware because these are the only branches in the gem
+# that fail **closed**. §3 rule 7 draws the line exactly here: an audit may
+# degrade and a page may be served unchanged, but a write, a credential and a
+# budget must refuse rather than guess. Every other file in this gem is written
+# so that a failure serves the customer's own bytes; every branch in this one is
+# written so that a failure serves a 401.
+#
+# Both replies carry `cache-control: no-store` and `x-robots-tag: noindex,
+# nofollow`, because the body describes the site's own SEO configuration and
+# belongs to whoever holds the token.
+#
+# Header names are emitted in lower case. Rack 3 requires it, Rack 2 does not
+# care, and HTTP has been case-insensitive about them since 1996 — so lower case
+# is the one spelling that is correct under both versions of the specification.
+#
+# Frozen string literals: on.
+
+require 'json'
+
+module Findxpand
+  class Admin
+    ROOT = '/__findxpand'
+    MANIFEST_PATH = "#{ROOT}/manifest"
+    STATUS_PATH = "#{ROOT}/status"
+
+    def self.admin_path?(path)
+      path == STATUS_PATH || path == MANIFEST_PATH
+    end
+
+    def initialize(store:, token:, max_bytes:, require_signature: true, clock: nil)
+      @store = store
+      @token = token.to_s
+      @max_bytes = max_bytes
+      @require_signature = require_signature
+      @clock = clock || -> { Time.now.to_f }
+    end
+
+    def call(env, path)
+      unless authorised?(env)
+        return json(401, { 'ok' => false, 'error' => 'bad or missing bearer token' })
+      end
+      # `attach` is merged in here rather than kept in `Store`, because the store
+      # holds what this *manifest* has done and these are facts about how this
+      # process was assembled — and because a Store that reached into `Auto`
+      # would be a Store that cannot be constructed in a suite that never loads
+      # it. Additive, and safe to be: the engine spreads whatever this endpoint
+      # answers (`engine.fix.origin.status`, `{"ok": True, "installed": True,
+      # **payload}`), and `middleware/php/src/Store.php:762-776`'s `runtime`
+      # block is the precedent — a package reports the failures only its own
+      # runtime can have, under a name that says what they mean.
+      #
+      # The one it exists for: `attach.built == 0` on a Rails process means the
+      # Railtie mounted us and the `RUBYOPT` hook never fired, which until
+      # 2 Sep 2026 was the *normal* state under Puma and was reported nowhere.
+      if path == STATUS_PATH
+        return json(200, @store.status.merge('attach' => Findxpand.attach_report))
+      end
+
+      # Anything but POST on the manifest path. Worded as an instruction rather
+      # than a refusal because the request that lands here most often is a human
+      # with a browser checking whether the install worked.
+      unless env['REQUEST_METHOD'] == 'POST'
+        return json(405, { 'ok' => false, 'error' => 'POST a manifest here' })
+      end
+
+      store_manifest(env)
+    end
+
+    private
+
+    # Constant-time, and a length mismatch answers false rather than raising.
+    #
+    # An empty configured token can never authorise: without this the gem would
+    # ship an open manifest endpoint to anybody who installed it and forgot to
+    # set `FINDXPAND_TOKEN`, since `'' == ''` is true.
+    def authorised?(env)
+      return false if @token.empty?
+
+      Signature.secure_compare(bearer(env), @token)
+    end
+
+    def bearer(env)
+      header = env['HTTP_AUTHORIZATION'].to_s
+      header.start_with?('Bearer ') ? header[7..].to_s : ''
+    end
+
+    def store_manifest(env)
+      raw = read_body(env)
+      return json(400, { 'ok' => false, 'error' => 'manifest too large' }) if raw.nil?
+
+      if @require_signature
+        reason = Signature.problem(env[Signature::SIGNATURE_ENV], env[Signature::TIMESTAMP_ENV],
+                                   raw, @token, now: @clock.call)
+        unless reason.empty?
+          # 401, not 400: this is an authentication failure, and a 400 would read
+          # as "our manifest was malformed" in our own logs.
+          return json(401, { 'ok' => false, 'error' => reason })
+        end
+      end
+
+      # The bytes arrive binary and are only ever interpreted as text here, after
+      # the signature has been checked over the bytes themselves. Doing it in the
+      # other order — parse, then re-serialise to verify — would reorder keys and
+      # reject every legitimate push.
+      text = raw.dup.force_encoding('UTF-8')
+      unless text.valid_encoding?
+        return json(400, { 'ok' => false, 'error' => 'manifest is not valid UTF-8' })
+      end
+
+      version = @store.replace(JSON.parse(text))
+      json(200, { 'ok' => true, 'version' => version })
+    rescue JSON::ParserError, ArgumentError => e
+      # `ArgumentError` is `Store#replace` refusing a payload that parsed but is
+      # not a manifest. Both are the sender's mistake and both are a 400.
+      json(400, { 'ok' => false, 'error' => e.message })
+    end
+
+    # The raw bytes, unparsed, or `nil` when the push is over the limit.
+    #
+    # Read with a cap rather than trusting `CONTENT_LENGTH`: the header is what
+    # the sender claims and the cap is what we will actually hold. Both are
+    # checked, because the header lets us refuse a large push without reading it
+    # and the cap catches a chunked one that declares no length at all.
+    def read_body(env)
+      declared = env['CONTENT_LENGTH'].to_s
+      return nil if !declared.empty? && declared.to_i > @max_bytes
+
+      input = env['rack.input']
+      # Rack 3 makes `rack.input` optional, and a GET that reached here has none.
+      return ''.b if input.nil?
+
+      # One byte past the limit, so "exactly at the limit" and "over it" are
+      # distinguishable without reading the rest of an enormous body.
+      raw = input.read(@max_bytes + 1).to_s
+      return nil if raw.bytesize > @max_bytes
+
+      raw
+    end
+
+    def json(status, payload)
+      body = JSON.generate(payload)
+      [status,
+       { 'content-type' => 'application/json',
+         'content-length' => body.bytesize.to_s,
+         'cache-control' => 'no-store',
+         'x-robots-tag' => 'noindex, nofollow' },
+       [body]]
+    end
+  end
+end