perchfall 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5547f2ac3310d1069229f015c558e1c13d2f21883feee453c0f80fd87ea00c80
-  data.tar.gz: 2e4a1d91838b8b97609c718cdad6cbe6d94ee6b577c7c165356eaef3d3e740b7
+  metadata.gz: 86b85c771d240f7c1ac7c255c6882a1d7cd1c5da2eb242bb681327612f079ae5
+  data.tar.gz: 1f1281e0e17c1e5ec91c841bc271990c85c752a2a97c3c5980d631d943d71460
 SHA512:
-  metadata.gz: bd5fc98a14b893767c4bb50aa943b7d0fff41211d06f83089a4a95c7545270e82be02a2761cdfe5643cc5812c92ddabf5260a18160ea99d84ec08376f3cd7741
-  data.tar.gz: 2d354eb422ec3196af811201422de3d0323dcdab30a6fc46fe7c7cd422fbd1874e06be0736c9da2f919173588c019140bdaf20a5834d0b5eccd6ca3e7635e4c8
+  metadata.gz: b552f554e7843c489c0c46905800f2f6f8a69bd9b577502262d8dde9a99f4cbf5e23e3a268f908e879ea65aced9587abce86753658d0e878d439d6987a12f1b6
+  data.tar.gz: 4504904e4ea3a877f51ca6f07b2a86ea2030f5ed42ae8d3519a6d39b77da28869a4af95a9a19d64a02dba8aec39811928722e9857862dcdedd52045e38bbec62

data/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-19
+
+### Added
+
+- `cache_profile:` option on `Perchfall.run` — replaces `bust_cache:` with four named profiles:
+  - `:query_bust` (default) — appends `?_pf=<unix_timestamp>` to force a cold fetch
+  - `:warm` — no URL mutation, no extra headers; measures real-user warm-cache experience
+  - `:no_cache` — sets `Cache-Control: no-cache` on all requests (main document + sub-resources)
+  - `:no_store` — sets `Cache-Control: no-store, no-cache` and `Pragma: no-cache`
+  - Custom Hash form: `cache_profile: { headers: { "Cache-Control" => "max-age=0" } }`
+- `report.cache_profile` — cache profile is stored on the `Report` and included in `to_h` / `to_json`
+- `--headers` argument to `playwright/check.js` — extra HTTP headers applied via `page.setExtraHTTPHeaders`
+- `check.js` integration specs (15 examples, tagged `:js`); excluded from default run, opt-in via `RUN_JS_SPECS=true`
+- `check-js.yml` GitHub Actions workflow — runs automatically when `playwright/check.js` or its specs change; caches Playwright Chromium binary keyed on `package-lock.json`
+
+### Changed
+
+- Renamed cache-bust query parameter from `_perchfall=` to `_pf=` (shorter, less intrusive in logs)
+- Validation order: `cache_profile` → `wait_until` → `timeout_ms` → URL validation — invalid params now raise before the effective URL is built
+- `check.js` now writes a `status: "error"` JSON result (exit 0) for malformed or non-object `--headers` instead of crashing
+
+### Breaking Changes
+
+- `bust_cache:` keyword argument removed. Migrate: `bust_cache: false` → `cache_profile: :warm`; `bust_cache: true` → `cache_profile: :query_bust` (or omit — it is the default)
+- Cache-bust query parameter renamed from `_perchfall=` to `_pf=` — update any log filters or URL allow-lists
+
+### Security
+
+- Custom `cache_profile` headers validated against a `FORBIDDEN_HEADERS` denylist (`Authorization`, `Cookie`, `Set-Cookie`, `Host`, `X-Forwarded-For`, `X-Forwarded-Host`, `X-Real-IP`) — these cannot be injected via the custom Hash form
+
 ## [0.1.0] - 2026-03-17
 
 ### Added
@@ -26,5 +56,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
+[Unreleased]: https://github.com/beflagrant/perchfall/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/beflagrant/perchfall/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/beflagrant/perchfall/releases/tag/v0.1.0

data/README.md

