delayable 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c001bbe027f6b3996e3fc497c5b72a7e32a9f53fca0a6a6f4f04c928231289bc
-  data.tar.gz: 9978c0fa7bce102c9105abfb72d54f674e4e8795fc0331a4181d776ef4e92dbd
+  metadata.gz: c17ddd3e91c54be2b587b653633a034aec19f240a0a15439b80aa5ed88a9c11f
+  data.tar.gz: e589da2392206c0f1574199fd1bc3b3c2c59161886a2f11effeb32b79fb5ecfd
 SHA512:
-  metadata.gz: ab775ae0fe6c43a1e9c59547f8837c80240d5c5ddda4cef7e7f404496b3f89dde80c838bce19350837ef7ed23eb6cf11a4f5e0741a6dc568e30a1b5fccea0964
-  data.tar.gz: 30e3510fa4f70edb0400fa469ada55255bf9552d6302d490b36b2878994ad58c3199b5d7ef1af86fe17dd0e3a1e3689edda6f7bd1a814de12fec95c30588474f
+  metadata.gz: 9c22ae61f2b817ac71bd85f96bb9d65f3d0d985a58b5fdf9dd67e10ec7654afc71943c09aa5710ac367a2a1bc9d5579b45eccdf365b486168f9df01ca0af5cbb
+  data.tar.gz: 6c73c6c141da927a236674c774ec8ad3124128b3f0017e6d05ac40ae4a72a04eaf2fb9ac4d22076cd5f241b68b9c9b19cac42e5ab2cbe9bc35c6093b18b333e1

data/README.md

@@ -1,10 +1,18 @@
 # Delayable
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+A Ruby gem that makes it easy to convert any method call into a background job using ActiveJob. Simply include the `Delayable` module and use the `delay` class method to mark methods that should be available for background execution.
+
+## Features
+
+- **Easy Background Jobs**: Convert any instance or class method into a background job with minimal setup
+- **Current Attributes Preservation**: Automatically preserves Rails `Current` attributes across job boundaries
+- **Flexible Configuration**: Configure queue names, delays, and concurrency limits per method
+- **Method Parameter Support**: Full support for regular arguments, keyword arguments, and blocks
+- **Bang Method Handling**: Automatic support for methods ending with `!`
+- **ActiveJob Integration**: Seamlessly integrates with your existing ActiveJob setup
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -13,7 +21,7 @@ gem "delayable"
 
 And then execute:
 ```bash
-$ bundle
+$ bundle install
 ```
 
 Or install it yourself as:
