crocodile 1.0 → 2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e35b8e2d866cda5902a83846d31abcff811cc74
-  data.tar.gz: 83e2ed773492325df10a068b6a8ed6b231df1531
+  metadata.gz: d2627bc70065abf622c9cb773882267676bd6fc8
+  data.tar.gz: 1b919c277bd260a7b972223111b07cc08e9d2536
 SHA512:
-  metadata.gz: ddc93616e432e0e0b060d28cfa818a484e4f0234dd2a0f4fc1923a51e4b74e8669254fe6a342cea2a4dfc27add42d95affd9674ae3fb90eb45522d84f5d3040b
-  data.tar.gz: 9ce1f4006abaf5a3c067760bb211fd7d0b70e7d5fc725feca5d9474e7e834fd06d10cffe9ba145a41a492a77f4dd2a2953008a886ded5baf1b8bedc0daa95aa8
+  metadata.gz: 6c7d0d8bf450e0f593004f9d10495d1a327b4a2a613b7f1283e0ace971e552ca252537aca06884774d8233d602fd95501b89771cc6d227326b2c7a6a20019c59
+  data.tar.gz: 753a061b3df20c39b1ff53db8c9e6dfbb77cc8dab37eefd9fb54792a8a2a4d75c81102ca59106474f366adfb6fdef24c931975c8ecaba28708f18fb9a8699ff7

data/.gems-test

@@ -0,0 +1 @@
+mocha -v 1.1.0

data/README.md

@@ -0,0 +1,129 @@
+##Crocodile
+
+Crocodile is a gem for running periodic [background] jobs written in Ruby.
+Crocodile provides a worker binary that's in charge of running the jobs you define, it also provides a base class for those jobs.
+
+###Install
+
+```
+gem install crocodile
+```
+
+###Jobs
+
+Crocodile is based on some conventions for running your jobs:
+
+* It will look for the jobs files in the `jobs` directory of your application
+* The job file name is the name of the job to run
+* The job class name must be the filename ending in `Job`, so if your file is `dummy.rb`, the class defined inside the file must be `DummyJob`.
+
+Your job class must respond to an interface in order to be ran by crocodile, for this, Crocodile provides the `CrocodileJob` class for you to inherit from there.
+
+However, the interface is very simple, you can write your own class and forget about CrocodileJob as long as:
+
+* You have a class method `YourClass#message` that returns a string
+* You have a class method `YourClass#interval` that returns an integer which indicates, in seconds, how often your job will be ran
+* You have a class method `YourClass#one_run_only` that returns a boolean indicating if crocodile has to run it only once
+* You have a class method `YourClass#logger` that returns a `Logger` object
+* You have a class method `YourClass#run` that implements the logic of your job
+
+If you use the `CrocodileJob` as the base class, you only need to reimplement:
+
+* `CrocodileJob#interval`
+* `CrocodileJob#run`
+
+The default logger will log to `STDOUT`, if you want to log to a file, reimplement `CrocodileJob#logger` with something like `Logger.new("jobs/logs/dummy.log")`
+
+###Example
+
+Suppose you have an application, let's say `dummy_app` and you need to run periodic background jobs on it.
+Go to the `dummy_app` dir and create the necessary directories:
+
+```
+mkdir -p jobs/pids
+```
+
+Then define a dummy job for your dummy app:
+
+```Ruby
+# file: jobs/dummy.rb
+
+require 'crocodile'
+
+class DummyJob < CrocodileJob
+  def self.interval
+    ENV['DUMMY_JOB_INTERVAL'] || 10
+  end
+
+  def self.run
+    puts "Look ma, I'm running!!"
+  end
+end
+```
+
+Once the job is defined, go to the terminal and run it:
+
+```
+crocodile dummy start
+```
+
+You will see the output of the `run` method every 10 seconds. If you want to override the interval, just export the evn var:
+
+```
+DUMMY_JOB_INTERVAL=3 crocodile dummy start
+```
+
+This is useful for testing your job works correcly, however, it won't be very useful when you need to run it in a server, since you will want to log out from the server and keep the job running, so you need to _daemonize_ your job. Also, to keep track of what your job is doing, you might want to use a log file:
+
+```Ruby
+# file: jobs/dummy.rb
+
+require 'crocodile'
+
+class DummyJob < CrocodileJob
+  def self.interval
+    ENV['DUMMY_JOB_INTERVAL'] || 10
+  end
+
+  def self.run
+    puts "Look ma, I'm running!!"
+  end
+
+  def self.logger
+    Logger.new("/tmp/dummy.log")
+  end
+end
+```
+
+Then, run it as a daemon:
+
+```
+crocodile -d dummy start
+```
+
+Now you can check the file `/tmp/dummy.log` for the output of your job at any given time.
+
+The file `jobs/pids/dummy.pid` will show the PID of the running job.
+
+If you need to stop the job, you do it through command line as well:
+
+```
+crocodile dummy stop
+```
+
+If you need just schedule the job instead to run it immediately, you do it through command line as well:
+
+```
+crocodile dummy schedule
+```
+
+
+So, that's pretty much it. We hope you enjoy it.
+
+###How to collaborate
+
+If you find a bug or want to collaborate with the code, you can:
+
+* Report issues trhough the issue tracker
+* Fork the repository into your own account and submit a Pull Request
+

