overseer-testing-protocol 0.1.0

data/docs/testing-control-protocol.md

@@ -0,0 +1,432 @@
+# Testing-control protocol v3
+
+Status: canonical framework-neutral wire specification. Testing-control v3 is
+the sole current testing-control protocol.
+
+The normative artifacts are:
+
+- [`../protocol/testing-control/v3/openapi.yaml`](../protocol/testing-control/v3/openapi.yaml)
+  for routes, methods, headers, media types, and response statuses;
+- [`../protocol/testing-control/v3/schema.json`](../protocol/testing-control/v3/schema.json)
+  for wire request and response envelopes;
+- [`../protocol/testing-control/v3/fixtures/`](../protocol/testing-control/v3/fixtures/)
+  for framework-neutral examples;
+- [`../protocol/testing-control/v3/conformance-case.schema.json`](../protocol/testing-control/v3/conformance-case.schema.json)
+  for trusted declarative backend scenarios; and
+- [`../protocol/testing-control/v3/conformance-report.schema.json`](../protocol/testing-control/v3/conformance-report.schema.json)
+  for bounded conformance diagnostic output.
+
+The OpenAPI document and wire schema take precedence if prose differs. The
+case and report formats support conformance; they are not additional
+testing-control protocols. The [framework-neutral implementation
+guide](./testing-control-implementation-guide.md) explains direct adoption.
+
+Requirement words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.
+
+## 1. Scope and non-goals
+
+Testing control is a test-only mechanism for:
+
+- discovering the exact protocol and safe product-owned capabilities;
+- witnessing application and test-environment identity;
+- returning a synthetic runtime to its declared baseline;
+- arranging allowlisted, schema-validated synthetic preconditions;
+- observing bounded, sanitized, read-only projections; and
+- querying bounded records captured by fake external-effect sinks.
+
+Testing control MUST NOT become a public business API, general database
+seeding language, factory API, model API, arbitrary query interface, command
+runner, workflow engine, authorization bypass, or replacement for the public
+OpenAPI contract. Public API calls and public workflow execution remain
+outside this protocol.
+
+The protocol calls product-owned state capabilities **arrangements** and
+product-owned probe and fake-sink capabilities **observations**. Their current
+wire route names remain `states`, `probes`, and `sinks`.
+
+## 2. Trust and deployment assumptions
+
+An implementation MUST expose testing control only inside a verified
+synthetic test environment. It MUST fail closed unless the backend's normal
+test-mode checks and the test runner's supplied runtime identity are valid.
+Authentication inside a production-capable environment is not a substitute.
+
+The runtime MUST use synthetic data, MUST omit real provider and user
+credentials, MUST NOT persist secrets, and MUST block or explicitly allowlist
+external network access. An implementation MUST NOT accept arbitrary commands,
+scripts, SQL, repository paths, runtime URLs, direct database operations, or
+credentials through any testing-control payload.
+
+The test runner owns runtime creation or explicit attachment, network containment,
+source and process verification, lifecycle cleanup, and evidence sanitization.
+The product owns its domain invariants, capability handlers, read-only
+projections, safe fields, and fake-effect interception.
+
+## 3. Transport and endpoints
+
+The backend and test client agree on one testing base path. Exactly
+these routes are relative to that base path:
+
+```text
+GET  /capabilities
+PUT  /reset
+POST /states
+POST /probes
+POST /sinks/query
+```
+
+Clients and servers MUST use HTTP over the already verified loopback origin.
+Testing-control redirects and arbitrary absolute targets are unsupported.
+Requests with bodies and all responses MUST use UTF-8 JSON with media type
+`application/json`. `GET /capabilities` and `PUT /reset` MUST have no body.
+Malformed JSON and a non-JSON request media type MUST fail as `invalid-request`
+with HTTP 400.
+
+An adapter MUST enforce its advertised `maxRequestBytes` and
+`maxResponseBytes`. It MUST reject an oversized request before executing a
+handler and MUST NOT construct or stream an unbounded response. Clients MUST
+use finite connection and response timeouts and MUST stop reading after the
+applicable byte limit. Exact client timeout values are runner policy, not wire
+semantics.
+
+Protocol envelopes are closed: fields not admitted by `schema.json` MUST be
+rejected. Product-owned capability payloads follow their advertised schemas;
+the product schema deliberately controls whether its own additional fields are
+allowed.
+
+## 4. Exact version negotiation
+
+Every request MUST carry:
+
+| Header                             | Requirement                                      |
+| ---------------------------------- | ------------------------------------------------ |
+| `Overseer-Testing-Control-Version` | Exact value `3`.                                 |
+| `Overseer-Run-Id`                  | Opaque valid identifier for the current attempt. |
+| `Overseer-Correlation-Id`          | Opaque valid identifier for this control call.   |
+
+`Overseer-Step-Id` MAY identify attributable setup or public-step context.
+`Overseer-Idempotency-Key` MAY be used for reset and MUST be used when an
+arrangement advertises required idempotency.
+
+Identifiers contain 1 through 128 ASCII characters, begin with a letter or
+digit, and then contain only letters, digits, `.`, `_`, `:`, or `-`.
+
+Every response, including an error, MUST set
+`Overseer-Testing-Control-Version: 3` and a valid
+`Overseer-Correlation-Id`. For a valid request correlation ID, the response
+MUST echo it. The body protocol member MUST be exactly:
+
+```json
+{
+  "name": "overseer-testing-control",
+  "version": "3"
+}
+```
+
+A request for any version other than `3` MUST return HTTP 409 with
+`protocol-version-unsupported`. It MUST NOT downgrade, dispatch to a legacy
+implementation, or serve a simultaneous v1/v2 compatibility path. Testing
+control v4 does not exist.
+
+## 5. Envelope identity
+
+Every normal request and successful response has `protocol`, `meta`, and
+`data`; every error has `protocol`, `meta`, and `errors`. `meta.runId` and
+`meta.correlationId` MUST match their headers. `meta.stepId` MUST be present
+and equal to its header when supplied and MUST otherwise be absent.
+
+When required identity headers are absent or invalid, an adapter MUST return a
+schema-valid safe error identity. Generated placeholder identifiers MAY be
+used; raw invalid values MUST NOT be echoed.
+
+## 6. Runtime identity and independently verified facts
+
+`GET /capabilities` owns these testing-control identity facts:
+
+- `data.application.id`: stable backend integration ID;
+- `data.application.version`: exact source identity injected into this
+  runtime;
+- `data.environment.id`: opaque environment ID injected by the runtime owner;
+- `data.environment.kind`: exact value `test`; and
+- `data.environment.isolated`: exact value `true` for a verified isolated
+  runtime.
+
+The test client MUST compare those values with the identities independently
+established when starting or attaching to the backend, before reset,
+arrangement, or observation. A mismatch is protocol nonconformance and MUST
+stop dependent stateful checks.
+
+Health status, loopback origin, source version resolution, whether the test
+runner created the process, container/network facts, and cleanup result are
+facts the runtime owner verifies independently. They MUST NOT be invented by the
+testing-control response or treated as product business evidence.
+
+## 7. Capability discovery
+
+`GET /capabilities` MUST return:
+
+- application and environment identity;
+- one reset strategy and its sink-clearing guarantee;
+- the required replay features;
+- size and record limits;
+- the safety declaration;
+- zero or more arrangement descriptors in `states`;
+- zero or more read-only observation descriptors in `probes`; and
+- zero or more fake-sink observation descriptors in `sinks`.
+
+The required features are `correlation-propagation`,
+`deterministic-replay`, `reset`, `schema-validation`, and `sink-clearing`.
+The safety declaration MUST require synthetic data, forbid real credentials
+and secret persistence, and declare external networking as `blocked` or
+`allowlisted`.
+
+Every capability is selected by an opaque product-owned `id` and positive
+decimal `version`. An `id@version` pair MUST be unique inside its family.
+The test client MUST NOT enumerate or interpret product capability names.
+
+Arrangement descriptors MUST advertise input and output JSON Schemas and an
+idempotency policy of `required`, `supported`, or `none`. Probe descriptors
+MUST advertise `readOnly: true` plus input and output schemas. Sink descriptors
+MUST advertise effect kinds, outcomes, a query-input schema, and a record
+payload schema.
+
+Advertised schemas MUST use JSON Schema Draft 2020-12, MUST have an object
+root, MUST fit `maxSchemaBytes`, MUST compile, and MUST use only local fragment
+references. The test client MUST NOT fetch an external schema URI supplied by a
+backend. The schemas remain product-owned and opaque even though the generic
+client validates values against them.
+
+## 8. Reset
+
+The advertised reset strategy is exactly `in-process` or `runtime-restart`.
+Both strategies MUST return the product to its declared synthetic baseline and
+MUST clear arrangement idempotency state and fake-sink records before the next
+run.
+
+For `in-process`, `PUT /reset` MUST return HTTP 200 with `resetAt`, matching
+strategy `in-process`, and `sinksCleared: true`. Repeating reset in the same
+isolated runtime MUST be safe and return the same declared baseline.
+
+For `runtime-restart`, `PUT /reset` MUST return HTTP 409 with
+`reset-requires-restart`. The runtime driver, not a product handler, recreates
+the isolated process and writable data, repeats normal test setup and health
+verification, and negotiates capabilities again. The replacement MUST preserve
+application source identity, environment identity, protocol v3, and
+the declared reset strategy. An explicitly attached process cannot satisfy
+runtime-restart unless its owner supplies a verified restart callback.
+
+Reset failure MUST prevent later arrangements and observations that depend on
+a clean baseline. Independent non-mutating protocol checks MAY continue.
+
+## 9. Arrangement
+
+`POST /states` selects one advertised arrangement:
+
+```json
+{
+  "protocol": { "name": "overseer-testing-control", "version": "3" },
+  "meta": {
+    "runId": "run-001",
+    "correlationId": "arrange-001",
+    "stepId": "setup-open-item"
+  },
+  "data": {
+    "capability": { "id": "open-item", "version": "1" },
+    "input": { "title": "Synthetic item" }
+  }
+}
+```
+
+The adapter MUST locate the exact advertised `id@version`, validate `input`
+against that descriptor's schema, execute only the registered product-owned
+handler, validate the output, and return the same capability reference plus
+bounded canonical identifiers and output. Product execution remains opaque to
+the client.
+
+An unknown capability MUST return HTTP 404 with `capability-not-found`. A
+schema-invalid input MUST return HTTP 422 with `schema-validation-failed`.
+Required idempotency MUST fail when its header is absent. Retrying an unchanged
+key and input MUST NOT create a second logical arrangement; reusing a key with
+different input MUST fail safely.
+
+An arrangement is setup, not a public product mutation or evidence that a
+consumer can create the same state.
+
+## 10. Observation
+
+`POST /probes` selects one advertised read-only probe, validates its input,
+executes only its registered product-owned observation, validates the result,
+and returns the same capability, `observedAt`, and a bounded `projection`.
+
+A probe MUST NOT mutate product state, enqueue work, or trigger an external
+effect. Unknown probes and invalid inputs use the same 404 and 422 behavior as
+arrangements.
+
+`POST /sinks/query` selects one advertised fake sink. It MUST require a public
+correlation filter and MAY narrow by step, advertised effect kind, capture
+time, opaque cursor, and bounded limit. Product query input and each record's
+payload MUST satisfy the advertised schemas. Record count and bytes MUST fit
+the negotiated limits.
+
+Fake-sink records contain a safe summary and bounded product-owned payload.
+They prove only that the contained product adapter recorded an attempted
+effect; they never prove provider delivery.
+
+## 11. Error model
+
+Errors MUST use the schema-defined envelope and MUST NOT return an HTML
+framework exception page, stack trace, source path, SQL, model attributes,
+credentials, raw personal data, or an unlimited body.
+
+| HTTP | Code                           | Meaning                                                 |
+| ---- | ------------------------------ | ------------------------------------------------------- |
+| 400  | `invalid-request`              | Invalid headers, JSON, media type, or generic envelope. |
+| 404  | `capability-not-found`         | Exact capability ID/version is not advertised.          |
+| 409  | `protocol-version-unsupported` | Requested protocol is not version 3.                    |
+| 409  | `reset-requires-restart`       | Runtime driver must recreate the runtime.               |
+| 413  | `payload-too-large`            | A transport or advertised byte bound was exceeded.      |
+| 422  | `schema-validation-failed`     | Product-owned input violates its schema.                |
+| 422  | `limit-exceeded`               | A declared semantic or query limit was exceeded.        |
+| 500  | `internal-error`               | Sanitized unexpected adapter failure.                   |
+| 503  | `runtime-unavailable`          | Isolated test runtime cannot currently serve the call.  |
+
+Every error item MUST contain `code`, bounded `title`, bounded `detail`, and
+`retryable`. A safe JSON Pointer MAY identify a schema location; the invalid
+value MUST NOT be copied into the error.
+
+## 12. Lifecycle ordering
+
+For every runtime, the test client MUST:
+
+1. create or explicitly attach to the test runtime and verify its health;
+2. negotiate protocol v3 and validate runtime identity and capabilities;
+3. reset before arrangements for a run or case;
+4. execute declared arrangements;
+5. execute public API operations outside testing control;
+6. evaluate configured read-only observations; and
+7. let the runtime driver release or clean the runtime.
+
+To demonstrate ordinary API behavior, setup mutations belong before the public
+API sequence. Inserting testing-control mutations between its calls does not
+prove that the same result is reachable through the public API alone. The
+runtime owner is responsible for cleanup after the test.
+
+### Optional discovery snapshots
+
+A client can use the Ruby library's `Discovery.build` method to produce a
+stable snapshot and SHA-256 digest from an already validated capabilities
+response. This is useful for detecting a changed testing API when the client
+restarts a backend or reuses an earlier discovery result. It adds no HTTP route
+and requires no backend registration file.
+
+The current library retains protocol and application identity, including the
+source version; test/isolation kind; features, limits, safety and reset facts;
+and the advertised capabilities, including their titles, descriptions, schemas
+and behavioral flags. It excludes per-request metadata and the environment
+instance ID, sorts set-like fields and capability families, and hashes a
+canonical JSON representation. Its limits are 128 entries per capability
+family and 256 KiB. The shared conformance runner requires the same digest
+after a runtime restart.
+
+Computing or storing a snapshot is a client implementation choice. Every client
+must still perform the live identity and capability checks required above.
+Discovery validates the advertised contract; behavioral tests are needed to
+check that its operations do what they promise.
+
+## 13. Safety, privacy, and evidence
+
+Clients and adapters MUST reject credentials according to the application and
+test runner's configured policy. Capability payloads MAY be used transiently for
+validation and execution, but conformance reports MUST NOT retain them.
+Reports MAY retain safe capability names and redacted, bounded advertised
+schemas.
+
+Response bodies, error messages, and evidence MUST be byte-bounded before
+persistence or presentation. Authorization headers, cookies, tokens,
+passwords, secrets, credentials, non-synthetic email addresses, and configured
+sensitive fields MUST be redacted. Invalid or raw framework responses MUST be
+omitted from persisted diagnostics.
+
+The test client MUST NOT decide product authorization or product outcome validity.
+Those decisions remain in the product and its public API.
+
+## 14. Extensibility
+
+A product MAY add a new capability without changing the test client. It does so
+by registering an opaque capability name/version, advertising bounded Draft
+2020-12 input and output schemas, and implementing its product-owned handler.
+Incompatible capability semantics require a new capability version, not a
+testing-control protocol version.
+
+An implementation MAY use an optional framework adapter or implement the HTTP
+contract directly. No official helper is required for discovery, execution,
+or conformance.
+
+## 15. Black-box conformance
+
+The shared runner checks an implementation through HTTP calls to testing-control
+routes. It does not import an adapter, inspect backend source, connect to a
+database, call factories or models, or execute backend commands.
+
+In package `0.1.0`, core checks cover discovery, exact version behavior, runtime
+identity, advertised capability schemas, reset responses, unknown arrangements
+and probes, malformed JSON, invalid request media types, structured errors,
+response formats and raw-exception exclusion. A product-input rejection check
+uses the first advertised state only when its schema rejects an empty object.
+The client enforces response byte limits and finite timeouts on its requests;
+it does not exhaustively test the backend's request-size enforcement.
+Independent safe checks continue after a mismatch. Stateful capability cases
+run only after discovery and capability validation succeed and the reset check
+passes.
+
+The current runner does not call `/sinks/query`, check idempotent retries, or
+verify that reset actually erased captured records or application data. For
+an in-process reset it validates the success response and `sinksCleared: true`
+declaration. It also does not prove that probes have no side effects. These
+protocol requirements still apply; application request and end-to-end tests
+must supply the missing behavioral evidence. A passing report describes the
+checks performed, not exhaustive compliance with this specification.
+
+The caller MAY supply a trusted, checked-in case file. The standalone CLI
+loads that file as bounded JSON. Selection of the file and isolation of the
+target belong to the caller; the file cannot execute commands. The case format permits only bounded arrangement and
+probe data, top-level probe input bindings from returned
+arrangement identifiers, and a JSON subset or JSON Schema assertion. It rejects
+commands, scripts, SQL, credentials, repository paths, runtime URLs, and
+arbitrary executable fields.
+
+Expected-subset assertions use one shared recursive JSON matcher. Expected
+objects are key subsets: every expected key must be present and recursively
+match, while additional actual object keys are allowed. Expected arrays are
+ordered exact-cardinality sequences: both arrays must have the same length and
+each expected element recursively matches the actual element at the same
+index. Object fields inside array elements may therefore be omitted from the
+declaration, but additional or missing array elements and different ordering
+fail. Empty arrays match only empty arrays.
+
+Parsed JSON scalars and null retain their existing value equality. The matcher
+does not coerce, stringify, convert, or apply truthiness; JSON numbers retain
+numeric equality. A missing object key is distinct from a present null, false,
+zero, empty string, empty object, or empty array. Protocol-envelope validation
+and advertised capability response-schema validation run before subset
+matching. This positional structural matcher has no wildcard, containment,
+unordered, predicate, transformation, or general assertion-language behavior.
+
+The standalone command in this repository attaches to one explicit loopback
+origin. It compares supplied application, source and environment identities
+before mutating data. `--allow-reset` is required because conformance resets
+synthetic data. It does not start or destroy runtimes. A `runtime-restart`
+adapter needs a caller that can recreate its runtime; the attached CLI reports
+that prerequisite as unmet.
+
+Exit codes: `0` passed, `4` nonconforming, `2` configuration failure, `3` invalid
+invocation. Passing conformance proves the observed HTTP behavior, not network
+containment, credential absence, or correctness of untested product effects.
+
+Spies are product-owned observations of internal events or calls. Expose their
+bounded, sanitized read-only projections through named `/probes` capabilities.
+There is no additional `/spies` route in v3. Sinks capture supported effects in
+place of real delivery and expose records through `/sinks/query`. A recorded
+intent before enqueue is not evidence of worker completion or provider delivery.
+Run identity partitions observations; it is not an authorization credential or
+a substitute for a separate runtime for concurrent test suites.