@@ -21,8 +29,422 @@ Or install it yourself as:
 $ gem install delayable
 ```
 
+## Prerequisites
+
+Before using Delayable, ensure you have the following defined in your Rails application:
+
+1. **ApplicationJob**: Your base job class
+2. **Current**: A CurrentAttributes class for maintaining context
+
+```ruby
+# app/jobs/application_job.rb
+class ApplicationJob < ActiveJob::Base
+  # Your job configuration
+end
+
+# app/models/current.rb
+class Current < ActiveSupport::CurrentAttributes
+  attribute :user, :request_id, :user_agent
+  # Add other attributes as needed
+end
+```
+
+## Basic Usage
+
+### Instance Methods
+
+Include `Delayable` in your class and use the `delay` method to mark methods for background execution:
+
+```ruby
+class DataProcessor
+  include Delayable
+
+  def process_csv_import(file_path, user_id)
+    user = User.find(user_id)
+    CSV.foreach(file_path, headers: true) do |row|
+      user.records.create!(row.to_h)
+    end
+  end
+  delay :process_csv_import
+
+  def sync_external_data(api_endpoint, last_sync_time)
+    # Fetch and process data from external API
+    ExternalApiClient.new(api_endpoint).sync_data_since(last_sync_time)
+  end
+  delay :sync_external_data
+end
+
+# Usage
+processor = DataProcessor.new
+processor.process_csv_import_later("/tmp/users.csv", 123)
+processor.sync_external_data_later("https://api.example.com/data", 1.hour.ago)
+```
+
+### Class Methods
+
+You can also delay class methods by setting the `class_method: true` option:
+
+```ruby
+class ReportGenerator
+  include Delayable
+
+  def self.generate_monthly_report(month, year)
+    # Generate report logic
+  end
+  delay :generate_monthly_report, class_method: true
+
+  def self.cleanup_old_reports!
+    # Cleanup logic
+  end
+  delay :cleanup_old_reports!, class_method: true
+end
+
+# Usage
+ReportGenerator.generate_monthly_report_later(12, 2023)
+ReportGenerator.cleanup_old_reports_later!
+```
+
+### Methods with Bang (!)
+
+Delayable automatically handles methods ending with `!`:
+
+```ruby
+class DataProcessor
+  include Delayable
+
+  def process_data!
+    # Processing logic
+  end
+  delay :process_data!
+end
+
+# Usage - note the bang is preserved in the delayed method name
+processor = DataProcessor.new
+processor.process_data_later!  # Creates ProcessDataBangJob
+```
+
+## Advanced Configuration
+
+### Queue Configuration
+
+Specify which queue to use for the background job:
+
+```ruby
+class DataProcessor
+  include Delayable
+
+  def process_csv_import(file_path)
+    # Large CSV processing logic
+  end
+  delay :process_csv_import, queue: :data_processing
+
+  def sync_external_api(endpoint)
+    # API synchronization logic
+  end
+  delay :sync_external_api, queue: :integrations
+end
+```
+
+### Delay Execution
+
+Set a default delay for job execution:
+
+```ruby
+class CacheManager
+  include Delayable
+
+  def warm_cache(cache_key)
+    # Pre-populate cache logic
+  end
+  delay :warm_cache, wait: 5.minutes
+
+  def cleanup_expired_entries
+    # Cache cleanup logic
+  end
+  delay :cleanup_expired_entries, wait: 1.hour
+end
+
+# You can also override the delay at call time
+manager = CacheManager.new
+manager.warm_cache_later("user_stats", wait: 30.seconds)  # Overrides the 5.minutes default
+```
+
+### Concurrency Limits
+
+Limit how many jobs of this type can run concurrently using SolidQueue's concurrency controls:
+
+```ruby
+class ResourceIntensiveTask
+  include Delayable
+
+  def process_large_file(file_path)
+    # Heavy processing that should be limited
+  end
+  delay :process_large_file, limits_concurrency: { to: 2 }
+
+  def generate_report(report_type)
+    # Report generation that should run one at a time per report type
+  end
+  delay :generate_report, limits_concurrency: { 
+    to: 1, 
+    key: ->(run_data, report_type) { "report_#{report_type}" }
+  }
+  
+  def process_batch(batch_id, options = {})
+    # Process a batch with concurrency control per batch
+  end
+  delay :process_batch, limits_concurrency: {
+    to: 3,
+    key: ->(_run_data, batch_id) { "batch_#{batch_id}" }
+  }
+end
+```
+
+**Important:** When using the `key` proc with `limits_concurrency`, the proc receives the delayed job arguments. The first argument is Delayable's internal `run_data` hash (`current_attributes` and `record`), followed by the arguments passed to your delayed method.
+
+**Note:** The `limits_concurrency` feature requires SolidQueue as your ActiveJob backend. Other job backends (Sidekiq, Resque, etc.) do not support this feature and will ignore the setting.
+
+## Current Attributes
+
+Delayable automatically preserves Rails `Current` attributes across job boundaries:
+
+```ruby
+class AuditLogger
+  include Delayable
+
+  def log_action(action, resource_id)
+    AuditLog.create!(
+      action: action,
+      resource_id: resource_id,
+      user: Current.user,      # This will be preserved from the original request
+      request_id: Current.request_id
+    )
+  end
+  delay :log_action
+end
+
+# In a controller
+class PostsController < ApplicationController
+  def create
+    Current.user = current_user
+    Current.request_id = request.id
+    
+    post = Post.create!(post_params)
+    
+    # The job will have access to Current.user and Current.request_id
+    AuditLogger.new.log_action_later("create", post.id)
+  end
+end
+```
+
+## Working with ActiveRecord Models
+
+Delayable works seamlessly with ActiveRecord models:
+
+```ruby
+class User < ApplicationRecord
+  include Delayable
+
+  def update_profile_completeness
+    score = calculate_completeness_score
+    update!(profile_completeness: score)
+  end
+  delay :update_profile_completeness
+
+  def calculate_metrics!
+    update!(
+      total_posts: posts.count,
+      total_comments: comments.count,
+      last_activity: Time.current
+    )
+  end
+  delay :calculate_metrics!
+
+  def archive_old_data!
+    # Archive user's old posts, comments, etc.
+    posts.where('created_at < ?', 1.year.ago).update_all(archived: true)
+    comments.where('created_at < ?', 1.year.ago).delete_all
+  end
+  delay :archive_old_data!
+end
+
+# Usage
+user = User.find(123)
+user.update_profile_completeness_later
+user.calculate_metrics_later!
+user.archive_old_data_later!
+```
+
+## Job Naming Convention
+
+Delayable automatically generates job class names based on your method names to ensure logging and debugging remain clear and meaningful:
+
+| Method Name | Method Type | Generated Job Class |
+|-------------|-------------|-------------------|
+| `process_data` | instance | `YourClass::ProcessDataJob` |
+| `process_data!` | instance | `YourClass::ProcessDataBangJob` |
+| `generate_report` | class | `YourClass::ClassGenerateReportJob` |
+| `cleanup!` | class | `YourClass::ClassCleanupBangJob` |
+
+This naming convention ensures that when you're monitoring job queues, reading logs, or debugging failed jobs, you can immediately understand what method was being executed and in what context. The job name directly corresponds to your original method, making it easy to trace issues back to your application code.
+
+## Error Handling
+
+Since Delayable creates standard ActiveJob jobs, you can use all the standard ActiveJob error handling mechanisms. Put defaults on `ApplicationJob`, or pass a block to `delay` to configure the generated job class:
+
+```ruby
+# In your ApplicationJob
+class ApplicationJob < ActiveJob::Base
+  retry_on StandardError, wait: :exponentially_longer, attempts: 5
+  discard_on ActiveRecord::RecordNotFound
+end
+
+class BookingSync
+  include Delayable
+
+  def sync_channex_bookings
+    # Sync bookings
+  end
+  delay :sync_channex_bookings,
+        limits_concurrency: {
+          to: 1,
+          key: ->(run_data) { "#{run_data[:record].to_global_id}-channex-bookings" }
+        } do
+    retry_on Channex::Api::ConnectionError,
+             wait: :polynomially_longer,
+             attempts: 5
+  end
+end
+```
+
+## Testing
+
+Delayable integrates with ActiveJob's testing helpers:
+
+```ruby
+require 'test_helper'
+
+class DataProcessorTest < ActiveSupport::TestCase
+  include ActiveJob::TestHelper
+
+  test "CSV import is enqueued" do
+    processor = DataProcessor.new
+    
+    assert_enqueued_jobs 1, only: DataProcessor::ProcessCsvImportJob do
+      processor.process_csv_import_later("/tmp/data.csv", 123)
+    end
+  end
+
+  test "CSV data is imported" do
+    processor = DataProcessor.new
+    
+    perform_enqueued_jobs do
+      processor.process_csv_import_later("/tmp/data.csv", 123)
+    end
+    
+    # Assert data was imported
+    user = User.find(123)
+    assert user.records.count > 0
+  end
+
+  test "current attributes are preserved" do
+    Current.user = users(:admin)
+    
+    perform_enqueued_jobs do
+      AuditLogger.new.log_action_later("test", 123)
+    end
+    
+    log = AuditLog.last
+    assert_equal users(:admin), log.user
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep Jobs Idempotent**: Design your delayed methods to be safely retried
+2. **Use Appropriate Queues**: Separate different types of work into different queues
+3. **Handle Failures Gracefully**: Use ActiveJob's retry and error handling features
+4. **Monitor Job Performance**: Use tools like Sidekiq's web UI or similar for your job backend
+5. **Test Background Behavior**: Always test both the enqueuing and execution of your jobs
+
+## Configuration Examples
+
+### Multiple Options Combined
+
+```ruby
+class ComplexProcessor
+  include Delayable
+
+  def process_batch(batch_id, options = {})
+    # Complex processing logic
+  end
+  delay :process_batch, 
+        queue: :batch_processing,
+        wait: 30.seconds,
+        limits_concurrency: { to: 3, key: ->(_run_data, batch_id) { "batch_#{batch_id}" } }
+end
+```
+
+### Dynamic Delays
+
+```ruby
+class NotificationSender
+  include Delayable
+
+  def send_reminder(user_id, urgency = :normal)
+    # Send reminder logic
+  end
+  delay :send_reminder
+
+  def send_reminder_with_delay(user_id, urgency = :normal)
+    delay_time = case urgency
+    when :urgent then 0.seconds
+    when :normal then 1.hour
+    when :low then 1.day
+    end
+    
+    send_reminder_later(user_id, urgency, wait: delay_time)
+  end
+end
+```
+
+## Troubleshooting
+
+### Debugging
+
+To see what jobs are being created, you can inspect the generated job classes:
+
+```ruby
+# In rails console
+DataProcessor::ProcessCsvImportJob.new.class.name
+# => "DataProcessor::ProcessCsvImportJob"
+
+DataProcessor::ProcessCsvImportJob.queue_name
+# => "default"
+```
+
+## Requirements
+
+- Ruby >= 3.4.0
+- Rails >= 7.0.4.3
+- ActiveJob configured with a backend (Sidekiq, Resque, etc.)
+- **SolidQueue** (optional) - Required only if using `limits_concurrency` feature
+
 ## Contributing
