kick_ahead 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 59e2d5091b3c8f9f670398b61d29f1622316acb8
-  data.tar.gz: c55ea15fbd789c84a2a4e92a01e7619f4359c69c
+SHA256:
+  metadata.gz: 4f3d6ee75adfef16b3bf5c823251802bae3a24ca120e7cce5d14b116ba2307de
+  data.tar.gz: 1aa641fb0dc11ba8306c22eaf6026d5ba0fb48eae9ea02ef6fd3d00408cc9e9d
 SHA512:
-  metadata.gz: 8da428f05bc52542d04eff590ac7189318c3788544945fdcce98cd66c3a45a8425dd2889816eb3b846ec0572c39020a6318c6682eb9debccfbd046e339a237f7
-  data.tar.gz: 4399934d5ea49829ba721e45acbf5be03f023e98ba4929c8b94d54794871f69ad6119d111f8eef306c4b9663b68787b65bd163f74029ffa438eee3c316685dec
+  metadata.gz: b21b43e59454a76721d0151ba1944ecae8d92dc12b7ebeb5ec6c0c804ab937727de98184ce29b064a349f89d13954137b889cae3c0a12d0eb8420b3d5a4f980c
+  data.tar.gz: a34683eed64f9879f1c17c651c4d7ba76c24850a078f4f2136f3d3142bbcaf41b7097637c9aae4560c48e75dbec9f84a2129d435c380cb2ccdafd5e80b943245

data/.travis.yml

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

data/README.md

@@ -1,7 +1,6 @@
-# KickAhead
+# Kick Ahead
 
-Allows you to push code to be executed in the future. The code is organized in Jobs with the same API
-sidekiq has:
+Kick Ahead allows you to push code to be executed in the future. The code is organized in Jobs with a simple API:
 
 ```ruby
 class MyJob < KickAhead::Job
@@ -9,65 +8,130 @@ class MyJob < KickAhead::Job
     # Your code
   end
 end
-```
 
-```ruby
-MyJob.run_in 3600, "some", "args"
-MyJob.run_at Time.now + 2 * 3600, "some", "args"
+MyJob.run_in 1.hour, "some", "args"
+MyJob.run_at 2.hours.from_now, "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.
+This library is minimalist and has no gem dependencies. However, in order to accomplish its task it requires
+the host app to provide certain features which this lib depends upon. By expressing dependencies in this
+way instead of by "hardcoded" gem dependencies, the user is free to reuse their existing solutions to common
+problems.   
+
+
+## Satisfying requirements
+
+We'll see first what requirements must be satisfied by the app. 
+
+
+### A Regular clock
 
+The most important thing is to have a regular clock available, which allows you to call code at regular intervals.
 
-## Installation
+Possible solutions to this problem are "plugins" for background systems (like sidekiq-cron for sidekiq),
+the traditional cron system in a server, or maybe having an independent process control times with a loop manually
+or with rufus-scheduler.
 
-Add this line to your application's Gemfile:
+Once you have a regular clock, you must use it to call `KickAhead.tick`. Also, the interval between your clock ticks 
+must be specified in `KickAhead.tick_interval` in seconds, for example:
+
+`KickAhead.tick_interval = 3600 # every hour`
+
+Additionally, you must make sure that no two `KickAhead.tick` can be running at the same time across you entire
+app (maybe across different servers). 
+
+### A Persistence repository
+
+Next you'll have to provide a persistence layer to store jobs, as a Repository object. A repository is any 
+object that responds to the following methods and signatures:
+
+- `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 the list of arguments.
+ 
+ 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 persistence repository.
+ 
+- `each_job_in_the_past`: Returns a collection of job objects. In no particular order, but always
+jobs that are in the past respect current time. 
+
+A job object is a hash with the following properties, example:
 
 ```ruby
-gem 'kick_ahead'
-```
+    {
+      id: "11",
+      job_class: "MyJob",
+      scheduled_at: Time.new(2017, 1, 1, 1, 1, 1),
+      job_args: [1, "foo"]
+    }
+``` 
 
-And then execute:
+   * id: The identifier you gave to the job
+   * job_class: same first argument of the `create` call.
+   * scheduled_at: same second argument of the `create` call.
+   * job_args: same third argument of the `create` call.
 
