allgood 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe79d04db962fcfc50cb094c0b122506d09f903b7ee02e2ee7ae0c3930c78557
-  data.tar.gz: fb9a69be909db1c10d5019dfadbdbee5b7da514913d8a907933cd2873e73f2f0
+  metadata.gz: 45bac1780ef5cb92516f0a6f02cd7aa7b476213d6595a937252c600dc3e870e0
+  data.tar.gz: b1f8f7e8e30609d67c6c28fb66cd651d13414f9161f74b3e3880f02113408c10
 SHA512:
-  metadata.gz: fc26bbc3685f38fbfa49e05047987537c64e06c55356c28d0c8a0a50b73b6981c10d66c96996ca44057720402f4f5ed1319309a33402b25a39d0bdf472518496
-  data.tar.gz: ea88c1027193b356560b2361e65a28c42d3b10683df7e777796ff5de10c0c6e3aa93f7bb42fa70ef6ce9699d288e4efa74ceaa82667a5208ec006aa41506e6ea
+  metadata.gz: b169c7d38987605312e2e013f645814e12fa23f2b0574793fa560f9f9ec9f97491eea5347c625e8b6d0909f3ec32c912a744925906f9e66b710486eb365cf35f
+  data.tar.gz: 0573a0b4918ec2e6e4a0ce40831d3e57afed34db5e8ada879d0db4450764dd0e72a8ffe4b3e779bf58758cf3d29546728600f9823437cdf1618627a48648fe5a

data/CHANGELOG.md

