sidekiq-cron 1.9.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d751ce0280b4d30f1f43a1e0ed973166c2f398d7ac976e6fea267e66e999bb8
-  data.tar.gz: 352b64238d89eb4eedb0e9c046f9d54f6f298c376804de1066cbdad3481c43af
+  metadata.gz: 24a9263df38117d217eaff38d09f5cc69029d2998a3cc07fd5f21878b340305c
+  data.tar.gz: 9cf118cc907fd84abdc0c0123fb23d6745b9fee021557560e35c55f9ff99fd35
 SHA512:
-  metadata.gz: ee7843b8dd62b31954de3db17c4cef76229050d2c4590bde276c77d6ad2c96bbb523620631ad41574d4b976ace4da6425130b1aa5c4a20986c4d42fdcdde1ef4
-  data.tar.gz: 95e74c836bdae7eb10fe1fe540fdc91ecb730c3a73bc1dd7e578d9324cf448e32054e9ad1b487036119076e966b0df1011978aa34b9215a334d996759d4bb684
+  metadata.gz: 238cd9ccbf1f621090eca667e9e1b4c198589897869c7e8d89746886297bac0456dcd0452aa91f0e5e07af5e4e686d93f140089a44cd676cdf1711c45ced4e40
+  data.tar.gz: 404d91026a551fefd3e2a4c37bae8220e522b9a38a377cbbdc2f692331926495835feb2a4decf8dfe4a059e84ff6c45fc99e6c96c0f6156d53130586bf70b1bb

data/CHANGELOG.md

@@ -2,6 +2,101 @@
 
 All notable changes to this project will be documented in this file.
 