-    $ bundle
+- `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.
 
-Or install it yourself as:
+If you want to use an Active Record model for persistence, you can get an already made repository with this:
 
-    $ gem install kick_ahead
+```ruby
+repository = KickAhead.create_active_record_repository_for(KickAheadJob)
+``` 
 
-## Usage
+The table structure must be as follows, taken from a rails schema (note you can name the table and the
+model whatever you like):
 
+      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
 
-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).
+### Current time
+
+Finally, since this library is heavily based on time, it cannot make any assumption about how are you managing
+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 might use
+some other way to get the current time (like rails `Time.current`).
 
-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).
+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.
 
-You'll also need to provide a Repository object, to offer a persistent storage (see below in Configuration).
+```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.
+
+
+
+## Usage
 
 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"
+class MyJob < KickAhead::Job
+  def perform(some, args)
+    # Your code
+  end
+end
+
+MyJob.run_in 1.hour, "some", "args"
+MyJob.run_at 2.hours.from_now, "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.
+tick_interval at most. If you want more precision, you'll need to reduce your tick_interval.
 
-If, for some reason, your polling fail and the `tick` method is not called for a long time, any job that
+If, for some reason, your clock fails 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:
+stale jobs and then the following logic will apply:
 
 If the job is configured with a `tolerance` value, and we're still inside the tolerance period, the job will 
 still run normally. 
@@ -89,161 +153,46 @@ 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:
+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 
+action to correct the situation (remove the job, run it, or fix the situation in some other way). 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
+the `perform` method would, giving you the chance 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 = :raise_exception
   # self.out_of_time_strategy = :ignore
-  self.out_of_time_strategy = :hook
+  # 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
+    # Your code
   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
+the exception, any other possible job will not be executed.
 
-`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). 
+- 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.
 
-A: You can set the tolerance value to an incredible high value (ie: 300 years).
+A: You can set the tolerance value to an very high value (ie: 300 years).
 
 
 ## Development

data/lib/kick_ahead/ar_repository.rb

@@ -0,0 +1,32 @@
+class ArRepository
+  def initialize(klass)
+    @klass = klass
+  end
+
+  def each_job_in_the_past
+    @klass.where('scheduled_at <= ?', KickAhead.current_time.call).find_each do |job|
+      yield(as_hash(job))
+    end
+  end
+
+  def create(job_class, schedule_at, *args)
+    job = @klass.create! job_class: job_class, job_args: args, scheduled_at: schedule_at
+    job.id
+  end
+
+  def delete(id)
+    raise 'Not possible!' if id.nil?
+    @klass.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

data/lib/kick_ahead/version.rb

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

data/lib/kick_ahead.rb

@@ -2,16 +2,18 @@
 
 require "kick_ahead/version"
 require "kick_ahead/job"
+require "kick_ahead/ar_repository"
 
 module KickAhead
   OutOfInterval = Class.new(StandardError)
   NoTickIntervalConfigured = Class.new(RuntimeError)
+  NoCurrentTimeConfigured = Class.new(RuntimeError)
 
   RAISE_EXCEPTION_STRATEGY = :raise_exception
   IGNORE_STRATEGY = :ignore
   HOOK_STRATEGY = :hook
 
-  ALL_STRATEGIES = [RAISE_EXCEPTION_STRATEGY, IGNORE_STRATEGY, HOOK_STRATEGY].freeze
+  STRATEGIES = [RAISE_EXCEPTION_STRATEGY, IGNORE_STRATEGY, HOOK_STRATEGY].freeze
 
   class << self
     attr_accessor :tick_interval
@@ -24,7 +26,7 @@ module KickAhead
       end
 
       if current_time.nil?
-        raise 'You must configure a way for me to know the current time!'
+        raise NoCurrentTimeConfigured, 'You must configure a current_time lambda (i.e.: KickAhead.current_time = -> { Time.current })'
       end
 
       KickAhead.repository.each_job_in_the_past do |job|
@@ -61,6 +63,10 @@ module KickAhead
       end
     end
 
+    def create_active_record_repository_for(ar_model)
+      ArRepository.new(ar_model)
+    end
+
     private
 
     # Extracted from activesupport/lib/active_support/inflector/methods.rb, line 258

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kick_ahead
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Roger Campos
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-11-29 00:00:00.000000000 Z
+date: 2018-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -79,10 +79,9 @@ files:
 - Gemfile.lock
 - README.md
 - Rakefile
-- bin/console
-- bin/setup
 - kick_ahead.gemspec
 - lib/kick_ahead.rb
+- lib/kick_ahead/ar_repository.rb
 - lib/kick_ahead/job.rb
 - lib/kick_ahead/version.rb
 homepage: https://github.com/rogercampos/kick_ahead
@@ -105,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: Push code to execute in the future, without dependencies

data/bin/console

@@ -1,14 +0,0 @@
-#!/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

@@ -1,8 +0,0 @@
-#!/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