data/lib/overseer/testing_control/conformance/case_file.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'json_schemer'
+
+module Overseer
+  module TestingControl
+    module Conformance
+      module CaseFile
+        MAX_BYTES = 256 * 1024
+        MAX_DEPTH = 24
+        SCHEMA_PATH = File.expand_path(
+          '../../../../protocol/testing-control/v3/conformance-case.schema.json',
+          __dir__
+        )
+        FORBIDDEN_KEY = Regexp.new(
+          '(?:command|script|sql|credential|password|token|secret|authorization|runtimeurl|repositorypath)\\z',
+          Regexp::IGNORECASE
+        )
+        FORBIDDEN_VALUE = %r{
+          (?:\A|\s)(?:https?|file)://|
+          \bBearer\s+|
+          \beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b|
+          (?:\A|\s)/(?:Users|home|etc|var|tmp)/|
+          \A\s*\#!|
+          \b(?:select\s+.+\s+from|insert\s+into|update\s+.+\s+set|delete\s+from|drop\s+table)\b
+        }ix
+
+        class Error < StandardError; end
+
+        module_function
+
+        def load(path)
+          source = File.binread(path, MAX_BYTES + 1)
+          parse(source, label: path)
+        rescue Errno::ENOENT, Errno::EACCES, Errno::EISDIR => e
+          raise Error, "Cannot read conformance case file: #{e.message}"
+        end
+
+        def parse(source, label: 'conformance case file')
+          raise Error, "Conformance case file exceeds #{MAX_BYTES} bytes" if source.bytesize > MAX_BYTES
+
+          document = JSON.parse(source)
+          errors = schemer.validate(document).take(5)
+          raise Error, "Invalid #{label}: #{details(errors)}" unless errors.empty?
+
+          validate_unique_ids!(document.fetch('cases'))
+          validate_safe_data!(document)
+          deep_freeze(document)
+        rescue JSON::ParserError => e
+          raise Error, "#{label.capitalize} is not valid JSON: #{e.message}"
+        end
+
+        def validate_schema!
+          schema = JSON.parse(File.read(SCHEMA_PATH, encoding: 'UTF-8'))
+          errors = JSONSchemer.validate_schema(schema).take(5)
+          raise Error, "Invalid conformance case schema: #{details(errors)}" unless errors.empty?
+
+          schema
+        end
+
+        def schemer
+          @schemer ||= JSONSchemer.schema(validate_schema!)
+        end
+        private_class_method :schemer
+
+        def validate_unique_ids!(cases)
+          duplicates = cases.group_by { |item| item.fetch('id') }.select { |_id, items| items.length > 1 }.keys
+          raise Error, "Duplicate conformance case IDs: #{duplicates.join(', ')}" unless duplicates.empty?
+        end
+        private_class_method :validate_unique_ids!
+
+        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def validate_safe_data!(value, depth = 0, field: nil)
+          raise Error, "Conformance case data exceeds nesting depth #{MAX_DEPTH}" if depth > MAX_DEPTH
+
+          case value
+          when Hash
+            value.each do |key, child|
+              if key.match?(FORBIDDEN_KEY)
+                raise Error,
+                      "Conformance case field #{key.inspect} is executable or sensitive"
+              end
+
+              validate_safe_data!(child, depth + 1, field: key)
+            end
+          when Array
+            value.each { |child| validate_safe_data!(child, depth + 1, field:) }
+          when String
+            return if field == '$schema' && value == 'https://json-schema.org/draft/2020-12/schema'
+
+            raise Error, 'Conformance case data contains a URL, path, credential, script, or SQL-like value' if
+              value.match?(FORBIDDEN_VALUE)
+          end
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        private_class_method :validate_safe_data!
+
+        def details(errors)
+          errors.map { |error| "#{error.fetch('data_pointer', '/')} #{error.fetch('type')}" }.join('; ')
+        end
+        private_class_method :details
+
+        def deep_freeze(value)
+          case value
+          when Hash
+            value.each do |key, child|
+              key.freeze
+              deep_freeze(child)
+            end
+          when Array
+            value.each { |child| deep_freeze(child) }
+          end
+          value.freeze
+        end
+        private_class_method :deep_freeze
+      end
+    end
+  end
+end