data/bin/crocodile

@@ -1,62 +1,11 @@
 #! /usr/bin/env ruby
+
 require 'optparse'
-require 'eventmachine'
+require_relative '../lib/crocodile/crocodile_process'
 
 module Crocodile
   def self.print_help
-    $stdout.puts "Usage: crocodile [-d] [-p /path/to/pids] job_name (start|stop)"
-  end
-end
-
-class CrocodileProcess
-  def initialize(job_name, pids_dir)
-    @name = job_name
-    @job_path = File.expand_path("jobs/#{job_name}")
-    @pid_path = File.expand_path("#{job_name}.pid", pids_dir)
-  end
-
-  def start
-    require @job_path
-    job_class = constantize(@name)
-
-    Signal.trap("INT")  { EventMachine.stop }
-    Signal.trap("TERM") { EventMachine.stop }
-
-    EventMachine.run do
-      timer = EventMachine::PeriodicTimer.new(job_class.interval || 60) do
-        job_class.logger.info job_class.message
-        job_class.run
-        if job_class.one_run_only
-          timer.cancel
-          EventMachine.stop
-        end
-      end
-    end
-  end
-  
-  def stop
-    if File.exists?(@pid_path)
-      Process.kill :TERM, File.open(@pid_path).read.strip.to_i
-      File.delete(@pid_path)
-      true
-    else
-      false
-    end
-  end
-
-  def daemonize!
-    Process.daemon(true)
-    File.open(@pid_path, File::RDWR|File::EXCL|File::CREAT, 0600) { |io| io.write(Process.pid) }
-  end
-
-  def clean
-    if File.exists?(@pid_path)
-      File.delete(@pid_path)
-    end
-  end
-
-  def constantize(name)
-    eval name.split("_").push("job").map(&:capitalize).join
+    $stdout.puts "Usage: crocodile [-d] [-p /path/to/pids] job_name (start|schedule|stop)"
   end
 end
 
@@ -76,7 +25,7 @@ job_name = ARGV.shift
 action   = ARGV.shift
 
 unless job_name
-  $stderr.puts "Must indicate a worker name"
+  $stderr.puts "Must indicate a job name"
   Crocodile.print_help
   exit 1
 end
@@ -102,6 +51,14 @@ when "start"
   $stdout.puts "Starting Job #{job_name} #{opts[:daemonize] ? "(daemonized)" : ""}"
   process.start
 
+when "schedule"
+  if opts[:daemonize]
+    process.daemonize!
+  end
+
+  $stdout.puts "Scheduling Job #{job_name} #{opts[:daemonize] ? "(daemonized)" : ""}"
+  process.schedule
+
 when "stop"
   $stdout.puts "Stopping Job #{job_name}"
   if process.stop
@@ -118,4 +75,3 @@ end
 at_exit do
   process.clean
 end
-

data/crocodile.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "crocodile"
+  s.version = "2.0"
+  s.summary = "Periodic Ruby jobs runner"
+  s.license = "MIT"
+  s.description = "A simple worker to run Ruby jobs periodically"
+  s.authors = ["Lautaro Orazi", "Leonardo Mateo"]
+  s.email = ["taro@threefunkymonkeys.com", "kandalf@threefunkymonkeys.com"]
+  s.homepage = "https://github.com/threefunkymonkeys/crocodile"
+  s.require_paths = ["lib"]
+  s.bindir = "bin"
+  s.executables << "crocodile"
+  s.add_dependency "eventmachine", '~> 1.0'
+  s.add_development_dependency 'mocha', '1.1.0'
+
+  s.files = `git ls-files`.split("\n")
+end

data/lib/crocodile/crocodile_job.rb

@@ -6,11 +6,11 @@ class CrocodileJob
   end
 
   def self.interval
-    raise RuntimeError.new("Must reimplement self.interval in a subclass")
+    raise NotImplementedError, "Must reimplement self.interval in a subclass"
   end
 
   def self.run
-    raise RuntimeError.new("Must reimplement self.interval in a subclass")
+    raise NotImplementedError, "Must reimplement self.run in a subclass"
   end
 
   def self.one_run_only

data/lib/crocodile/crocodile_process.rb

