rails_maint 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2b1b8a1904b4d02c2f73d2274afdef2bd999883d326e1c12308802454b97c22
-  data.tar.gz: 5772a26f65a8c5bd00d76ed7b155fb6bb34fd4f20e524a337d0da1b2471c663c
+  metadata.gz: 644b76b9127a7f3d676d57ac465b5d4a0e51c182ed7e688255521c525c04b8ff
+  data.tar.gz: 93a468bdd47373347f2b4da22b471fb3b3792b403e394a24aa7fb3106d5f9767
 SHA512:
-  metadata.gz: fef32a839d45b57beed5f2bb3937a41b00ec546557c5117d061c6104bdd55d35576ce35634cef15c421ed10261d1dbfcd4992856c4afce23d07c021c0c14144a
-  data.tar.gz: 7315dcadd5a482c59c85a301e157b2fd786459d6f15c75434992f6498c0ac6da27acd346854754b923afa9b4e7139c3643c1c2e9e15122cb0b6be294518dfe54
+  metadata.gz: d9f1558562c106f2acb1e6cdcce18bbd2d4c7d12af5e199d985f313f488e375562aaf086433c0d4faa33e9dca946c6c65e2913424284b31248bddcf5f32c5171
+  data.tar.gz: a1e1ff3f2d802c22d37c41306f0e0fe41b4c0a5c9983852c08f7284563753f0155851407f78df86cd817d022cc9df0a03881dd34695f4287449b3316212460e4

data/CHANGELOG.md

@@ -1,5 +1,70 @@
-## [0.1.1] - 2024-03-XX
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-02-28
+
 ### Added
-- New feature
+- **Configuration DSL** — `RailsMaint.configure { |c| c.retry_after = 1800 }` for programmatic configuration
+- **Railtie** — Middleware is now auto-registered in Rails apps (no manual `config.middleware.use` needed)
+- **Rails Generator** — `rails generate rails_maint:install` creates config, locale, and initializer files
+- **Retry-After header** — 503 responses include a `Retry-After` header (default: 3600s, configurable)
+- **Route-based maintenance** — `bypass_paths` (always accessible) and `maintenance_paths` (only these paths show maintenance)
+- **Custom maintenance page** — Serve a custom HTML file instead of the default template
+- **Scheduled maintenance** — `rails_maint enable --start="..." --end="..."` for time-windowed maintenance
+- **CLI `status` command** — `rails_maint status` shows current maintenance state and configuration
+- **Webhook notifications** — POST JSON to a configured URL on enable/disable events
+- **ConfigLoader module** — Shared YAML config loading extracted from middleware and CLI
+- **Rails.logger integration** — All log output goes through `RailsMaint.logger` (auto-wired to `Rails.logger` via Railtie)
+- **ActiveSupport::Notifications** — Instrumentation events: `request_blocked.rails_maint`, `enabled.rails_maint`, `disabled.rails_maint`
+- **Custom error classes** — `InvalidConfigurationError`, `InvalidLocaleError`, `ScheduleError`, `WebhookError`
+- **Configuration validation** — `validate!` checks locale format, retry_after, and webhook_url on `RailsMaint.configure`
+- **SimpleCov code coverage** — 99%+ line coverage with branch coverage tracking
+- **README badges** — Gem version, CI status, Codecov, RuboCop style, MIT license
+- **Schedule module** — Parses scheduled maintenance windows with backward-compatible flag file format
+- `remaining_time` translation key added to en.yml and tr.yml
+
+### Security
+- Fix IP spoofing vulnerability via X-Forwarded-For header
+- Fix XSS vulnerability in maintenance page template
+- Fix YAML deserialization vulnerability (switched to safe_load)
+- Fix path traversal vulnerability in locale handling
+- Path traversal protection for custom maintenance page
+
 ### Fixed
-- Bug fix
+- Remove debug puts statement from production code path
+- Add missing require statements in middleware
+- Fix uninstall command to dynamically find locale files
+- Add locale validation for install command
+- Ensure tmp/ directory exists before writing maintenance file
+
+### Changed
+- Minimum Ruby version updated to 3.0+
+- Migrated CI from Travis CI to GitHub Actions
+- Improved error handling throughout
+- Installation reduced from 4 steps to 2 steps (`bundle add` + `rails generate`)
+- Middleware refactored to use Configuration DSL with YAML precedence
+- CLI `uninstall` now also removes the initializer file
+
+### Removed
+- Remove unused create_maintenance_page method
+- Remove obsolete .travis.yml
+
+## [0.1.1] - 2024-03-28
+
+### Added
+- Multi-language support (English, Turkish)
+- IP whitelist support with proxy header detection
+- CLI commands (install, enable, disable, uninstall)
+- Rack middleware integration
+- Customizable maintenance page with modern design
+
+## [0.1.0] - 2024-03-20
+
+### Added
+- Initial release
+- Basic maintenance mode functionality
+- Simple CLI interface

