path_coverage 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc1af74670e1171318d1d58fbd6a27f19b89c01ac95ee556f4e6bac3afa2bfbf
-  data.tar.gz: 2ecf0d75608a054914d31e426c77f75cc607ac578671a8e93fe4494efd040ea2
+  metadata.gz: 7146cc322217826aadc2bd040b560b5e77d6fad7b6de4d2ae43e8bdfaa893940
+  data.tar.gz: 29135bab12a1cc92d1a15dd8d383d3e79d75b3b8716fff7efa95fbbb6f8c3b34
 SHA512:
-  metadata.gz: 41b26c437c12f9b6aa7ab78d3a4a50a2fd532d2a8db0923813a059943fc0289d3421a78e754c633db0ea20962e42564031b98453c2e2ad6cb6d61cef81557ac8
-  data.tar.gz: 52b79781e54c09a07d1b6733ef3356ba8aac5cc87881fdb0303aae99842d2ef48cf00e555e29f11215fc8c1516986bf2f8bff02fdb5d539da3f48c0e688d1c79
+  metadata.gz: 4ebf32a5b048eb5d3d1b1cbbca0e2ed9c217e429481d1bd77a242f0a3baff83ee7b83a2b4a4cd99f6a6611885d1c165a56b6bd6f814be28c4cb6a92cffbc8282
+  data.tar.gz: 9ee6e1f2aea70b34ffb38ec5fa16a52f92ae5daf0a680727903db858fcdb557c244d0ae61a048e1a7bc09d99128c0b7068dd408686b2aca683b9f037afe3f6f3

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2026, [CyberDojo Foundation](http://blog.cyber-dojo.org/2015/08/cyber-dojo-foundation.html)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,353 @@
+# path_coverage
+
+[![Gem Version](https://img.shields.io/gem/v/path_coverage)](https://rubygems.org/gems/path_coverage)
+[![Downloads](https://img.shields.io/gem/dt/path_coverage)](https://rubygems.org/gems/path_coverage)
+[![License](https://img.shields.io/github/license/cyber-dojo/path_coverage)](LICENSE.md)
+
+Path coverage for Ruby, to run alongside SimpleCov's line and branch
+coverage.
+
+Gem: https://rubygems.org/gems/path_coverage (which shows the latest
+version).
+
+Status: sites cover `&&`, `||`, `and`, `or`, the ternary `?:`,
+`if`/`elsif`/`else` and `unless` (modifiers included), `case`/`when`
+with a subject, and the block methods `any?` `all?` `none?` `find`
+`detect` `find_index` `take_while` `select` `filter` `reject`
+`partition` `count` `filter_map`. Method paths cover `if` decisions.
+More decisions hidden inside calls come next (see Roadmap).
+
+Demo: https://cyber-dojo.github.io/path_coverage/ shows the HTML report
+for the mock source tree in `demo/`. `make demo` builds and opens the
+same report locally.
+
+Take this method:
+
+```ruby
+def fee(user, order)
+  total = 100
+  if user.member? && order.paid?
+    total -= 5
+  end
+  if order.big?
+    total -= 10
+  end
+  total
+end
+```
+
+Tests that run both `if`s both ways reach every line and every branch,
+so SimpleCov, which reads Ruby's built-in `Coverage`, reports 100%. Yet
+they can still miss paths, at two scopes, and path_coverage lists each
+path no test took.
+
+## Within each decision
+
+The first `if` can go three ways: member and paid, member and not
+paid, not a member. A member who has not paid may never have been
+tried.
+
+![The first if's grid: a column per way it can go, each headed by
+its count, the member who has not paid at 0](docs/decision.png)
+
+## Across a method's decisions
+
+The two `if`s can go four ways together. A paying member with a small
+order may never have been tried.
+
+![fee's grid: a column per way its two ifs can go together, each
+headed by its count, true then false at 0 and selected](docs/method.png)
+
+## Use
+
+```ruby
+# test coverage config, before any application code is required
+require 'simplecov'
+require 'path_coverage'
+SimpleCov.start do
+  # ...
+end
+PathCoverage.start do
+  root APP_DIR                 # cover globs and site names are relative to it
+  cover 'source/**/*.rb'       # each matching file is instrumented as it loads
+  coverage_dir '/tmp/coverage' # where path_coverage.json is written
+  measure :decisions, :methods # :decisions alone unless :methods is named
+  report :gaps, :html          # the reporters run at exit (default :gaps)
+end
+```
+
+A misspelt setting or an unknown reporter is refused by name, with the list
+of the ones there are. Calling `start` again replaces the configuration.
+
+A run whose code cannot be changed, such as a script in a `docker build`
+step, can be covered from its environment alone:
+
+```sh
+RUBYOPT=-rpath_coverage/auto
+PATH_COVERAGE_ROOT=/app                   # root
+PATH_COVERAGE_COVER=src/**/*.rb,lib/*.rb  # cover, comma-separated
+PATH_COVERAGE_DIR=/tmp/paths              # coverage_dir
+PATH_COVERAGE_COLLECTOR=http://host.docker.internal:4570/runs
+```
+
+This starts with `report :post`. With no `PATH_COVERAGE_COLLECTOR` it
+starts nothing and prints nothing, so an image can set `RUBYOPT` for every
+run and measure only those given a collector.
+
+The gem's `path_coverage_collector` command is that collector. It saves
+each report POSTed to it as a numbered file, and once every run is done
+they render as one report:
+
+```sh
+path_coverage_collector 4570 /tmp/paths/runs   # until sent TERM
+```
+
+- A report is saved before it is answered 200, so a 200 means it is on
+  disk. A report cut short, eg by a sender dying mid-send, is answered
+  400 and not saved. One that cannot be saved is answered 500.
+- `GET /alive` answers 200 while the collector runs.
+- `GET /ready` answers 200 when its dir is writable, 503 when not. Wait
+  for it before starting the runs.
+- On TERM it stops accepting connections, finishes the report in hand,
+  and exits 0.
+
+```ruby
+runs = Dir['/tmp/paths/runs/*.json']
+PathCoverage::Render.from_json(config, runs)
+```
+
+## What a run reports
+
+As the process exits:
+
+- `path_coverage.json` is always written to `coverage_dir`: every site
+  of every covered file, with each operand's true and false counts under
+  `sites`, and each site's paths under `paths`. It is the base the other
+  reporters read, so they can also be run later, in another process, from
+  it alone: `PathCoverage::Render.from_json(config)`, where `config` is a
+  `PathCoverage::Configuration` built from the same settings block.
+  Given several runs' reports, `Render.from_json(config, paths)` adds
+  their counts together first, so the report shows only the gaps that
+  every run left.
+- `:gaps` prints one line per path never taken, in manifest order: a
+  site's naming the outcome of each leaf on it, a method's the outcome
+  of each decision on it, by line:
+
+```text
+source/kata.rb:3:23 path never taken: `ok?(id)` true, `new?(id)` false
+source/kata.rb:4:24 never reached
+source/fee.rb:2:2 fee path never taken: line 4 true, line 7 false
+```
+
+### Decisions
+
+Measured always, as `:decisions`: the paths within each decision.
+
+A site is named by the `path:line:column` where it starts, the path
+relative to `root`. A site in a covered file the run never loaded is
+still reported, as `never reached`.
+
+A path is the outcome of each leaf one evaluation of the site reached, in
+order; a leaf that short-circuiting skipped is not on it. Each leaf is
+quoted as a Markdown code span, on one line, its fence one backtick longer
+than any run of backticks inside it. The gap lines are for people; a tool
+should read the JSON, whose `paths` give each site's leaves as
+`line:column` spans, and each possible path with its count:
+
+```json
+"paths": {
+  "source/kata.rb:3:23": {
+    "leaves": [["3:23", "3:30"], ["3:34", "3:42"]],
+    "taken": [
+      { "path": [true, true], "count": 2 },
+      { "path": [true, false], "count": 0 },
+      { "path": [false, null], "count": 1 }
+    ]
+  }
+}
+```
+
+A site is an outermost condition. Its leaves are numbered left to right
+across the whole of it, nested conditions included:
+
+```ruby
+ok?(id) && new?(id) && id.size == 6       # one && site, leaves 0 1 2
+ok?(id) && (new?(id) || id.size == 6)     # an || nested in an && site, 0 1 2
+ok?(id) && new?(id) || id.size == 6       # an && nested in an || site, 0 1 2
+ids.map { |k| k && k.ok? } && ok?(id)     # two sites: the block's is its own
+ok?(id) ? :ok : :no                       # a ?: site, its predicate leaf 0
+ok?(id) && new?(id) ? :ok : :no           # an && nested in a ?: site, 0 1
+ok?(id) ? new?(id) && id.size == 6 : :no  # one ?: site, its then arm 1 2
+```
+
+A ternary is a site even when its predicate is a single leaf. An arm
+holding a condition of `&&`, `||`, `and`, `or` or `?:` is part of the
+ternary's site, its leaves numbered after the predicate's, so the site's
+paths run through whichever arm the predicate picks. Any other arm, like a
+block, is not part of it, though a condition inside it is a site of its
+own.
+
+An `if` or an `unless`, a modifier included, is a site too, even when
+its predicate is a single leaf: its predicate nests in it, an `&&` there
+being no site of its own, and its `then` and `else` arms are plain, as
+they are statements; an `unless` takes its `then` arm when its predicate
+is false. It is named at its keyword, and its extent is its keyword to
+the end of its predicate, so a site inside an arm keeps its own button.
+An `elsif` is a site of its own.
+
+A `case` with a subject is a site whose leaves are its `when` patterns,
+tried in order until one matches. Each pattern is wrapped in a stand-in
+whose `===` calls the pattern's `===` once, exactly as the `case` would,
+and notes whether it matched. A `case` with no subject, or with a splat
+among its patterns, is no site.
+
+A call to a block method, with no arguments and a block of one
+expression, is a site named at its method. Its two leaves are its
+receiver, showing how many items its block was called with (`0 items`,
+`1 item` or `2+ items`), and its block's expression: for `any?` `all?`
+`none?` `find` `detect` `find_index` and `take_while`, which stop once
+their block decides, its last answer; for `select` `filter` `reject`
+`partition` `count` and `filter_map`, which call it with every item,
+whether its answers were `all true`, `all false` or `both`. Both are
+noted from the block's own calls, so the receiver is never asked for its
+size, which could consume a sequence that can be read only once.
+
+A chain of one operator is flat; a change of operator, by precedence or by
+parentheses, nests. Parentheses are not part of the tree, since they decide
+nothing.
+
+A leaf whose form allows one outcome only needs only to be evaluated: a
+path needing its other outcome is impossible, not a gap. `Foo.new`,
+literals (`'s'`, `1`, `:k`, `[]`, `{}`, `true`) and lambdas can only be
+truthy, as can `$stdout` and `$stderr`, which Ruby refuses to set to nil
+or false. Other globals, `$stdin` among them, can be either, as can
+constants, since one can hold nil or false (`VERBOSE = false`). `nil` and
+`false` can only be falsy:
+
+```ruby
+@clock = options[:clock] || MonotonicClock.new  # leaf 1: never evaluated, or no gap
+```
+
+### Methods
+
+With `measure :decisions, :methods`, each method with two or more
+decisions also counts each call's path through them: the outcome of each
+decision it reached, in order. A method is named by the `path:line:column`
+of its `def`, then its name. Each decision is one outcome on the path,
+however many leaves its predicate has; those are its site's to show. So a
+site's columns stay its own leaves' combinations, and a method's its own
+decisions', rather than multiplying together. A decision whose arm always
+leaves the method ends the path there.
+
+### Reporters
+
+- `:html` writes `index.html` to `coverage_dir`: the covered files with
+  their sites and their paths taken of all possible, within each decision
+  and, when `:methods` is measured, across a method's decisions (eg
+  `9 / 28 (32%)`, or `-` for a file with no method of two or more
+  decisions), each column sortable, and a Total row for every file
+  together. Each file name opens `files/<path>.html`, the file's
+  source. On a line holding a site the line number is a button (blue
+  and outlined when every outcome was seen, solid orange when any is
+  missing) that opens a grid of the site's paths, on the left. Its rows
+  are the site's tree: its operators, nested as Ruby groups them, a
+  ternary's arms marked `?` and `:`, an `if`'s named `then` and `else`,
+  and its leaves. Its columns are the site's paths, never taken first,
+  each headed by its count, orange when zero; a leaf shows its outcome on
+  each path, T or F, blank where the path never reached it, and a plain
+  arm a dot on each path that took it. A site written over several lines
+  has one button over all of its line numbers. Grids with gaps start
+  open. A header that stays at the top of the page lists every site as a
+  link to its line, covered sites first, then those with gaps, and arrows
+  beside each site with gaps jump to the previous and next one, wrapping
+  round at either end. Measuring paths, each method's grid of its
+  decisions' paths opens on the right.
+- `:post` sends the JSON report, as an HTTP POST, to the url set by
+  `collector 'http://...'`. It is for a run whose own files are thrown
+  away, such as a failing `docker build` step. It prints nothing, never
+  goes through an `http_proxy`, and gives up in silence on a collector
+  that cannot be reached or does not answer within a second, so the
+  run's output and exit status are unchanged.
+
+## How it works
+
+At load time each covered file is read and parsed once, with Prism. The
+parse gives the manifest: each site's condition tree and the byte range of
+each of its leaves. The rewriter then inserts a record call around each
+leaf, and a leave call around the whole site, whose first argument enters
+it, without parsing again, and the result is compiled in place of the
+file:
+
+```ruby
+ok?(id) && new?(id)
+# compiles as
+PathCoverage.leave(PathCoverage.enter("k.rb:2:2", 2), PathCoverage.record("k.rb:2:2", 0, ok?(id)) && PathCoverage.record("k.rb:2:2", 1, new?(id)))
+```
+
+An `if` site's leave call wraps its predicate alone, as its path is
+decided there, so an arm that returns or raises still counts it.
+Measuring paths, each method starts a path at its entry, and each
+decision's predicate is wrapped in a decide call too, outside its site's
+calls.
+
+A command call such as `ok? id` (after `and`) is not valid as a bare
+argument, so that leaf alone gets parentheses of its own, and so does a
+whole `and` or `or` inside its leave call. Nothing else does:
+parentheses make a statement, and a statement on a continuation line gives
+that line a line-coverage count of its own, which changes SimpleCov's line
+totals. So a command call, or an `and` or `or`, written over several lines
+can add to SimpleCov's relevant lines; nothing else does.
+
+`record` counts whether its value was truthy or falsy, and notes it on the
+site's current path; `enter` starts that path, and `leave` counts it.
+Each returns its value unchanged, so short-circuiting and the value of
+the expression are preserved. Paths are kept per fiber, so threads never
+mix their outcomes; an evaluation cut short by a raise counts no path,
+so no path is ever claimed that was not taken. Only text is inserted,
+never a newline, so backtrace line numbers still match the file. The
+rewrite happens in memory; no file on disk changes.
+
+At exit the manifests parsed during the run are reused; only covered files
+the run never loaded are read and parsed then.
+
+## Roadmap
+
+- decisions hidden inside calls, each with its own outcome classes:
+  - `one?`, whose last answer does not decide it, and block methods
+    with blocks of more than one expression
+  - `fetch(k, default)`, `dig`, `Hash#[]` with a default: present vs default
+  - `x || default` in value context, `&.` safe navigation: nil vs not nil
+  - `||=` and `&&=`, on variables, attributes and index targets: the
+    right side evaluated vs skipped, counted without evaluating the
+    target twice
+  - `x rescue y` modifier: raised vs not raised
+  - `case` with no subject, and `case`/`in` patterns
+  - regex matches: nil vs MatchData
+
+## Constraints
+
+- CRuby only: the hook is `RubyVM::InstructionSequence.load_iseq`.
+- Ruby 3.2 or later, for `String#bytesplice`.
+- That hook has a single slot, which Bootsnap also uses, so the two cannot
+  both be active in one process.
+
+## Development
+
+`make all` runs, in a Docker image built from the repo's `Dockerfile`:
+
+- `make lint`: rubocop over `lib/`, `test/` and `bin/` alike
+- `make test`: the tests, then a check that the coverage report has zero
+  missed lines and branches in both the code and the tests, within the
+  bounds in `test/coverage_metrics_params.json`
+  (`make test tids='6D1K'` runs only matching tests, and skips the check)
+- `make test_check`: shunit2 tests showing that a breached bound fails the
+  check with a non-zero exit
+
+`make demo` (not part of `make all`) runs `demo/run.rb` through
+`bin/build_demo.sh`, writing the report to `site/` and opening it. The
+Pages workflow (`.github/workflows/pages.yml`) runs the same script on
+each push to `main` and publishes `site/`.
+
+`bin/capture_readme_images.sh` rebuilds the demo and saves this README's
+two screenshots, `docs/decision.png` and `docs/method.png`, from it with
+headless Chrome. Run it again whenever the report's look changes.

data/exe/path_coverage_collector

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+require 'fileutils'
+require 'socket'
+require 'path_coverage/collector'
+
+if ARGV.first == '-h'
+  puts <<~HELP
+    Usage: path_coverage_collector PORT DIR
+
+    Listens on PORT and saves each JSON report the :post reporter
+    sends as DIR/run-0001.json, DIR/run-0002.json, and so on,
+    creating DIR if need be. A 200 means the report is saved.
+
+    GET /alive answers 200 while it runs.
+    GET /ready answers 200 when DIR is writable, 503 when not.
+
+    Runs until sent TERM. It then stops accepting connections,
+    finishes the report in hand, and exits 0.
+
+    Options:
+      -h    Show this help
+
+    Example:
+      path_coverage_collector 4570 /tmp/condition/runs
+  HELP
+  exit 0
+end
+
+port, dir = ARGV
+FileUtils.mkdir_p(dir)
+server = TCPServer.new('0.0.0.0', Integer(port))
+# Closing the server on TERM makes serve return once the
+# report in hand, if any, is saved and answered. The close
+# runs in a thread of its own, as the trap runs on the thread
+# that may be waiting in accept, where a close deadlocks.
+Signal.trap('TERM') { Thread.new { server.close } }
+PathCoverage::Collector.serve(server, dir)

data/lib/path_coverage/auto.rb

@@ -0,0 +1,5 @@
+require_relative 'kernel'
+
+# Required by RUBYOPT=-rpath_coverage/auto, to cover a run
+# with no change to its code, its settings all in ENV.
+PathCoverage.start_from_env(ENV)

data/lib/path_coverage/calls.rb

@@ -0,0 +1,67 @@
+# The calls rewritten code makes, each handed to the kernel's
+# one recorder. Like the kernel, this file loads before any
+# covered file and is never itself instrumented.
+module PathCoverage
+  # The call rewritten code makes around each operand; returns
+  # value unchanged.
+  def self.record(site, index, value)
+    @recorder.record(site, index, value)
+  end
+
+  # The call rewritten code makes before a site's first leaf,
+  # site having size leaves; returns the evaluation's trail.
+  def self.enter(site, size)
+    @recorder.enter(site, size)
+  end
+
+  # The call rewritten code makes around a site as a whole,
+  # with the trail enter gave it; returns value unchanged.
+  def self.leave(trail, value)
+    @recorder.leave(trail, value)
+  end
+
+  # The call rewritten code makes around a case's pattern, the
+  # index-th of size at site; returns the pattern's stand-in.
+  def self.when_match(site, index, size, pattern)
+    @recorder.when_match(site, index, size, pattern)
+  end
+
+  # The call rewritten code makes before a block method's call
+  # at site runs; returns the evaluation's trail.
+  def self.enter_items(site)
+    @recorder.enter_items(site)
+  end
+
+  # The call rewritten code makes around a block method's
+  # block's expression at site; returns value unchanged.
+  def self.item(site, value)
+    @recorder.item(site, value)
+  end
+
+  # The call rewritten code makes around the block's expression
+  # of a block method that calls it with every item; returns
+  # value unchanged.
+  def self.answer(site, value)
+    @recorder.answer(site, value)
+  end
+
+  # The call rewritten code makes around a block method's call
+  # as a whole, with the trail enter_items gave it; returns
+  # value unchanged.
+  def self.leave_items(trail, value)
+    @recorder.leave_items(trail, value)
+  end
+
+  # The call rewritten code makes as a call reaches its
+  # method's first decision; returns the call's new path.
+  def self.path(site, size)
+    @recorder.path(site, size)
+  end
+
+  # The call rewritten code makes around each decision's
+  # predicate, with exits for one whose arm leaves the method;
+  # returns value unchanged.
+  def self.decide(path, index, value, exits = nil)
+    @recorder.decide(path, index, value, exits)
+  end
+end

data/lib/path_coverage/collector.rb

@@ -0,0 +1,112 @@
+module PathCoverage
+  # Receives the JSON reports the :post reporter sends, so the
+  # runs that sent them, eg failing docker build steps, can
+  # be merged and rendered once they are all done.
+  module Collector
+    # Answers every request on server until server is closed,
+    # then returns.
+    # Each report is saved in dir as run-0001.json,
+    # run-0002.json, and so on, in the order they arrive.
+    # A connection sending no request is skipped.
+    def self.serve(server, dir)
+      n = 0
+      while (client = accept(server))
+        saved = receive(client, dir) do |body|
+          save(dir, format('run-%<n>04d.json', n: n + 1), body)
+        end
+        n += 1 if saved
+      end
+    end
+
+    # The next connection to server; nil once server is closed,
+    # which is how serve is told to return.
+    def self.accept(server)
+      server.accept
+    rescue IOError
+      nil
+    end
+
+    # Saves body as dir/name whole or not at all: it is written
+    # to name.tmp and renamed, so a collector stopped mid-write
+    # leaves no partial report under a run's name.
+    def self.save(dir, name, body)
+      path = "#{dir}/#{name}"
+      File.write("#{path}.tmp", body)
+      File.rename("#{path}.tmp", path)
+    end
+
+    # Hands the body of the one HTTP request on client to the
+    # block, which saves it, and returns whether it was saved.
+    # dir is where reports are saved, which GET /ready checks.
+    # A client that closes without sending a request, eg a
+    # check that the collector is up, is closed unanswered and
+    # nothing is saved.
+    def self.receive(client, dir, &)
+      headers = []
+      while (line = client.gets) && line != "\r\n"
+        headers << line
+      end
+      saved = !headers.empty? && respond(client, headers, dir, &)
+      client.close
+      saved
+    end
+
+    # The check each GET path makes of the collector's dir.
+    # GET /alive passes whenever the collector answers.
+    # GET /ready passes only when dir is a writable directory,
+    # so a report sent now could be saved.
+    PROBES = {
+      '/alive' => ->(_dir) { true },
+      '/ready' => lambda do |dir|
+        File.directory?(dir) && File.writable?(dir)
+      end
+    }.freeze
+
+    # Answers the request with headers on client, and returns
+    # whether a report was saved in dir.
+    # A GET of a path in PROBES is answered 200 when its check
+    # passes, 503 when not. Nothing is saved for it.
+    # Any other request is a report, handed to answer.
+    def self.respond(client, headers, dir, &)
+      probe = PROBES[headers.first[/\AGET (\S+) /, 1]]
+      return answer(client, headers, &) if probe.nil?
+
+      up = probe.call(dir)
+      reply(client, up ? '200 OK' : '503 Service Unavailable')
+      false
+    end
+
+    # Reads the body of a request with headers from client and
+    # yields it to be saved. Returns whether it was saved.
+    # The 200 is sent only once it is saved.
+    # So a 200 always means the report is on disk.
+    # A body shorter than its Content-Length is answered 400.
+    # Eg its sender died mid-send. It is not saved.
+    # A save that fails is answered 500.
+    def self.answer(client, headers)
+      length = content_length(headers)
+      body = client.read(length).to_s
+      whole = body.bytesize == length
+      yield body if whole
+      reply(client, whole ? '200 OK' : '400 Bad Request')
+      whole
+    rescue SystemCallError
+      reply(client, '500 Internal Server Error')
+      false
+    end
+
+    # The byte length headers give the request's body; 0 when
+    # they give none.
+    def self.content_length(headers)
+      headers.sum do |line|
+        name, value = line.split(':', 2)
+        name.casecmp?('content-length') ? value.to_i : 0
+      end
+    end
+
+    # Writes an HTTP response of status, with no body, to client.
+    def self.reply(client, status)
+      client.write("HTTP/1.1 #{status}\r\nContent-Length: 0\r\n\r\n")
+    end
+  end
+end