@@ -0,0 +1,64 @@
+require 'eventmachine'
+
+class CrocodileProcess
+  def initialize(job_name, pids_dir)
+    @name = job_name
+    @job_path = File.expand_path("jobs/#{job_name}")
+    @pid_path = File.expand_path("#{job_name}.pid", pids_dir)
+  end
+
+  def start
+    schedule(launch_immediately=true)
+  end
+
+  def schedule(launch_immediately=false)
+    require @job_path
+    job_class = constantize(@name)
+
+    Signal.trap("INT")  { EventMachine.stop }
+    Signal.trap("TERM") { EventMachine.stop }
+
+    EventMachine.run do
+      EventMachine.next_tick do
+        job_class.logger.info job_class.message
+        job_class.run
+        EventMachine.stop if job_class.one_run_only
+      end if launch_immediately
+
+      timer = EventMachine::PeriodicTimer.new(job_class.interval || 60) do
+        job_class.logger.info job_class.message
+        job_class.run
+        if job_class.one_run_only
+          timer.cancel
+          EventMachine.stop
+        end
+      end
+    end
+  end
+
+  def stop
+    if File.exists?(@pid_path)
+      Process.kill :TERM, File.open(@pid_path).read.strip.to_i
+      File.delete(@pid_path)
+      true
+    else
+      false
+    end
+  end
+
+  def daemonize!
+    Process.daemon(true)
+    File.open(@pid_path, File::RDWR|File::EXCL|File::CREAT, 0600) { |io| io.write(Process.pid) }
+  end
+
+  def clean
+    if File.exists?(@pid_path)
+      File.delete(@pid_path)
+    end
+  end
+
+  def constantize(name)
+    Kernel.const_get(name.split("_").push("job").map(&:capitalize).join)
+  end
+
+end

data/test/unit/crocodile_job_test.rb

@@ -0,0 +1,15 @@
+require 'minitest/autorun'
+require 'minitest/spec'
+require 'mocha/mini_test'
+require_relative '../../lib/crocodile/crocodile_job'
+
+describe 'CrocodileJob' do
+  it 'should respond to basic methods' do
+    CrocodileJob.must_respond_to :message
+    CrocodileJob.must_respond_to :interval
+    CrocodileJob.must_respond_to :run
+    CrocodileJob.must_respond_to :one_run_only
+    CrocodileJob.must_respond_to :logger
+  end
+end
+

data/test/unit/crocodile_process_test.rb

@@ -0,0 +1,46 @@
+require 'minitest/autorun'
+require 'minitest/spec'
+require 'mocha/mini_test'
+require_relative '../../lib/crocodile/crocodile_process'
+require_relative '../../lib/crocodile/crocodile_job'
+
+describe 'CrocodileProcess' do
+  def setup
+    job =<<-CLASS
+    class TestJob < CrocodileJob
+      def self.interval;1;end
+      def self.logger;Logger.new('/dev/null');end
+      def self.run;end
+    end
+    CLASS
+
+    Dir.mkdir("jobs") unless File.exist? "jobs"
+    File.open("jobs/test.rb", "w") do |f|
+      f.puts job
+    end
+  end
+
+  def teardown
+    File.unlink("jobs/test.rb")
+  end
+
+  it 'should run the job' do
+    require './jobs/test' #required to be able to set expectation
+
+    process = CrocodileProcess.new('test', '/tmp')
+    TestJob.expects(:interval).returns(0.1)
+    TestJob.expects(:message).returns("Testing Process")
+    TestJob.expects(:run)
+    TestJob.expects(:one_run_only).returns(true)
+
+    process.start
+  end
+
+  it 'should daemonize the process' do
+    process = CrocodileProcess.new('test', '/tmp')
+
+    Process.expects(:daemon).returns(true)
+    process.daemonize!
+  end
+end
+

data/test/unit/worker_test.rb

@@ -0,0 +1,18 @@
+require 'minitest/autorun'
+require 'minitest/spec'
+
+describe 'Executable Worker' do
+  it 'should ask for job name' do
+    output = `./bin/crocodile 2>&1`
+
+    output.must_include "Must indicate a job name"
+    output.must_include "Usage"
+  end
+
+  it 'should ask for an action' do
+    output = `./bin/crocodile test 2>&1`
+
+    output.must_include "Must indicate an action"
+    output.must_include "Usage"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crocodile
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '2.0'
 platform: ruby
 authors:
 - Lautaro Orazi
@@ -9,22 +9,36 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-15 00:00:00.000000000 Z
+date: 2015-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.0
 description: A simple worker to run Ruby jobs periodically
 email:
 - taro@threefunkymonkeys.com
@@ -35,10 +49,17 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gems"
+- ".gems-test"
 - LICENSE
+- README.md
 - bin/crocodile
+- crocodile.gemspec
 - lib/crocodile.rb
 - lib/crocodile/crocodile_job.rb
+- lib/crocodile/crocodile_process.rb
+- test/unit/crocodile_job_test.rb
+- test/unit/crocodile_process_test.rb
+- test/unit/worker_test.rb
 homepage: https://github.com/threefunkymonkeys/crocodile
 licenses:
 - MIT