ru.Bee 2.7.3 → 2.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dae50d53499025c3bb722a77239ffaf3c7ef566dbe58e665986b62148bcbf60
-  data.tar.gz: 012e74d3c4c3cb488462689bcd0ba0b5c56488cf77da19e3c98caf3682847b26
+  metadata.gz: 2661a78ea4d5fe99234d85375b48b2020bee244951103f0514f51ad727804824
+  data.tar.gz: 581395ecfbce635f11b6647ee1c25eadea0a68ae737b9bb1b4f88584af33d66b
 SHA512:
-  metadata.gz: 7d22033e1be9a7583e872582bff2455715964d934905789b99065a702284b8bd8831f6bf4d2fc20c354c8a828e188cfa130b5396d443056bda1179cca9634e92
-  data.tar.gz: f7941cc128ac31cea3c98da487fdff20da3f01acfb14bfe3d1dcba4fa2a0a7fb6ade7404af5d5bca98746689cdb42f53b9ce7fec59540e74a745de35e27d2b7e
+  metadata.gz: 5175ca33f398ea99103fae92e84f83dd23926ce3ab1074b95cd00a98ef1515a1c0c56635f71898a732cfc55cd3bf70630a47150cd915af04a7b31ae174b22d25
+  data.tar.gz: 215401fd826cc1e003a6cfec1619ca8704370d319eae717d874f27a48c13506465aeffb8572b4f3c0ff8decbc1fc19e5b727891ac8b6598d6330ce35714379ba

data/lib/rubee/async/sidekiq_async.rb

@@ -1,15 +1,48 @@
 module Rubee
   class SidekiqAsync
     def perform_async(**args)
-      options = if args[:options].is_a?(Hash)
-        [JSON.generate(args[:options])]
-      elsif args[:options].is_a?(Array)
-        args[:options]
-      else
-        [args[:options]]
+      options = serialize_options(args[:options])
+      args[:_class].perform_async(*options)
+    end
+
+    def perform_at(interval, **args)
+      options = serialize_options(args[:options])
+      args[:_class].perform_at(interval, *options)
+    end
+
+    def perform_in(interval, **args)
+      options = serialize_options(args[:options])
+      args[:_class].perform_in(interval, *options)
+    end
+
+    def perform_later(interval, **args)
+      perform_in(interval, **args)
+    end
+
+    def perform_bulk(jobs_args)
+      jobs_args.map! do |args|
+        options = serialize_options(args[:options])
+        { args: options }
       end
 
-      args[:_class].perform_async(*options)
+      args[:_class].perform_bulk(jobs_args)
+    end
+
+    def set(options, **args)
+      serialized_options = serialize_options(args[:options])
+      args[:_class].set(options).perform_async(*serialized_options)
+    end
+
+    private
+
+    def serialize_options(options)
+      if options.is_a?(Hash)
+        [JSON.generate(options)]
+      elsif options.is_a?(Array)
+        options
+      else
+        [options]
+      end
     end
   end
 end

data/lib/rubee.rb

@@ -20,7 +20,7 @@ module Rubee
     RUBEE_SUPPORT = { "Rubee::Support::Hash" => Hash, "Rubee::Support::String" => String }
   end
 
-  VERSION = '2.7.3'
+  VERSION = '2.7.4'
 
   require_relative 'rubee/router'
   require_relative 'rubee/logger'

data/readme.md