@@ -1,4 +1,19 @@
-## [Unreleased]
+## [0.3.0] - 2024-10-27
+
+- Added rate limiting for expensive checks with the `run: "N times per day/hour"` option
+- Added a cache mechanism to store check results and error states, which allows for rate limiting and avoiding redundant runs when checks fail
+- Added automatic cache key expiration
+- Added error handling and feedback for rate-limited checks
+
+## [0.2.0] - 2024-10-26
+
+- Improved the `allgood` DSL by adding optional conditionals on when individual checks are run
+- Allow for environment-specific checks with `only` and `except` options (`check "Test Check", only: [:development, :test]`)
+- Allow for conditional checks with `if` and `unless` options, which can be procs or any other condition (`check "Test Check", if: -> { condition }`)
+- Added visual indication of skipped checks in the healthcheck page
+- Improved developer experience by showing why checks were skipped (didn't meet conditions, environment-specific, etc.)
+- New DSL changes are fully backward compatible with the previous version (new options are optional, and checks will run normally if they are not specified), so the new version won't break existing configurations
+- Changed configuration loading to happen after Rails initialization so we fix the segfault that could occur when requiring gems in the `allgood.rb` configuration file before Rails was initialized
 
 ## [0.1.0] - 2024-08-22
 

data/README.md

@@ -1,12 +1,22 @@
 # ✅ Allgood - Rails gem for health checks
 
-Add quick, simple, and beautiful health checks to your Rails application.
+[![Gem Version](https://badge.fury.io/rb/allgood.svg)](https://badge.fury.io/rb/allgood)
 
-`allgood` allows you to define custom, business-oriented health checks (as in: are there any new users in the past 24 hours, are they actually using the app, does the last record have all the attributes we expect, etc.) in a very intuitive way that reads just like English – and provides a `/healthcheck` endpoint that displays the results in a beautiful page.
+Add quick, simple, and beautiful health checks to your Rails application via a `/healthcheck` page.
 
-You can then use that endpoint to monitor the health of your application via UptimeRobot, Pingdom, etc. These services will load your `/healthcheck` page every few minutes, so all checks will be run when UptimeRobot fetches the page.
+Use it for smoke testing, to make sure your app is healthy and functioning as expected.
 
-![alt text](allgood.jpeg)
+![Example dashboard of the Allgood health check page](allgood.jpeg)
+
+## How it works
+
+`allgood` allows you to define custom health checks / smoke tests (as in: can the Rails app connect to the DB, are there any new users in the past 24 hours, are they actually using the app, etc.) in a very intuitive way that reads just like English.
+
+It provides a `/healthcheck` endpoint that displays the results in a beautiful page.
+
+You can then [use that endpoint to monitor the health of your application via UptimeRobot](https://uptimerobot.com/?rid=854006b5fe82e4), Pingdom, etc. These services will load your `/healthcheck` page every few minutes, so all checks will be run when UptimeRobot fetches the page.
+
+`allgood` aims to provide developers with peace of mind by answering the question "is production okay?" at a glance.
 
 ## Installation
 
@@ -17,9 +27,10 @@ gem 'allgood'
 
 Then run `bundle install`.
 
-## Usage
+After installing the gem, you need to mount the `/healthcheck` route and define your health checks in a `config/allgood.rb` file.
 
-### Mounting the Engine
+
+## Mount the `/healthcheck` route
 
 In your `config/routes.rb` file, mount the Allgood engine:
 ```ruby
@@ -28,36 +39,83 @@ mount Allgood::Engine => '/healthcheck'
 
 You can now navigate to `/healthcheck` to see the health check results.
 
-The `/healthcheck` page returns a `200` HTTP code if all checks are successful – and error `503 Service Unavailable` otherwise.
+The `/healthcheck` page returns HTTP codes:
+ - `200 OK` if all checks are successful
+ - `503 Service Unavailable` error otherwise
+
+Services like UptimeRobot pick up these HTTP codes, which makes monitoring easy.
 
-`allgood` is also a nice replacement for the default `/up` Rails action, so Kamal to also checks things like if the database connection is good. Just change the mounting route to `/up` instead of `/healthcheck`
+**Kamal**: `allgood` can also be used as a replacement for the default `/up` Rails action, to make [Kamal](https://github.com/basecamp/kamal) check things like if the database connection is healthy when deploying your app's containers. Just change `allgood`'s mounting route to `/up` instead of `/healthcheck`, or configure Kamal to use the `allgood` route.
 
+> [!TIP]
+> If you're using Kamal with `allgood`, container deployment will fail if any defined checks fail, [without feedback from Kamal](https://github.com/rameerez/allgood/issues/1) on what went wrong. Your containers will just not start, and you'll get a generic error message. To avoid this, you can either keep the `allgood.rb` file very minimal (e.g., only check for active DB connection, migrations up to date, etc.) so the app deployment is likely to succeed, or you can use the default `/up` route for Kamal, and then mount `allgood` on another route for more advanced business-oriented checks. What you want to avoid is your app deployment failing because of usage-dependent or business-oriented checks, like your app not deploying because it didn't get any users in the past hour, or something like that.
 
-### Configuring Health Checks
+## Configure your health checks
 
-Create a file `config/allgood.rb` in your Rails application. This is where you'll define your health checks:
+Create a file `config/allgood.rb` in your Rails application. This is where you'll define your health checks. Here's a simple example:
 ```ruby
 # config/allgood.rb
 
 check "We have an active database connection" do
-  make_sure ActiveRecord::Base.connection.active?
+  make_sure ActiveRecord::Base.connection.connect!.active?
 end
 ```
 
-This will run the check upon page load, and will show "Check passed" or "Check failed" next to it. You can also specify a custom human-readable success / error message for each check, so you don't go crazy when things fail and you can't figure out what the check expected output was:
+`allgood` will run all checks upon page load, and will show "Check passed" or "Check failed" next to it. That's it – add as many health checks as you want!
+
+Here's my default `config/allgood.rb` file that should work for most Rails applications, feel free to use it as a starting point:
+
 ```ruby
-check "Cache is accessible and functioning" do
-  Rails.cache.write('health_check_test', 'ok')
-  make_sure Rails.cache.read('health_check_test') == 'ok', "The `health_check_test` key in the cache should contain `'ok'`"
+# config/allgood.rb
+
+check "We have an active database connection" do
+  make_sure ActiveRecord::Base.connection.connect!.active?
+end
+
+check "Database can perform a simple query" do
+  make_sure ActiveRecord::Base.connection.execute("SELECT 1").any?
+end
+
+check "Database migrations are up to date" do
+  make_sure ActiveRecord::Migration.check_all_pending! == nil
+end
+
+check "Disk space usage is below 90%" do
+  usage = `df -h / | tail -1 | awk '{print $5}' | sed 's/%//'`.to_i
+  expect(usage).to_be_less_than(90)
+end
+
+check "Memory usage is below 90%" do
+  usage = `free | grep Mem | awk '{print $3/$2 * 100.0}' | cut -d. -f1`.to_i
+  expect(usage).to_be_less_than(90)
 end
 ```
 
-As you can see, there's a very simple DSL (Domain-Specific Language) you can use to define health checks. It reads almost like natural English, and allows you to define powerful yet simple checks to make sure your app is healthy.
+I've also added an example [`config/allgood.rb`](examples/allgood.rb) file in the `examples` folder, with very comprehensive checks for a Rails 8+ app, that you can use as a starting point.
+
+> [!IMPORTANT]
+> Make sure you restart the Rails server (`bin/rails s`) every time you modify the `config/allgood.rb` file for the changes to apply – the `allgood` config is only loaded once when the Rails server starts.
+
+### The `allgood` DSL
+
+As you can see, there's a very simple DSL (Domain-Specific Language) you can use to define health checks.
+
+It reads almost like natural English, and allows you to define powerful yet simple checks to make sure your app is healthy.
+
+For example, you can specify a custom human-readable success / error message for each check, so you don't go crazy when things fail and you can't figure out what the check expected output was:
+```ruby
+check "Cache is accessible and functioning" do
+  Rails.cache.write('allgood_test', 'ok')
+  make_sure Rails.cache.read('allgood_test') == 'ok', "The `allgood_test` key in the cache should contain `'ok'`"
+end
+```
 
 Other than checking for an active database connection, it's useful to check for business-oriented metrics, such as whether your app has gotten any new users in the past 24 hours (to make sure your signup flow is not broken), check whether there have been any new posts / records created recently (to make sure your users are performing the actions you'd expect them to do in your app), check for recent purchases, check for external API connections, check whether new records contain values within expected range, etc.
 
 Some business health check examples that you'd need to adapt to the specifics of your particular app:
 ```ruby
+# Adapt these to your app specifics
+
 check "There's been new signups in the past 24 hours" do
   count = User.where(created_at: 24.hours.ago..Time.now).count
   expect(count).to_be_greater_than(0)
@@ -70,63 +128,96 @@ check "The last created Purchase has a valid total" do
 end
 ```
 
-Other nice checks to have:
+### Available check methods
+
+- `make_sure(condition, message = nil)`: Ensures that the given condition is true.
+- `expect(actual).to_eq(expected)`: Checks if the actual value equals the expected value.
+- `expect(actual).to_be_greater_than(expected)`: Checks if the actual value is greater than the expected value.
+- `expect(actual).to_be_less_than(expected)`: Checks if the actual value is less than the expected value.
+
+Please help us develop by adding more expectation methods in the `Expectation` class!
+
+### Run checks only in specific environments or under certain conditions
+
+You can also make certain checks run only in specific environments or under certain conditions. Some examples:
+
 ```ruby
-check "Database can perform a simple query" do
-  make_sure ActiveRecord::Base.connection.execute("SELECT 1").any?
+# Only run in production
+check "There have been new user signups in the past hour", only: :production do
+  make_sure User.where(created_at: 1.hour.ago..Time.now).count.positive?
 end
 
-check "Database migrations are up to date" do
-  make_sure ActiveRecord::Migration.check_all_pending! == nil
+# Run in both staging and production
+check "External API is responsive", only: [:staging, :production] do
+  # ...
 end
 
-check "Cache is accessible and functioning" do
-  Rails.cache.write('health_check_test', 'ok')
-  make_sure Rails.cache.read('health_check_test') == 'ok', "The `health_check_test` key in the cache should contain `'ok'`"
+# Run everywhere except development
+check "A SolidCable connection is active and healthy", except: :development do
+  # ...
 end
 
-check "Disk space usage is below 90%" do
-  usage = `df -h / | tail -1 | awk '{print $5}' | sed 's/%//'`.to_i
-  expect(usage).to_be_less_than(90)
+# Using if with a direct boolean
+check "Feature flag is enabled", if: ENV['FEATURE_ENABLED'] == 'true' do
+  # ...
 end
 
-check "Memory usage is below 90%" do
-  usage = `free | grep Mem | awk '{print $3/$2 * 100.0}' | cut -d. -f1`.to_i
-  expect(usage).to_be_less_than(90)
+# Using if with a Proc for more complex conditions
+check "Complex condition", if: -> { User.count > 1000 && User.last.created_at < 10.minutes.ago } do
+  # ...
 end
-```
 
-If you have other nice default checks, please open a PR! I'd love to provide a good default `config/allgood.rb` file.
+# Override default timeout (in seconds) for specific checks
+# By default, each check has a timeout of 10 seconds
+check "Slow external API", timeout: 30 do
+  # ...
+end
 
-> ⚠️ Make sure to restart the Rails server every time you modify the `config/allgood.rb` file for the config to reload and the changes to apply.
+# Combine multiple conditions
+check "Complex check",
+      only: :production,
+      if: -> { User.count > 1000 },
+      timeout: 15 do
+  # ...
+end
+```
 
+### Rate Limiting Expensive Checks
 
-### Available Check Methods
+For expensive operations (like testing paid APIs), you can limit how often checks run:
 
-- `make_sure(condition, message = nil)`: Ensures that the given condition is true.
-- `expect(actual).to_eq(expected)`: Checks if the actual value equals the expected value.
-- `expect(actual).to_be_greater_than(expected)`: Checks if the actual value is greater than the expected value.
-- `expect(actual).to_be_less_than(expected)`: Checks if the actual value is less than the expected value.
+```ruby
+# Run expensive checks a limited number of times
+check "OpenAI is responding with a valid LLM message", run: "2 times per day" do
+  # expensive API call
+end
 
-Please help us develop by adding more expectation methods in the `Expectation` class!
+check "Analytics can be processed", run: "4 times per hour" do
+  # expensive operation
+end
+```
 
-## Customization
+Important notes:
+- Rate limits reset at the start of each period (hour/day)
+- The error state persists between rate-limited runs
+- Rate-limited checks show clear feedback about remaining runs and next reset time
 
-### Timeout
+When a check is skipped due to its conditions not being met, it will appear in the healthcheck page with a skip emoji (⏭️) and a clear explanation of why it was skipped.
 
-By default, each check has a timeout of 10 seconds.
+![Example dashboard of the Allgood health check page with skipped checks](allgood_skipped.webp)
 
+_Note: the `allgood` health check dashboard has an automatic dark mode, based on the system's appearance settings._
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/allgood Our code of conduct is: just be nice and make your mom proud of what you do and post online.
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/allgood. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/allgood/healthcheck_controller.rb

@@ -29,25 +29,77 @@ module Allgood
 
     def run_checks
       Allgood.configuration.checks.map do |check|
-        run_single_check(check)
+        if check[:status] == :skipped
+          {
+            name: check[:name],
+            success: true,
+            skipped: true,
+            message: check[:skip_reason],
+            duration: 0
+          }
+        else
+          run_single_check(check)
+        end
       end
     end
 
     def run_single_check(check)
+      last_result_key = "allgood:last_result:#{check[:name].parameterize}"
+      last_result = Allgood::CacheStore.instance.read(last_result_key)
+
+      unless Allgood.configuration.should_run_check?(check)
+        message = check[:skip_reason]
+        if last_result
+          status_info = "Last check #{last_result[:success] ? 'passed' : 'failed'} #{time_ago_in_words(last_result[:time])} ago: #{last_result[:message]}"
+          message = "#{message}. #{status_info}"
+        end
+
+        return {
+          name: check[:name],
+          success: last_result ? last_result[:success] : true,
+          skipped: true,
+          message: message,
+          duration: 0
+        }
+      end
+
       start_time = Time.now
       result = { success: false, message: "Check timed out after #{check[:timeout]} seconds" }
+      error_key = "allgood:error:#{check[:name].parameterize}"
 
       begin
         Timeout.timeout(check[:timeout]) do
           check_result = Allgood.configuration.run_check(&check[:block])
           result = { success: check_result[:success], message: check_result[:message] }
+
+          if result[:success]
+            # Clear error state and store successful result
+            Allgood::CacheStore.instance.write(error_key, nil)
+            Allgood::CacheStore.instance.write(last_result_key, {
+              success: true,
+              message: result[:message],
+              time: Time.current
+            })
+          end
         end
-      rescue Timeout::Error
-        # The result is already set to a timeout message
-      rescue Allgood::CheckFailedError => e
-        result = { success: false, message: e.message }
-      rescue StandardError => e
-        result = { success: false, message: "Error: #{e.message}" }
+      rescue Timeout::Error, Allgood::CheckFailedError, StandardError => e
+        error_message = case e
+        when Timeout::Error
+          "Check timed out after #{check[:timeout]} seconds"
+        when Allgood::CheckFailedError
+          e.message
+        else
+          "Error: #{e.message}"
+        end
+
+        # Store error state and failed result
+        Allgood::CacheStore.instance.write(error_key, error_message)
+        Allgood::CacheStore.instance.write(last_result_key, {
+          success: false,
+          message: error_message,
+          time: Time.current
+        })
+        result = { success: false, message: error_message }
       end
 
       {

data/app/views/allgood/healthcheck/index.html.erb

@@ -14,6 +14,10 @@
   .check {
     margin: 0.5em 0;
   }
+
+  .skipped {
+    opacity: 0.6;
+  }
 </style>
 
 <header>
@@ -22,11 +26,18 @@
 
 <% if @results.any? %>
   <% @results.each do |result| %>
-    <div class="check">
-      <%= result[:success] ? "✅" : "❌" %>
-      <b><%= result[:name] %></b>: <i><%= result[:message] %></i> <code>[<%= result[:duration] %>ms]</code>
+    <div class="check <%= 'skipped' if result[:skipped] %>">
+      <% if result[:skipped] %>
+        ⏭️
+      <% else %>
+        <%= result[:success] ? "✅" : "❌" %>
+      <% end %>
+      <b><%= result[:name] %></b>: <i><%= result[:message] %></i> 
+      <% unless result[:skipped] %>
+        <code>[<%= result[:duration] %>ms]</code>
+      <% end %>
     </div>
   <% end %>
 <% else %>
   <p>No health checks were run. Please check your configuration.</p>
-<% end %>
+<% end %>

data/examples/allgood.rb

@@ -0,0 +1,216 @@
+require 'open-uri'
+TEST_IMAGE = URI.open("https://picsum.photos/id/237/536/354").read
+
+# --- ACTIVE RECORD ---
+
+check "We have an active database connection" do
+  make_sure ActiveRecord::Base.connection.connect!.active?
+end
+
+check "The database can perform a simple query" do
+  make_sure ActiveRecord::Base.connection.execute("SELECT 1 LIMIT 1").any?
+end
+
+check "The database can perform writes" do
+  table_name = "allgood_health_check_#{Time.now.to_i}"
+  random_id = rand(1..999999)
+
+  result = ActiveRecord::Base.connection.execute(<<~SQL)
+    DROP TABLE IF EXISTS #{table_name};
+    CREATE TEMPORARY TABLE #{table_name} (id integer);
+    INSERT INTO #{table_name} (id) VALUES (#{random_id});
+    SELECT id FROM #{table_name} LIMIT 1;
+  SQL
+
+  ActiveRecord::Base.connection.execute("DROP TABLE #{table_name}")
+
+  make_sure result.present? && result.first["id"] == random_id, "Able to write to temporary table"
+end
+
+check "The database connection pool is healthy" do
+  pool = ActiveRecord::Base.connection_pool
+
+  used_connections = pool.connections.count
+  max_connections = pool.size
+  usage_percentage = (used_connections.to_f / max_connections * 100).round
+
+  make_sure usage_percentage < 90, "Pool usage at #{usage_percentage}% (#{used_connections}/#{max_connections})"
+end
+
+check "Database migrations are up to date" do
+  make_sure ActiveRecord::Migration.check_all_pending! == nil
+end
+
+# --- IMAGE PROCESSING ---
+
+check "Vips (libvips) is installed on Linux", except: :development do
+  output = `ldconfig -p | grep libvips`
+  make_sure output.present? && output.include?("libvips.so") && output.include?("libvips-cpp.so"), "libvips is found in the Linux system's library cache"
+end
+
+check "Vips is available to Rails" do
+  throw "ImageProcessing::Vips is not available" if !ImageProcessing::Vips.present? # Need this line to load `Vips`
+
+  make_sure Vips::VERSION.present?, "Vips available with version #{Vips::VERSION}"
+end
+
+check "Vips can perform operations on images" do
+  throw "ImageProcessing::Vips is not available" if !ImageProcessing::Vips.present? # Need this line to load `Vips`
+
+  image = Vips::Image.new_from_buffer(TEST_IMAGE, "")
+  processed_image = image
+    .gaussblur(10)                   # Apply Gaussian blur with sigma 10
+    .linear([1.2], [0])              # Increase brightness
+    .invert                          # Invert colors for a wild effect
+    .sharpen                         # Apply sharpening
+    .resize(0.5)
+
+  make_sure processed_image.present? && processed_image.width == 268 && processed_image.height == 177, "If we input an image of 536x354px, and we apply filters and a 0.5 resize, we should get an image of 268x177px"
+end
+
+check "ImageProcessing::Vips is available to Rails" do
+  make_sure ImageProcessing::Vips.present?
+end
+
+check "ImageProcessing can perform operations on images" do
+  image_processing_image = ImageProcessing::Vips
+    .source(Vips::Image.new_from_buffer(TEST_IMAGE, ""))
+    .resize_to_limit(123, 123)        # Resize to fit within 500x500
+    .convert("webp")                  # Convert to webp format
+    .call
+  processed_image = Vips::Image.new_from_file(image_processing_image.path)
+
+  make_sure processed_image.present? && processed_image.width == 123 && processed_image.get("vips-loader") == "webpload", "ImageProcessing can resize and convert to webp"
+end
+
+# --- ACTIVE STORAGE ---
+
+check "Active Storage is available to Rails" do
+  make_sure ActiveStorage.present?
+end
+
+check "Active Storage tables are present in the database" do
+  make_sure ActiveRecord::Base.connection.table_exists?("active_storage_attachments") && ActiveRecord::Base.connection.table_exists?("active_storage_blobs")
+end
+
+check "Active Storage has a valid client configured" do
+  service = ActiveStorage::Blob.service
+  service_name = service&.class&.name&.split("::")&.last&.split("Service")&.first
+
+  if !service_name.downcase.include?("disk")
+    make_sure service.present? && service.respond_to?(:client) && service.client.present?, "Active Storage service has a valid #{service_name} client configured"
+  else
+    make_sure !Rails.env.production? && service.present?, "Active Storage using #{service_name} service in #{Rails.env.to_s}"
+  end
+end
+
+check "ActiveStorage can store images, retrieve them, and purge them" do
+  blob = ActiveStorage::Blob.create_and_upload!(io: StringIO.new(TEST_IMAGE), filename: "allgood-test-image-#{Time.now.to_i}.jpg", content_type: "image/jpeg")
+  blob_key = blob.key
+  make_sure blob.persisted? && blob.service.exist?(blob_key)
+  blob.purge
+  make_sure !blob.service.exist?(blob_key), "Image needs to be successfully stored, retrieved, and purged from #{ActiveStorage::Blob.service.name} (#{ActiveStorage::Blob.service.class.name})"
+end
+
+# --- CACHE ---
+
+check "Cache is accessible and functioning" do
+  cache_value = "allgood_#{Time.now.to_i}"
+  Rails.cache.write("allgood_health_check_test", cache_value, expires_in: 1.minute)
+  make_sure Rails.cache.read("allgood_health_check_test") == cache_value, "The `allgood_health_check_test` key in the cache should return the string `#{cache_value}`"
+end
+
+# --- SOLID QUEUE ---
+
+check "SolidQueue is available to Rails" do
+  make_sure SolidQueue.present?
+end
+
+check "We have an active SolidQueue connection to the database" do
+  make_sure SolidQueue::Job.connection.connect!.active?
+end
+
+check "SolidQueue tables are present in the database" do
+  make_sure SolidQueue::Job.connection.table_exists?("solid_queue_jobs") && SolidQueue::Job.connection.table_exists?("solid_queue_failed_executions") && SolidQueue::Job.connection.table_exists?("solid_queue_semaphores")
+end
+
+check "The percentage of failed jobs in the last 24 hours is less than 1%", only: :production do
+  failed_jobs = SolidQueue::FailedExecution.where(created_at: 24.hours.ago..Time.now).count
+  all_jobs = SolidQueue::Job.where(created_at: 24.hours.ago..Time.now).count
+
+  if all_jobs > 10
+    percentage = all_jobs > 0 ? (failed_jobs.to_f / all_jobs.to_f * 100) : 0
+    make_sure percentage < 1, "#{percentage.round(2)}% of jobs are failing"
+  else
+    make_sure true, "Not enough jobs to calculate meaningful failure rate (only #{all_jobs} jobs in last 24h)"
+  end
+end
+
+# --- ACTION CABLE ---
+
+check "ActionCable is configured and running" do
+  make_sure ActionCable.server.present?, "ActionCable server should be running"
+end
+
+check "ActionCable is configured to accept connections with a valid adapter" do
+  make_sure ActionCable.server.config.allow_same_origin_as_host, "ActionCable server should be configured to accept connections"
+
+  adapter = ActionCable.server.config.cable["adapter"]
+
+  if Rails.env.production?
+    make_sure adapter.in?(["solid_cable", "redis"]), "ActionCable running #{adapter} adapter in #{Rails.env.to_s}"
+  else
+    make_sure adapter.in?(["solid_cable", "async"]), "ActionCable running #{adapter} adapter in #{Rails.env.to_s}"
+  end
+end
+
+check "ActionCable can broadcast messages and store them in SolidCable" do
+  test_message = "allgood_test_#{Time.now.to_i}"
+
+  begin
+    ActionCable.server.broadcast("allgood_test_channel", { message: test_message })
+
+    # Verify message was stored in SolidCable
+    message = SolidCable::Message.where(channel: "allgood_test_channel")
+                                .order(created_at: :desc)
+                                .first
+
+    make_sure message.present?, "Message should be stored in SolidCable"
+    make_sure message.payload.include?(test_message) && message.destroy, "Message payload should contain our test message"
+  rescue => e
+    make_sure false, "Failed to broadcast/verify message: #{e.message}"
+  end
+end
+
+# --- SYSTEM ---
+
+check "Disk space usage is below 90%", only: :production do
+  usage = `df -h / | tail -1 | awk '{print $5}' | sed 's/%//'`.to_i
+  expect(usage).to_be_less_than(90)
+end
+
+check "Memory usage is below 90%", only: :production do
+  usage = `free | grep Mem | awk '{print $3/$2 * 100.0}' | cut -d. -f1`.to_i
+  expect(usage).to_be_less_than(90)
+end
+
+# --- SITEMAP ---
+
+check "The sitemap generator is available" do
+  make_sure SitemapGenerator.present?
+end
+
+check "sitemap.xml.gz exists", only: :production do
+  make_sure File.exist?(Rails.public_path.join("sitemap.xml.gz"))
+end
+
+
+# --- USAGE-DEPENDENT CHECKS ---
+
+check "SolidQueue has processed jobs in the last 24 hours", only: :production do
+  make_sure SolidQueue::Job.where(created_at: 24.hours.ago..Time.now).order(created_at: :desc).limit(1).any?
+end
+
+# --- PAY / STRIPE ---
+
+# TODO: no error webhooks in the past 24 hours, new sales in the past few hours, etc.

data/lib/allgood/cache_store.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Allgood
+  class CacheStore
+    def self.instance
+      @instance ||= new
+    end
+
+    def initialize
+      @memory_store = {}
+    end
+
+    def read(key)
+      if rails_cache_available?
+        Rails.cache.read(key)
+      else
+        @memory_store[key]
+      end
+    end
+
+    def write(key, value)
+      if rails_cache_available?
+        expiry = key.include?('day') ? 1.day : 1.hour
+        Rails.cache.write(key, value, expires_in: expiry)
+      else
+        @memory_store[key] = value
+      end
+    end
+
+    def cleanup_old_keys
+      return unless rails_cache_available?
+
+      keys_pattern = "allgood:*"
+      if Rails.cache.respond_to?(:delete_matched)
+        Rails.cache.delete_matched("#{keys_pattern}:*:#{(Time.current - 2.days).strftime('%Y-%m-%d')}*")
+      end
+    rescue StandardError => e
+      Rails.logger.warn "Allgood: Failed to cleanup old cache keys: #{e.message}"
+    end
+
+    private
+
+    def rails_cache_available?
+      Rails.cache && Rails.cache.respond_to?(:read) && Rails.cache.respond_to?(:write) &&
+        Rails.cache.write("allgood_rails_cache_test_ok", "true") &&
+        Rails.cache.read("allgood_rails_cache_test_ok") == "true"
+    rescue StandardError => e
+      Rails.logger.warn "Allgood: Rails.cache not available (#{e.message}), falling back to memory store"
+      false
+    end
+  end
+end

data/lib/allgood/configuration.rb

@@ -8,13 +8,167 @@ module Allgood
       @default_timeout = 10 # Default timeout of 10 seconds
     end
 
-    def check(name, &block)
-      @checks << { name: name, block: block, timeout: @default_timeout }
+    def check(name, **options, &block)
+      check_info = {
+        name: name,
+        block: block,
+        timeout: options[:timeout] || @default_timeout,
+        options: options,
+        status: :pending
+      }
+
+      # Handle rate limiting
+      if options[:run]
+        begin
+          check_info[:rate] = parse_run_frequency(options[:run])
+        rescue ArgumentError => e
+          check_info[:status] = :skipped
+          check_info[:skip_reason] = "Invalid run frequency: #{e.message}"
+          @checks << check_info
+          return
+        end
+      end
+
+      # Handle environment-specific options
+      if options[:only]
+        environments = Array(options[:only])
+        unless environments.include?(Rails.env.to_sym)
+          check_info[:status] = :skipped
+          check_info[:skip_reason] = "Only runs in #{environments.join(', ')}"
+          @checks << check_info
+          return
+        end
+      end
+
+      if options[:except]
+        environments = Array(options[:except])
+        if environments.include?(Rails.env.to_sym)
+          check_info[:status] = :skipped
+          check_info[:skip_reason] = "This check doesn't run in #{environments.join(', ')}"
+          @checks << check_info
+          return
+        end
+      end
+
+      # Handle conditional checks
+      if options[:if]
+        condition = options[:if]
+        unless condition.is_a?(Proc) ? condition.call : condition
+          check_info[:status] = :skipped
+          check_info[:skip_reason] = "Check condition not met"
+          @checks << check_info
+          return
+        end
+      end
+
+      if options[:unless]
+        condition = options[:unless]
+        if condition.is_a?(Proc) ? condition.call : condition
+          check_info[:status] = :skipped
+          check_info[:skip_reason] = "Check `unless` condition met"
+          @checks << check_info
+          return
+        end
+      end
+
+      check_info[:status] = :active
+      @checks << check_info
     end
 
     def run_check(&block)
       CheckRunner.new.instance_eval(&block)
     end
+
+    def should_run_check?(check)
+      return true unless check[:rate]
+
+      cache_key = "allgood:last_run:#{check[:name].parameterize}"
+      runs_key = "allgood:runs_count:#{check[:name].parameterize}:#{current_period(check[:rate])}"
+      error_key = "allgood:error:#{check[:name].parameterize}"
+      last_result_key = "allgood:last_result:#{check[:name].parameterize}"
+
+      last_run = Allgood::CacheStore.instance.read(cache_key)
+      period_runs = Allgood::CacheStore.instance.read(runs_key).to_i
+      last_result = Allgood::CacheStore.instance.read(last_result_key)
+
+      current_period_key = current_period(check[:rate])
+      stored_period = Allgood::CacheStore.instance.read("allgood:current_period:#{check[:name].parameterize}")
+
+      # If we're in a new period, reset the counter
+      if stored_period != current_period_key
+        period_runs = 0
+        Allgood::CacheStore.instance.write("allgood:current_period:#{check[:name].parameterize}", current_period_key)
+        Allgood::CacheStore.instance.write(runs_key, 0)
+      end
+
+      # If there's an error, wait until next period
+      if previous_error = Allgood::CacheStore.instance.read(error_key)
+        next_period = next_period_start(check[:rate])
+        rate_info = "Rate limited (#{period_runs}/#{check[:rate][:max_runs]} runs this #{check[:rate][:period]})"
+        check[:skip_reason] = "#{rate_info}. Waiting until #{next_period.strftime('%H:%M:%S %Z')} to retry failed check"
+        return false
+      end
+
+      # If we haven't exceeded the max runs for this period
+      if period_runs < check[:rate][:max_runs]
+        Allgood::CacheStore.instance.write(cache_key, Time.current)
+        Allgood::CacheStore.instance.write(runs_key, period_runs + 1)
+        true
+      else
+        next_period = next_period_start(check[:rate])
+        rate_info = "Rate limited (#{period_runs}/#{check[:rate][:max_runs]} runs this #{check[:rate][:period]})"
+        next_run = "Next check at #{next_period.strftime('%H:%M:%S %Z')}"
+        check[:skip_reason] = "#{rate_info}. #{next_run}"
+        false
+      end
+    end
+
+    private
+
+    def parse_run_frequency(frequency)
+      case frequency.to_s.downcase
+      when /(\d+)\s+times?\s+per\s+(day|hour)/i
+        max_runs, period = $1.to_i, $2
+        if max_runs <= 0
+          raise ArgumentError, "Number of runs must be positive"
+        end
+        if max_runs > 1000
+          raise ArgumentError, "Maximum 1000 runs per period allowed"
+        end
+        { max_runs: max_runs, period: period }
+      else
+        raise ArgumentError, "Unsupported frequency format. Use 'N times per day' or 'N times per hour'"
+      end
+    end
+
+    def current_period(rate)
+      case rate[:period]
+      when 'day'
+        Time.current.strftime('%Y-%m-%d')
+      when 'hour'
+        Time.current.strftime('%Y-%m-%d-%H')
+      end
+    end
+
+    def new_period?(last_run, rate)
+      case rate[:period]
+      when 'day'
+        !last_run.to_date.equal?(Time.current.to_date)
+      when 'hour'
+        last_run.strftime('%Y-%m-%d-%H') != Time.current.strftime('%Y-%m-%d-%H')
+      end
+    end
+
+    def next_period_start(rate)
+      case rate[:period]
+      when 'day'
+        Time.current.beginning_of_day + 1.day
+      when 'hour'
+        Time.current.beginning_of_hour + 1.hour
+      else
+        raise ArgumentError, "Unsupported period: #{rate[:period]}"
+      end
+    end
   end
 
   class CheckRunner

data/lib/allgood/engine.rb

@@ -2,7 +2,7 @@ module Allgood
   class Engine < ::Rails::Engine
     isolate_namespace Allgood
 
-    initializer "allgood.load_configuration" do
+    config.after_initialize do
       config_file = Rails.root.join("config", "allgood.rb")
       if File.exist?(config_file)
         Allgood.configure do |config|

data/lib/allgood/version.rb

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

data/lib/allgood.rb

@@ -3,6 +3,7 @@
 require_relative "allgood/version"
 require_relative "allgood/engine"
 require_relative "allgood/configuration"
+require_relative "allgood/cache_store"
 
 module Allgood
   class Error < StandardError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: allgood
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-23 00:00:00.000000000 Z
+date: 2024-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,12 +24,13 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 6.0.0
-description: 'Define custom, business-oriented health checks for your app (as in:
-  are there any new users in the past 24 hours) and see the results in a simple /healthcheck
-  page that you can use to monitor your app with UptimeRobot, Pingdom, or other monitoring
-  services.'
+description: 'Define custom health checks for your app (as in: are there any new users
+  in the past 24 hours) and see the results in a simple /healthcheck page that you
+  can use to monitor your production app with UptimeRobot, Pingdom, or other monitoring
+  services. It''s also useful as a drop-in replacement for the default `/up` health
+  check endpoint for Kamal deployments.'
 email:
-- allgood@rameerez.com
+- rubygems@rameerez.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -39,12 +40,15 @@ files:
 - README.md
 - Rakefile
 - allgood.jpeg
+- allgood_skipped.webp
 - app/controllers/allgood/base_controller.rb
 - app/controllers/allgood/healthcheck_controller.rb
 - app/views/allgood/healthcheck/index.html.erb
 - app/views/layouts/allgood/application.html.erb
 - config/routes.rb
+- examples/allgood.rb
 - lib/allgood.rb
+- lib/allgood/cache_store.rb
 - lib/allgood/configuration.rb
 - lib/allgood/engine.rb
 - lib/allgood/version.rb
@@ -56,7 +60,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/rameerez/allgood
   source_code_uri: https://github.com/rameerez/allgood
-  changelog_uri: https://github.com/rameerez/allgood
+  changelog_uri: https://github.com/rameerez/allgood/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -72,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Add quick, simple, and beautiful health checks to your Rails application.