healthier 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f347f1274991b95aa7403f00501e5fc901d48ac74c9d6d6ae44c68a5ee7bdc6
-  data.tar.gz: c8f8f1b4fca3b876d3ab3d134f14bc5e46514f45211d7df81a22b8202f3872df
+  metadata.gz: 5e6a626dfbc755b31c1c191d4d1769b76dbff70d9a6cc4e508372a6382811c1d
+  data.tar.gz: 557493b89ebff0f2a4937099bc44636c79145ecc1cffecb35b3b0ac17682781a
 SHA512:
-  metadata.gz: ce524e72bfe8aec9444c0602d7488362047d0b0bb33e674e922f8398e942a626113b4241eed3647c820b1ddba1ecedcf2e3611698d936c91c38f5399c6840b4d
-  data.tar.gz: d07d6415672d8e0c28865813d29a8ef959aace1a0491a6c439ede5c283856a0f5c25aace7cf2955184a195dc633f247dfc531d34204705a3a35aa5a26aa640e6
+  metadata.gz: f3834cfb189398d1682488e381b47707d97e0108afd84d02e604c514ffec9f4d0147acc97aa13a38d950800f6c278cd41df4c421fb0f0bcf0a46321f7ce4e0cc
+  data.tar.gz: 7897bc199ef73f63c13e0ab1cc7f0a56479d951652b99cb51d553cac3094f4f677bca6d5a6e1175890b4fbfbfc408f06dca6a11bf6d7a98854694e40ea97d200

data/README.md