+## 2.4.0
+
+- Fix reflected XSS on Sidekiq-UI (https://github.com/sidekiq-cron/sidekiq-cron/pull/568)
+- Add `cron_process_count_override` config option (https://github.com/sidekiq-cron/sidekiq-cron/pull/572)
+- Fix Spanish translation for enabled/disabled states (https://github.com/sidekiq-cron/sidekiq-cron/pull/575)
+- Allow to conditionally disable Sidekiq-Cron (https://github.com/sidekiq-cron/sidekiq-cron/pull/574)
+
+## 2.3.1
+
+- Fix manually launch enqueue job not working from web UI (https://github.com/sidekiq-cron/sidekiq-cron/pull/564)
+
+## 2.3.0
+
+- **WARNING** The default value for `available_namespaces` has changed from `nil` to `[default_namespace]`. Please refer to the [migration guide](https://github.com/sidekiq-cron/sidekiq-cron/blob/master/README.md#migrating-to-23) for further details (https://github.com/sidekiq-cron/sidekiq-cron/pull/552)
+- Fix deprecation warning for using raw params in WEB extension (https://github.com/sidekiq-cron/sidekiq-cron/pull/547)
+- Allow for sidekiq embedded configuration (https://github.com/sidekiq-cron/sidekiq-cron/pull/549)
+- Load schedule file within sidekiq callback (https://github.com/sidekiq-cron/sidekiq-cron/pull/550)
+- Fix missing default namespace if namespaces are explicitly provided (https://github.com/sidekiq-cron/sidekiq-cron/pull/551)
+
+## 2.2.0
+
+- Add support for Sidekiq v8 (https://github.com/sidekiq-cron/sidekiq-cron/pull/531, https://github.com/sidekiq-cron/sidekiq-cron/pull/538)
+- Always show parsed cron expression in web UI (https://github.com/sidekiq-cron/sidekiq-cron/pull/535)
+- Add fallback to .yaml extension (https://github.com/sidekiq-cron/sidekiq-cron/pull/534)
+- Refactor constantize helper to use Object.const_get (https://github.com/sidekiq-cron/sidekiq-cron/pull/541)
+- Allow testing of schedule by library consumers (https://github.com/sidekiq-cron/sidekiq-cron/pull/543)
+
+## 2.1.0
+
+- Add `available_namespaces` configuration option (https://github.com/sidekiq-cron/sidekiq-cron/pull/524)
+- I18n fixes and enhancements (https://github.com/sidekiq-cron/sidekiq-cron/pull/520, https://github.com/sidekiq-cron/sidekiq-cron/pull/522)
+
+## 2.0.1
+
+- Fix usage of ActiveJob::Base.queue_name (https://github.com/sidekiq-cron/sidekiq-cron/pull/517)
+- Fix: Add quotes to Japanese translations containing multi-byte symbols (https://github.com/sidekiq-cron/sidekiq-cron/pull/515)
+
+## 2.0.0
+
+Sidekiq-Cron v2 is here! In this release we refactored some internals, plus:
+
+- Review web UI translations for all available locales (https://github.com/sidekiq-cron/sidekiq-cron/pull/506)
+- Fix detection of ActiveJob in Sidekiq v7.3.3+ (https://github.com/sidekiq-cron/sidekiq-cron/pull/510)
+- Add retry job configuration option to set Sidekiq retry job option (https://github.com/sidekiq-cron/sidekiq-cron/pull/509)
+
+Please take a look to the RC1 and RC2 changes too if you are coming from the v1.X series.
+
+## 2.0.0.rc2
+
+- Remove support for Sidekiq < 6.5 (https://github.com/sidekiq-cron/sidekiq-cron/pull/480)
+- Require at least Fugit >= 1.11.1 (https://github.com/sidekiq-cron/sidekiq-cron/pull/475)
+- Update how Redis values are stored on save (https://github.com/sidekiq-cron/sidekiq-cron/pull/479)
+- Web extension: Add compatibility with Sidekiq 7.3+ and remove inline styles (https://github.com/sidekiq-cron/sidekiq-cron/pull/480)
+- Remove support for old Redis (< 4.2) (https://github.com/sidekiq-cron/sidekiq-cron/pull/490)
+- Ensure date_as_argument option can be set from true to false in Sidekiq Cron jobs (https://github.com/sidekiq-cron/sidekiq-cron/pull/485)
+- Rename `enque!` to `enqueue!` (https://github.com/sidekiq-cron/sidekiq-cron/pull/494)
+- Refactor gem configuration module (https://github.com/sidekiq-cron/sidekiq-cron/pull/495)
+
+## 2.0.0.rc1
+
+- Introduce `Namespacing` (https://github.com/sidekiq-cron/sidekiq-cron/pull/268)
+- Human readable cron format in UI (https://github.com/sidekiq-cron/sidekiq-cron/pull/445)
+- Add Bahasa Indonesia locale (https://github.com/sidekiq-cron/sidekiq-cron/pull/446)
+- Fetch queue name from ActiveJob class (https://github.com/sidekiq-cron/sidekiq-cron/pull/448)
+- Allows symbol keys in `.load_from_array!` (https://github.com/sidekiq-cron/sidekiq-cron/pull/458)
+- Add natural language parsing mode (https://github.com/sidekiq-cron/sidekiq-cron/pull/459)
+- Add ability to configure the past scheduled time threshold (https://github.com/sidekiq-cron/sidekiq-cron/pull/465)
+- Docs: clarify worker vs process terminology (https://github.com/sidekiq-cron/sidekiq-cron/issues/453)
+
+## 1.12.0
+
+- Remove Sidekiq.server? check from schedule loader (https://github.com/sidekiq-cron/sidekiq-cron/pull/436)
+- Parse arguments on `args=` method (https://github.com/sidekiq-cron/sidekiq-cron/pull/442)
+- Only check out a Redis connection if necessary (https://github.com/sidekiq-cron/sidekiq-cron/pull/438)
+
+## 1.11.0
+
+- Differentiates b/w "schedule" vs "dynamic" jobs (https://github.com/sidekiq-cron/sidekiq-cron/pull/431)
+- Clears scheduled jobs upon schedule load (https://github.com/sidekiq-cron/sidekiq-cron/pull/431)
+- Reduce gem size by excluding test files (https://github.com/sidekiq-cron/sidekiq-cron/pull/414)
+
+## 1.10.1
+
+- Use `hset` instead of deprecated `hmset` (https://github.com/sidekiq-cron/sidekiq-cron/pull/410)
+
+## 1.10.0
+
+- Remove EOL Ruby 2.6 support (https://github.com/sidekiq-cron/sidekiq-cron/pull/399)
+- Add a logo for the project! (https://github.com/sidekiq-cron/sidekiq-cron/pull/402)
+- Added support for ActiveRecord serialize/deserialize using GlobalID (https://github.com/sidekiq-cron/sidekiq-cron/pull/395)
+- Allow for keyword args (`embedded: true`) in Poller (https://github.com/sidekiq-cron/sidekiq-cron/pull/398)
+- Make last_enqueue_time be always an instance of Time (https://github.com/sidekiq-cron/sidekiq-cron/pull/354)
+- Fix argument error problem update from 1.6.0 to newer (https://github.com/sidekiq-cron/sidekiq-cron/pull/392)
+- Clear old jobs while loading the jobs from schedule via the schedule loader (https://github.com/sidekiq-cron/sidekiq-cron/pull/405)
+
 ## 1.9.1
 
 - Always enqueue via Active Job interface when defined in cron job config (https://github.com/sidekiq-cron/sidekiq-cron/pull/381)
@@ -35,7 +130,7 @@ All notable changes to this project will be documented in this file.
 
 ## 1.5.1
 
--  Fixes an issue that prevented the gem to work in previous Sidekiq versions (https://github.com/sidekiq-cron/sidekiq-cron/pull/335)
+- Fixes an issue that prevented the gem to work in previous Sidekiq versions (https://github.com/sidekiq-cron/sidekiq-cron/pull/335)
 
 ## 1.5.0
 
@@ -45,7 +140,7 @@ All notable changes to this project will be documented in this file.
 ## 1.4.0
 
 - Fix buttons order in job show view (https://github.com/sidekiq-cron/sidekiq-cron/pull/302)
-- Dark Mode support in UI (https://github.com/sidekiq-cron/sidekiq-cron/pull/317/282)
+- Dark Mode support in UI (https://github.com/sidekiq-cron/sidekiq-cron/pull/282)
 - Remove invocation of deprecated Redis functionality (https://github.com/sidekiq-cron/sidekiq-cron/pull/318)
 - Internal code cleanup (https://github.com/sidekiq-cron/sidekiq-cron/pull/317)
 - Optimize gem size (https://github.com/sidekiq-cron/sidekiq-cron/pull/322)
@@ -130,6 +225,6 @@ All notable changes to this project will be documented in this file.
 
 ## 0.3.0
 
-- Suport for Active Job
+- Support for Active Job
 - Sidekiq cron web ui needs to be loaded by: require 'sidekiq/cron/web'
 - Add load_from_hash! and load_from_array! which cleanup jobs before adding new ones

data/Gemfile

@@ -1,3 +1,9 @@
 source 'https://rubygems.org'
 
 gemspec
+
+# To test different Sidekiq versions
+gem "sidekiq", ENV.fetch("SIDEKIQ_VERSION", ">= 6")
+
+# To test different Rails versions
+gem "rails", ENV.fetch("RAILS_VERSION", "~> 7")

data/README.md

@@ -1,37 +1,27 @@
-# Sidekiq-Cron
+![Sidekiq-Cron](logos/cover.png)
 
 [![Gem Version](https://badge.fury.io/rb/sidekiq-cron.svg)](https://badge.fury.io/rb/sidekiq-cron)
-[![Build Status](https://github.com/sidekiq-cron/sidekiq-cron/workflows/CI/badge.svg?branch=master)](https://github.com/sidekiq-cron/sidekiq-cron/actions)
-[![Coverage Status](https://coveralls.io/repos/github/ondrejbartas/sidekiq-cron/badge.svg?branch=master)](https://coveralls.io/github/ondrejbartas/sidekiq-cron?branch=master)
+[![CI](https://github.com/sidekiq-cron/sidekiq-cron/actions/workflows/ci.yml/badge.svg)](https://github.com/sidekiq-cron/sidekiq-cron/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/sidekiq-cron/sidekiq-cron/branch/master/graph/badge.svg?token=VK9IVLIaY8)](https://codecov.io/gh/sidekiq-cron/sidekiq-cron)
 
 > A scheduling add-on for [Sidekiq](https://sidekiq.org/)
 
 🎬 [Introduction video about Sidekiq-Cron by Drifting Ruby](https://www.driftingruby.com/episodes/periodic-tasks-with-sidekiq-cron)
 
-Sidekiq-Cron runs a thread alongside Sidekiq workers to schedule jobs at specified times (using cron notation `* * * * *` parsed by [Fugit](https://github.com/floraison/fugit)).
+Sidekiq-Cron runs a thread alongside Sidekiq workers to schedule jobs at specified times (using cron notation `* * * * *` or natural language, powered by [Fugit](https://github.com/floraison/fugit)).
 
-Checks for new jobs to schedule every 30 seconds and doesn't schedule the same job multiple times when more than one Sidekiq worker is running.
+Checks for new jobs to schedule every 30 seconds and doesn't schedule the same job multiple times when more than one Sidekiq process is running.
 
 Scheduling jobs are added only when at least one Sidekiq process is running, but it is safe to use Sidekiq-Cron in environments where multiple Sidekiq processes or nodes are running.
 
 If you want to know how scheduling work, check out [under the hood](#under-the-hood).
 
-Works with ActiveJob (Rails 4.2+).
-
-You don't need Sidekiq PRO, you can use this gem with plain Sidekiq.
-
 ## Changelog
 
 Before upgrading to a new version, please read our [Changelog](CHANGELOG.md).
 
 ## Installation
 
-### Requirements
-
-- Redis 2.8 or greater is required (Redis 3.0.3 or greater is recommended for large scale use)
-- Sidekiq 4.2 or greater is required (for Sidekiq < 4 use version sidekiq-cron 0.3.1)
-- Sidekiq 6.5 requires Sidekiq-Cron 1.5+
-
 Install the gem:
 
 ```
@@ -48,7 +38,7 @@ gem "sidekiq-cron"
 
 ## Getting Started
 
- ### Job properties
+### Job properties
 
 ```ruby
 {
@@ -57,17 +47,41 @@ gem "sidekiq-cron"
   'cron' => '1 * * * *',  # execute at 1 minute of every hour, ex: 12:01, 13:01, 14:01, ...
   'class' => 'MyClass',
   # OPTIONAL
+  'namespace' => 'YourNamespace', # groups jobs together in a namespace (Default value is 'default'),
+  'source' => 'dynamic', # source of the job, `schedule`/`dynamic` (default: `dynamic`)
   'queue' => 'name of queue',
+  'retry' => '5', # Sidekiq (not supported by ActiveJob) number of retries, or false to discard on first failure
   'args' => '[Array or Hash] of arguments which will be passed to perform method',
   'date_as_argument' => true, # add the time of execution as last argument of the perform method
-  'active_job' => true,  # enqueue job through Rails 4.2+ Active Job interface
-  'queue_name_prefix' => 'prefix', # Rails 4.2+ Active Job queue with prefix
-  'queue_name_delimiter' => '.', # Rails 4.2+ Active Job queue with custom delimiter
-  'description' => 'A sentence describing what work this job performs'
+  'active_job' => true,  # enqueue job through Active Job interface
+  'queue_name_prefix' => 'prefix', # Active Job queue with prefix
+  'queue_name_delimiter' => '.', # Active Job queue with custom delimiter (default: '_')
+  'description' => 'A sentence describing what work this job performs',
   'status' => 'disabled' # default: enabled
 }
 ```
 
+**NOTE** The `status` of a job does not get changed in Redis when a job gets reloaded unless the `status` property is explicitly set.
+
+### Configuration
+
+All configuration options:
+
+```ruby
+Sidekiq::Cron.configure do |config|
+  config.enabled = false # Default is true
+  config.cron_poll_interval = 10 # Default is 30
+  config.cron_schedule_file = 'config/my_schedule.yml' # Default is 'config/schedule.yml'
+  config.cron_history_size = 20 # Default is 10
+  config.default_namespace = 'statistics' # Default is 'default'
+  config.available_namespaces = %w[statistics maintenance billing] # Default is `[config.default_namespace]`
+  config.natural_cron_parsing_mode = :strict # Default is :single
+  config.reschedule_grace_period = 300 # Default is 60
+end
+```
+
+If you are using Rails, you should add the above block inside an initializer (`config/initializers/sidekiq-cron.rb`).
+
 ### Time, cron and Sidekiq-Cron
 
 For testing your cron notation you can use [crontab.guru](https://crontab.guru).
@@ -81,18 +95,50 @@ like this `'0 22 * * 1-5 America/Chicago'`.
 
 #### Natural-language formats
 
-Since sidekiq-cron `v1.7.0`, you can use the natural-language formats supported by Fugit, such as:
+Since Sidekiq-Cron `v1.7.0`, you can use the natural-language formats supported by Fugit, such as:
 
-```rb
+```ruby
 "every day at five" # => '0 5 * * *'
 "every 3 hours"     # => '0 */3 * * *'
 ```
 
 See [the relevant part of Fugit documentation](https://github.com/floraison/fugit#fugitnat) for details.
 
+There are multiple modes that determine how natural-language cron strings will be parsed.
+
+1. `:single` (default)
+
+```ruby
+Sidekiq::Cron.configure do |config|
+  # Note: This doesn't need to be specified since it's the default.
+  config.natural_cron_parsing_mode = :single
+end
+```
+
+This parses the first possible cron line from the given string and then ignores any additional cron lines.
+
+Ex. `every day at 3:15 and 4:30`
+
+- Equivalent to `15 3 * * *`.
+- `30 4 * * *` gets ignored.
+
+2. `:strict`
+
+```ruby
+Sidekiq::Cron.configure do |config|
+  config.natural_cron_parsing_mode = :strict
+end
+```
+
+This throws an error if the given string would be parsed into multiple cron lines.
+
+Ex. `every day at 3:15 and 4:30`
+
+- Would throw an error and the associated cron job would be invalid
+
 #### Second-precision (sub-minute) cronlines
 
-In addition to the standard 5-parameter cronline format, sidekiq-cron supports scheduling jobs with second-precision using a modified 6-parameter cronline format:
+In addition to the standard 5-parameter cronline format, Sidekiq-Cron supports scheduling jobs with second-precision using a modified 6-parameter cronline format:
 
 `Seconds Minutes Hours Days Months DayOfWeek`
 
@@ -101,11 +147,93 @@ For example: `"*/30 * * * * *"` would schedule a job to run every 30 seconds.
 Note that if you plan to schedule jobs with second precision you may need to override the default schedule poll interval so it is lower than the interval of your jobs:
 
 ```ruby
-Sidekiq::Options[:cron_poll_interval] = 10
+Sidekiq::Cron.configure do |config|
+  config.cron_poll_interval = 10
+end
 ```
 
 The default value at time of writing is 30 seconds. See [under the hood](#under-the-hood) for more details.
 
+### Namespacing
+
+#### Default namespace
+
+When not giving a namespace, the `default` one will be used.
+
+In the case you'd like to change this value, you can change it via the following configuration flag:
+
+```ruby
+Sidekiq::Cron.configure do |config|
+  config.default_namespace = 'statistics'
+end
+```
+
+#### Renaming namespace
+
+If you rename the namespace of a job that is already running, the gem will not automatically delete the cron job associated with the old namespace. This means you could end up with two cron jobs running simultaneously.
+
+To avoid this, it is recommended to delete all existing cron jobs associated with the old namespace before making the change. You can achieve this with the following code:
+
+```ruby
+Sidekiq::Cron::Job.all('YOUR_OLD_NAMESPACE_NAME').each { |job| job.destroy }
+```
+
+#### Available namespaces
+
+By default, Sidekiq Cron uses the available_namespaces configuration option to determine which namespaces your application utilizes. The default namespace (`"default"`, by default) is always included in the list of available namespaces.
+
+If you want Sidekiq Cron to automatically detect existing namespaces from the Redis database, you can set `available_namespaces` to the special option `:auto`.
+
+If available_namespaces is explicitly set and a job is created with an unexpected namespace, a warning will be printed, and the job will be assigned to the default namespace.
+
+#### Migrating to 2.3
+
+As discussed in [this issue](https://github.com/sidekiq-cron/sidekiq-cron/issues/516), the approach introduced in Sidekiq Cron 2.0 for determining available namespaces using the `KEYS` command is not acceptable. Therefore, starting from version 2.3, namespacing has been reworked:
+
+- If you were not using the namespacing feature, no action is required. You can even remove `available_namespaces = %w[default]`, as it is now the default.
+
+- If you were using the namespacing feature and explicitly specified available namespaces as a list, no changes are needed.
+
+- If you were using the namespacing feature and relied on automatic namespace inference, you should either specify all used namespaces explicitly or set `available_namespaces` to `:auto` to maintain automatic detection. However, note that this approach does not scale well (see the referenced issue for details).
+
+#### Usage
+
+When creating a new job, you can optionally give a `namespace` attribute, and then you can pass it too in the `find` or `destroy` methods.
+
+```ruby
+Sidekiq::Cron::Job.create(
+  name: 'Hard worker - every 5min',
+  namespace: 'Foo',
+  cron: '*/5 * * * *',
+  class: 'HardWorker'
+)
+# INFO: Cron Jobs - add job with name Hard worker - every 5min in the namespace Foo
+
+# Without specifying the namespace, Sidekiq::Cron use the `default` one, therefore `count` return 0.
+Sidekiq::Cron::Job.count
+#=> 0
+
+# Searching in the job's namespace returns 1.
+Sidekiq::Cron::Job.count 'Foo'
+#=> 1
+
+# Same applies to `all`. Without a namespace, no jobs found.
+Sidekiq::Cron::Job.all
+
+# But giving the job's namespace returns it.
+Sidekiq::Cron::Job.all 'Foo'
+#=> [#<Sidekiq::Cron::Job:0x00007f7848a326a0 ... @name="Hard worker - every 5min", @namespace="Foo", @cron="*/5 * * * *", @klass="HardWorker", @status="enabled" ... >]
+
+# If you'd like to get all the jobs across all the namespaces then pass an asterisk:
+Sidekiq::Cron::Job.all '*'
+#=> [#<Sidekiq::Cron::Job ...>]
+
+job = Sidekiq::Cron::Job.find('Hard worker - every 5min', 'Foo').first
+job.destroy
+# INFO: Cron Jobs - deleted job with name Hard worker - every 5min from namespace Foo
+#=> true
+```
+
 ### What objects/classes can be scheduled
 
 #### Sidekiq Worker
@@ -122,7 +250,9 @@ class HardWorker
 end
 ```
 
-#### Active Job Worker
+For Sidekiq workers, `symbolize_args: true` in `Sidekiq::Cron::Job.create` or in Hash configuration is gonna be ignored as Sidekiq currently only allows for [simple JSON datatypes](https://github.com/sidekiq/sidekiq/wiki/The-Basics#:~:text=These%20two%20methods,not%20serialize%20properly.).
+
+#### Active Job
 
 You can schedule `ExampleJob` which looks like:
 
@@ -136,10 +266,12 @@ class ExampleJob < ActiveJob::Base
 end
 ```
 
-For Active jobs you can use `symbolize_args: true` in `Sidekiq::Cron::Job.create` or in Hash configuration,
+For Active Job you can use `symbolize_args: true` in `Sidekiq::Cron::Job.create` or in Hash configuration,
 which will ensure that arguments you are passing to it will be symbolized when passed back to `perform` method in worker.
 
-#### Adding Cron job
+### Adding Cron jobs
+
+Refer to [Schedule vs Dynamic jobs](#schedule-vs-dynamic-jobs) to understand the difference.
 
 ```ruby
 class HardWorker
@@ -171,6 +303,25 @@ unless job.save
 end
 ```
 
+Use ActiveRecord models as arguments:
+
+```ruby
+class Person < ApplicationRecord
+end
+
+class HardWorker < ActiveJob::Base
+  queue_as :default
+
+  def perform(person)
+    puts "person: #{person}"
+  end
+end
+
+person = Person.create(id: 1)
+Sidekiq::Cron::Job.create(name: 'Hard worker - every 5min', cron: '*/5 * * * *', class: 'HardWorker', args: person)
+# => true
+```
+
 Load more jobs from hash:
 
 ```ruby
@@ -209,14 +360,16 @@ array = [
 Sidekiq::Cron::Job.load_from_array array
 ```
 
-Bang-suffixed methods will remove jobs that are not present in the given hash/array, update jobs that have the same names, and create new ones when the names are previously unknown.
+Bang-suffixed methods will remove jobs where source is `schedule` and are not present in the given hash/array, update jobs that have the same names, and create new ones when the names are previously unknown.
 
 ```ruby
 Sidekiq::Cron::Job.load_from_hash! hash
 Sidekiq::Cron::Job.load_from_array! array
 ```
 
-Or from YAML (same notation as Resque-scheduler):
+### Loading jobs from schedule file
+
+You can also load multiple jobs from a YAML file:
 
 ```yaml
 # config/schedule.yml
@@ -237,22 +390,31 @@ second_job:
 There are multiple ways to load the jobs from a YAML file
 
 1. The gem will automatically load the jobs mentioned in `config/schedule.yml` file (it supports ERB)
-2. When you want to load jobs from a different filename, mention the filename in sidekiq configuration, i.e. `cron_schedule_file: "config/users_schedule.yml"`
+2. When you want to load jobs from a different filename, mention the filename in Sidekiq configuration as follows:
+
+    ```ruby
+    Sidekiq::Cron.configure do |config|
+      config.cron_schedule_file = "config/users_schedule.yml"
+    end
+    ```
+
 3. Load the file manually as follows:
 
-```ruby
-# config/initializers/sidekiq.rb
+    ```ruby
+    # config/initializers/sidekiq.rb
+
+    Sidekiq.configure_server do |config|
+      config.on(:startup) do
+        schedule_file = "config/users_schedule.yml"
 
-Sidekiq.configure_server do |config|
-  config.on(:startup) do
-    schedule_file = "config/users_schedule.yml"
+        if File.exist?(schedule_file)
+          schedule = YAML.load_file(schedule_file)
 
-    if File.exist?(schedule_file)
-      Sidekiq::Cron::Job.load_from_hash YAML.load_file(schedule_file)
+          Sidekiq::Cron::Job.load_from_hash!(schedule, source: "schedule")
+        end
+      end
     end
-  end
-end
-```
+    ```
 
 ### Finding jobs
 
@@ -298,9 +460,19 @@ job.status
 # => enabled/disabled
 
 # enqueue job right now!
-job.enque!
+job.enqueue!
 ```
 
+### Schedule vs Dynamic jobs
+
+There are two potential job sources: `schedule` and `dynamic`.
+Jobs associated with schedule files are labeled as `schedule` as their source,
+whereas jobs created at runtime without the `source=schedule` argument are classified as `dynamic`.
+
+The key distinction lies in how these jobs are managed.
+When a schedule is loaded, any stale `schedule` jobs are automatically removed to ensure synchronization within the schedule.
+The `dynamic` jobs remain unaffected by this process.
+
 ### How to start scheduling?
 
 Just start Sidekiq workers by running:
@@ -316,7 +488,7 @@ add `require 'sidekiq/cron/web'` after `require 'sidekiq/web'`.
 
 With this, you will get:
 
-![Web UI](examples/web-cron-ui.jpeg)
+![Web UI](docs/images/web-cron-ui.jpeg)
 
 ## Under the hood
 
@@ -327,12 +499,83 @@ Sidekiq-Cron adds itself into this start procedure and starts another thread wit
 Sidekiq-Cron is checking jobs to be enqueued every 30s by default, you can change it by setting:
 
 ```ruby
-Sidekiq::Options[:cron_poll_interval] = 10
+Sidekiq::Cron.configure do |config|
+  config.cron_poll_interval = 10
+end
+```
+
+When Sidekiq (and Sidekiq-Cron) is not used in zero-downtime deployments, after the deployment is done Sidekiq-Cron starts to catch up. It will consider older jobs that missed their schedules during that time. By default, only jobs that should have started less than 1 minute ago are considered. This is problematic for some jobs, e.g., jobs that run once a day. If on average Sidekiq is shut down for 10 minutes during deployments, you can configure Sidekiq-Cron to consider jobs that were about to be scheduled during that time:
+
+```ruby
+Sidekiq::Cron.configure do |config|
+  config.reschedule_grace_period = 600 # 10 minutes in seconds
+end
 ```
 
 Sidekiq-Cron is safe to use with multiple Sidekiq processes or nodes. It uses a Redis sorted set to determine that only the first process who asks can enqueue scheduled jobs into the queue.
 
-When running with many Sidekiq processes, the polling can add significant load to Redis. You can disable polling on some processes by setting `Sidekiq::Options[:cron_poll_interval] = 0` on these processes.
+When running with many Sidekiq processes, the polling can add significant load to Redis. You can disable polling on some processes by setting:
+
+```ruby
+Sidekiq::Cron.configure do |config|
+  config.cron_poll_interval = 0
+end
+```
+
+You can also disable the entire engine by setting `enabled` to `false`. When disabled, Sidekiq-Cron will skip loading the schedule file on startup, which is useful for environments or specific Sidekiq processes where you don't need cron job scheduling at all:
+
+```ruby
+Sidekiq::Cron.configure do |config|
+  config.enabled = false
+end
+```
+
+Sidekiq will internally determine the process count by checking Redis but if polling has been disabled from some Sidekiq processes by setting the cron poll interval to zero, as explained above, that count might be incorrect. In that case, it is possible to override the default process count for Sidekiq Cron. This affects the way the random poll interval is calculated internally.
+
+```ruby
+Sidekiq::Cron.configure do |config|
+  config.cron_poll_process_count = 2
+end
+```
+
+## Testing your configuration
+
+You can test your application's configuration by loading the schedule in your test suite. Below is an example using RSpec in a Rails project:
+
+```ruby
+# spec/cron_schedule_spec.rb
+require "rails_helper"
+
+RSpec.describe "Cron Schedule" do
+  let(:schedule_loader) { Sidekiq::Cron::ScheduleLoader.new }
+  let(:all_jobs) { Sidekiq::Cron::Job.all }
+
+  # Confirms that `config.cron_schedule_file` points to a real file.
+  it "has a schedule file" do
+    expect(schedule_loader).to have_schedule_file
+  end
+
+  # Confirms that no jobs in the schedule have an invalid cron string.
+  it "does not return any errors" do
+    expect(schedule_loader.load_schedule).to be_empty
+  end
+
+  # May be subject to churn, but adds confidence.
+  it "adds the expected number of jobs" do
+    schedule_loader.load_schedule
+    expect(all_jobs.size).to eq 5
+  end
+
+  # Confirms that all job classes exist.
+  it "has a valid class for each added job" do
+    schedule_loader.load_schedule
+    # Shows that all classes exist (as we can constantize the names without raising).
+    job_classes = all_jobs.map { |job| job.klass.constantize }
+    # Naive check that classes are sidekiq jobs (as they all have `.perfrom_async`).
+    expect(job_classes).to all(respond_to(:perform_async))
+  end
+end
+```
 
 ## Contributing
 
@@ -354,6 +597,39 @@ You can execute the test suite by running:
 $ bundle exec rake test
 ```
 
+### Using Docker
+
+This project uses [Docker Compose](https://docs.docker.com/compose/) in order to orchestrate containers and get the test suite running on you local machine, and here you find the commands to run in order to get a complete environment to build and test this gem:
+
+1. Build the Docker image (only the first time):
+```
+docker compose -f docker/docker-compose.yml build
+```
+
+2. Run the test suite:
+```
+docker compose -f docker/docker-compose.yml run --rm tests
+```
+
+_This command will download the first time the project's dependencies (Redis so far), create the containers and run the default command to run the tests._
+
+**Running other commands**
+
+In the case you need to run a command in the gem's container, you would do it like so:
+
+```
+docker compose -f docker/docker-compose.yml run --rm tests <HERE IS YOUR COMMAND>
+```
+_Note that `tests` is the Docker Compose service name defined in the `docker/docker-compose.yml` file._
+
+**Running a single test file**
+
+Given you only want to run the tests from the `test/unit/web_extension_test.rb` file, you need to pass its path with the `TEST` env variable, so here is the command:
+
+```
+docker compose -f docker/docker-compose.yml run --rm --env TEST=test/unit/web_extension_test.rb tests
+```
+
 ## License
 
 Copyright (c) 2013 Ondrej Bartas. See [LICENSE](LICENSE.txt) for further details.