recheck 0.0.1 → 0.5.0

data/template/regression_checker_sample.rb

@@ -0,0 +1,206 @@
+# Recheck Checker API Documentation
+#
+# This file documents the complete Checker API for Recheck.
+# Use this as a reference when creating your own checkers.
+
+# All checkers must inherit from Recheck::Checker::Base to be registered
+class SampleChecker < Recheck::Checker::Base
+  #
+  # CHECKER LIFECYCLE AND HOOKS
+  # ==========================
+  #
+  # Checkers have a simple lifecycle with four hooks:
+  #
+  # 1. initialize - Optional setup
+  # 2. query_* methods - Required to fetch records to check
+  # 3. check_* methods - Required to validate each record
+  # 4. Metadata methods - Optional for routing and prioritization
+  #
+
+  # Hook 1: initialize (optional)
+  # ----------------------------
+  # Use initialize to set up any resources needed by your checks.
+  # This runs once when the checker is instantiated.
+  def initialize
+    # You can:
+    # - Connect to external services
+    # - Load reference data
+    # - Set up caches or other shared resources
+    # - Configure the checker based on environment
+
+    @external_service = ExternalService.new(api_key: ENV["API_KEY"])
+    @reference_data = load_reference_data
+    @cache = {}
+  end
+
+  # You can use helper methods to organize your code
+  def load_reference_data
+    # Load data from a file, database, or API
+    # This is just a helper method, not part of the Checker API
+    {}
+  end
+
+  # Hook 2: query_* methods (one required)
+  # ---------------------------------
+  # At least one query method is required. Query methods must:
+  # - Start with "query" (or they won't be detected)
+  # - Return an Enumerable of records to check
+  # - Be efficient (they often run against production databases)
+
+  # Basic query method - returns all records of a type
+  def query
+    # The simplest query just returns all records
+    # Use find_each with ActiveRecord for batching
+    Model.find_each
+  end
+
+  # You can have multiple query methods to:
+  # - Check different record types
+  # - Optimize performance with targeted queries
+  # - Focus on specific subsets of data
+  def query_recent
+    # Focus on recently created/updated records
+    Model.where("updated_at > ?", 1.day.ago).find_each
+  end
+
+  def query_problematic
+    # Target records that might have issues
+    Model.where(status: "error")
+      .or(Model.where(processed_at: nil))
+      .includes(:related_records) # Eager load associations
+      .find_each
+  end
+
+  # Query methods can return any Enumerable, not just ActiveRecord
+  def query_external_data
+    # You can check data from external sources
+    @external_service.fetch_records.map do |record|
+      # Transform external data if needed
+      {id: record["id"], data: record["payload"]}
+    end
+  end
+
+  # Query methods can return arrays, hashes, or custom objects
+  def query_composite
+    # You can join data from multiple sources
+    [
+      {type: "config", value: AppConfig.settings},
+      {type: "status", value: SystemStatus.current}
+    ]
+  end
+
+  # Hook 3: check_* methods (one required)
+  # ---------------------------------
+  # Check methods must:
+  # - Start with "check_" (or they won't be detected)
+  # - Take a single record parameter
+  # - Return false/nil for failing records, anything else for passing
+
+  # Basic check - validates a single aspect of a record
+  def check_record_is_valid(record)
+    # The simplest check just calls ActiveRecord validations
+    # Returns false if invalid, true if valid
+    record.valid?
+  end
+
+  # Checks can implement complex business rules
+  def check_business_rule(record)
+    # Implement any business logic
+    # Return false/nil for failing records
+    if record.status == "completed" && record.completed_at.nil?
+      # This is a failing condition
+      return false
+    end
+
+    # Any non-false/nil return is considered passing
+    true
+  end
+
+  # Checks can integrate with external systems
+  def check_external_consistency(record)
+    # Check that record matches external system
+    external_data = @external_service.find(record.external_id)
+
+    # Return false if inconsistent
+    return false if external_data.nil?
+    return false if external_data["status"] != record.status
+
+    # Return true if consistent
+    true
+  end
+
+  # Checks can automatically fix issues (use carefully!)
+  def check_and_fix(record)
+    # Check if there's an issue
+    if record.calculated_total != record.stored_total
+      # Fix the issue
+      record.stored_total = record.calculated_total
+      record.save!
+
+      # Log the fix
+      LoggingService.info("Fixed total for record #{record.id}")
+    end
+
+    # Return true since we've fixed the issue
+    true
+  end
+
+  # Checks can handle different record types from different queries
+  def check_config_is_valid(record)
+    # Handle records from query_composite
+    if record[:type] == "config"
+      # Check config settings
+      return record[:value].valid?
+    elsif record[:type] == "status"
+      # Check system status
+      return record[:value].ok?
+    end
+
+    # Skip records this check doesn't understand
+    true
+  end
+
+  #
+  # METADATA METHODS
+  # ===============
+  #
+  # These optional methods provide metadata about your checker
+  # for use by reporters and the Recheck runner.
+  #
+
+  # Team responsible for this checker
+  # Used by reporters to route notifications
+  def team
+    :data_integrity
+  end
+
+  # Priority of this checker
+  # Used by reporters to prioritize notifications
+  def priority
+    :high # :high, :medium, :low
+  end
+
+  # Tags for this checker
+  # Used for filtering and categorization
+  def tags
+    [:critical, :customer_facing]
+  end
+
+  # Documentation URL
+  # Link to runbook or documentation
+  def documentation_url
+    "https://internal-docs.example.com/data-integrity/sample-checker"
+  end
+
+  # Slack channel for notifications
+  # Used by SlackReporter
+  def slack_channel
+    "#data-alerts"
+  end
+
+  # Email recipients for notifications
+  # Perhaps used by EmailReporter
+  def email_recipients
+    ["data-team@example.com", "oncall@example.com"]
+  end
+end