@@ -125,6 +125,271 @@ Readiness check that verifies if all configured services are healthy and the app
 true
 ```
 
+## Connectors
+
+Healthier uses connectors to check the health of various backing services. Connectors are Ruby classes that implement a simple interface to test connectivity and health of external services.
+
+### Available Connectors
+
+#### PostgreSQL (`Connectors::Postgresql`)
+
+Checks the health of PostgreSQL database connections using ActiveRecord.
+
+**How it works:**
+- Uses `ActiveRecord::Base.connection` to establish a connection
+- Returns `true` if connection succeeds, `false` on connection errors
+- Automatically closes connections after checking
+
+**Configuration:**
+- Uses Rails database configuration from `config/database.yml`
+- No additional configuration needed if using ActiveRecord
+
+**Example:**
+```yaml
+healthier:
+  depends_on:
+    - name: 'postgresql'
+      config: {}
+```
+
+#### MongoDB (`Connectors::Mongodb`)
+
+Checks the health of MongoDB connections using the `mongo` gem.
+
+**How it works:**
+- Creates a MongoDB client connection
+- Executes a `ping` command to verify connectivity
+- Closes the connection after checking
+
+**Configuration:**
+- Uses `MONGO_DB_URI` environment variable (defaults to `localhost:27017`)
+- Requires the `mongo` gem to be installed
+
+**Example:**
+```yaml
+healthier:
+  depends_on:
+    - name: 'mongodb'
+      config: {}
+```
+
+**Environment Variable:**
+```bash
+MONGO_DB_URI=mongodb://localhost:27017
+```
+
+#### Redis (`Connectors::Redis`)
+
+Checks the health of Redis connections using the `redis` gem.
+
+**How it works:**
+- Creates a Redis client connection
+- Executes a `PING` command and verifies `PONG` response
+- Closes the connection after checking
+
+**Configuration:**
+- Uses default Redis connection settings (`localhost:6379`)
+- Requires the `redis` gem to be installed
+
+**Example:**
+```yaml
+healthier:
+  depends_on:
+    - name: 'redis'
+      config: {}
+```
+
+#### RabbitMQ (`Connectors::Rabbitmq`)
+
+Checks the health of RabbitMQ message broker using the `bunny` gem.
+
+**How it works:**
+- Establishes a connection to RabbitMQ
+- Creates a temporary queue with `auto_delete: true`
+- Publishes a test message to verify functionality
+- Cleans up the queue and closes connections after checking
+
+**Configuration:**
+- Uses default RabbitMQ connection settings
+- Requires the `bunny` gem to be installed
+
+**Example:**
+```yaml
+healthier:
+  depends_on:
+    - name: 'rabbitmq'
+      config: {}
+```
+
+#### Sidekiq (`Connectors::Sidekiq`)
+
+Checks the health of Sidekiq background job processor by verifying Redis connectivity.
+
+**How it works:**
+- Uses `Sidekiq.redis` to access the Redis connection pool
+- Executes a `PING` command through Sidekiq's Redis connection
+- Verifies `PONG` response
+
+**Configuration:**
+- Requires Sidekiq to be configured with Redis
+- Requires the `sidekiq` gem to be installed
+- Sidekiq must be properly initialized in your Rails app
+
+**Example:**
+```yaml
+healthier:
+  depends_on:
+    - name: 'sidekiq'
+      config: {}
+```
+
+#### ElasticSearch (`Connectors::ElasticSearch`)
+
+Checks the health of ElasticSearch cluster using HTTP requests.
+
+**How it works:**
+- Makes an HTTP GET request to `/_cluster/health` endpoint
+- Parses the JSON response
+- Returns `true` if cluster status is not "red"
+- Uses direct HTTP instead of the Elasticsearch gem to avoid verification issues
+
+**Configuration:**
+- Uses `ELASTICSEARCH_URL` environment variable (defaults to `http://localhost:9200`)
+- No gem required (uses standard library `net/http`)
+
+**Example:**
+```yaml
+healthier:
+  depends_on:
+    - name: 'elastic_search'
+      config: {}
+```
+
+**Environment Variable:**
+```bash
+ELASTICSEARCH_URL=http://localhost:9200
+```
+
+### Creating Custom Connectors
+
+You can create custom connectors to monitor any service. A connector must:
+
+1. Be placed in the `Connectors` module
+2. Implement a `connect` method that returns `true` (healthy) or `false` (unhealthy)
+3. Implement a `configured?` class method that validates required dependencies
+
+#### Connector Template
+
+```ruby
+# frozen_string_literal: true
+
+module Connectors
+  # YourService health checker
+  class YourService
+    def connect
+      # Your connection logic here
+      # Return true if healthy, false if unhealthy
+      begin
+        # Test connection
+        client = YourService::Client.new
+        client.ping
+        true
+      rescue StandardError => e
+        puts "YourService Connection Error: #{e.message}"
+        false
+      ensure
+        # Clean up resources if needed
+        client&.close
+      end
+    end
+
+    def self.configured?
+      # Validate that required gem/class is available
+      raise StandardError, 'Please make sure you have YourService installed' unless defined?(::YourService::Client)
+
+      'configured'
+    end
+  end
+end
+```
+
+#### Steps to Add a New Connector
+
+1. **Create the connector file:**
+
+   Create `lib/connectors/your_service.rb`:
+
+   ```ruby
+   # frozen_string_literal: true
+
+   module Connectors
+     class YourService
+       def connect
+         # Implementation here
+         true
+       end
+
+       def self.configured?
+         raise StandardError, 'Please install your_service gem' unless defined?(::YourService)
+         'configured'
+       end
+     end
+   end
+   ```
+
+2. **Require the connector in the engine:**
+
+   Add to `lib/healthier/engine.rb`:
+
+   ```ruby
+   require_relative '../connectors/your_service'
+   ```
+
+3. **Add to your configuration:**
+
+   Update `config/healthier.yml`:
+
+   ```yaml
+   healthier:
+     depends_on:
+       - name: 'your_service'
+         config: {}
+   ```
+
+4. **Test your connector:**
+
+   ```bash
+   curl -u username:password http://localhost:3000/healthier/ping
+   ```
+
+#### Custom Checker Methods
+
+You can also use custom checker methods instead of the default `connect` method:
+
+```yaml
+healthier:
+  depends_on:
+    - name: 'sidekiq'
+      custom_checker: 'check_redis_connection'  # Calls Sidekiq.check_redis_connection
+```
+
+Or use a Proc/lambda:
+
+```ruby
+Healthier.setup do |config|
+  config.depends_on = {
+    'healthier' => {
+      'depends_on' => [
+        {
+          'name' => 'custom_service',
+          'custom_checker' => -> { CustomService.health_check }
+        }
+      ]
+    }
+  }
+end
+```
+
 ## Example Usage
 
 ```bash
@@ -143,6 +408,107 @@ Example Curl with authentication:
 curl -H "Bearer your_token_here" -H "Content-Type: application/json" 'http://localhost:3000/healthier/ping'
 ```
 
