periodic_job_mongoid 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c5b281d510336a50b949ceb174dbb388041a15c6467f7abe1cb9c8e32efb200
+  data.tar.gz: fd32ff0b4c6c05c8645fbc018800cdb59779359dd75b7636a9f300903fc1d773
+SHA512:
+  metadata.gz: f7c58cce1f73add0b97b2ab0fe982010014bc92bd7172e4e41f64b9f0bbaa36db0e911e39dfef15985aa2731df49f6395309177c51aa3ddab6aebc16e2d82220
+  data.tar.gz: 696704a8f8f45d11c3042c901c590ad1d4085c1a627196e3a6e1166f61f168ab124aac0796efbc0e0161df1bc7ef8b3c9565ff132112ccac3a03070280f8f461

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+3.1.2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## Releases
+
+## [0.1.0] - 2022-12-01
+
+- Initial release

data/Gemfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in periodic_job_mongoid.gemspec
+gemspec
+
+# Rake is a Make-like program implemented in Ruby. Tasks and dependencies are specified in standard Ruby syntax. Rake has the following features: * Rakefiles (rake's version of Makefiles) are completely defined in standard Ruby syntax. No XML files to edit. No quirky Makefile syntax to worry about (is that a tab or a space?) * Users can specify tasks with prerequisites. * Rake supports rule patterns to synthesize implicit tasks. * Flexible FileLists that act like arrays but know about manipulating file names and paths. * Supports parallel execution of tasks.
+gem "rake", "~> 13.0"
+
+# BDD for Ruby
+gem "rspec", "~> 3.12"
+
+# A gem providing "time travel" and "time freezing" capabilities, making it dead simple to test time-dependent code. It provides a unified method to mock Time.now, Date.today, and DateTime.now in a single call.
+gem 'timecop', "~> 0.9"
+
+# The mongoid-rspec library provides a collection of RSpec-compatible matchers that help to test Mongoid documents.
+gem 'mongoid-rspec', "~> 4.1.0"
+

data/Gemfile.lock

@@ -0,0 +1,70 @@
+PATH
+  remote: .
+  specs:
+    periodic_job_mongoid (0.1.1)
+      mongoid (~> 7.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (7.0.4)
+      activesupport (= 7.0.4)
+    activesupport (7.0.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    bson (4.15.0)
+    concurrent-ruby (1.1.10)
+    diff-lcs (1.5.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    minitest (5.16.3)
+    mongo (2.18.1)
+      bson (>= 4.14.1, < 5.0.0)
+    mongoid (7.5.2)
+      activemodel (>= 5.1, < 7.1, != 7.0.0)
+      mongo (>= 2.10.5, < 3.0.0)
+      ruby2_keywords (~> 0.0.5)
+    mongoid-compatibility (0.6.0)
+      activesupport
+      mongoid (>= 2.0)
+    mongoid-rspec (4.1.0)
+      activesupport (>= 3.0.0)
+      mongoid (>= 3.1)
+      mongoid-compatibility (>= 0.5.1)
+      rspec-core (~> 3.3)
+      rspec-expectations (~> 3.3)
+      rspec-mocks (~> 3.3)
+    rake (13.0.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.0)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    ruby2_keywords (0.0.5)
+    timecop (0.9.6)
+    tzinfo (2.0.5)
+      concurrent-ruby (~> 1.0)
+
+PLATFORMS
+  x86_64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  mongoid-rspec (~> 4.1.0)
+  periodic_job_mongoid!
+  rake (~> 13.0)
+  rspec (~> 3.12)
+  timecop (~> 0.9)
+
+BUNDLED WITH
+   2.3.26

data/LICENSE.md

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2022 Yurie Nagorny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,272 @@
+# Periodic Job for Mongoid
+
+Periodic Job executes jobs with a specified interval between runs. If you have several application servers, they will coordinate their work so that only one of the servers will run a job when the time comes to run the job. The coordination is done with help of the collection **periodic_job_checkpoints** in MongoDB database.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add periodic_job_mongoid
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install periodic_job_mongoid
+
+## Usage
+
+### Basic Usage
+
+Create an instance of **PeriodicJob::Scheduler**, define jobs, and then run scheduler's **#tick** method periodically:
+
+```ruby
+require 'periodic_job_mongoid'
+
+scheduler = PeriodicJob::Scheduler.new
+
+scheduler.every 30.seconds, :foo do
+  Foo.work
+end
+
+scheduler.every 1.minute, :bar do
+  Bar.work
+end
+
+loop do
+  sleep 1.second
+  scheduler.tick 
+end
+```
+
+In the above example when **scheduler#tick** is called, **Foo#work** will be executed after the initial 30 seconds pass, and then it will be called again 30 seconds **_after_** the point in time when **Foo#work** completes. **Bar#work** will be executed similarly, but with 1 minute gaps.
+
+The first argument to **#every** is how much time should pass between block executions. So if **Foo#work** takes 10 seconds to complete, effectively it will be called every 40 seconds.
+
+The second argument to **#every** (**:foo** and **:bar** above) are job IDs. If you have several instances of Periodic Job schedulers running, only one block passed to **#every** will be executed for a given job ID when the time comes for the job to run. This will be true regardless of whether the Priodic Job schedulers run in the same or different processes, and on the same or different machines as long as they share the same MongoDB database.  
+
+Only one job will be executed at a time per process regardless of job ID. If a job is due to run but another one is running, it will be delayed until the previous job completes. Having multiple processes with Periodic Job (for example if you have several application servers) will allow running jobs with differed IDs in parallel, but still only one per process.
+
+Obviously the above example is not production ready (who wants infinite loops in their code). Later on you will find a more realistic example.
+
+### Before and After hooks
+
+You may define hooks that are executed before or after each job run:
+
+```ruby
+scheduler.before do |job_id|
+  puts "Before #{job_id}"
+end
+
+scheduler.before do |job_id|
+  puts "After #{job_id}"
+end
+```
+
+Before and after hooks should be defined before you make calls to **#every**.
+
+You can have only one before and one after hook per scheduler.
+
+### Common error handler
+
+If a job raises an exception, you may intercept it in a shared error handler:
+
+```ruby
+scheduler.error_handler do |e, job_id|
+  Rails.logger.error "Error in job #{job_id}: #{e.message}"
+end
+```
+
+Error handler hooks should be defined before you make calls to **#every**.
+
+You can have only one error handler per scheduler.
+
+### All together now
+
+Here's an example using all mentioned above:
+
+```ruby
+require 'periodic_job_mongoid'
+
+@start = Time.now
+
+def timestamp(string)
+  printf "%.3f: %s\n", Time.now - @start, string
+end
+
+scheduler = PeriodicJob::Scheduler.new
+
+scheduler.before do |job_id|
+  timestamp "Before #{job_id}"
+end
+
+scheduler.after do |job_id|
+  timestamp "After #{job_id}"
+end
+
+scheduler.error_handler do |e, job_id|
+  timestamp "Error in #{job_id}: #{e.message}"
+end
+
+counter = Hash.new 0
+
+scheduler.every 10.seconds, :foo do
+  counter[:foo] += 1
+  timestamp "Start foo, run #: #{counter[:foo]}"
+  raise "Foo failed" if counter[:foo] % 5 == 0
+  sleep 2
+  timestamp "End foo, run #: #{counter[:foo]}"
+end
+
+scheduler.every 15.seconds, :bar do
+  counter[:bar] += 1
+  timestamp "Start bar, run #: #{counter[:bar]}"
+  sleep 4
+  timestamp "End bar, run #: #{counter[:bar]}"
+end
+
+timestamp "Start"
+
+loop do
+  sleep 1.second
+  scheduler.tick 
+end
+```
+
+Here's the output produced:
+
+```text
+0.225: Start
+10.603: Before foo
+10.603: Start foo, run #: 1
+12.603: End foo, run #: 1
+12.603: After foo
+16.189: Before bar
+16.189: Start bar, run #: 1
+20.190: End bar, run #: 1
+20.190: After bar
+23.365: Before foo
+23.365: Start foo, run #: 2
+25.365: End foo, run #: 2
+25.365: After foo
+35.810: Before foo
+35.810: Start foo, run #: 3
+37.811: End foo, run #: 3
+37.811: After foo
+37.937: Before bar
+37.937: Start bar, run #: 2
+41.937: End bar, run #: 2
+41.937: After bar
+48.000: Before foo
+48.000: Start foo, run #: 4
+50.001: End foo, run #: 4
+50.001: After foo
+57.088: Before bar
+57.088: Start bar, run #: 3
+61.088: End bar, run #: 3
+61.088: After bar
+62.252: Before foo
+62.252: Start foo, run #: 5
+62.252: Error in foo: Foo failed
+62.252: After foo
+72.433: Before foo
+72.433: Start foo, run #: 6
+74.433: End foo, run #: 6
+74.433: After foo
+76.474: Before bar
+76.474: Start bar, run #: 4
+80.475: End bar, run #: 4
+80.475: After bar
+^C
+```
+
+### A more realistic example
+
+Below is a more realistic example of using PeriodicJob, this time in a background process of a Ruby on Rails application managed by systemd on linux.
+
+```ruby
+#!/usr/bin/env -S rails runner
+
+# it will run until it receives signal TERM
+
+# Customize process title
+Process.setproctitle 'periodic_job'
+
+# make sure STDOUT/ERR are not buffered
+$stdout.sync = true
+$stderr.sync = true
+
+require 'periodic_job_mongoid'
+
+scheduler = PeriodicJob::Scheduler.new
+
+scheduler.error_handler do |e, job_id|
+  Rails.logger.error "Periodic Job #{job_id}: #{e.message}"
+  Rails.logger.error e.backtrace.join "\n"
+end
+
+scheduler.before do |job_id|
+  # run before every job
+end
+
+scheduler.after do |job_id|
+  # run after every job
+end
+
+scheduler.every 30.seconds, :job_a do |job_id|
+  # do work here 
+end
+
+# ...
+
+$running = true
+Signal.trap "TERM" do
+  $running = false
+end
+
+while $running do
+  sleep 1.second
+  scheduler.tick
+end
+```
+
+A systemd unit file that you may use to run the process for a rails application (assuming the above script is in **script/periodic_jobs**)
+
+```
+[Unit]
+Description = Periodic Job process
+After = syslog.target network.target
+
+[Service]
+Type = simple
+User = <user under which your rails app runs>
+WorkingDirectory = <path to your rails app>
+Environment = RAILS_ENV=production
+
+ExecStart = /bin/bash -lc 'bundle exec --keep-file-descriptors rails runner script/periodoc_jobs'
+
+KillSignal = SIGTERM
+
+Restart = always
+RestartSec = 10
+
+StandardOutput = syslog
+StandardError = syslog
+SyslogIdentifier = priodic_job
+SyslogFacility = local7
+
+[Install]
+WantedBy = multi-user.target
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/periodic_job_mongoid.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec]

data/lib/periodic_job_mongoid/checkpoint.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module PeriodicJob
+  class Checkpoint
+    include Mongoid::Document
+    include Mongoid::Timestamps::Short
+
+    # checkpoints reached this far in the future will be considered erroneous and will be treated as unreached
+    FUTURE_CUTOFF_TIME = 10.minutes
+
+    field :name, type: StringifiedSymbol
+      validates_presence_of :name
+
+    field :reached_at, type: Time
+
+    def age
+      Time.now - reached_at if reached_at
+    end
+
+    def advance_if_older_than(max_age)
+      time_now = Time.now.utc
+      result = self.class.where(id: self.id)
+        .and(self.class
+          .or(
+            { reached_at: nil },
+            { :reached_at.lte => time_now - max_age },
+            { :reached_at.gte => time_now + FUTURE_CUTOFF_TIME },
+            ).selector
+        ).find_one_and_update({'$set' => { reached_at: time_now }})
+
+      !result.nil?
+    end
+
+    def self.[](name)
+      return nil if name.to_s.strip.empty?
+      Checkpoint.find_or_create_by name: name
+    end
+  end
+end

data/lib/periodic_job_mongoid/job.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module PeriodicJob
+  class Job
+    attr_reader :interval
+    attr_reader :job_id
+    attr_reader :block
+    attr_reader :run_after
+    attr_reader :error_handler
+    attr_reader :before
+    attr_reader :after
+
+    def initialize(interval, job_id, block, error_handler, before, after)
+      @interval = interval
+      @job_id = job_id
+      @block = block
+      @error_handler = error_handler
+      @before = before
+      @after = after
+      schedule
+    end
+
+    def checkpoint
+      Checkpoint[@job_id]
+    end
+
+    def tick
+      if checkpoint.advance_if_older_than @run_after
+        run
+        schedule
+      end
+    end
+
+    private
+
+    def run
+      protected_before
+      protected_call
+      protected_after
+    end
+
+    def protected_before
+      begin
+        @before&.call @job_id
+      rescue => e
+        error_handler&.call e, @job_id
+      end
+    end
+
+    def protected_call
+      begin
+        @block.call @job_id
+      rescue => e
+        @error_handler&.call e, @job_id
+      end
+    end
+
+    def protected_after
+      begin
+        @after&.call @job_id
+      rescue => e
+        @error_handler&.call e, @job_id
+      end
+    end
+
+    def schedule
+      checkpoint.advance_if_older_than 0 if checkpoint.age.nil?
+      @run_after = checkpoint.age + @interval
+    end
+  end
+end

data/lib/periodic_job_mongoid/scheduler.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PeriodicJob
+  class Scheduler
+
+    def initialize
+      @jobs = []
+    end
+
+    def every(interval, job_id, &block)
+      @jobs << Job.new(interval, job_id, block, @error_handler, @before, @after)
+    end
+
+    def tick
+      @jobs.each &:tick
+    end
+
+    def error_handler(&block)
+      @error_handler = block
+    end
+
+    def before(&block)
+      @before = block
+    end
+    
+    def after(&block)
+      @after = block
+    end
+
+  end
+end

data/lib/periodic_job_mongoid/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PeriodicJob
+  VERSION = "0.1.1"
+end

data/lib/periodic_job_mongoid.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'mongoid'
+
+require_relative "periodic_job_mongoid/version"
+require_relative "periodic_job_mongoid/checkpoint"
+require_relative "periodic_job_mongoid/job"
+require_relative "periodic_job_mongoid/scheduler"

data/mongoid.yml

@@ -0,0 +1,6 @@
+test:
+  clients:
+    default:
+      database: periodic_job_test
+      hosts:
+        - localhost:27017

data/periodic_job_mongoid.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/periodic_job_mongoid/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "periodic_job_mongoid"
+  spec.version = PeriodicJob::VERSION
+  spec.authors = ["Yurie Nagorny"]
+  spec.email = ["ynagorny@bearincorp.com"]
+
+  spec.summary = "Coordinate and run periodic background jobs for a distributed application built using Mongoid ODM for MongoDB."
+  spec.description = <<EOS
+Periodic Job helps you run jobs with a time interval between runs. You may have several copies of your Periodic Job process running (e.g. as part of an application server cluster) and they will coordinate their work with help of a collection stored in a shared MongoDB database to avoid duplicate runs of a job.
+EOS
+  spec.homepage = "https://github.com/ynagorny/periodic_job_mongoid"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.6"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ynagorny/periodic_job_mongoid"
+  spec.metadata["changelog_uri"] = "https://github.com/ynagorny/periodic_job_mongoid/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "mongoid", "~> 7.4"
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: periodic_job_mongoid
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Yurie Nagorny
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.4'
+description: 'Periodic Job helps you run jobs with a time interval between runs. You
+  may have several copies of your Periodic Job process running (e.g. as part of an
+  application server cluster) and they will coordinate their work with help of a collection
+  stored in a shared MongoDB database to avoid duplicate runs of a job.
+
+  '
+email:
+- ynagorny@bearincorp.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".ruby-version"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/periodic_job_mongoid.rb
+- lib/periodic_job_mongoid/checkpoint.rb
+- lib/periodic_job_mongoid/job.rb
+- lib/periodic_job_mongoid/scheduler.rb
+- lib/periodic_job_mongoid/version.rb
+- mongoid.yml
+- periodic_job_mongoid.gemspec
+homepage: https://github.com/ynagorny/periodic_job_mongoid
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ynagorny/periodic_job_mongoid
+  source_code_uri: https://github.com/ynagorny/periodic_job_mongoid
+  changelog_uri: https://github.com/ynagorny/periodic_job_mongoid/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.6
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Coordinate and run periodic background jobs for a distributed application
+  built using Mongoid ODM for MongoDB.
+test_files: []