kick_ahead 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 59e2d5091b3c8f9f670398b61d29f1622316acb8
+  data.tar.gz: c55ea15fbd789c84a2a4e92a01e7619f4359c69c
+SHA512:
+  metadata.gz: 8da428f05bc52542d04eff590ac7189318c3788544945fdcce98cd66c3a45a8425dd2889816eb3b846ec0572c39020a6318c6682eb9debccfbd046e339a237f7
+  data.tar.gz: 4399934d5ea49829ba721e45acbf5be03f023e98ba4929c8b94d54794871f69ad6119d111f8eef306c4b9663b68787b65bd163f74029ffa438eee3c316685dec

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,8 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.1.10
+  - 2.2.8
+  - 2.3.4
+  - 2.4.2
+before_install: gem install bundler -v 1.16.0

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in kick_ahead.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,24 @@
+PATH
+  remote: .
+  specs:
+    kick_ahead (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.10.3)
+    rake (10.5.0)
+    timecop (0.9.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  kick_ahead!
+  minitest (~> 5.0)
+  rake (~> 10.0)
+  timecop
+
+BUNDLED WITH
+   1.16.0

data/README.md

@@ -0,0 +1,257 @@
+# KickAhead
+
+Allows you to push code to be executed in the future. The code is organized in Jobs with the same API
+sidekiq has:
+
+```ruby
+class MyJob < KickAhead::Job
+  def perform(some, args)
+    # Your code
+  end
+end
+```
+
+```ruby
+MyJob.run_in 3600, "some", "args"
+MyJob.run_at Time.now + 2 * 3600, "some", "args"
+```
+
+This library is minimalist and the user must provide a persistent storage system as well as a polling 
+mechanism, that will be used to control the timings.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'kick_ahead'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kick_ahead
+
+## Usage
+
+
+First, you need to provide a polling mechanism that allows you to call `KickAhead.tick` at regular intervals. 
+This interval must be also configured at `KickAhead.tick_interval`. You application can call `tick` more 
+frequently than what you establish here, but never less frequently. If your polling source is not accurate
+but have a predictable behavior / margin of error, configure the `tick_interval` to be your maximum possible 
+frequency even if your real polling source frequency is usually higher.
+
+If you fail to call `tick` frequently enough, you may have dropped jobs (see below).
+
+Also importantly, your call to `tick` must be atomic in your application. Only one `tick` must be in execution
+at any given time. You must use some sort of locking mechanism to ensure this, like ruby's `Mutex#synchronize`
+if you only have one process that may tick in your application, or some other application-wide lock mechanism 
+otherwise (i.e. using redis or postgres advisory locks).
+
+You'll also need to provide a Repository object, to offer a persistent storage (see below in Configuration).
+
+The basic idea is that you write code in Jobs, and then "push" those jobs to be executed at some point in the
+future. Examples:
+
+```ruby
+MyJob.run_in 3600, "some", "args"
+MyJob.run_at Time.now + 2 * 3600, "some_args"
+```
+
+This lib guarantees that your job will be executed between your given time and your given time + your configured
+tick_interval at most. If you want more precision, you'll need to decrease your tick_interval.
+
+If, for some reason, your polling fail and the `tick` method is not called for a long time, any job that
+was configured to run during that time will not run as expected. On the next tick, we'll detect those 
+stale jobs and then the following may occur:
+
+If the job is configured with a `tolerance` value, and we're still inside the tolerance period, the job will 
+still run normally. 
+
+Tolerance can be configured from the job class and can be different per job:
+
+```ruby
+class MyJob < KickAhead::Job
+  self.tolerance = 30.minutes
+  
+  def perform(some, args)
+    # Your code
+  end
+end
+```
+
+Or externally as well:
+
+`MyJob.tolerance = 2.hours`
+
+If tolerance is not satisfied, then the behavior depends on the `out_of_time_strategy` configured. This
+can be configured on a per job basis and by default is "raise_exception". The options are:
+
+- `raise_exception`: An exception will be raised. The job is kept in the repository, waiting for an external
+action to correct the situation (remove the job, change it's schedule time, etc.). The exception gives 
+information about the job class and arguments. No further jobs will be executed until this is corrected.
+
+- `ignore`: The out of time jobs will be simply deleted with no execution.
+
+- `hook`: In this case, the method `out_of_time_hook` will be called on the job instance in the same way
+the `perform` method would, giving you the change to do specific logics. The first argument, however, will be the
+original scheduling time, so you can perform comparisons with this information. 
+
+Configure it with:
+
+```ruby
+class MyJob < KickAhead::Job
+  # self.out_of_time_strategy = :raise_exception
+  # self.out_of_time_strategy = :ignore
+  self.out_of_time_strategy = :hook
+  
+  def perform(some, args)
+    # Your code
+  end
+  
+  def out_of_time_hook(scheduled_at, some, args)
+    # Your code when out of time
+  end
+end
+```
+
+In case an exception occurs inside your Job, nothing extraordinary will happen. Kick Ahead will not capture
+the exception, any other possible jobs will not be processed.
+
+Your jobs are expected to be quick. If a heavy work has to be done, delegate it to the background.
+
+
+## Configuration
+
+### Polling interval
+
+`KickAhead.tick_interval = 3600`
+
+This value must be set to the expected polling interval, in seconds. In the example, the polling frequency
+is 1 hour. Your code is then expected to call:
+
+`KickAhead.tick`
+
+every hour. 
+
+
+### Repository
+
+You're also expected to provide a repository to implement persistence over the data used to store jobs.
+
+A repository is any object that responds to the following methods:
+
+- `create(klass, schedule_at, *args)`: Used to create a new job. `klass` is a string representing the
+ job class, `schedule_at` is a datetime representing the moment in time when this is expected to be executed,
+ and `*args` is an expandable list of arguments (you can use json columns in postgres to store those easily).
+ 
+ This method is expected to return an identifier as a string, whatever you want that to be, so that it can be
+ used in the future to reference this job in the persistent repository.
+ 
+- `each_job_in_the_past`: Returns a collection of job objects (hashes). In no particular order, but always
+jobs that are in the past respect current time. Kick Ahead will then either execute or discard them depending
+on the configurations.
+
+    A job is a hash with the following properties, example:
+    
+    ```ruby
+        {
+          id: "11",
+          job_class: "MyJob",
+          job_args: [1, "foo"],
+          scheduled_at: Time.new(2017, 1, 1, 1, 1, 1)
+        }
+    ``` 
+    
+    - id: The identifier you gave to the job
+    - job_class: same first argument of the `create` call.
+    - job_args: same third argument of the `create` call.
+    - scheduled_at: same second argument of the `create` call.
+
+- `delete(id)`: Used to remove a job from the persistent storage. The given "id" is the identifier of the
+job as returned by the `create` or `each_job_in_the_past` methods.
+
+
+### Current time
+
+Since this library is heavily based on time, it cannot make any assumption about how are you managing
+the time in your application. Ruby's default behavior is to return the system time, but for a distributed
+application that may run in different machines this is usually not desirable, and instead you should instead use
+some other way to get the current time (i.e. rails `Time.current`).
+
+Since this is a choice of the host app, you must also configure how KickAhead should get the current time by
+providing a lambda to return it.
+
+```ruby
+KickAhead.current_time = -> { Time.current }
+```
+
+This way you can control what is considered to be the current time, and then make sure that this value is consistent
+with the `each_job_in_the_past` method in the repository, so time comparisons work as expected.
+
+
+### Repository example with ActiveRecord
+
+```ruby
+# create_table "kick_ahead_jobs", force: :cascade do |t|
+#   t.string "job_class", null: false
+#   t.jsonb "job_args", null: false
+#   t.datetime "scheduled_at", null: false
+#   t.index ["scheduled_at"], name: "index_kick_ahead_jobs_on_scheduled_at"
+# end
+class KickAheadJob < ActiveRecord::Base
+end
+
+module RepositoryExample
+  extend self
+
+  def each_job_in_the_past
+    KickAheadJob.where('scheduled_at <= ?', Time.current).find_each do |job|
+      yield(as_hash(job))
+    end
+  end
+
+  def create(klass, schedule_at, *args)
+    job = KickAheadJob.create! job_class: klass, job_args: args, scheduled_at: schedule_at
+    job.id
+  end
+
+  def delete(id)
+    KickAheadJob.find(id).delete
+  end
+
+  private
+
+  def as_hash(job)
+    {
+      id: job.id,
+      job_class: job.job_class,
+      job_args: job.job_args,
+      scheduled_at: job.scheduled_at
+    }
+  end
+end
+
+```
+
+## FAQS
+
+Q: What If I don't care about jobs executing out of time? I want the job to execute after time X, but after that, I
+don't need to be specific (ej: fail if the time doesn't fit). 
+
+A: You can set the tolerance value to an incredible high value (ie: 300 years).
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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 tags, 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/rogercampos/kick_ahead.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "kick_ahead"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/kick_ahead.gemspec

@@ -0,0 +1,35 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "kick_ahead/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "kick_ahead"
+  spec.version       = KickAhead::VERSION
+  spec.authors       = ["Roger Campos"]
+  spec.email         = ["roger@rogercampos.com"]
+
+  spec.summary       = %q{Push code to execute in the future, without dependencies}
+  spec.description   = %q{Push code to execute in the future, without dependencies}
+  spec.homepage      = "https://github.com/rogercampos/kick_ahead"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "timecop"
+end

data/lib/kick_ahead/job.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module KickAhead
+  class Job
+    # Simplified version extracted from ActiveSupport
+    def self.class_attribute(name)
+      define_singleton_method(name) { nil }
+
+      ivar = "@#{name}"
+
+      define_singleton_method("#{name}=") do |val|
+        singleton_class.class_eval do
+          define_method(name) { val }
+        end
+
+        if singleton_class?
+          class_eval do
+            define_method(name) do
+              if instance_variable_defined? ivar
+                instance_variable_get ivar
+              else
+                singleton_class.send name
+              end
+            end
+          end
+        end
+        val
+      end
+    end
+
+    class_attribute :tolerance
+    class_attribute :out_of_time_strategy
+
+    self.tolerance = 0
+    self.out_of_time_strategy = :raise_exception
+
+    def self.run_in(delta, *args)
+      KickAhead.repository.create(name, KickAhead.current_time.call + delta, *args)
+    end
+
+    def self.run_at(time, *args)
+      KickAhead.repository.create(name, time, *args)
+    end
+
+    def perform(*)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/kick_ahead/version.rb

@@ -0,0 +1,3 @@
+module KickAhead
+  VERSION = "0.1.0"
+end

data/lib/kick_ahead.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "kick_ahead/version"
+require "kick_ahead/job"
+
+module KickAhead
+  OutOfInterval = Class.new(StandardError)
+  NoTickIntervalConfigured = Class.new(RuntimeError)
+
+  RAISE_EXCEPTION_STRATEGY = :raise_exception
+  IGNORE_STRATEGY = :ignore
+  HOOK_STRATEGY = :hook
+
+  ALL_STRATEGIES = [RAISE_EXCEPTION_STRATEGY, IGNORE_STRATEGY, HOOK_STRATEGY].freeze
+
+  class << self
+    attr_accessor :tick_interval
+    attr_accessor :repository
+    attr_accessor :current_time
+
+    def tick
+      if tick_interval.nil?
+        raise NoTickIntervalConfigured, 'No tick_interval configured! Please set `KickAhead.tick_interval`'
+      end
+
+      if current_time.nil?
+        raise 'You must configure a way for me to know the current time!'
+      end
+
+      KickAhead.repository.each_job_in_the_past do |job|
+        if job[:scheduled_at] < KickAhead.current_time.call - tick_interval - constantize(job[:job_class]).tolerance
+          out_of_time_job(job)
+        else
+          run_job(job)
+        end
+      end
+    end
+
+    def run_job(job)
+      constantize(job[:job_class]).new.perform(*job[:job_args])
+      KickAhead.repository.delete(job[:id])
+    end
+
+    def out_of_time_job(job)
+      case constantize(job[:job_class]).out_of_time_strategy.to_sym
+        when RAISE_EXCEPTION_STRATEGY
+          raise OutOfInterval, "The job of class #{job[:job_class]} with args #{job[:job_args].inspect} "\
+                          'was not possible to run because of an out of interval tick '\
+                          "(we didn't receive a tick in time to run it) and it's maximum tolerance "\
+                          'threshold is also overdue.'
+
+        when IGNORE_STRATEGY
+          KickAhead.repository.delete(job[:id])
+
+        when HOOK_STRATEGY
+          constantize(job[:job_class]).new.out_of_time_hook(job[:scheduled_at], *job[:job_args])
+          KickAhead.repository.delete(job[:id])
+
+        else
+          raise 'Invalid strategy'
+      end
+    end
+
+    private
+
+    # Extracted from activesupport/lib/active_support/inflector/methods.rb, line 258
+    def constantize(camel_cased_word)
+      names = camel_cased_word.split("::".freeze)
+
+      # Trigger a built-in NameError exception including the ill-formed constant in the message.
+      Object.const_get(camel_cased_word) if names.empty?
+
+      # Remove the first blank element in case of '::ClassName' notation.
+      names.shift if names.size > 1 && names.first.empty?
+
+      names.inject(Object) do |constant, name|
+        if constant == Object
+          constant.const_get(name)
+        else
+          candidate = constant.const_get(name)
+          next candidate if constant.const_defined?(name, false)
+          next candidate unless Object.const_defined?(name)
+
+          # Go down the ancestors to check if it is owned directly. The check
+          # stops when we reach Object or the end of ancestors tree.
+          constant = constant.ancestors.inject(constant) do |const, ancestor|
+            break const    if ancestor == Object
+            break ancestor if ancestor.const_defined?(name, false)
+            const
+          end
+
+          # owner is in Object, so raise
+          constant.const_get(name, false)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: kick_ahead
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Roger Campos
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-11-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Push code to execute in the future, without dependencies
+email:
+- roger@rogercampos.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- kick_ahead.gemspec
+- lib/kick_ahead.rb
+- lib/kick_ahead/job.rb
+- lib/kick_ahead/version.rb
+homepage: https://github.com/rogercampos/kick_ahead
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Push code to execute in the future, without dependencies
+test_files: []