perchfall 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5547f2ac3310d1069229f015c558e1c13d2f21883feee453c0f80fd87ea00c80
+  data.tar.gz: 2e4a1d91838b8b97609c718cdad6cbe6d94ee6b577c7c165356eaef3d3e740b7
+SHA512:
+  metadata.gz: bd5fc98a14b893767c4bb50aa943b7d0fff41211d06f83089a4a95c7545270e82be02a2761cdfe5643cc5812c92ddabf5260a18160ea99d84ec08376f3cd7741
+  data.tar.gz: 2d354eb422ec3196af811201422de3d0323dcdab30a6fc46fe7c7cd422fbd1874e06be0736c9da2f919173588c019140bdaf20a5834d0b5eccd6ca3e7635e4c8

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-17
+
+### Added
+
+- `Perchfall.run(url:)` — primary public API; returns an immutable `Report` value object
+- `bust_cache:` option (default `true`) appends a `_perchfall=<timestamp>` query parameter to prevent CDN and proxy caching from masking real page state; `report.url` always reflects the original caller URL, not the cache-busted one
+- `scenario_name:` option included in the report for labelling checks
+- `wait_until:` option (`load`, `domcontentloaded`, `networkidle`, `commit`) controls when Playwright considers navigation complete
+- `timeout_ms:` option (default 30 000, max 60 000) for Playwright navigation timeout
+- `Report` value object with `ok?`, `http_status`, `duration_ms`, `network_errors`, `console_errors`, `to_json`
+- `ignored_network_errors` / `ignored_console_errors` on `Report` — errors suppressed by ignore rules are captured, not silently dropped
+- Configurable ignore rules via `ignore:` — `IgnoreRule` supports substring, regex, and wildcard matching on URL/text and failure/type fields
+- Default ignore rule suppresses `net::ERR_ABORTED` (analytics beacons, cancelled prefetches)
+- Typed exception hierarchy: `PageLoadError` (with partial report), `ConcurrencyLimitError`, `InvocationError`, `ScriptError`, `ParseError`
+- Process-wide concurrency limiter (default 5 simultaneous Chromium instances) using Mutex + ConditionVariable — no spinning, slot always released
+- SSRF mitigations: scheme allowlist (`http`/`https` only), literal IP blocklist (loopback, link-local, RFC-1918), DNS resolution check; URL validation always runs against the effective URL sent to Playwright (post cache-bust)
+- Full dependency injection throughout — test suite runs in ~0.4 s with no browser, Node, or network required
+- GitHub Actions CI workflow (unit suite) and manual Playwright smoke check workflow
+
+[Unreleased]: https://github.com/beflagrant/perchfall/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/beflagrant/perchfall/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flagrant LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# Perchfall
+
+[![CI](https://github.com/beflagrant/perchfall/actions/workflows/ci.yml/badge.svg)](https://github.com/beflagrant/perchfall/actions/workflows/ci.yml)
+[![Playwright smoke check](https://github.com/beflagrant/perchfall/actions/workflows/playwright.yml/badge.svg)](https://github.com/beflagrant/perchfall/actions/workflows/playwright.yml)
+
+**Synthetic browser monitoring for Ruby.** Give it a URL; get back a structured report of what a real Chromium browser saw — HTTP status, broken assets, JavaScript errors, and load time. No framework required.
+
+```ruby
+report = Perchfall.run(url: "https://example.com")
+
+report.ok?             # => true
+report.http_status     # => 200
+report.duration_ms     # => 834
+report.network_errors  # => []
+report.console_errors  # => []
+report.to_json         # => '{"status":"ok","url":"https://example.com",...}'
+```
+
+---
+
+## Why Perchfall
+
+**Uptime monitoring tells you a server is responding. Perchfall tells you the page actually works.**
+
+- A `200 OK` doesn't mean your JavaScript loaded.
+- An APM trace doesn't capture a missing CDN asset.
+- A health check endpoint doesn't know your checkout flow is broken.
+
+Perchfall runs a headless Chromium browser against your URL and gives you back everything it found: the HTTP status, every failed network request, every JavaScript error logged to the console, and how long it took. The result is an **immutable Ruby value object** you can store, log, or alert on — no database schema imposed, no framework lock-in.
+
+Drop it into a Sidekiq job, a Rake task, a CI step, or a plain Ruby script. It works anywhere Ruby runs.
+
+---
+
+## Requirements
+
+| Dependency | Version |
+| --- | --- |
+| Ruby | ≥ 3.2 |
+| Node | ≥ 18 |
+| Playwright | installed via npm |
+
+---
+
+## Installation
+
+```sh
+# 1. Add the gem
+bundle add perchfall
+
+# 2. Install Playwright (once per machine)
+npm install playwright
+npx playwright install chromium
+```
+
+---
+
+## Quickstart
+
+```ruby
+require "perchfall"
+
+report = Perchfall.run(url: "https://example.com")
+
+if report.ok?
+  puts "#{report.url} loaded in #{report.duration_ms}ms"
+else
+  puts "Page failed: #{report.network_errors.map(&:failure).join(", ")}"
+end
+```
+
+### Detect broken assets and JS errors
+
+```ruby
+report = Perchfall.run(url: "https://example.com")
+
+report.network_errors.each do |e|
+  puts "#{e.http_method} #{e.url} — #{e.failure}"
+end
+# GET https://example.com/assets/app.js — HTTP 404
+# GET https://cdn.example.com/font.woff — net::ERR_NAME_NOT_RESOLVED
+
+report.console_errors.each do |e|
+  puts "#{e.type}: #{e.text}"
+end
+# error: Uncaught ReferenceError: Stripe is not defined
+```
+
+A page can be `ok: true` (it loaded) and still have broken sub-resources. Perchfall captures both.
+
+### Handle page load failures
+
+```ruby
+begin
+  report = Perchfall.run(url: "https://example.com", timeout_ms: 10_000)
+rescue Perchfall::Errors::PageLoadError => e
+  # Page couldn't load at all — a partial report is always attached.
+  store_report(e.report.to_json)
+end
+```
+
+### Use in a background job
+
+```ruby
+class SyntheticCheckJob
+  include Sidekiq::Job
+
+  def perform(url)
+    report = Perchfall.run(url: url)
+    SyntheticResult.create!(ok: report.ok?, payload: report.to_json)
+  rescue Perchfall::Errors::PageLoadError => e
+    SyntheticResult.create!(ok: false, payload: e.report.to_json)
+  end
+end
+```
+
+---
+
+## What's in a report
+
+Every check returns a `Perchfall::Report`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `ok?` | Boolean | `true` if the page loaded successfully |
+| `http_status` | Integer / nil | HTTP response code |
+| `duration_ms` | Integer | Total time from navigation start to `load` event |
+| `url` | String | The URL checked |
+| `timestamp` | Time | When the check ran (UTC) |
+| `network_errors` | Array | Failed or errored network requests |
+| `console_errors` | Array | JavaScript errors logged to the browser console |
+| `to_json` | String | Full report as JSON |
+
+→ [Full report schema and JSON reference](docs/report-schema.md)
+
+---
+
+## Errors
+
+| Exception | When |
+| --- | --- |
+| `ArgumentError` | URL is invalid (bad scheme, internal address) |
+| `Perchfall::Errors::PageLoadError` | Page couldn't load; partial report attached at `e.report` |
+| `Perchfall::Errors::ConcurrencyLimitError` | All browser slots are busy; back off and retry |
+| `Perchfall::Errors::InvocationError` | Node isn't installed or not in PATH |
+| `Perchfall::Errors::Error` | Base class — catches any Perchfall error |
+
+→ [Full error handling guide](docs/error-handling.md)
+
+---
+
+## Configuration
+
+```ruby
+Perchfall.run(
+  url:           "https://example.com",
+  timeout_ms:    10_000,          # default 30_000, max 60_000
+  wait_until:    "domcontentloaded",  # default "load"
+  scenario_name: "homepage_smoke" # included in report JSON
+)
+```
+
+→ [All options and wait_until strategies](docs/configuration.md)
+
+---
+
+## Further reading
+
+- [Rails integration — Sidekiq job, schema, scheduling](docs/rails-integration.md)
+- [Security — SSRF protection, URL validation, ignore rules](docs/security.md)
+- [Architecture decisions](doc/adr/)
+
+---
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec    # ~0.4s, no browser or Node required
+bin/console          # IRB with perchfall loaded
+```
+
+---
+
+## License
+
+MIT

data/lib/perchfall/client.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Perchfall
+  # The primary entry point for library consumers.
+  #
+  # Usage (simple):
+  #   client = Perchfall::Client.new
+  #   report = client.run(url: "https://example.com")
+  #
+  # Usage (with options):
+  #   report = client.run(
+  #     url:           "https://example.com",
+  #     timeout_ms:    10_000,
+  #     scenario_name: "homepage_smoke"
+  #   )
+  #
+  # Usage (with custom invoker — testing or alternate runtimes):
+  #   client = Perchfall::Client.new(invoker: MyCustomInvoker.new)
+  #
+  # Client is intentionally thin. It owns the public method signature
+  # and delegates all real work to the invoker.
+  class Client
+    VALID_WAIT_UNTIL = %w[load domcontentloaded networkidle commit].freeze
+
+    def initialize(
+      invoker:   PlaywrightInvoker.new,
+      validator: UrlValidator.new,
+      limiter:   Perchfall.default_limiter
+    )
+      @invoker   = invoker
+      @validator = validator
+      @limiter   = limiter
+    end
+
+    # Run a synthetic browser check against the given URL.
+    #
+    # @param url [String] the URL to check (required, must be http or https)
+    # @param timeout_ms [Integer] ms before Playwright gives up (default 30_000)
+    # @param scenario_name [String, nil] optional label included in the report
+    # @param timestamp [Time] override the run timestamp (default Time.now.utc)
+    # @return [Report] on success
+    # @raise [ArgumentError] if the URL is not http/https
+    # @raise [Errors::ConcurrencyLimitError] if the concurrency cap is reached
+    # @raise [Errors::InvocationError] if Node could not be started
+    # @raise [Errors::ScriptError] if the Node script exited non-zero
+    # @raise [Errors::ParseError] if the script output was not valid JSON
+    # @raise [Errors::PageLoadError] if the page itself failed to load
+
+    def run(url:, ignore: [], wait_until: "load", timeout_ms: 30_000, scenario_name: nil, timestamp: Time.now.utc, bust_cache: true)
+      effective_url = bust_cache ? append_cache_buster(url) : url
+      @validator.validate!(effective_url)
+      validate_wait_until!(wait_until)
+      validate_timeout_ms!(timeout_ms)
+      merged_ignore = Perchfall::DEFAULT_IGNORE_RULES + ignore
+      @limiter.acquire do
+        @invoker.run(
+          url:           effective_url,
+          original_url:  url,
+          ignore:        merged_ignore,
+          wait_until:    wait_until,
+          timeout_ms:    timeout_ms,
+          scenario_name: scenario_name,
+          timestamp:     timestamp
+        )
+      end
+    end
+
+    private
+
+    def validate_wait_until!(value)
+      return if VALID_WAIT_UNTIL.include?(value)
+
+      raise ArgumentError,
+            "wait_until must be one of #{VALID_WAIT_UNTIL.join(", ")}. Got: #{value.inspect}"
+    end
+
+    def append_cache_buster(url)
+      separator = url.include?("?") ? "&" : "?"
+      "#{url}#{separator}_perchfall=#{Time.now.utc.to_i}"
+    end
+
+    MAX_TIMEOUT_MS = 60_000
+
+    def validate_timeout_ms!(value)
+      return if value.is_a?(Integer) && value > 0 && value <= MAX_TIMEOUT_MS
+
+      raise ArgumentError,
+            "timeout_ms must be a positive integer no greater than #{MAX_TIMEOUT_MS}. Got: #{value.inspect}"
+    end
+  end
+end

data/lib/perchfall/command_runner.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Perchfall
+  # Wraps Open3.capture3 behind an injectable interface.
+  #
+  # Interface contract (implement this to build a test fake):
+  #
+  #   result = runner.call(command)
+  #   result.stdout      # => String
+  #   result.stderr      # => String
+  #   result.success?    # => Boolean
+  #   result.exit_status # => Integer
+  #
+  # Always pass argv arrays, never shell strings — this prevents injection.
+  class CommandRunner
+    Result = Data.define(:stdout, :stderr, :exit_status) do
+      def success?
+        exit_status.zero?
+      end
+    end
+
+    def call(command)
+      stdout, stderr, status = Open3.capture3(*command)
+      Result.new(
+        stdout:      stdout,
+        stderr:      stderr,
+        exit_status: status.exitstatus
+      )
+    end
+  end
+end

data/lib/perchfall/concurrency_limiter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Perchfall
+  # Caps the number of Playwright browser processes that can run simultaneously.
+  #
+  # Uses a Mutex + ConditionVariable semaphore so threads block (up to
+  # timeout_ms) rather than spinning. The slot is always released in an
+  # ensure block so a raising caller cannot leak it.
+  #
+  # Usage:
+  #   limiter = ConcurrencyLimiter.new(limit: 5, timeout_ms: 10_000)
+  #   limiter.acquire { do_expensive_work }
+  #
+  # Raises Errors::ConcurrencyLimitError if timeout_ms elapses before a
+  # slot is available.
+  class ConcurrencyLimiter
+    DEFAULT_TIMEOUT_MS = 30_000
+
+    def initialize(limit:, timeout_ms: DEFAULT_TIMEOUT_MS)
+      @limit      = limit
+      @timeout_s  = timeout_ms / 1000.0
+      @count      = 0
+      @mutex      = Mutex.new
+      @condvar    = ConditionVariable.new
+    end
+
+    def acquire
+      acquire_slot!
+      begin
+        yield
+      ensure
+        release_slot!
+      end
+    end
+
+    def available_slots
+      @mutex.synchronize { @limit - @count }
+    end
+
+    private
+
+    def acquire_slot!
+      @mutex.synchronize do
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout_s
+
+        while @count >= @limit
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise Errors::ConcurrencyLimitError,
+                "Concurrency limit of #{@limit} reached; timeout of #{@timeout_s}s exceeded" if remaining <= 0
+
+          @condvar.wait(@mutex, remaining)
+        end
+
+        @count += 1
+      end
+    end
+
+    def release_slot!
+      @mutex.synchronize do
+        @count -= 1
+        @condvar.signal
+      end
+    end
+  end
+end

data/lib/perchfall/console_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Perchfall
+  # Immutable value object representing a browser console error message
+  # captured during a Playwright browser run.
+  ConsoleError = Data.define(:type, :text, :location) do
+    def to_h
+      { type: type, text: text, location: location }
+    end
+
+    def to_json(...)
+      to_h.to_json(...)
+    end
+  end
+end

data/lib/perchfall/error_filter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Perchfall
+  # Applies a unified list of IgnoreRule objects to both NetworkError and ConsoleError arrays.
+  #
+  # Rules are routed by target:
+  #   :network — applied only to NetworkError (matched on url + failure)
+  #   :console — applied only to ConsoleError (matched on text + type)
+  #   :all     — applied to both error types
+  class ErrorFilter
+    def initialize(rules:)
+      @network_rules = rules.select { |r| r.target == :network || r.target == :all }
+      @console_rules = rules.select { |r| r.target == :console || r.target == :all }
+    end
+
+    # @param errors [Array<NetworkError>]
+    # @return [Hash{Symbol => Array<NetworkError>}] with keys :kept and :ignored
+    def filter_network(errors)
+      partition(errors) { |e| @network_rules.any? { |r| r.match?(e.url, e.failure) } }
+    end
+
+    # @param errors [Array<ConsoleError>]
+    # @return [Hash{Symbol => Array<ConsoleError>}] with keys :kept and :ignored
+    def filter_console(errors)
+      partition(errors) { |e| @console_rules.any? { |r| r.match?(e.text, e.type) } }
+    end
+
+    private
+
+    def partition(errors, &should_ignore)
+      kept, ignored = errors.partition { |e| !should_ignore.call(e) }
+      { kept: kept, ignored: ignored }
+    end
+  end
+end

data/lib/perchfall/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Errors
+    # Base for all Perchfall errors. Rescue this to catch anything from the gem.
+    class Error < StandardError; end
+
+    # The Node/Playwright process could not be started.
+    # Cause: Node not installed, script path wrong, etc.
+    class InvocationError < Error; end
+
+    # The Node process ran but exited non-zero, or produced unparseable output.
+    # exit_status is exposed for callers that need to distinguish failure modes.
+    # stderr is intentionally not public — it may contain server filesystem paths,
+    # Node version strings, and stack traces that should not be surfaced to end users.
+    # Log stderr at the framework/application level using a rescue block if needed.
+    class ScriptError < Error
+      attr_reader :exit_status
+
+      def initialize(message, exit_status: nil, stderr: nil)
+        super(message)
+        @exit_status = exit_status
+        @stderr      = stderr
+      end
+
+      private
+
+      attr_reader :stderr
+    end
+
+    # The JSON the Node script produced was structurally invalid.
+    class ParseError < Error; end
+
+    # The concurrency limit was reached and the caller's timeout expired
+    # before a slot became available.
+    class ConcurrencyLimitError < Error; end
+
+    # The target URL was unreachable at the network/page level (Playwright
+    # reported status: "error"). Carries the partial Report so callers can
+    # inspect whatever was captured before failure.
+    class PageLoadError < Error
+      attr_reader :report
+
+      def initialize(report)
+        super("Page failed to load: #{report.url} — #{report.error}")
+        @report = report
+      end
+    end
+  end
+end

data/lib/perchfall/ignore_rule.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Perchfall
+  # Describes a single error suppression rule applicable to NetworkError,
+  # ConsoleError, or both.
+  #
+  # pattern - String (substring match) or Regexp matched against the primary field:
+  #           NetworkError#url or ConsoleError#text.
+  # type    - String (substring match), Regexp, or "*" (wildcard) matched against
+  #           the secondary field: NetworkError#failure or ConsoleError#type.
+  # target  - Symbol: :network, :console, or :all — which error type this rule applies to.
+  #
+  # A rule matches when both pattern and type match their respective values.
+  # The filter is responsible for routing rules to the correct error type via target.
+  IgnoreRule = Data.define(:pattern, :type, :target) do
+    # @param primary   [String] the primary field value (url or text)
+    # @param secondary [String] the secondary field value (failure or type)
+    def match?(primary, secondary)
+      pattern_matches?(primary) && type_matches?(secondary)
+    end
+
+    private
+
+    def pattern_matches?(value)
+      case pattern
+      when Regexp then pattern.match?(value)
+      else             value.include?(pattern)
+      end
+    end
+
+    def type_matches?(value)
+      case type
+      when "*"    then true
+      when Regexp then type.match?(value)
+      else             value.include?(type)
+      end
+    end
+  end
+end

data/lib/perchfall/network_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Perchfall
+  # Immutable value object representing a single failed network request
+  # captured during a Playwright browser run.
+  NetworkError = Data.define(:url, :http_method, :failure) do
+    def to_h
+      { url: url, method: http_method, failure: failure }
+    end
+
+    def to_json(...)
+      to_h.to_json(...)
+    end
+  end
+end

data/lib/perchfall/parsers/playwright_json_parser.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Perchfall
+  module Parsers
+    # Parses the raw JSON string produced by playwright/check.js into a Report.
+    #
+    # This is the only place where raw data becomes domain objects.
+    # No side effects — pure data transformation, fully unit-testable with strings.
+    class PlaywrightJsonParser
+      def initialize(filter: ErrorFilter.new(rules: []))
+        @filter = filter
+      end
+
+      def parse(raw_json, timestamp:, scenario_name: nil, original_url: nil)
+        data = JSON.parse(raw_json, symbolize_names: true)
+        build_report(data, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url)
+      rescue JSON::ParserError => e
+        raise Errors::ParseError, "Invalid JSON from Playwright script: #{e.message}"
+      end
+
+      private
+
+      def build_report(data, scenario_name:, timestamp:, original_url: nil)
+        net_filtered     = @filter.filter_network(parse_network_errors(data.fetch(:network_errors, [])))
+        console_filtered = @filter.filter_console(parse_console_errors(data.fetch(:console_errors, [])))
+
+        Report.new(
+          status:                 data.fetch(:status),
+          url:                    original_url || data.fetch(:url),
+          duration_ms:            data.fetch(:duration_ms),
+          http_status:            data[:http_status],
+          network_errors:         net_filtered[:kept],
+          ignored_network_errors: net_filtered[:ignored],
+          console_errors:         console_filtered[:kept],
+          ignored_console_errors: console_filtered[:ignored],
+          error:                  data[:error],
+          scenario_name:          scenario_name,
+          timestamp:              timestamp
+        )
+      rescue KeyError => e
+        raise Errors::ParseError, "Playwright JSON missing required field: #{e.message}"
+      end
+
+      def parse_network_errors(raw)
+        raw.map do |item|
+          NetworkError.new(
+            url:         item.fetch(:url),
+            http_method: item.fetch(:method),
+            failure:     item.fetch(:failure)
+          )
+        end
+      rescue KeyError => e
+        raise Errors::ParseError, "Malformed network_error entry: #{e.message}"
+      end
+
+      def parse_console_errors(raw)
+        raw.map do |item|
+          ConsoleError.new(
+            type:     item.fetch(:type),
+            text:     item.fetch(:text),
+            location: item.fetch(:location)
+          )
+        end
+      rescue KeyError => e
+        raise Errors::ParseError, "Malformed console_error entry: #{e.message}"
+      end
+    end
+  end
+end

data/lib/perchfall/playwright_invoker.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Perchfall
+  # Knows how to invoke the Playwright Node script and return a Report.
+  #
+  # Collaborators (all injectable):
+  #   runner      - responds to #call(argv_array) -> Result
+  #   parser      - responds to #parse(raw_json, **opts) -> Report
+  #   script_path - String path to playwright/check.js
+  #
+  # PlaywrightInvoker owns the command shape and error-promotion semantics.
+  # It does not know how to run a process (runner's job) or parse JSON (parser's job).
+  class PlaywrightInvoker
+    DEFAULT_SCRIPT_PATH = File.expand_path(
+      "../../playwright/check.js",
+      __dir__
+    ).freeze
+
+    def initialize(
+      runner: CommandRunner.new,
+      script_path: DEFAULT_SCRIPT_PATH
+    )
+      @runner      = runner
+      @script_path = script_path
+    end
+
+    def run(url:, timestamp:, timeout_ms: 30_000, wait_until: "load", scenario_name: nil, ignore: [], original_url: nil)
+      parser = build_parser(ignore)
+      result = execute(build_command(url: url, timeout_ms: timeout_ms, wait_until: wait_until))
+      report = parse(result, parser: parser, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url || url)
+      raise_if_page_load_error(report)
+      report
+    end
+
+    private
+
+    def build_parser(ignore_rules)
+      Parsers::PlaywrightJsonParser.new(filter: ErrorFilter.new(rules: ignore_rules))
+    end
+
+    def build_command(url:, timeout_ms:, wait_until:)
+      ["node", @script_path, "--url", url, "--timeout", timeout_ms.to_s, "--wait-until", wait_until]
+    end
+
+    def execute(command)
+      @runner.call(command)
+    rescue => e
+      raise Errors::InvocationError, "Could not start Node process: #{e.message}"
+    end
+
+    def parse(result, parser:, **opts)
+      unless result.success?
+        raise Errors::ScriptError.new(
+          "Playwright script exited with status #{result.exit_status}",
+          exit_status: result.exit_status,
+          stderr:      result.stderr
+        )
+      end
+
+      parser.parse(result.stdout, **opts)
+    end
+
+    def raise_if_page_load_error(report)
+      raise Errors::PageLoadError.new(report) unless report.ok?
+    end
+  end
+end

data/lib/perchfall/report.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Perchfall
+  # Immutable value object representing the full result of one synthetic check.
+  #
+  # Attributes:
+  #   status                 - String: "ok" or "error"
+  #   url                    - String: the checked URL
+  #   scenario_name          - String or nil: optional label for the check
+  #   timestamp              - Time: when the run was initiated
+  #   duration_ms            - Integer: wall-clock time of the browser run
+  #   http_status            - Integer or nil: HTTP response code, nil if page never loaded
+  #   network_errors         - Array<NetworkError>: failures not matched by any ignore rule
+  #   ignored_network_errors - Array<NetworkError>: failures suppressed by ignore rules
+  #   console_errors         - Array<ConsoleError>: errors not matched by any ignore rule
+  #   ignored_console_errors - Array<ConsoleError>: errors suppressed by ignore rules
+  #   error                  - String or nil: set only when status == "error"
+  class Report
+    attr_reader :status, :url, :scenario_name, :timestamp, :duration_ms,
+                :http_status, :network_errors, :ignored_network_errors,
+                :console_errors, :ignored_console_errors, :error
+
+    def initialize(
+      status:,
+      url:,
+      duration_ms:,
+      http_status:,
+      network_errors:,
+      console_errors:,
+      error:,
+      ignored_network_errors: [],
+      ignored_console_errors: [],
+      scenario_name: nil,
+      timestamp: Time.now.utc
+    )
+      @status                 = status.freeze
+      @url                    = url.freeze
+      @scenario_name          = scenario_name&.freeze
+      @timestamp              = timestamp
+      @duration_ms            = duration_ms
+      @http_status            = http_status
+      @network_errors         = network_errors.freeze
+      @ignored_network_errors = ignored_network_errors.freeze
+      @console_errors         = console_errors.freeze
+      @ignored_console_errors = ignored_console_errors.freeze
+      @error                  = error&.freeze
+      freeze
+    end
+
+    def ok?
+      status == "ok"
+    end
+
+    def to_h
+      {
+        status:         status,
+        url:            url,
+        scenario_name:  scenario_name,
+        timestamp:      timestamp.iso8601,
+        ok:             ok?,
+        http_status:    http_status,
+        duration_ms:    duration_ms,
+        network_errors:         network_errors.map(&:to_h),
+        ignored_network_errors: ignored_network_errors.map(&:to_h),
+        console_errors:         console_errors.map(&:to_h),
+        ignored_console_errors: ignored_console_errors.map(&:to_h),
+        error:          error
+      }
+    end
+
+    def to_json(...)
+      to_h.to_json(...)
+    end
+
+    def ==(other)
+      other.is_a?(Report) && to_h == other.to_h
+    end
+  end
+end

data/lib/perchfall/url_validator.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "uri"
+require "ipaddr"
+require "resolv"
+
+module Perchfall
+  # Validates that a URL is safe to pass to Playwright.
+  #
+  # Three checks are applied in order:
+  #   1. Scheme must be http or https.
+  #   2. Hostname must not be a known-internal literal address (literal IP or "localhost").
+  #   3. Hostname is resolved via DNS; any address in a blocked range is rejected.
+  #
+  # Check 3 shrinks the DNS rebinding window but does not eliminate it — a TOCTOU
+  # race remains between our resolution and Playwright's. Network-level egress
+  # filtering (security groups, firewall rules) is still required as the authoritative
+  # control when accepting untrusted URLs.
+  #
+  # The resolver: keyword argument is injectable for testing (pass a fake that
+  # responds to #getaddresses(hostname) → Array<String>).
+  class UrlValidator
+    PERMITTED_SCHEMES = %w[http https].freeze
+
+    # Blocked as exact hostname strings (case-insensitive).
+    BLOCKED_HOSTNAMES = %w[localhost].freeze
+
+    # Blocked IP ranges. Any literal IPv4 or IPv6 address falling within these
+    # ranges is rejected. Order does not matter; all are checked.
+    BLOCKED_RANGES = [
+      IPAddr.new("127.0.0.0/8"),       # IPv4 loopback
+      IPAddr.new("::1"),               # IPv6 loopback
+      IPAddr.new("169.254.0.0/16"),    # IPv4 link-local (incl. AWS metadata 169.254.169.254)
+      IPAddr.new("fe80::/10"),         # IPv6 link-local
+      IPAddr.new("10.0.0.0/8"),        # RFC-1918
+      IPAddr.new("172.16.0.0/12"),     # RFC-1918
+      IPAddr.new("192.168.0.0/16"),    # RFC-1918
+      IPAddr.new("0.0.0.0/8"),         # unroutable
+    ].freeze
+
+    def initialize(resolver: Resolv)
+      @resolver = resolver
+    end
+
+    def validate!(url)
+      uri = parse!(url)
+      assert_permitted_scheme!(uri, url)
+      assert_not_internal_host!(uri, url)
+      assert_not_internal_resolved_addresses!(uri, url)
+    end
+
+    private
+
+    def parse!(url)
+      URI.parse(url)
+    rescue URI::InvalidURIError
+      raise ArgumentError, "Invalid URL: #{url.inspect}"
+    end
+
+    def assert_permitted_scheme!(uri, url)
+      return if PERMITTED_SCHEMES.include?(uri.scheme)
+
+      raise ArgumentError,
+            "URL scheme #{uri.scheme.inspect} is not permitted. " \
+            "Only #{PERMITTED_SCHEMES.join(", ")} URLs are accepted. Got: #{url.inspect}"
+    end
+
+    def assert_not_internal_host!(uri, url)
+      host = uri.hostname.to_s.downcase
+
+      if BLOCKED_HOSTNAMES.include?(host)
+        raise ArgumentError, internal_error(url)
+      end
+
+      addr = parse_ip(host)
+      if addr && blocked_ip?(addr)
+        raise ArgumentError, internal_error(url)
+      end
+    end
+
+    def assert_not_internal_resolved_addresses!(uri, url)
+      host = uri.hostname.to_s
+      # Skip resolution for literal IPs — already checked in assert_not_internal_host!
+      return if parse_ip(host)
+
+      addresses = @resolver.getaddresses(host)
+      addresses.each do |address|
+        addr = parse_ip(address)
+        raise ArgumentError, internal_error(url) if addr && blocked_ip?(addr)
+      end
+    end
+
+    def parse_ip(host)
+      IPAddr.new(host)
+    rescue IPAddr::InvalidAddressError
+      nil
+    end
+
+    def blocked_ip?(addr)
+      BLOCKED_RANGES.any? { |range| range.include?(addr) }
+    end
+
+    def internal_error(url)
+      "URL resolves to an internal or reserved address and is not permitted. Got: #{url.inspect}"
+    end
+  end
+end

data/lib/perchfall/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Perchfall
+  VERSION = "0.1.0"
+end

data/lib/perchfall.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "perchfall/version"
+require_relative "perchfall/errors"
+require_relative "perchfall/network_error"
+require_relative "perchfall/console_error"
+require_relative "perchfall/report"
+require_relative "perchfall/ignore_rule"
+require_relative "perchfall/error_filter"
+require_relative "perchfall/command_runner"
+require_relative "perchfall/concurrency_limiter"
+require_relative "perchfall/url_validator"
+require_relative "perchfall/parsers/playwright_json_parser"
+require_relative "perchfall/playwright_invoker"
+require_relative "perchfall/client"
+
+# Perchfall — synthetic browser monitoring via Playwright.
+#
+# Quick start:
+#   report = Perchfall.run(url: "https://example.com")
+#   report.ok?          # => true
+#   report.http_status  # => 200
+#   report.to_json      # => '{"status":"ok",...}'
+#
+# For advanced use, inject collaborators:
+#   client = Perchfall::Client.new(invoker: MyInvoker.new)
+#   report = client.run(url: "https://example.com", scenario_name: "homepage_smoke")
+module Perchfall
+  # Errors suppressed by default on every run.
+  # ERR_ABORTED is a browser-side abort (analytics beacons, cancelled prefetches)
+  # and is never a signal of real page failure.
+  # Callers extend this list by passing ignore: to Perchfall.run or Client#run.
+  DEFAULT_IGNORE_RULES = [
+    IgnoreRule.new(pattern: //, type: "net::ERR_ABORTED", target: :network),
+  ].freeze
+
+  # Process-wide concurrency limiter. Caps simultaneous Chromium instances
+  # across all threads. Override by passing limiter: to Client.new.
+  #
+  # Lazily initialised so requiring the gem does not create threads or
+  # mutexes until the first actual run.
+  def self.default_limiter
+    @default_limiter ||= ConcurrencyLimiter.new(limit: 5)
+  end
+
+  # Convenience method. Equivalent to Perchfall::Client.new.run(url:, **opts).
+  # Creates a fresh Client (and thus a fresh PlaywrightInvoker) on each call —
+  # no shared state between invocations.
+  #
+  # @param url [String]
+  # @param opts [Hash] forwarded to Client#run
+  # @return [Report]
+  def self.run(url:, **opts)
+    Client.new.run(url: url, **opts)
+  end
+end

data/perchfall.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'lib/perchfall/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'perchfall'
+  spec.version       = Perchfall::VERSION
+  spec.authors       = ['Jim Remsik']
+  spec.email         = ['jim@beflagrant.com']
+
+  spec.summary       = 'Synthetic browser monitoring via Playwright'
+  spec.description   = <<~DESC
+    Run headless browser checks against a URL using Playwright and receive a
+    structured, immutable Ruby report object — framework-agnostic, no persistence.
+  DESC
+  spec.homepage      = 'https://github.com/beflagrant/perchfall'
+  spec.license       = 'MIT'
+  spec.metadata      = {
+    'source_code_uri' => 'https://github.com/beflagrant/perchfall',
+    'changelog_uri' => 'https://github.com/beflagrant/perchfall/blob/main/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/beflagrant/perchfall/issues',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.files = Dir[
+    'lib/**/*',
+    'playwright/**/*',
+    'README.md',
+    'CHANGELOG.md',
+    'LICENSE.txt',
+    'perchfall.gemspec'
+  ].reject { |f| File.directory?(f) }
+
+  spec.require_paths = ['lib']
+
+  # json is in stdlib but declared explicitly so bundler resolves it correctly
+  spec.add_dependency 'json', '>= 2.0'
+
+  spec.add_development_dependency 'rspec',      '~> 3.13'
+  spec.add_development_dependency 'rubocop',    '~> 1.70'
+  spec.add_development_dependency 'simplecov',  '~> 0.22'
+end

data/playwright/check.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// playwright/check.js
+//
+// Runs a single synthetic check against a URL using Playwright.
+// Writes one JSON object to stdout; exits 0 when JSON is trustworthy,
+// exits 1 only for infrastructure failures (Node crash, missing args) where
+// stdout cannot be trusted.
+//
+// Usage:
+//   node playwright/check.js --url https://example.com --timeout 30000
+
+"use strict";
+
+const { chromium } = require("playwright");
+const { parseArgs } = require("node:util");
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+const { values: args } = parseArgs({
+  options: {
+    url:        { type: "string" },
+    timeout:    { type: "string", default: "30000" },
+    "wait-until": { type: "string", default: "load" },
+  },
+  strict: true,
+});
+
+if (!args.url) {
+  process.stderr.write("Error: --url is required\n");
+  process.exit(1);
+}
+
+const TARGET_URL  = args.url;
+const TIMEOUT_MS  = parseInt(args.timeout, 10);
+const WAIT_UNTIL  = args["wait-until"];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildResult({ status, durationMs, httpStatus, networkErrors, consoleErrors, error }) {
+  return JSON.stringify({
+    status,
+    url:            TARGET_URL,
+    duration_ms:    durationMs,
+    http_status:    httpStatus  ?? null,
+    network_errors: networkErrors,
+    console_errors: consoleErrors,
+    error:          error ?? null,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function run() {
+  const startedAt      = Date.now();
+  const networkErrors  = [];
+  const consoleErrors  = [];
+  let   browser;
+
+  try {
+    browser = await chromium.launch({ headless: true });
+    const page = await browser.newPage();
+
+    // Collect failed network requests (4xx/5xx responses + connection failures).
+    page.on("requestfailed", (request) => {
+      networkErrors.push({
+        url:     request.url(),
+        method:  request.method(),
+        failure: request.failure()?.errorText ?? "unknown",
+      });
+    });
+
+    // Collect non-2xx/3xx responses as network errors too.
+    page.on("response", (response) => {
+      const status = response.status();
+      if (status >= 400) {
+        networkErrors.push({
+          url:     response.url(),
+          method:  response.request().method(),
+          failure: `HTTP ${status}`,
+        });
+      }
+    });
+
+    // Collect browser console errors.
+    page.on("console", (msg) => {
+      if (msg.type() === "error") {
+        const loc = msg.location();
+        consoleErrors.push({
+          type:     msg.type(),
+          text:     msg.text(),
+          location: loc ? `${loc.url}:${loc.lineNumber}:${loc.columnNumber}` : "",
+        });
+      }
+    });
+
+    const response = await page.goto(TARGET_URL, {
+      timeout:   TIMEOUT_MS,
+      waitUntil: WAIT_UNTIL,
+    });
+
+    const durationMs = Date.now() - startedAt;
+
+    process.stdout.write(buildResult({
+      status:        "ok",
+      durationMs,
+      httpStatus:    response ? response.status() : null,
+      networkErrors,
+      consoleErrors,
+      error:         null,
+    }));
+
+    process.exit(0);
+
+  } catch (err) {
+    // Page-level failure (timeout, DNS, etc.) — exit 0 so Ruby reads the JSON.
+    const durationMs = Date.now() - startedAt;
+
+    process.stdout.write(buildResult({
+      status:        "error",
+      durationMs,
+      httpStatus:    null,
+      networkErrors,
+      consoleErrors,
+      error:         err.message,
+    }));
+
+    process.exit(0);
+
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+// Infrastructure-level failure — stdout cannot be trusted, exit 1.
+run().catch((err) => {
+  process.stderr.write(`Unhandled error: ${err.stack ?? err.message}\n`);
+  process.exit(1);
+});

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: perchfall
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jim Remsik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.70'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.70'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: |
+  Run headless browser checks against a URL using Playwright and receive a
+  structured, immutable Ruby report object — framework-agnostic, no persistence.
+email:
+- jim@beflagrant.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/perchfall.rb
+- lib/perchfall/client.rb
+- lib/perchfall/command_runner.rb
+- lib/perchfall/concurrency_limiter.rb
+- lib/perchfall/console_error.rb
+- lib/perchfall/error_filter.rb
+- lib/perchfall/errors.rb
+- lib/perchfall/ignore_rule.rb
+- lib/perchfall/network_error.rb
+- lib/perchfall/parsers/playwright_json_parser.rb
+- lib/perchfall/playwright_invoker.rb
+- lib/perchfall/report.rb
+- lib/perchfall/url_validator.rb
+- lib/perchfall/version.rb
+- perchfall.gemspec
+- playwright/check.js
+homepage: https://github.com/beflagrant/perchfall
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/beflagrant/perchfall
+  changelog_uri: https://github.com/beflagrant/perchfall/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/beflagrant/perchfall/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Synthetic browser monitoring via Playwright
+test_files: []