data/lib/overseer/testing_control/conformance/http_transport.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Overseer
+  module TestingControl
+    module Conformance
+      class HTTPTransport
+        Response = Data.define(:status, :headers, :body, :duration_ms)
+        OPEN_TIMEOUT_SECONDS = 2
+        READ_TIMEOUT_SECONDS = 10
+
+        attr_reader :origin
+
+        def initialize(origin:, base_path:)
+          @origin = self.class.origin!(origin)
+          @base_path = normalized_base_path(base_path)
+        end
+
+        def request(method:, path:, headers:, body:, max_response_bytes:)
+          uri = request_uri(path)
+          request = request_class(method).new(uri)
+          headers.each { |name, value| request[name] = value }
+          request.body = body unless body.nil?
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          response = perform(uri, request, max_response_bytes:)
+          response.with(duration_ms: elapsed_milliseconds(started))
+        rescue Net::OpenTimeout, Net::ReadTimeout
+          raise TimeoutError, 'Testing-control request exceeded its bounded timeout'
+        rescue ResponseTooLarge, Error
+          raise
+        rescue IOError, SystemCallError => e
+          raise ConnectionError, "Testing-control loopback request failed (#{e.class.name})"
+        end
+
+        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def self.origin!(value)
+          uri = URI.parse(value)
+          valid = uri.is_a?(URI::HTTP) && uri.scheme == 'http' && uri.host == '127.0.0.1' &&
+                  uri.authority&.match?(/:\d+\z/) && uri.port.between?(1, 65_535) && !uri.userinfo &&
+                  uri.path.empty? && !uri.query && !uri.fragment
+          raise Error, 'Conformance requires an explicit bare 127.0.0.1 HTTP origin' unless valid
+
+          uri.to_s
+        rescue URI::InvalidURIError
+          raise Error, 'Conformance requires an explicit bare 127.0.0.1 HTTP origin'
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+        private
+
+        def normalized_base_path(value)
+          unless value.is_a?(String) && value.start_with?('/') && !value.include?('?') && !value.include?('#')
+            raise Error, 'Testing-control base path must be an absolute path'
+          end
+
+          value.sub(%r{/+\z}, '')
+        end
+
+        def request_uri(path)
+          raise Error, 'Testing-control route must be a fixed absolute path' unless path.start_with?('/')
+
+          uri = URI.parse(origin)
+          uri.path = "#{@base_path}#{path}"
+          uri
+        end
+
+        def request_class(method)
+          {
+            get: Net::HTTP::Get,
+            put: Net::HTTP::Put,
+            post: Net::HTTP::Post
+          }.fetch(method)
+        rescue KeyError
+          raise Error, "Unsupported testing-control HTTP method #{method.inspect}"
+        end
+
+        def perform(uri, request, max_response_bytes:)
+          client = Net::HTTP.new(uri.host, uri.port, nil)
+          client.open_timeout = OPEN_TIMEOUT_SECONDS
+          client.read_timeout = READ_TIMEOUT_SECONDS
+          result = nil
+          client.request(request) do |response|
+            body = +''
+            response.read_body do |chunk|
+              if body.bytesize + chunk.bytesize > max_response_bytes
+                raise ResponseTooLarge, "Testing-control response exceeds #{max_response_bytes} bytes"
+              end
+
+              body << chunk
+            end
+            result = Response.new(
+              status: response.code.to_i,
+              headers: response.each_header.to_h,
+              body:,
+              duration_ms: nil
+            )
+          end
+          result || raise(ConnectionError, 'Testing-control loopback response was unavailable')
+        end
+
+        def elapsed_milliseconds(started)
+          ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(3)
+        end
+
+        class Error < StandardError; end
+        class TimeoutError < Error; end
+        class ResponseTooLarge < Error; end
+        class ConnectionError < Error; end
+      end
+    end
+  end
+end