@@ -2,6 +2,7 @@
 
 [![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)
+[![Gem Version](https://badge.fury.io/rb/perchfall.svg)](https://badge.fury.io/rb/perchfall)
 
 **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.
 
@@ -127,6 +128,7 @@ Every check returns a `Perchfall::Report`:
 | `duration_ms` | Integer | Total time from navigation start to `load` event |
 | `url` | String | The URL checked |
 | `timestamp` | Time | When the check ran (UTC) |
+| `cache_profile` | Symbol / nil | Cache profile used (`:query_bust`, `:warm`, `:no_cache`, `:no_store`) |
 | `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 |
@@ -154,13 +156,14 @@ Every check returns a `Perchfall::Report`:
 ```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
+  timeout_ms:    10_000,             # default 30_000, max 60_000
+  wait_until:    "domcontentloaded", # default "load"
+  scenario_name: "homepage_smoke",   # included in report JSON
+  cache_profile: :no_cache           # default :query_bust
 )
 ```
 
-→ [All options and wait_until strategies](docs/configuration.md)
+→ [All options, cache profiles, and wait_until strategies](docs/configuration.md)
 
 ---
 
@@ -176,8 +179,9 @@ Perchfall.run(
 
 ```sh
 bundle install
-bundle exec rspec    # ~0.4s, no browser or Node required
-bin/console          # IRB with perchfall loaded
+bundle exec rspec              # ~0.5s, no browser or Node required (208 examples)
+RUN_JS_SPECS=true bundle exec rspec  # includes check.js integration specs (223 examples)
+bin/console                    # IRB with perchfall loaded
 ```
 
 ---

data/lib/perchfall/client.rb

@@ -24,6 +24,26 @@ module Perchfall
   class Client
     VALID_WAIT_UNTIL = %w[load domcontentloaded networkidle commit].freeze
 
+    CACHE_PROFILES = {
+      query_bust: { bust_url: true,  headers: {}.freeze }.freeze,
+      warm:       { bust_url: false, headers: {}.freeze }.freeze,
+      no_cache:   { bust_url: false, headers: { "Cache-Control" => "no-cache" }.freeze }.freeze,
+      no_store:   { bust_url: false, headers: { "Cache-Control" => "no-store, no-cache", "Pragma" => "no-cache" }.freeze }.freeze
+    }.freeze
+
+    # Headers that could carry credentials, impersonate infrastructure, or
+    # manipulate routing. Rejected in custom cache profiles to prevent
+    # accidental or malicious injection into all page-load requests.
+    FORBIDDEN_HEADERS = %w[
+      authorization
+      cookie
+      set-cookie
+      host
+      x-forwarded-for
+      x-forwarded-host
+      x-real-ip
+    ].freeze
+
     def initialize(
       invoker:   PlaywrightInvoker.new,
       validator: UrlValidator.new,
@@ -48,22 +68,26 @@ module Perchfall
     # @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)
+    def run(url:, ignore: [], wait_until: "load", timeout_ms: 30_000, scenario_name: nil, timestamp: Time.now.utc, cache_profile: :query_bust)
+      profile = resolve_cache_profile!(cache_profile)
       validate_wait_until!(wait_until)
       validate_timeout_ms!(timeout_ms)
+      effective_url = profile[:bust_url] ? append_cache_buster(url) : url
+      @validator.validate!(effective_url)
       merged_ignore = Perchfall::DEFAULT_IGNORE_RULES + ignore
+      invoker_opts  = {
+        url:           effective_url,
+        original_url:  url,
+        ignore:        merged_ignore,
+        wait_until:    wait_until,
+        timeout_ms:    timeout_ms,
+        scenario_name: scenario_name,
+        timestamp:     timestamp,
+        cache_profile: cache_profile
+      }
+      invoker_opts[:extra_headers] = profile[:headers] unless profile[:headers].empty?
       @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
-        )
+        @invoker.run(**invoker_opts)
       end
     end
 
@@ -76,9 +100,32 @@ module Perchfall
             "wait_until must be one of #{VALID_WAIT_UNTIL.join(", ")}. Got: #{value.inspect}"
     end
 
+    def resolve_cache_profile!(profile)
+      if profile.is_a?(Symbol)
+        CACHE_PROFILES.fetch(profile) do
+          raise ArgumentError, "cache_profile must be one of #{CACHE_PROFILES.keys.join(", ")} or a Hash with :headers. Got: #{profile.inspect}"
+        end
+      else
+        headers = profile.fetch(:headers, {})
+        validate_custom_headers!(headers)
+        { bust_url: false, headers: headers }
+      end
+    end
+
+    def validate_custom_headers!(headers)
+      headers.each_key do |name|
+        if FORBIDDEN_HEADERS.include?(name.to_s.downcase)
+          raise ArgumentError,
+                "cache_profile contains a forbidden header: #{name.inspect}. " \
+                "Headers that carry credentials or influence routing (#{FORBIDDEN_HEADERS.join(", ")}) " \
+                "may not be set via cache_profile."
+        end
+      end
+    end
+
     def append_cache_buster(url)
       separator = url.include?("?") ? "&" : "?"
-      "#{url}#{separator}_perchfall=#{Time.now.utc.to_i}"
+      "#{url}#{separator}_pf=#{Time.now.utc.to_i}"
     end
 
     MAX_TIMEOUT_MS = 60_000

data/lib/perchfall/parsers/playwright_json_parser.rb

@@ -13,16 +13,16 @@ module Perchfall
         @filter = filter
       end
 
-      def parse(raw_json, timestamp:, scenario_name: nil, original_url: nil)
+      def parse(raw_json, timestamp:, scenario_name: nil, original_url: nil, cache_profile: nil)
         data = JSON.parse(raw_json, symbolize_names: true)
-        build_report(data, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url)
+        build_report(data, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url, cache_profile: cache_profile)
       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)
+      def build_report(data, scenario_name:, timestamp:, original_url: nil, cache_profile: 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, [])))
 
@@ -37,7 +37,8 @@ module Perchfall
           ignored_console_errors: console_filtered[:ignored],
           error:                  data[:error],
           scenario_name:          scenario_name,
-          timestamp:              timestamp
+          timestamp:              timestamp,
+          cache_profile:          cache_profile
         )
       rescue KeyError => e
         raise Errors::ParseError, "Playwright JSON missing required field: #{e.message}"

data/lib/perchfall/playwright_invoker.rb

@@ -24,10 +24,10 @@ module Perchfall
       @script_path = script_path
     end
 
-    def run(url:, timestamp:, timeout_ms: 30_000, wait_until: "load", scenario_name: nil, ignore: [], original_url: nil)
+    def run(url:, timestamp:, timeout_ms: 30_000, wait_until: "load", scenario_name: nil, ignore: [], original_url: nil, extra_headers: {}, cache_profile: 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)
+      result = execute(build_command(url: url, timeout_ms: timeout_ms, wait_until: wait_until, extra_headers: extra_headers))
+      report = parse(result, parser: parser, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url || url, cache_profile: cache_profile)
       raise_if_page_load_error(report)
       report
     end
@@ -38,8 +38,10 @@ module Perchfall
       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]
+    def build_command(url:, timeout_ms:, wait_until:, extra_headers: {})
+      cmd = ["node", @script_path, "--url", url, "--timeout", timeout_ms.to_s, "--wait-until", wait_until]
+      cmd += ["--headers", extra_headers.to_json] unless extra_headers.empty?
+      cmd
     end
 
     def execute(command)

data/lib/perchfall/report.rb

@@ -17,10 +17,11 @@ module Perchfall
   #   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"
+  #   cache_profile          - Symbol or nil: the cache profile used for this run
   class Report
     attr_reader :status, :url, :scenario_name, :timestamp, :duration_ms,
                 :http_status, :network_errors, :ignored_network_errors,
-                :console_errors, :ignored_console_errors, :error
+                :console_errors, :ignored_console_errors, :error, :cache_profile
 
     def initialize(
       status:,
@@ -33,7 +34,8 @@ module Perchfall
       ignored_network_errors: [],
       ignored_console_errors: [],
       scenario_name: nil,
-      timestamp: Time.now.utc
+      timestamp: Time.now.utc,
+      cache_profile: nil
     )
       @status                 = status.freeze
       @url                    = url.freeze
@@ -46,6 +48,7 @@ module Perchfall
       @console_errors         = console_errors.freeze
       @ignored_console_errors = ignored_console_errors.freeze
       @error                  = error&.freeze
+      @cache_profile          = cache_profile
       freeze
     end
 
@@ -66,7 +69,8 @@ module Perchfall
         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
+        error:          error,
+        cache_profile:  cache_profile
       }
     end
 

data/lib/perchfall/version.rb

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

data/playwright/check.js

@@ -23,6 +23,7 @@ const { values: args } = parseArgs({
     url:        { type: "string" },
     timeout:    { type: "string", default: "30000" },
     "wait-until": { type: "string", default: "load" },
+    headers:    { type: "string", default: "{}" },
   },
   strict: true,
 });
@@ -32,9 +33,34 @@ if (!args.url) {
   process.exit(1);
 }
 
-const TARGET_URL  = args.url;
-const TIMEOUT_MS  = parseInt(args.timeout, 10);
-const WAIT_UNTIL  = args["wait-until"];
+const TARGET_URL = args.url;
+const TIMEOUT_MS = parseInt(args.timeout, 10);
+const WAIT_UNTIL = args["wait-until"];
+
+let EXTRA_HEADERS;
+try {
+  const parsed = JSON.parse(args.headers);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new TypeError("--headers must be a JSON object, got: " + args.headers);
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    if (typeof value !== "string") {
+      throw new TypeError(`--headers value for "${key}" must be a string, got ${typeof value}`);
+    }
+  }
+  EXTRA_HEADERS = parsed;
+} catch (err) {
+  process.stdout.write(JSON.stringify({
+    status:         "error",
+    url:            TARGET_URL,
+    duration_ms:    0,
+    http_status:    null,
+    network_errors: [],
+    console_errors: [],
+    error:          "Invalid --headers: " + err.message,
+  }));
+  process.exit(0);
+}
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -66,6 +92,10 @@ async function run() {
     browser = await chromium.launch({ headless: true });
     const page = await browser.newPage();
 
+    if (Object.keys(EXTRA_HEADERS).length > 0) {
+      await page.setExtraHTTPHeaders(EXTRA_HEADERS);
+    }
+
     // Collect failed network requests (4xx/5xx responses + connection failures).
     page.on("requestfailed", (request) => {
       networkErrors.push({

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: perchfall
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jim Remsik