data/template/reporter_sample.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+# Reporters are how you turn failing checks into emails, bug tracker tickets,
+# or any other useful notification or report. You can notify different teams
+# however they most "enjoy" hearing about bad data.
+
+class SampleReporter < Recheck::Reporter::Base
+  # Optional but strongly recommended: Provide help text that appears when running `recheck
+  # reporters`. This should briefly explain what your reporter does and any argument it takes.
+  def self.help
+    "A template reporter showing how to implement your own custom reporter. Takes an optional argument."
+  end
+
+  # Optional: Initialize with the argument string from the command line.
+  # The arg is passed as a single string, or nil if no arg is provided
+  # Arguments:
+  # * arg: The string argument passed after the colon in the reporter specification
+  #   For example: `--reporter SampleReporter:api_key_123` -> `api_key_123`
+  def initialize(arg:)
+    # Process your argument here if needed
+    @config = arg || "default_config"
+  end
+
+  # Important: If you define an around_ hook, it must 'yield' to run the next step.
+  # A hook method's return value is not used.
+
+  # around_run: Fires around the entire run.
+  # This is a good place to set up resources, send summary emails, etc.
+  # Arguments:
+  # * checkers: Array of checker instances that will be run
+  def around_run(checkers: [])
+    # Setup before the run
+    start_time = Time.now
+
+    # yield returns: a CountStats about the entire run
+    # CountStats tracks counts of passes, failures, and other result types
+    # It provides methods like #all_pass?, #any_errors?, #summary, etc.
+    total_counts = yield
+
+    # Teardown/reporting after the run
+    duration = Time.now - start_time
+
+    # Example of how you might report results
+    if total_counts.any_errors?
+      puts "SampleReporter: Found errors in #{duration.round(2)}s: #{total_counts.summary}"
+      # In a real reporter, you might:
+      # - Send an email
+      # - Post to Slack
+      # - Create a ticket in your issue tracker
+      # - Log to a monitoring service
+    end
+
+    # Return the counts (optional)
+    total_counts
+  end
+
+  # around_checker: Fires around each checker.
+  # Arguments:
+  # * checker: The checker instance being run
+  # * queries: Array of query method names defined on the checker
+  # * checks: Array of check method names defined on the checker
+  def around_checker(checker:, queries: [], checks: [])
+    # Before running this checker
+    checker_name = checker.class.name
+
+    # yields returns a CountStats for the checker
+    counts = yield
+
+    # After running this checker
+    if counts.any_errors?
+      puts "SampleReporter: Checker #{checker_name} had issues: #{counts.summary}"
+      # In a real reporter, you might group errors by checker
+    end
+  end
+
+  # around_query: Fires around each query
+  # This is useful for tracking which queries are slow or problematic
+  # Arguments:
+  # * checker: The checker instance being run
+  # * query: The name of the query method being executed
+  # * checks: Array of check method names that will be run against query results
+  def around_query(checker:, query:, checks: [])
+    # Before running this query
+    query_start = Time.now
+
+    # yield does not return anything for this hook
+    yield
+
+    # After running this query
+    query_duration = Time.now - query_start
+    if query_duration > 5 # seconds
+      puts "SampleReporter: Slow query #{checker.class.name}##{query} took #{query_duration.round(2)}s"
+    end
+  end
+
+  # The around_check and halt hooks both receive one of two result objects.
+  #
+  # Recheck::Pass: A successful check.
+  # Attributes:
+  #   #type: always :pass
+  #
+  # Recheck::Error: A failed check.
+  # Attributes:
+  #   #type: One of the following symbols
+  #     fail: The check returned a falsey value
+  #     exception: The check raised an exception
+  #     blanket: The first 20 checks all failed or raised; the runner skips
+  #     no_query_methods: The checker does not define a query_methods
+  #     no_queries: The checker defines query_methods, but did not return any
+  #     no_check_methods: The checker does not define a check_methods
+  #     no_checks: The checker defines check_methods, but did not return any
+  #   #checker: Checker instance
+  #   #query: Query method name
+  #   #check: Check method name
+  #   #record: The record being checked
+  #   #exception: rescued Exception
+  #
+
+  # around_check: Fires for each call to a check_ method on each record
+  # This is where you can collect detailed information about failures.
+  # Arguments:
+  # * checker: The checker instance being run
+  # * query: The name of the query method that produced this record
+  # * check: The name of the check method being executed
+  # * record: The individual record being checked
+  def around_check(checker:, query:, check:, record:)
+    # Returns a result object, see comment above
+    result = yield
+
+    # Process the result
+    if result.is_a?(Recheck::Error)
+      case result.type
+      when :fail
+        record_id = fetch_record_id(result.record)
+        puts "SampleReporter: #{checker.class.name}##{check} failed for record: #{record_id}"
+      when :exception
+        puts "SampleReporter: #{checker.class.name}##{check} raised exception: #{result.exception.message}"
+      end
+
+      # In a real reporter, you might:
+      # - Collect failures to report in a batch
+      # - Send immediate alerts for critical failures
+      # - Log to a monitoring system
+    end
+  end
+
+  # halt: Called when a checker is halted due to an error.
+  # This is useful for reporting fatal errors that prevent checks from running
+  # Arguments:
+  # * checker: The checker instance that was halted
+  # * query: The name of the query method that was running (if any)
+  # * check: The name of the check method that was running (if any)
+  # * error: The error result, see comment above around_check
+  def halt(checker:, query:, error:, check: nil)
+    puts "SampleReporter: Halted #{checker.class.name}##{query} due to #{error.type}"
+
+    # In a real reporter, you might:
+    # - Send an urgent alert
+    # - Create a high-priority ticket
+    # - Log a critical error
+  end
+
+  # You can add any helper methods, include modules, etc.
+
+  # Example of a helper method to format data for reporting
+  def format_error_message(error)
+    case error.type
+    when :fail
+      "Record is invalid"
+    when :exception
+      "Exception occurred: #{error.exception.message}"
+    when :blanket
+      "Blanket failure - first 20 checks all failed"
+    else
+      "Other error: #{error.type}"
+    end
+  end
+end

