perchfall-notify 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 794750f0863a55a3da86f6127a9cee66b340bb551ab16a7d69181a7b793e09a6
+  data.tar.gz: 6b7591466107ed3c03581e817e079c6eb08b307eee7db7fde2f9f175dfe39e69
+SHA512:
+  metadata.gz: cee07f7fcb3ab999a3dde58e0dd9f679c2cc4447711b437ff8872baa4b166fc08561e7f20ff54451bd807761f2f5343626af284e50c8d53a327e1fa7b24d0d67
+  data.tar.gz: ecf544f28317029bd970a63571a8107200e024cb9827aecf5fe7a6888ae5ce6809b7924082c044b7103cb83a62772cdb84d25b3c4861e2c9d362fbf5b2120e8e

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [0.1.0] - 2026-03-20
+
+### Added
+
+- `Perchfall::Notify.deliver` convenience method for one-line delivery
+- `Perchfall::Notify::Notifier` — delivers reports to multiple channels, attempting all before raising
+- `Perchfall::Notify::Channel` — base class for custom channel implementations
+- `Perchfall::Notify::Channels::Slack` — Slack incoming webhook channel with Block Kit formatting
+- `Perchfall::Notify::SlackFormatter` — default formatter; injectable for custom message shapes
+- `Perchfall::Notify::DeliveryError` and `Perchfall::Notify::ConfigurationError`
+
+[0.1.0]: https://github.com/beflagrant/perchfall-notify/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jim Remsik
+
+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,179 @@
+# perchfall-notify
+
+[![CI](https://github.com/beflagrant/perchfall-notify/actions/workflows/ci.yml/badge.svg)](https://github.com/beflagrant/perchfall-notify/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/perchfall-notify.svg)](https://badge.fury.io/rb/perchfall-notify)
+
+**Notification channels for [Perchfall](https://github.com/beflagrant/perchfall) synthetic monitoring.** Get alerted in Slack — or anywhere you like — the moment a check fails.
+
+```ruby
+slack = Perchfall::Notify::Channels::Slack.new(
+  webhook_url: ENV["SLACK_WEBHOOK_URL"]
+)
+
+report = Perchfall.run(url: "https://example.com")
+Perchfall::Notify.deliver(report, channels: [slack])
+```
+
+---
+
+## Why perchfall-notify
+
+Perchfall tells you what a real browser saw. perchfall-notify tells your team about it.
+
+- **Fail-open delivery** — if one channel errors, the others still fire. A Slack outage won't suppress your SMS alert.
+- **Ships with Slack** — Block Kit messages with status, URL, HTTP code, duration, and a full list of network and console errors.
+- **Bring your own channel** — implement one method and plug anything in: webhooks, PagerDuty, SMS, email.
+- **No framework required** — works in Sidekiq jobs, Rake tasks, plain Ruby scripts, or anywhere Perchfall runs.
+
+---
+
+## Requirements
+
+| Dependency | Version |
+| --- | --- |
+| Ruby | ≥ 3.2 |
+| perchfall | ≥ 0.3.0 |
+
+---
+
+## Installation
+
+```sh
+bundle add perchfall-notify
+```
+
+---
+
+## Quickstart
+
+```ruby
+require "perchfall/notify"
+
+slack = Perchfall::Notify::Channels::Slack.new(
+  webhook_url: ENV["SLACK_WEBHOOK_URL"]
+)
+
+report = Perchfall.run(url: "https://example.com")
+
+Perchfall::Notify.deliver(report, channels: [slack])
+```
+
+That's it. If the report has network errors or console errors, they'll appear in the Slack message.
+
+---
+
+## Slack channel
+
+Create a [Slack incoming webhook](https://api.slack.com/messaging/webhooks) and pass the URL:
+
+```ruby
+slack = Perchfall::Notify::Channels::Slack.new(
+  webhook_url: "https://hooks.slack.com/services/..."
+)
+```
+
+The default message format uses Block Kit and includes:
+
+- Pass/fail header with optional scenario name
+- URL, HTTP status, and duration
+- Network errors with method, URL, and failure reason
+- Console errors with type and message
+
+### Custom message format
+
+Inject a formatter to control message shape:
+
+```ruby
+class MyFormatter
+  def format(report)
+    {
+      text: report.ok? ? "✅ #{report.url} OK" : "🚨 #{report.url} FAILED"
+    }
+  end
+end
+
+slack = Perchfall::Notify::Channels::Slack.new(
+  webhook_url: ENV["SLACK_WEBHOOK_URL"],
+  formatter: MyFormatter.new
+)
+```
+
+---
+
+## Delivering to multiple channels
+
+Pass any number of channels. All are attempted — a failure in one does not skip the others.
+
+```ruby
+Perchfall::Notify.deliver(report, channels: [slack, pagerduty, sms])
+```
+
+If any channels fail, a single `Perchfall::Notify::DeliveryError` is raised after all have been attempted, with a summary of every failure.
+
+---
+
+## Building a custom channel
+
+Subclass `Perchfall::Notify::Channel` and implement `#deliver`:
+
+```ruby
+class WebhookChannel < Perchfall::Notify::Channel
+  def initialize(url)
+    @url = url
+  end
+
+  def deliver(report)
+    # post report.to_json to @url
+  rescue => e
+    raise Perchfall::Notify::DeliveryError, "Webhook failed: #{e.message}"
+  end
+end
+```
+
+Raise `DeliveryError` on failure so `Notifier` can accumulate it alongside other channel failures.
+
+---
+
+## Use in a background job
+
+```ruby
+class SyntheticCheckJob
+  include Sidekiq::Job
+
+  def perform(url)
+    channels = [
+      Perchfall::Notify::Channels::Slack.new(webhook_url: ENV.fetch("SLACK_WEBHOOK_URL"))
+    ]
+    report = Perchfall.run(url: url)
+    Perchfall::Notify.deliver(report, channels: channels)
+  rescue Perchfall::Errors::PageLoadError => e
+    Perchfall::Notify.deliver(e.report, channels: channels)
+  end
+end
+```
+
+---
+
+## Errors
+
+| Exception | When |
+| --- | --- |
+| `Perchfall::Notify::ConfigurationError` | A channel was constructed with invalid configuration (e.g. missing webhook URL) |
+| `Perchfall::Notify::DeliveryError` | One or more channels failed to deliver |
+| `Perchfall::Notify::Error` | Base class — catches any perchfall-notify error |
+
+---
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bin/console
+```
+
+---
+
+## License
+
+MIT

data/lib/perchfall/notify/channel.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Notify
+    # Base interface for notification channels.
+    #
+    # A channel is responsible for delivering a formatted message derived from
+    # a Perchfall::Report to an external destination (Slack, SMS, webhook, etc.).
+    #
+    # Implement #deliver(report) in subclasses. Raise DeliveryError on failure.
+    #
+    # Example:
+    #
+    #   class MyChannel < Perchfall::Notify::Channel
+    #     def deliver(report)
+    #       # send the report somewhere
+    #     end
+    #   end
+    class Channel
+      # Deliver a notification for the given report.
+      #
+      # @param report [Perchfall::Report]
+      # @raise [NotImplementedError] if subclass does not implement this method
+      # @raise [DeliveryError] if delivery fails
+      def deliver(report)
+        raise NotImplementedError, "#{self.class}#deliver is not implemented"
+      end
+    end
+  end
+end

data/lib/perchfall/notify/channels/slack.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Notify
+    module Channels
+      # Delivers Perchfall::Report notifications to a Slack incoming webhook.
+      #
+      # Requires a webhook URL. Accepts an optional formatter to control
+      # message shape, and an optional http_client for testability.
+      #
+      # Example:
+      #
+      #   slack = Perchfall::Notify::Channels::Slack.new(
+      #     webhook_url: "https://hooks.slack.com/services/..."
+      #   )
+      #   slack.deliver(report)
+      #
+      class Slack < Channel
+        # @param webhook_url [String] Slack incoming webhook URL
+        # @param formatter [#format] converts a Report to a Slack payload Hash
+        # @param http_client [#post] sends the payload; defaults to NetHttpClient
+        def initialize(webhook_url:, formatter: SlackFormatter.new, http_client: NetHttpClient.new)
+          super()
+          raise ConfigurationError, "webhook_url is required" if webhook_url.nil? || webhook_url.strip.empty?
+
+          uri = begin
+            URI.parse(webhook_url)
+          rescue URI::InvalidURIError
+            raise ConfigurationError, "webhook_url is not a valid URL"
+          end
+
+          raise ConfigurationError, "webhook_url must use https" unless uri.is_a?(URI::HTTPS)
+
+          @webhook_url = webhook_url
+          @formatter = formatter
+          @http_client = http_client
+        end
+
+        # @param report [Perchfall::Report]
+        # @raise [DeliveryError] if the HTTP request fails or Slack rejects the payload
+        def deliver(report)
+          payload = @formatter.format(report)
+          @http_client.post(@webhook_url, payload)
+        rescue DeliveryError
+          raise
+        rescue StandardError => e
+          raise DeliveryError, "Slack delivery failed: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/perchfall/notify/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Notify
+    # Base error for all perchfall-notify failures.
+    Error = Class.new(StandardError)
+
+    # Raised when a channel fails to deliver a notification.
+    DeliveryError = Class.new(Error)
+
+    # Raised when a channel is constructed with invalid configuration.
+    ConfigurationError = Class.new(Error)
+  end
+end

data/lib/perchfall/notify/net_http_client.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Perchfall
+  module Notify
+    # Sends a JSON payload to a URL via HTTP POST using Ruby's net/http.
+    #
+    # This is the default http_client for Channels::Slack. Inject a fake or
+    # stub in tests — do not mock this class directly.
+    class NetHttpClient
+      OPEN_TIMEOUT = 5  # seconds
+      READ_TIMEOUT = 10 # seconds
+
+      # @param url [String] destination URL
+      # @param payload [Hash] will be serialized to JSON
+      # @raise [DeliveryError] on network failure or non-2xx response
+      def post(url, payload)
+        uri = URI.parse(url)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.open_timeout = OPEN_TIMEOUT
+          http.read_timeout = READ_TIMEOUT
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(payload)
+          http.request(request)
+        end
+
+        return if response.is_a?(Net::HTTPSuccess)
+
+        raise DeliveryError, "HTTP #{response.code}: #{response.body}"
+      rescue DeliveryError
+        raise
+      rescue StandardError => e
+        raise DeliveryError, "HTTP request failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/perchfall/notify/notifier.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Notify
+    # Delivers a Perchfall::Report to one or more notification channels.
+    #
+    # Notifier is the primary entry point. It accepts an array of Channel
+    # objects and calls #deliver on each one in order. All channels are
+    # attempted even if one fails; DeliveryError is raised at the end if
+    # any channel failed, with all failures captured.
+    #
+    # Example:
+    #
+    #   slack = Perchfall::Notify::Channels::Slack.new(webhook_url: "https://...")
+    #   notifier = Perchfall::Notify::Notifier.new(channels: [slack])
+    #   notifier.notify(report)
+    #
+    class Notifier
+      # @param channels [Array<Channel>] one or more delivery channels
+      def initialize(channels:)
+        raise ConfigurationError, "at least one channel is required" if channels.empty?
+
+        @channels = channels
+      end
+
+      # Deliver the report to all configured channels.
+      #
+      # @param report [Perchfall::Report]
+      # @raise [DeliveryError] if one or more channels fail
+      def notify(report)
+        failures = []
+
+        @channels.each do |channel|
+          channel.deliver(report)
+        rescue DeliveryError => e
+          failures << e
+        end
+
+        raise_if_failed(failures)
+      end
+
+      private
+
+      def raise_if_failed(failures)
+        return if failures.empty?
+
+        messages = failures.map(&:message).join("; ")
+        raise DeliveryError, "#{failures.size} channel(s) failed: #{messages}"
+      end
+    end
+  end
+end

data/lib/perchfall/notify/slack_formatter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Perchfall
+  module Notify
+    # Converts a Perchfall::Report into a Slack Block Kit payload Hash.
+    #
+    # The default format posts a concise status message with:
+    #   - pass/fail indicator
+    #   - URL and scenario name (if present)
+    #   - HTTP status and duration
+    #   - counts of network and console errors (if any)
+    #
+    # Inject a custom formatter into Channels::Slack to change message shape.
+    class SlackFormatter
+      # @param report [Perchfall::Report]
+      # @return [Hash] Slack Block Kit payload
+      def format(report)
+        {
+          blocks: [
+            header_block(report),
+            details_block(report),
+            *error_blocks(report)
+          ]
+        }
+      end
+
+      private
+
+      def header_block(report)
+        icon = report.ok? ? ":white_check_mark:" : ":rotating_light:"
+        label = report.scenario_name ? " — #{report.scenario_name}" : ""
+        {
+          type: "header",
+          text: { type: "plain_text", text: "#{icon} Perchfall#{label}" }
+        }
+      end
+
+      def details_block(report)
+        status_text = report.ok? ? "OK" : "FAILED"
+        lines = [
+          "*Status:* #{status_text}",
+          "*URL:* #{report.url}",
+          "*HTTP:* #{report.http_status}",
+          "*Duration:* #{report.duration_ms}ms"
+        ]
+        lines << "*Error:* #{escape(report.error)}" if report.error
+
+        {
+          type: "section",
+          text: { type: "mrkdwn", text: lines.join("\n") }
+        }
+      end
+
+      def error_blocks(report)
+        blocks = []
+
+        if report.network_errors.any?
+          lines = report.network_errors.map { |e| "• `#{e.http_method} #{e.url}` — #{escape(e.failure)}" }
+          blocks << section("*Network errors (#{report.network_errors.size}):*\n#{lines.join("\n")}")
+        end
+
+        if report.console_errors.any?
+          lines = report.console_errors.map { |e| "• `#{e.type}` #{escape(e.text)}" }
+          blocks << section("*Console errors (#{report.console_errors.size}):*\n#{lines.join("\n")}")
+        end
+
+        blocks
+      end
+
+      def section(text)
+        { type: "section", text: { type: "mrkdwn", text: text } }
+      end
+
+      def escape(str)
+        str.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+      end
+    end
+  end
+end

data/lib/perchfall/notify/version.rb

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

data/lib/perchfall/notify.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "perchfall"
+
+require_relative "notify/version"
+require_relative "notify/errors"
+require_relative "notify/channel"
+require_relative "notify/slack_formatter"
+require_relative "notify/net_http_client"
+require_relative "notify/notifier"
+require_relative "notify/channels/slack"
+
+module Perchfall
+  module Notify
+    # Convenience method. Delivers a report to one or more channels.
+    #
+    #   Perchfall::Notify.deliver(report, channels: [slack_channel])
+    #
+    # @param report [Perchfall::Report]
+    # @param channels [Array<Channel>]
+    def self.deliver(report, channels:)
+      Notifier.new(channels: channels).notify(report)
+    end
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: perchfall-notify
+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: perchfall
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.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: |
+  Delivers Perchfall check reports via configurable notification channels.
+  Ships with Slack support; extensible to SMS, webhooks, and beyond.
+email:
+- jim@beflagrant.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/perchfall/notify.rb
+- lib/perchfall/notify/channel.rb
+- lib/perchfall/notify/channels/slack.rb
+- lib/perchfall/notify/errors.rb
+- lib/perchfall/notify/net_http_client.rb
+- lib/perchfall/notify/notifier.rb
+- lib/perchfall/notify/slack_formatter.rb
+- lib/perchfall/notify/version.rb
+homepage: https://github.com/beflagrant/perchfall-notify
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/beflagrant/perchfall-notify
+  changelog_uri: https://github.com/beflagrant/perchfall-notify/blob/main/CHANGELOG.md
+  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.6
+specification_version: 4
+summary: Notification channels for Perchfall synthetic monitoring
+test_files: []