@@ -91,6 +91,8 @@ The comparison is based on generic and subjective information available on the i
 - [Rubee::Support](#rubee-support)
 - [Testing](#testing)
 - [Background jobs](#background-jobs)
+- [Sidekiq engine](#sidekiq-engine)
+- [ThreadAsync engine](#threadasync-engine)
 - [Modular application](#modular-application)
 - [Logger](#logger)
 - [WebSocket](#websocket)
@@ -1240,14 +1242,24 @@ rubee test models/user_model_test.rb --line=12      # run a specific line
 
 ## Background jobs
 
-### Sidekiq engine
+There are currently two ways to integrate background jobs into your application:
 
-1. Add Sidekiq to your Gemfile
-```bash
+- [Sidekiq](#sidekiq-engine)
+- [ThreadAsync](#threadasync-engine)
+
+## Sidekiq Engine
+
+## Installation & Setup
+
+### 1. Add Sidekiq to your Gemfile
+
+```ruby
 gem 'sidekiq'
+gem 'rack-session'  # Required for Sidekiq Web UI
 ```
 
-2. Configure the adapter for the desired environment
+### 2. Configure the adapter for the desired environment
+
 ```ruby
 # config/base_configuration.rb
 Rubee::Configuration.setup(env = :development) do |config|
@@ -1256,20 +1268,32 @@ Rubee::Configuration.setup(env = :development) do |config|
 end
 ```
 
-3. Install dependencies
+### 3. Install dependencies
+
 ```bash
 bundle install
 ```
 
-4. Start Redis
+### 4. Start Redis
+
+Redis must be running before starting Sidekiq.
+
 ```bash
+# Start Redis server
 redis-server
+
+# Or in background (macOS with Homebrew)
+brew services start redis
+
+# Verify Redis is running
+redis-cli ping
+# Should respond: PONG
 ```
 
-5. Add a Sidekiq configuration file
+### 5. Add Sidekiq configuration file
+
 ```yaml
 # config/sidekiq.yml
-
 development:
   redis: redis://localhost:6379/0
   concurrency: 5
@@ -1279,29 +1303,302 @@ development:
     high:
 ```
 
-6. Create a Sidekiq worker
+### 6. Create Sidekiq boot file
+
 ```ruby
-# app/async/test_async_runner.rb
-require_relative 'extensions/asyncable' unless defined? Asyncable
+# inits/sidekiq.rb
 
+# Configure Redis connection
+Sidekiq.configure_server do |config|
+  config.redis = { url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0') }
+end
+
+Sidekiq.configure_client do |config|
+  config.redis = { url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0') }
+end
+
+# Load Rubee application context
+unless Object.const_defined?('Rubee')
+  require 'rubee'
+
+  # Load environment variables from the Ruby file.
+  require_relative 'dev.rb' if File.exist?(File.join(__dir__, 'dev.rb'))
+
+  # Trigger Rubee autoload
+  Rubee::Autoload.call
+end
+```
+
+### 7. Create a Sidekiq worker
+
+```ruby
+# app/workers/test_async_runner.rb
 class TestAsyncRunner
   include Rubee::Asyncable
   include Sidekiq::Worker
 
-  sidekiq_options queue: :default
+  sidekiq_options queue: :default, retry: 3
 
   def perform(options)
-    User.create(email: options['email'], password: options['password'])
+    options = parse_options(options)
+
+    User.create(
+      email: options['email'],
+      password: options['password']
+    )
+  end
+
+  private
+
+  def parse_options(options)
+    return options unless options.is_a?(String)
+
+    begin
+      JSON.parse(options)
+    rescue JSON::ParserError
+      options
+    end
   end
 end
 ```
 
-7. Use it in your codebase
+### 8. Use it in your codebase
+
 ```ruby
-TestAsyncRunner.new.perform_async(options: { "email" => "new@new.com", "password" => "123" })
+
+TestAsyncRunner.new.perform_async(
+  "email" => "new@new.com",
+  "password" => "123"
+)
 ```
 
-### Default engine — ThreadAsync
+---
+
+## Running Sidekiq
+
+### Start Sidekiq (Foreground)
+
+```bash
+bundle exec sidekiq -C config/sidekiq.yml -r ./inits/sidekiq.rb
+```
+
+### Start Sidekiq (Background/Daemon)
+
+```bash
+# Start as daemon
+bundle exec sidekiq -d -C config/sidekiq.yml -r ./inits/sidekiq.rb
+
+# Stop daemon
+kill -TERM $(cat tmp/pids/sidekiq.pid)
+
+# View logs
+tail -f log/sidekiq.log
+```
+
+### Helper Scripts
+
+Create convenient management scripts:
+
+```bash
+# bin/sidekiq_start
+#!/bin/bash
+bundle exec sidekiq -d \
+  -C config/sidekiq.yml \
+  -r ./inits/sidekiq.rb \
+```
+
+```bash
+# bin/sidekiq_stop
+#!/bin/bash
+if [ -f tmp/pids/sidekiq.pid ]; then
+  kill -TERM $(cat tmp/pids/sidekiq.pid)
+  rm tmp/pids/sidekiq.pid
+  echo "✓ Sidekiq stopped"
+else
+  echo "✗ Sidekiq is not running"
+fi
+```
+
+Make them executable:
+```bash
+chmod +x bin/sidekiq_start bin/sidekiq_stop
+```
+
+---
+
+## Enable Sidekiq Web Dashboard
+
+### 1. Create Sidekiq middleware
+
+```ruby
+# inits/middlewares/sidekiq_middleware.rb
+require 'sidekiq/web'
+require 'rack/session'
+
+class SidekiqMiddleware
+  def initialize(app)
+    @app = app
+
+    # Get or generate session secret
+    session_secret = ENV.fetch('SESSION_SECRET') { generate_secret }
+
+    # Build Sidekiq Web app with authentication
+    @sidekiq_app = Rack::Builder.new do
+      # Session support (required for CSRF protection)
+      use Rack::Session::Cookie,
+          secret: session_secret,
+          same_site: true,
+          max_age: 86400
+
+      # Basic authentication
+      use Rack::Auth::Basic, "Sidekiq Dashboard" do |username, password|
+        username == ENV.fetch('SIDEKIQ_USERNAME', 'admin') &&
+        password == ENV.fetch('SIDEKIQ_PASSWORD', 'password')
+      end
+
+      run Sidekiq::Web
+    end
+  end
+
+  def call(env)
+    if env['PATH_INFO'].start_with?('/sidekiq')
+      # Route to Sidekiq Web UI
+      env['SCRIPT_NAME'] = '/sidekiq'
+      env['PATH_INFO'] = env['PATH_INFO'].sub(%r{^/sidekiq}, '') || '/'
+      @sidekiq_app.call(env)
+    else
+      # Pass through to main app
+      @app.call(env)
+    end
+  end
+
+  private
+
+  def generate_secret
+    secret_file = '.session.key'
+
+    if File.exist?(secret_file)
+      File.read(secret_file).strip
+    else
+      require 'securerandom'
+      secret = SecureRandom.hex(64)
+      File.write(secret_file, secret)
+      puts "Generated new session secret in #{secret_file}"
+      secret
+    end
+  end
+end
+```
+
+### 2. Access the dashboard
+
+Start your Rubee application and visit /sidekiq:
+```
+http://localhost:7000/sidekiq
+```
+
+Login with credentials from your `/inits/dev.rb` file for developmet purposes.
+
+---
+
+## Worker Examples
+
+### Worker with Database Records
+
+```ruby
+# app/workers/booking_confirmation_worker.rb
+class BookingConfirmationWorker
+  include Rubee::Asyncable
+  include Sidekiq::Worker
+
+  sidekiq_options queue: :mailers, retry: 3
+
+  def perform(options)
+    options = parse_options(options)
+
+    # Fetch records from database
+    service = Service.find(options['service_id'])
+    time_slot = TimeSlot.find(options['time_slot_id'])
+
+    Mailer.booking_confirmation(
+      to: options['to'],
+      client_name: options['client_name'],
+      service: service,
+      time_slot: time_slot
+    )
+  end
+
+  private
+
+  def parse_options(options)
+    return options unless options.is_a?(String)
+    JSON.parse(options) rescue options
+  end
+end
+
+# Usage
+BookingConfirmationWorker.new.perform_async(options: {
+  "to" => "client@example.com",
+  "client_name" => "John Doe",
+  "service_id" => 15,
+  "time_slot_id" => 91
+})
+```
+
+---
+## Monitoring & Troubleshooting
+
+### Check Sidekiq Status
+
+```bash
+# View running processes
+ps aux | grep sidekiq
+
+# Check Redis connection
+redis-cli ping
+
+# View queue sizes
+redis-cli LLEN queue:default
+```
+
+### Common Issues
+
+**Workers not processing:**
+- Ensure Redis is running: `redis-cli ping`
+- Check Sidekiq is started: `ps aux | grep sidekiq`
+- Verify queue names match in worker and config
+
+**Authentication errors on Web UI:**
+- Ensure `rack-session` gem is installed
+- Check SESSION_SECRET is at least 64 bytes
+- Verify SIDEKIQ_USERNAME and SIDEKIQ_PASSWORD are set
+
+**Jobs failing:**
+- Check `log/sidekiq.log` for errors
+- View failed jobs in Web UI at `/sidekiq/retries`
+- Verify environment variables are loaded in `inits/sidekiq.rb`
+
+---
+
+## Best Practices
+
+1. **Pass IDs, not objects** - Use `booking.id`, not `booking` itself
+2. **Keep jobs small** - One job should do one thing
+3. **Make jobs idempotent** - Safe to run multiple times
+4. **Set appropriate retries** - Critical: more retries, notifications: fewer
+5. **Use different queues** - Separate critical from low-priority jobs
+6. **Handle JSON properly** - Always parse options in `perform` method
+7. **Monitor your queues** - Use Web UI to watch for backlogs
+
+---
+
+## Additional Resources
+
+- [Sidekiq Official Docs](https://github.com/sidekiq/sidekiq/wiki)
+- [Best Practices](https://github.com/sidekiq/sidekiq/wiki/Best-Practices)
+- [Error Handling](https://github.com/sidekiq/sidekiq/wiki/Error-Handling)
+
+### ThreadAsync engine
 
 The default adapter is `ThreadAsync`. It is not yet recommended for production — use with caution.
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ru.Bee
 version: !ruby/object:Gem::Version
-  version: 2.7.3
+  version: 2.7.4
 platform: ruby
 authors:
 - Oleg Saltykov