data/template/site/dns_checker.rb

@@ -0,0 +1,31 @@
+require "resolv"
+
+class EmailRecordsChecker < Recheck::Checker::Base
+  def query
+    # domains you send email from
+    []
+  end
+
+  def check_mx_records(domain)
+    mx_records = Resolv::DNS.open do |dns|
+      dns.getresources(domain, Resolv::DNS::Resource::IN::MX)
+    end
+    !mx_records.empty?
+  end
+
+  def check_soa_record(domain)
+    soa_record = Resolv::DNS.open do |dns|
+      dns.getresource(domain, Resolv::DNS::Resource::IN::SOA)
+    end
+    !soa_record.nil?
+  rescue Resolv::ResolvError
+    false
+  end
+
+  def check_spf_record(domain)
+    txt_records = Resolv::DNS.open do |dns|
+      dns.getresources(domain, Resolv::DNS::Resource::IN::TXT)
+    end
+    txt_records.any? { |record| record.strings.first.start_with?("v=spf1") }
+  end
+end

data/template/site/tls_checker.rb

@@ -0,0 +1,51 @@
+require "openssl"
+require "socket"
+require "uri"
+
+class TlsChecker < Recheck::Checker::Base
+  def query
+    # array of domains you host web servers on
+    [].map do |domain|
+      cert = fetch_certificate(domain)
+      {domain: domain, cert: cert}
+    end
+  end
+
+  def check_not_expiring_soon(record)
+    expiration_date = record[:cert].not_after
+    days_until_expiration = (expiration_date - Time.now) / (24 * 60 * 60)
+    days_until_expiration > 30
+  end
+
+  def check_cert_matches_domain(record)
+    cert = record[:cert]
+    domain = record[:domain]
+    cert.subject.to_a.any? { |name, value| name == "CN" && (value == domain || value == "*.#{domain}") } ||
+      cert.extensions.any? { |ext| ext.oid == "subjectAltName" && ext.value.include?("DNS:#{domain}") }
+  end
+
+  def check_cert_suites_no_old(record)
+    ctx = OpenSSL::SSL::SSLContext.new
+    ctx.set_params(verify_mode: OpenSSL::SSL::VERIFY_NONE)
+    socket = TCPSocket.new(record[:domain], 443)
+    ssl = OpenSSL::SSL::SSLSocket.new(socket, ctx)
+    ssl.connect
+    ciphers = ssl.cipher
+    ssl.close
+    socket.close
+
+    !["RC4", "MD5", "SHA1"].any? { |weak| ciphers.include?(weak) }
+  end
+
+  private
+
+  def fetch_certificate(domain)
+    uri = URI::HTTPS.build(host: domain)
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true
+    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+    http.start do |h|
+      h.peer_cert
+    end
+  end
+end

data/template/site/whois_checker.rb

@@ -0,0 +1,25 @@
+require "whois"
+require "whois-parser"
+
+class WhoisChecker < Recheck::Checker::Base
+  def query
+    whois = Whois::Client.new
+    # array of your domains
+    [].map do |domain|
+      whois.lookup(domain).parser
+    end
+  end
+
+  def check_not_expiring_soon(parser)
+    expiration_date = parser.expires_on
+    expiration_date > (Time.now + 180 * 24 * 60 * 60) # 180 days
+  end
+
+  def check_registrar_lock(domain)
+    domain_status.any? { |status| status.downcase.include?("clienttransferprohibited") }
+  end
+
+  def check_nameservers(domain)
+    parser.nameservers.length >= 2
+  end
+end