data/README.md

@@ -1,129 +1,259 @@
 # RailsMaint
 
+[![Gem Version](https://badge.fury.io/rb/rails_maint.svg)](https://badge.fury.io/rb/rails_maint)
+[![Build Status](https://github.com/codescaptain/rails_maint/workflows/CI/badge.svg)](https://github.com/codescaptain/rails_maint/actions)
+[![codecov](https://codecov.io/gh/codescaptain/rails_maint/branch/main/graph/badge.svg)](https://codecov.io/gh/codescaptain/rails_maint)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<img src="https://github.com/user-attachments/assets/4daa45fe-833b-48c5-9f69-457424769804" width="500" height="500" alt="rails_maint">
+
+
 RailsMaint is a simple and customizable maintenance mode gem for Rails applications. It allows you to display a sleek maintenance page to your users during maintenance work.
 
 ## Features
 
-- 🚀 Easy setup and usage
-- 🎨 Customizable, modern maintenance page design
-- 🌍 Multi-language support (English and Turkish)
-- 🔒 IP whitelist support
-- 💻 Simple CLI commands
-- 🎯 Rails Middleware integration
+- Easy setup — just 2 commands to install
+- Automatic middleware registration via Railtie
+- Configuration DSL and YAML config support
+- Retry-After HTTP header for SEO-friendly 503 responses
+- Route-based maintenance with bypass paths
+- Scheduled maintenance windows with auto-deactivation
+- Custom maintenance page support
+- Multi-language support (English and Turkish)
+- IP whitelist support
+- CLI commands (install, enable, disable, status, uninstall)
+- Webhook notifications on enable/disable events
+- Rails Generator for quick setup
 
 ## Installation
 
-1. Add this line to your application's Gemfile:
+### Rails Apps (Recommended)
 
+```bash
+bundle add rails_maint
+rails generate rails_maint:install
 ```
+
+That's it! The Railtie automatically registers the middleware. The generator creates:
+- `config/rails_maint.yml` — Configuration file
+- `config/locales/rails_maint.en.yml` — Language file
+- `config/initializers/rails_maint.rb` — Initializer with DSL configuration
+
+### Manual Setup
+
+1. Add to your Gemfile:
+
+```ruby
 gem 'rails_maint'
 ```
 
-2. Execute:
+2. Run:
 
-```
+```bash
 bundle install
+rails_maint install
 ```
 
-3. Add the middleware to your Rails application's `config/application.rb`:
+3. If you need manual middleware registration (the Railtie handles this automatically):
 
-```
+```ruby
+# config/application.rb
 config.middleware.use RailsMaint::Middleware
 ```
 
 ## Usage
 
-### Installing the Gem
-
-```
-# For English (default)
-rails_maint install
-
-# For Turkish
-rails_maint install --locale=tr
-```
-
-This command creates the following files:
-- `config/rails_maint.yml` - Configuration file
-- `config/locales/rails_maint.{locale}.yml` - Language file
-
 ### Managing Maintenance Mode
 
-```
-# To enable maintenance mode
+```bash
+# Enable maintenance mode
 rails_maint enable
 
-# To disable maintenance mode
+# Enable with scheduled window
+rails_maint enable --start="2024-06-01 10:00" --end="2024-06-01 12:00"
+
+# Disable maintenance mode
 rails_maint disable
 
-# To remove all files
+# Check current status
+rails_maint status
+
+# Remove all RailsMaint files
 rails_maint uninstall
 ```
 
+### Status Command
+
+```bash
+$ rails_maint status
+Status: ENABLED
+  Enabled at: 2024-06-01 10:00:00 +0000
+  Start time: 2024-06-01 10:00:00 +0000
+  End time:   2024-06-01 12:00:00 +0000
+  Remaining:  3542s
+
+Locale: en
+Whitelisted IPs: 127.0.0.1, ::1
+Bypass paths: /health, /up
+Retry-After: 3600s
+Custom page: none
+Webhook URL: none
+```
+
 ## Configuration
 
-You can customize your settings in `config/rails_maint.yml`:
+### YAML Configuration
 
-```
+Customize your settings in `config/rails_maint.yml`:
+
+```yaml
 # Default language setting
 locale: en
 
-# IP addresses allowed to access
+# IP addresses allowed to access during maintenance
 white_listed_ips:
-- 127.0.0.1
-- ::1
-# Add your IPs
-# - 192.168.1.1
+  - 127.0.0.1
+  - "::1"
+
+# Retry-After header value in seconds (default: 3600)
+retry_after: 3600
+
+# Paths that bypass maintenance mode (always accessible)
+bypass_paths:
+  - /health
+  - /up
+  - /api/status
+
+# Only apply maintenance to specific paths (empty = all paths)
+# maintenance_paths:
+#   - /api/*
+
+# Custom maintenance page (relative to app root)
+# custom_page: public/maintenance.html
+
+# Webhook URL for maintenance notifications
+# webhook_url: https://hooks.slack.com/services/...
 ```
 
-## Language Support
+### DSL Configuration
 
-Language files are stored in the `config/locales` directory. You can customize existing translations or add new languages:
+Configure programmatically in `config/initializers/rails_maint.rb`:
 
+```ruby
+RailsMaint.configure do |config|
+  config.locale = 'en'
+  config.white_listed_ips = ['127.0.0.1', '::1']
+  config.retry_after = 3600
+  config.bypass_paths = ['/health', '/up']
+  config.maintenance_paths = []
+  config.custom_page_path = 'public/maintenance.html'
+  config.webhook_url = 'https://hooks.slack.com/services/...'
+end
 ```
-# config/locales/rails_maint.en.yml
-en:
-rails_maint:
-title: "System Maintenance"
-description: "Our system is currently being updated..."
-estimated_time: "Estimated time: 1 hour"
+
+**Precedence:** YAML config > DSL config > defaults
+
+## Route-Based Maintenance
+
+### Bypass Paths
+
+Keep certain endpoints accessible during maintenance:
+
+```yaml
+bypass_paths:
+  - /health
+  - /up
+  - /api/status
+```
+
+### Maintenance Paths
+
+Only show maintenance for specific paths (all others pass through):
+
+```yaml
+maintenance_paths:
+  - /api/*
 ```
 
+Wildcard matching is supported with `/*` suffix for prefix matching. When both are configured, `bypass_paths` takes precedence.
+
+## Scheduled Maintenance
+
+Schedule a maintenance window that auto-deactivates:
+
+```bash
+rails_maint enable --start="2024-06-01 10:00" --end="2024-06-01 12:00"
 ```
-# config/locales/rails_maint.tr.yml
-tr:
-rails_maint:
-title: "Sistem Bakımda"
-description: "Sistemimiz şu anda güncelleniyor..."
-estimated_time: "Tahmini süre: 1 saat"
+
+- Before `start_time`: requests pass through normally
+- Between `start_time` and `end_time`: maintenance page is shown
+- After `end_time`: requests pass through again
+- The `Retry-After` header is automatically computed from the remaining time
+
+## Custom Maintenance Page
+
+Serve your own HTML file instead of the default template:
+
+```yaml
+custom_page: public/maintenance.html
+```
+
+The file path is validated against path traversal attacks. If the file doesn't exist, the default template is used as a fallback.
+
+## Webhook Notifications
+
+Get notified when maintenance mode changes:
+
+```yaml
+webhook_url: https://hooks.slack.com/services/T00/B00/xxx
+```
+
+The gem sends a POST request with a JSON payload:
+
+```json
+{
+  "event": "maintenance.enabled",
+  "timestamp": "2024-06-01T10:00:00+00:00",
+  "gem": "rails_maint",
+  "version": "0.1.1"
+}
+```
+
+Events: `maintenance.enabled`, `maintenance.disabled`
+
+## Language Support
+
+Language files are stored in the `config/locales` directory. You can customize existing translations or add new languages:
+
+```yaml
+# config/locales/rails_maint.en.yml
+en:
+  rails_maint:
+    title: "System Maintenance"
+    description: "Our system is currently being updated..."
+    estimated_time: "Estimated time: 1 hour"
+    remaining_time: "Estimated remaining time: %{time}"
 ```
 
 ## How IP Whitelist Works
 
 - When maintenance mode is active, IPs in the whitelist can access the site normally
 - All other IPs will see the maintenance page
-- If behind a proxy, the gem checks the X-Forwarded-For header
-- Each IP should be added to the configuration file
+- The gem uses `REMOTE_ADDR` for IP checking (not `X-Forwarded-For`, to prevent spoofing)
+- IPs can be configured via both YAML and DSL (merged from both sources)
+
+## Requirements
+
+- Rails 6.0 or higher
+- Ruby 3.0 or higher
 
 ## Development
 
 1. Clone the repository
 2. Install dependencies: `bundle install`
 3. Run tests: `bundle exec rspec`
-
-## Customizing the Maintenance Page
-
-The maintenance page template can be customized by creating your own version in `public/maintenance.html`. The default template includes:
-
-- Responsive design
-- Animated maintenance icon
-- Clean and modern layout
-- Estimated time display
-
-## Rails Version Support
-
-- Rails 6.0 or higher
-- Ruby 2.6 or higher
+4. Run linter: `bundle exec rubocop`
 
 ## Contributing
 
@@ -133,32 +263,13 @@ The maintenance page template can be customized by creating your own version in
 4. Push to the branch (`git push origin feature/amazing_feature`)
 5. Create a Pull Request
 
-## Best Practices
-
-- Always test your changes
-- Follow the Ruby Style Guide
-- Write meaningful commit messages
-- Add tests for new features
-- Update documentation when needed
-
-## Common Issues
-
-### IP Whitelist Not Working
-
-Make sure your IP is correctly added to the configuration file and you're not behind an unexpected proxy.
-
-### Language Not Changing
-
-Verify that:
-1. The locale file exists
-2. The locale is correctly set in the configuration
-3. The Rails server was restarted after changes
-
 ## Security
 
-- The gem uses Rails' built-in security features
-- IP validation is performed securely
-- No sensitive information is exposed
+- Uses `REMOTE_ADDR` for IP validation (prevents spoofing via `X-Forwarded-For`)
+- HTML-escapes all translation values to prevent XSS
+- Uses `YAML.safe_load_file` for safe deserialization
+- Validates locale format with strict regex pattern
+- Path traversal protection for custom maintenance pages and locale files
 
 ## License
 
@@ -175,4 +286,4 @@ Developed and maintained by [CodesCaptain](https://github.com/codescaptain)
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes.

data/lib/generators/rails_maint/install/install_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RailsMaint
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :locale, type: :string, default: 'en',
+                            desc: 'Set the language for maintenance page (e.g., en, tr)'
+
+      desc 'Installs RailsMaint configuration, locale, and initializer files'
+
+      def create_config_file
+        template 'rails_maint.yml.tt', 'config/rails_maint.yml'
+      end
+
+      def copy_locale_file
+        locale = options[:locale]
+        source = gem_locale_path(locale)
+
+        unless File.exist?(source)
+          say "Locale '#{locale}' is not supported. Falling back to 'en'.", :red
+          locale = 'en'
+          source = gem_locale_path(locale)
+        end
+
+        create_file "config/locales/rails_maint.#{locale}.yml", File.read(source)
+      end
+
+      def create_initializer
+        template 'initializer.rb.tt', 'config/initializers/rails_maint.rb'
+      end
+
+      def show_post_install_message
+        say ''
+        say 'RailsMaint installed successfully!', :green
+        say ''
+        say 'Usage:'
+        say '  rails_maint enable   # Enable maintenance mode'
+        say '  rails_maint disable  # Disable maintenance mode'
+        say '  rails_maint status   # Show maintenance status'
+        say ''
+        say 'Configuration: config/rails_maint.yml'
+        say 'Initializer:   config/initializers/rails_maint.rb'
+        say ''
+      end
+
+      private
+
+      def gem_locale_path(locale)
+        File.expand_path("../../../rails_maint/assets/locales/#{locale}.yml", __dir__)
+      end
+    end
+  end
+end

data/lib/generators/rails_maint/install/templates/initializer.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# RailsMaint Configuration
+# Middleware is automatically registered via Railtie.
+# Settings here override defaults; YAML config (config/rails_maint.yml) takes precedence.
+
+RailsMaint.configure do |config|
+  # Locale for the maintenance page (default: 'en')
+  # config.locale = '<%= options[:locale] %>'
+
+  # IP addresses that bypass maintenance mode
+  # config.white_listed_ips = ['127.0.0.1', '::1']
+
+  # Path to the maintenance flag file
+  # config.maintenance_file_path = 'tmp/maintenance_mode.txt'
+
+  # Retry-After header value in seconds
+  # config.retry_after = 3600
+
+  # Paths that always bypass maintenance mode
+  # config.bypass_paths = ['/health', '/up']
+
+  # Only apply maintenance to specific paths (empty = all paths)
+  # config.maintenance_paths = []
+
+  # Custom maintenance page path (relative to app root)
+  # config.custom_page_path = 'public/maintenance.html'
+
+  # Webhook URL for maintenance event notifications
+  # config.webhook_url = 'https://hooks.slack.com/services/...'
+end

data/lib/generators/rails_maint/install/templates/rails_maint.yml.tt

@@ -0,0 +1,32 @@
+# RailsMaint Configuration
+# -----------------------
+
+# Default locale for maintenance page
+locale: <%= options[:locale] %>
+
+# IP addresses that can access the application during maintenance
+white_listed_ips:
+  - 127.0.0.1
+  - "::1"
+  # Add more IPs below
+  # - 192.168.1.1
+
+# Retry-After header value in seconds (default: 3600)
+# retry_after: 3600
+
+# Paths that bypass maintenance mode (always accessible)
+# bypass_paths:
+#   - /health
+#   - /up
+#   - /api/status
+
+# Paths that are affected by maintenance mode (all others pass through)
+# When empty, all paths are affected
+# maintenance_paths:
+#   - /api/*
+
+# Custom maintenance page (relative to app root)
+# custom_page: public/maintenance.html
+
+# Webhook URL for maintenance notifications (e.g., Slack incoming webhook)
+# webhook_url: https://hooks.slack.com/services/...

data/lib/rails_maint/assets/locales/en.yml

@@ -2,4 +2,5 @@ en:
   rails_maint:
     title: "System Maintenance"
     description: "Our system is currently being updated..."
-    estimated_time: "Estimated time: 1 hour"
+    estimated_time: "Estimated time: 1 hour"
+    remaining_time: "Estimated remaining time: %{time}"

data/lib/rails_maint/assets/locales/tr.yml

@@ -2,4 +2,5 @@ tr:
   rails_maint:
     title: "Sistem Bakımda"
     description: "Sistemimiz şu anda güncelleniyor..."
-    estimated_time: "Tahmini süre: 1 saat"
+    estimated_time: "Tahmini süre: 1 saat"
+    remaining_time: "Tahmini kalan süre: %{time}"

data/lib/rails_maint/cli/status_printer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RailsMaint
+  class StatusPrinter
+    def print
+      config = ConfigLoader.load
+      print_maintenance_status
+      puts ''
+      print_config_status(config)
+    end
+
+    private
+
+    def print_maintenance_status
+      maintenance_file = 'tmp/maintenance_mode.txt'
+
+      unless File.exist?(maintenance_file)
+        puts 'Status: DISABLED'
+        return
+      end
+
+      schedule = RailsMaint::Schedule.load(maintenance_file)
+      puts schedule.active? ? 'Status: ENABLED' : 'Status: ENABLED (not currently active — outside scheduled window)'
+      print_schedule_details(schedule)
+    end
+
+    def print_schedule_details(schedule)
+      puts "  Enabled at: #{schedule.enabled_at}" if schedule.enabled_at
+      puts "  Start time: #{schedule.start_time}" if schedule.start_time
+      puts "  End time:   #{schedule.end_time}" if schedule.end_time
+
+      return unless schedule.end_time
+
+      remaining = schedule.seconds_until_end
+      puts "  Remaining:  #{remaining}s" if remaining
+    end
+
+    def print_config_status(config)
+      puts "Locale: #{config['locale'] || 'en'}"
+      print_list('Whitelisted IPs', config['white_listed_ips'])
+      print_list('Bypass paths', config['bypass_paths'])
+      puts "Retry-After: #{config['retry_after'] || 3600}s"
+      puts "Custom page: #{config['custom_page'] || 'none'}"
+      puts "Webhook URL: #{config['webhook_url'] || 'none'}"
+    end
+
+    def print_list(label, items)
+      items ||= []
+      puts "#{label}: #{items.empty? ? 'none' : items.join(', ')}"
+    end
+  end
+end