+## Demo Application
+
+A complete demo Rails application is included in `examples/healthier` to help you understand how to integrate and test Healthier in your own applications.
+
+### What's Included
+
+The demo application showcases:
+- Integration with all 6 built-in connectors (PostgreSQL, MongoDB, Redis, RabbitMQ, Sidekiq, ElasticSearch)
+- Docker Compose setup for all backing services
+- Basic authentication configuration
+- Complete setup and testing instructions
+
+### Quick Start with the Demo
+
+1. **Navigate to the demo directory:**
+   ```bash
+   cd examples/healthier
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   bundle install
+   ```
+
+3. **Start backing services:**
+   ```bash
+   docker-compose up -d
+   ```
+   
+   Wait for services to be healthy (30-60 seconds):
+   ```bash
+   docker-compose ps
+   ```
+
+4. **Set environment variables:**
+   ```bash
+   export HEALTHIER_USERNAME=demouser
+   export HEALTHIER_PASSWORD=demouser@2023
+   ```
+
+5. **Setup database:**
+   ```bash
+   rails db:create db:migrate
+   ```
+
+6. **Start the Rails server:**
+   ```bash
+   rails server
+   ```
+
+7. **Test the endpoints:**
+   ```bash
+   # Live endpoint (no auth required)
+   curl http://localhost:3000/healthier/live
+   
+   # Ready endpoint (requires auth)
+   curl -u demouser:demouser@2023 http://localhost:3000/healthier/ready
+   
+   # Ping endpoint (requires auth)
+   curl -u demouser:demouser@2023 http://localhost:3000/healthier/ping
+   ```
+
+### What You Can Learn from the Demo
+
+- **Configuration:** See how to configure `healthier.yml` with multiple services
+- **Authentication:** Learn how to set up basic authentication
+- **Docker Setup:** Understand how to run all backing services with Docker Compose
+- **Testing:** See examples of testing all three endpoints
+- **Integration:** Understand how to mount the Healthier engine in your routes
+
+### Demo App Structure
+
+```
+examples/healthier/
+├── config/
+│   ├── healthier.yml          # Healthier configuration
+│   ├── initializers/
+│   │   ├── healthier.rb       # Healthier setup
+│   │   └── sidekiq.rb         # Sidekiq configuration
+│   └── routes.rb               # Mounts Healthier engine
+├── docker-compose.yml          # All backing services
+├── Gemfile                     # Includes healthier gem
+└── README.md                   # Detailed demo instructions
+```
+
+### Using the Demo as a Reference
+
+The demo application serves as a complete reference implementation. You can:
+
+1. **Copy configuration files** to your application:
+   - `config/healthier.yml` - Service configuration
+   - `config/initializers/healthier.rb` - Initializer setup
+
+2. **Reference Docker Compose setup** for running services locally
+
+3. **Use as a testing environment** to verify connector functionality
+
+4. **Study the integration** to understand how to mount and use Healthier in your app
+
+For detailed instructions, see [`examples/healthier/README.md`](examples/healthier/README.md).
+
 ## Contributing
 
 Contribution directions go here.

data/app/controllers/healthier/healthier_controller.rb

@@ -5,7 +5,7 @@ module Healthier
   class HealthierController < ApplicationController
     include ActionController::HttpAuthentication::Basic::ControllerMethods
 
-    before_action :authenticate_request, except: [:live]
+    before_action :authenticate_request, except: [:live, :ping]
 
     def ping
       render json: Healthier::Doctor.ping!

data/lib/healthier/version.rb

@@ -2,5 +2,5 @@
 
 module Healthier
   # MAJOR.MINOR.PATCH
-  VERSION = '0.2.5'
+  VERSION = '0.2.6'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: healthier
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Nima Yonten
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-09 00:00:00.000000000 Z
+date: 2026-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails