allgood 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe79d04db962fcfc50cb094c0b122506d09f903b7ee02e2ee7ae0c3930c78557
+  data.tar.gz: fb9a69be909db1c10d5019dfadbdbee5b7da514913d8a907933cd2873e73f2f0
+SHA512:
+  metadata.gz: fc26bbc3685f38fbfa49e05047987537c64e06c55356c28d0c8a0a50b73b6981c10d66c96996ca44057720402f4f5ed1319309a33402b25a39d0bdf472518496
+  data.tar.gz: ea88c1027193b356560b2361e65a28c42d3b10683df7e777796ff5de10c0c6e3aa93f7bb42fa70ef6ce9699d288e4efa74ceaa82667a5208ec006aa41506e6ea

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-08-22
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Javi R
+
+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,132 @@
+# ✅ Allgood - Rails gem for health checks
+
+Add quick, simple, and beautiful health checks to your Rails application.
+
+`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.
+
+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.
+
+![alt text](allgood.jpeg)
+
+## Installation
+
+Add this line to your application's Gemfile:
+```ruby
+gem 'allgood'
+```
+
+Then run `bundle install`.
+
+## Usage
+
+### Mounting the Engine
+
+In your `config/routes.rb` file, mount the Allgood engine:
+```ruby
+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.
+
+`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`
+
+
+### Configuring Health Checks
+
+Create a file `config/allgood.rb` in your Rails application. This is where you'll define your health checks:
+```ruby
+# config/allgood.rb
+
+check "We have an active database connection" do
+  make_sure ActiveRecord::Base.connection.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:
+```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'`"
+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.
+
+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
+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)
+end
+
+check "The last created Purchase has a valid total" do
+  last_purchase = Purchase.order(created_at: :desc).limit(1).first
+  make_sure last_purchase.total.is_a?(Numeric), "Purchase total should be a number"
+  expect(last_purchase.total).to_be_greater_than(0)
+end
+```
+
+Other nice checks to have:
+```ruby
+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 "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'`"
+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
+```
+
+If you have other nice default checks, please open a PR! I'd love to provide a good default `config/allgood.rb` file.
+
+> ⚠️ 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.
+
+
+### 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!
+
+## Customization
+
+### Timeout
+
+By default, each check has a timeout of 10 seconds.
+
+
+## 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.
+
+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).
+
+## 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.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/app/controllers/allgood/base_controller.rb

@@ -0,0 +1,5 @@
+module Allgood
+  class BaseController < ApplicationController
+    layout 'allgood/application'
+  end
+end

data/app/controllers/allgood/healthcheck_controller.rb

@@ -0,0 +1,61 @@
+require 'timeout'
+
+module Allgood
+  class HealthcheckController < BaseController
+    def index
+      @results = run_checks
+      @status = @results.all? { |r| r[:success] } ? "ok" : "error"
+      status_code = @status == "ok" ? :ok : :service_unavailable
+
+      respond_to do |format|
+        format.html { render :index, status: status_code }
+        format.json { render json: { status: @status, checks: @results }, status: status_code }
+      end
+    rescue StandardError => e
+      # Log the error
+      Rails.logger.error "Allgood Healthcheck Error: #{e.message}\n#{e.backtrace.join("\n")}"
+
+      # Return a minimal response
+      @results = [{ name: "Healthcheck Error", success: false, message: "Internal error occurred", duration: 0 }]
+      @status = "error"
+
+      respond_to do |format|
+        format.html { render :index, status: :internal_server_error }
+        format.json { render json: { status: @status, checks: @results }, status: :internal_server_error }
+      end
+    end
+
+    private
+
+    def run_checks
+      Allgood.configuration.checks.map do |check|
+        run_single_check(check)
+      end
+    end
+
+    def run_single_check(check)
+      start_time = Time.now
+      result = { success: false, message: "Check timed out after #{check[:timeout]} seconds" }
+
+      begin
+        Timeout.timeout(check[:timeout]) do
+          check_result = Allgood.configuration.run_check(&check[:block])
+          result = { success: check_result[:success], message: check_result[:message] }
+        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}" }
+      end
+
+      {
+        name: check[:name],
+        success: result[:success],
+        message: result[:message],
+        duration: ((Time.now - start_time) * 1000).round(1)
+      }
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+<style>
+  header {
+    min-height: 20vh;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    color: white;
+    background-color: <%= @status == "ok" ? "MediumSeaGreen" : "FireBrick" %> !important;
+    font-weight: bold;
+    font-size: 2.7rem;
+    margin-bottom: 1em;
+  }
+
+  .check {
+    margin: 0.5em 0;
+  }
+</style>
+
+<header>
+  <h1><%= @status == "ok" ? "🤙 It's all good" : "❌ Something's wrong" %></h1>
+</header>
+
+<% 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>
+  <% end %>
+<% else %>
+  <p>No health checks were run. Please check your configuration.</p>
+<% end %>

data/app/views/layouts/allgood/application.html.erb

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Health Check</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+  <link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css">
+</head>
+<body>
+  <%= yield %>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,3 @@
+Allgood::Engine.routes.draw do
+  root to: "healthcheck#index"
+end

data/lib/allgood/configuration.rb

@@ -0,0 +1,75 @@
+module Allgood
+  class Configuration
+    attr_reader :checks
+    attr_accessor :default_timeout
+
+    def initialize
+      @checks = []
+      @default_timeout = 10 # Default timeout of 10 seconds
+    end
+
+    def check(name, &block)
+      @checks << { name: name, block: block, timeout: @default_timeout }
+    end
+
+    def run_check(&block)
+      CheckRunner.new.instance_eval(&block)
+    end
+  end
+
+  class CheckRunner
+    def make_sure(condition, message = nil)
+      if condition
+        { success: true, message: message || "Check passed" }
+      else
+        raise CheckFailedError.new(message || "Check failed")
+      end
+    end
+
+    def expect(actual)
+      Expectation.new(actual)
+    end
+  end
+
+  class Expectation
+    def initialize(actual)
+      @actual = actual
+    end
+
+    def to_eq(expected)
+      if @actual == expected
+        { success: true, message: "Got: #{@actual || 'nil'}" }
+      else
+        raise CheckFailedError.new("Expected #{expected} to equal #{@actual || 'nil'} but it doesn't")
+      end
+    end
+
+    def to_be_greater_than(expected)
+      if @actual > expected
+        { success: true, message: "Got: #{@actual || 'nil'} (> #{expected})" }
+      else
+        raise CheckFailedError.new("We were expecting #{@actual || 'nil'} to be greater than #{expected} but it's not")
+      end
+    end
+
+    def to_be_less_than(expected)
+      if @actual < expected
+        { success: true, message: "Got: #{@actual || 'nil'} (< #{expected})" }
+      else
+        raise CheckFailedError.new("We were expecting #{@actual || 'nil'} to be less than #{expected} but it's not")
+      end
+    end
+
+    # Add more expectations as needed
+  end
+
+  class CheckFailedError < StandardError; end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/allgood/engine.rb

@@ -0,0 +1,14 @@
+module Allgood
+  class Engine < ::Rails::Engine
+    isolate_namespace Allgood
+
+    initializer "allgood.load_configuration" do
+      config_file = Rails.root.join("config", "allgood.rb")
+      if File.exist?(config_file)
+        Allgood.configure do |config|
+          config.instance_eval(File.read(config_file))
+        end
+      end
+    end
+  end
+end

data/lib/allgood/version.rb

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

data/lib/allgood.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "allgood/version"
+require_relative "allgood/engine"
+require_relative "allgood/configuration"
+
+module Allgood
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/allgood.rbs

@@ -0,0 +1,4 @@
+module Allgood
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: allgood
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-08-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !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.'
+email:
+- allgood@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- allgood.jpeg
+- 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
+- lib/allgood.rb
+- lib/allgood/configuration.rb
+- lib/allgood/engine.rb
+- lib/allgood/version.rb
+- sig/allgood.rbs
+homepage: https://github.com/rameerez/allgood
+licenses:
+- MIT
+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
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key:
+specification_version: 4
+summary: Add quick, simple, and beautiful health checks to your Rails application.
+test_files: []