sidekiq_queue_manager 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: decb676a394e280ac75b0a45c17541551d2191ad74205c57bf8cf5b333eb4341
+  data.tar.gz: ef24c3fd05b309c5df6eb852791238d8a458393f002d371c526b8fd3dc2512ed
+SHA512:
+  metadata.gz: 553576ce338f3b59688ad806a5d227f021d2c2a0b84a775246724e1ba4e1c089a4f66ac796e7a155ce2da0da13b95bacd941287d31315c273b9e0a54f483f448
+  data.tar.gz: 100b3bdbf614358e6099721185ef05ed395620172fe743030cd1d64698c161afa72a75aac413cb6af450b0abef3dbbac48e71677909aa4031138c7c15a6ff032

data/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  # ========================================
+  # Basic Build Test - Multiple Ruby versions
+  # ========================================
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['3.0', '3.1', '3.2', '3.3']
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+
+    - name: Install dependencies
+      run: bundle install
+
+    - name: Verify assets exist
+      run: bundle exec rake assets
+
+    - name: Build gem
+      run: gem build sidekiq_queue_manager.gemspec
+
+    - name: Test gem installation
+      run: gem install sidekiq_queue_manager-*.gem

data/INSTALLATION.md

@@ -0,0 +1,191 @@
+# Sidekiq Queue Manager Installation Guide
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sidekiq_queue_manager'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Quick Setup
+
+### **1. Set Authentication (REQUIRED)**
+
+Create `config/initializers/sidekiq_queue_manager.rb`:
+
+```ruby
+SidekiqQueueManager.configure do |config|
+  # REQUIRED: Set basic auth password (follows Sidekiq Web UI pattern)
+  config.basic_auth_password = 'your-secure-password-here'
+  
+  # Optional: Protect critical queues
+  config.critical_queues = %w[mailers high_priority]
+end
+```
+
+**⚠️ Professional Standard**: Like Sidekiq Web UI, this gem requires explicit authentication configuration. You must set a password or configure custom authentication.
+
+### **2. Mount the Engine**
+
+Add to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount SidekiqQueueManager::Engine => '/sidekiq_manager'
+  # your other routes...
+end
+```
+
+### **3. Access the Interface**
+
+Visit `http://localhost:3000/sidekiq_manager` and login with:
+
+- **Username**: `admin` (default)
+- **Password**: `your-secure-password-here`
+
+That's it! 🎉
+
+## Authentication Options
+
+### Basic HTTP Authentication (Default)
+
+Following professional standards like Sidekiq Web UI, the gem uses explicit authentication:
+
+```ruby
+SidekiqQueueManager.configure do |config|
+  config.basic_auth_password = 'your-secure-password'
+  config.basic_auth_username = 'admin'  # optional, defaults to 'admin'
+end
+```
+
+### Custom Authentication
+
+Integrate with your existing Rails authentication system:
+
+```ruby
+SidekiqQueueManager.configure do |config|
+  config.authentication_method = :authenticate_admin!  # Your method name
+  config.basic_auth_enabled = false  # Disable basic auth when using custom
+end
+
+# Then implement in your ApplicationController:
+class ApplicationController < ActionController::Base
+  private
+
+  def authenticate_admin!
+    redirect_to login_path unless current_user&.admin?
+  end
+end
+```
+
+### Disable Authentication (Development Only)
+
+```ruby
+SidekiqQueueManager.configure do |config|
+  config.basic_auth_enabled = false  # NOT recommended for production
+end
+```
+
+### Professional Examples
+
+#### Rails App with Devise
+
+```ruby
+# config/initializers/sidekiq_queue_manager.rb
+SidekiqQueueManager.configure do |config|
+  # Integrate with Devise authentication
+  config.authentication_method = :authenticate_user!
+  config.basic_auth_enabled = false
+  config.critical_queues = %w[mailers]
+end
+```
+
+#### Rails App with Custom Auth
+
+```ruby
+# config/initializers/sidekiq_queue_manager.rb  
+SidekiqQueueManager.configure do |config|
+  # Use custom authentication method
+  config.authentication_method = :require_admin_access!
+  config.basic_auth_enabled = false
+  config.critical_queues = %w[mailers]
+end
+```
+
+#### API-only Rails App (No Authentication)
+
+```ruby
+# config/initializers/sidekiq_queue_manager.rb
+SidekiqQueueManager.configure do |config|
+  # Basic auth required for security
+  config.basic_auth_password = ENV['SIDEKIQ_ADMIN_PASSWORD']
+  config.critical_queues = %w[mailers]
+end
+```
+
+## Advanced Configuration
+
+For complete configuration options, see `examples/advanced_configuration.rb`.
+
+## What You DON'T Need to Configure
+
+The gem handles these automatically:
+
+- ✅ Asset compilation and loading (CSS, JavaScript, modals)
+- ✅ Redis connection (uses Sidekiq's connection)
+- ✅ Cache TTL and Redis key prefixes
+- ✅ UI refresh rates and timeouts
+- ✅ Default queue priorities
+
+## Troubleshooting
+
+### Configuration Error: Password Required
+
+```bash
+basic_auth_password must be set when basic_auth_enabled is true
+```
+
+**Solution**: Set a password in your configuration:
+
+```ruby
+config.basic_auth_password = ENV['SIDEKIQ_ADMIN_PASSWORD']
+```
+
+### Runtime Error: Authentication Not Configured
+
+If you see "Sidekiq Queue Manager: Authentication Not Configured" when accessing the interface:
+
+**Cause**: You have `basic_auth_enabled = true` (default) but haven't set a password.
+
+**Solution**: Add password to your `config/initializers/sidekiq_queue_manager.rb`:
+
+```ruby
+SidekiqQueueManager.configure do |config|
+  config.basic_auth_password = 'your-secure-password'
+end
+```
+
+### Missing Sidekiq Dependencies
+
+If you see warnings about `sidekiq-limit_fetch`:
+
+```bash
+sidekiq-limit_fetch not available
+```
+
+**Solution**: This is normal and safe. The gem works without it but some advanced features may be limited.
+
+### Compatibility
+
+- ✅ Rails 7.0+
+- ✅ Sidekiq 7.0+  
+- ✅ Ruby 3.0+
+- ✅ API-only Rails apps
+- ✅ Standard Rails apps with asset pipeline

data/README.md

@@ -0,0 +1,376 @@
+# 📊 Sidekiq Queue Manager
+
+[![Gem Version](https://badge.fury.io/rb/sidekiq_queue_manager.svg)](https://badge.fury.io/rb/sidekiq_queue_manager)
+[![Rails](https://img.shields.io/badge/Rails-7.0%2B-red.svg)](https://rubyonrails.org)
+[![Ruby](https://img.shields.io/badge/Ruby-3.0%2B-red.svg)](https://ruby-lang.org)
+[![Sidekiq](https://img.shields.io/badge/Sidekiq-7.0%2B-orange.svg)](https://sidekiq.org)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Professional Sidekiq queue monitoring and management interface for Rails applications.**
+
+A modern, real-time web interface for monitoring and managing Sidekiq queues with zero configuration required. Perfect for production environments requiring professional queue monitoring capabilities.
+
+---
+
+## ✨ Features
+
+### 🚀 **Real-Time Queue Management**
+
+- **Live Statistics** - Real-time queue metrics with 5-second auto-refresh
+- **Universal Queue Discovery** - Automatically detects ALL Sidekiq queues
+- **Pause/Resume Operations** - Individual and bulk queue control
+- **Advanced Queue Controls** - Set limits, block queues, manage process limits
+- **Job Management** - View, delete, and paginate through individual jobs
+
+### 🎨 **Professional Interface**
+
+- **Modern UI/UX** - Dark-mode optimized responsive design
+- **Live Pull Toggle** - Enable/disable real-time updates
+- **Custom Modal System** - Professional confirmations and prompts
+- **Mobile Responsive** - Optimized for all device sizes
+- **Accessibility Ready** - ARIA labels, keyboard navigation, screen reader support
+
+### 🔒 **Enterprise Features**
+
+- **Authentication Integration** - Configurable authentication methods
+- **Critical Queue Protection** - Prevents accidental modification of important queues
+- **Security Headers** - Built-in CSP and security middleware
+- **Comprehensive Logging** - Configurable request and operation logging
+- **Error Recovery** - Automatic retry logic and graceful error handling
+
+### ⚡ **Advanced Operations**
+
+- **Queue Limits** - Set maximum job limits per queue
+- **Process Limits** - Control how many processes can work on a queue
+- **Queue Blocking** - Temporarily block queues from accepting new jobs
+- **Bulk Operations** - Pause/resume multiple queues simultaneously
+- **Job Inspection** - View job arguments, creation time, and metadata
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'sidekiq_queue_manager'
+```
+
+```bash
+bundle install
+```
+
+### Setup
+
+Mount the engine in your routes:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount SidekiqQueueManager::Engine, at: '/admin/queues'
+  # or mount at root level
+  # mount SidekiqQueueManager::Engine, at: '/queues'
+end
+```
+
+**That's it!** 🎉 Visit `/admin/queues` to access your professional queue management interface.
+
+---
+
+## ⚙️ Configuration
+
+### Basic Configuration
+
+```ruby
+# config/initializers/sidekiq_queue_manager.rb
+SidekiqQueueManager.configure do |config|
+  # Protect critical queues from bulk operations (recommended)
+  config.critical_queues = ['mailer', 'billing', 'notifications']
+  
+  # Add authentication (recommended for production)
+  config.authentication_method = :authenticate_admin!
+  
+  # Customize refresh interval (milliseconds)
+  config.refresh_interval = 5000
+  
+  # Set theme preference
+  config.theme = 'auto' # 'auto', 'dark', 'light'
+end
+```
+
+### Advanced Configuration
+
+```ruby
+SidekiqQueueManager.configure do |config|
+  # Security & Performance
+  config.enable_csp = true
+  config.enable_caching = true
+  config.cache_ttl = 300
+  
+  # Logging
+  config.enable_logging = true
+  config.log_level = :info
+  
+  # Redis Configuration
+  config.redis_timeout = 5
+  config.redis_key_prefix = 'sqm'
+  
+  # Default Queue Priorities
+  config.default_queue_priorities = {
+    'critical' => 10,
+    'high' => 7,
+    'default' => 5,
+    'low' => 1
+  }
+end
+```
+
+### Authentication Integration
+
+```ruby
+# config/initializers/sidekiq_queue_manager.rb
+SidekiqQueueManager.configure do |config|
+  config.authentication_method = :authenticate_admin!
+end
+
+# In your ApplicationController
+def authenticate_admin!
+  redirect_to login_path unless current_user&.admin?
+end
+```
+
+---
+
+## 📖 Usage Guide
+
+### Dashboard Overview
+
+The main dashboard provides:
+
+- **Global Statistics** - Processed, failed, busy, and enqueued job counts
+- **Queue Summary** - Total queues, paused queues, and total jobs
+- **Live Controls** - Toggle real-time updates and manual refresh
+- **Queue Table** - Detailed view of all queues with actions
+
+### Queue Operations
+
+#### Individual Queue Actions
+
+- **Pause/Resume** - Stop or start job processing for specific queues
+- **View Jobs** - Browse jobs with pagination and search
+- **Delete Jobs** - Remove specific jobs from queues
+- **Set Limits** - Configure maximum jobs and process limits
+- **Block/Unblock** - Prevent new jobs from being enqueued
+
+#### Bulk Operations
+
+- **Pause All** - Pause all non-critical queues simultaneously
+- **Resume All** - Resume all paused queues
+- **Critical Queue Protection** - Automatically protects specified critical queues
+
+### Advanced Features
+
+#### Queue Limits
+
+```ruby
+# Set maximum jobs in queue
+# Via UI: Queue Actions → Set Queue Limit
+# Prevents queue from growing beyond specified size
+```
+
+#### Process Limits
+
+```ruby
+# Set maximum Sidekiq processes working on queue
+# Via UI: Queue Actions → Set Process Limit  
+# Controls parallel processing capacity
+```
+
+#### Job Management
+
+- **Pagination** - Navigate through large job lists
+- **Job Details** - View arguments, creation time, retry count
+- **Individual Deletion** - Remove problematic jobs
+- **Bulk Clearing** - Clear entire queues (with confirmation)
+
+---
+
+## 🔌 API Reference
+
+The gem provides a comprehensive REST API for programmatic access:
+
+### Global Endpoints
+
+```http
+GET  /metrics              # Real-time queue statistics
+GET  /queues/summary       # Queue summary statistics
+POST /queues/pause_all     # Pause all non-critical queues
+POST /queues/resume_all    # Resume all paused queues
+```
+
+### Queue-Specific Endpoints
+
+```http
+GET    /queues/:name/status          # Get queue status
+POST   /queues/:name/pause           # Pause specific queue
+POST   /queues/:name/resume          # Resume specific queue
+GET    /queues/:name/jobs            # List jobs (paginated)
+DELETE /queues/:name/delete_job      # Delete specific job
+POST   /queues/:name/clear           # Clear all jobs in queue
+
+# Advanced Operations
+POST   /queues/:name/set_limit       # Set queue limit
+DELETE /queues/:name/remove_limit    # Remove queue limit
+POST   /queues/:name/set_process_limit    # Set process limit
+DELETE /queues/:name/remove_process_limit # Remove process limit
+POST   /queues/:name/block           # Block queue
+POST   /queues/:name/unblock         # Unblock queue
+```
+
+### Real-Time Updates
+
+```http
+GET /live    # Server-Sent Events stream for real-time updates
+```
+
+---
+
+## 🛡️ Security
+
+### Production Recommendations
+
+1. **Authentication Required**
+
+   ```ruby
+   config.authentication_method = :authenticate_admin!
+   ```
+
+2. **Network Security**
+
+   ```ruby
+   # Mount behind authentication
+   authenticated :admin do
+     mount SidekiqQueueManager::Engine, at: '/admin/queues'
+   end
+   ```
+
+3. **Critical Queue Protection**
+
+   ```ruby
+   config.critical_queues = ['billing', 'payments', 'notifications']
+   ```
+
+### Security Features
+
+- **CSRF Protection** - Built-in Rails CSRF protection
+- **Content Security Policy** - Configurable CSP headers
+- **Request Logging** - Comprehensive request and action logging
+- **Input Validation** - All parameters validated and sanitized
+
+---
+
+## 🚀 Deployment
+
+### Production Setup
+
+After setting limits or process limits, restart your Sidekiq processes:
+
+```bash
+# Systemd
+sudo systemctl restart sidekiq
+
+# Docker
+docker-compose restart sidekiq
+
+# Manual
+kill -USR1 $(pgrep -f sidekiq)
+```
+
+### Docker Integration
+
+```dockerfile
+# Dockerfile
+FROM ruby:3.1
+# ... your existing setup
+
+# The gem works seamlessly in containerized environments
+RUN bundle install
+```
+
+### Heroku Deployment
+
+The gem works out-of-the-box on Heroku with no additional configuration needed.
+
+---
+
+## 📋 Requirements
+
+- **Ruby** 3.0 or higher
+- **Rails** 7.0 or higher  
+- **Sidekiq** 7.0 or higher
+- **Redis** (required by Sidekiq)
+
+### Compatibility
+
+- ✅ **Sidekiq Pro/Enterprise** - Full compatibility
+- ✅ **Multi-process Sidekiq** - Advanced process management
+- ✅ **Existing Sidekiq setups** - Zero breaking changes
+- ✅ **All queue types** - Works with any Sidekiq job
+- ✅ **Docker/Kubernetes** - Container-ready
+- ✅ **Heroku/Cloud platforms** - Platform-agnostic
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+git clone https://github.com/jamalawd/sidekiq_queue_manager.git
+cd sidekiq_queue_manager
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Start development server
+cd spec/dummy
+rails server
+```
+
+### Reporting Bugs
+
+Please use our [Issue Tracker](https://github.com/jamalawd/sidekiq_queue_manager/issues) to report bugs or request features.
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- Built with ❤️ for the Ruby and Rails community by [Jamal Awad](https://github.com/jamalawd)  
+- Powered by [Sidekiq](https://sidekiq.org) - Simple, efficient background processing
+- Designed for production environments requiring professional queue management
+
+---
+
+## 📞 Support
+
+- **Documentation**: [GitHub Wiki](https://github.com/jamalawd/sidekiq_queue_manager/wiki)
+- **Issues**: [GitHub Issues](https://github.com/jamalawd/sidekiq_queue_manager/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/jamalawd/sidekiq_queue_manager/discussions)
+
+---
+
+**Created and maintained by [Jamal Awad](https://github.com/jamalawd)**  
+*Ruby enthusiast, tech lead, & architect passionate about open-source development*
+
+*Transform your Sidekiq monitoring experience with professional-grade queue management.*