-Contribution directions go here.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Add tests for your changes
+4. Make sure all tests pass (`bundle exec rake test`)
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create a new Pull Request
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/trobrock/delayable/CHANGELOG.md) for details about changes in each version.

data/lib/delayable/version.rb

@@ -1,3 +1,3 @@
 module Delayable
-  VERSION = '0.4.1'.freeze
+  VERSION = '0.4.2'.freeze
 end

data/lib/delayable.rb

@@ -12,10 +12,16 @@ module Delayable
   end
 
   class_methods do
-    def delay(method_name, class_method: false, wait: nil, limits_concurrency: nil, queue: :default)
+    def delay(method_name, class_method: false, wait: nil, limits_concurrency: nil, queue: :default, &job_configuration)
       job = const_set(
         delayable_job_name(method_name, class_method:),
-        delayable_job_class(method_name, class_method:, concurrency_limits: limits_concurrency, queue:)
+        delayable_job_class(
+          method_name,
+          class_method:,
+          concurrency_limits: limits_concurrency,
+          queue:,
+          &job_configuration
+        )
       )
 
       defined_wait = wait
@@ -28,12 +34,19 @@ module Delayable
 
     private
 
-    def delayable_job_class(method_name, class_method: false, concurrency_limits: nil, queue: :default)
+    def delayable_job_class(
+      method_name,
+      class_method: false,
+      concurrency_limits: nil,
+      queue: :default,
+      &job_configuration
+    )
       klass = self
       Class.new(ApplicationJob) do
         queue_as queue
 
-        limits_concurrency(**concurrency_limits) if concurrency_limits.is_a?(Hash)
+        limits_concurrency(**concurrency_limits) if concurrency_limits.is_a?(Hash) && respond_to?(:limits_concurrency)
+        class_eval(&job_configuration) if job_configuration
 
         define_method(:perform) do |run_data = {}, *arguments, **kwargs|
           Current.set(run_data[:current_attributes] || {}) do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: delayable
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Trae Robrock
 bindir: exe
 cert_chain: []
-date: 2025-04-25 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails