jobly 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c291317ad0589ae8edc781249eed56684185e31e7b376a71c426ca31cade67f9
-  data.tar.gz: 5bf18f622297cc8446e7e5c3ec3fcc28584cc41a5d80f611fde5e339f44f09ed
+  metadata.gz: 2e477c569a3ff769ded464f2d52e4775b254b348464057de68d3a63f2eec053c
+  data.tar.gz: 4bfdc207e0b541a52eb7e363cce13ed54635ed0b63e15e61ac5f2b17959ec98d
 SHA512:
-  metadata.gz: db20fe73b659b6a90234537a5058d908ed857e1c1b11092afae45d60bb9bfc4565c8d865a104f54c931518197c6fb834d65fe0c1f36734b3e77ffb6daee81ac0
-  data.tar.gz: 96757bbd1e809d05d6a752cce7bfc4a9c0967d83a78ef913f1ed9c807575dc6c415c31d2a7c6ce4adc629c7aade641bbcb088ff5e5c00b130b5df26c964aba19
+  metadata.gz: 1a427c799068ede5b6a1b97b92f22d14cbc6569cd373d06168058e75f7b91a7cc3bb54e9a91774327ca557bef6c9de54af9e0f28bb7359db514ff7ef1f0bcad3
+  data.tar.gz: deacef64bbfa47d091134103d7450701a5dcdda4e9f5c21175c05969d17b9370552abc7f8e930a00d2271fc79669752e7aec0a5781d1c0e58cb59060b6fd6f82

data/README.md

@@ -15,20 +15,34 @@ Compact job server with API, CLI, Web UI and a Sidekiq heart.
 
 ---
 
+<table><tr>
+  <td width='50%'><a target='_screenshot' href='/demo/terminal.gif'><img src='/demo/terminal.gif'/></a></td>
+  <td width='50%'><a target='_screenshot' href='/demo/screen.gif'><img src='/demo/screen.gif'/></a></td>
+</tr></table>
+
+---
+
 * [Installation](#installation)
 * [What's in the Box](#whats-in-the-box)
 * [Quick Start](#quick-start)
 * [Usage](#usage)
-   * [Server](#server)
-   * [Worker](#worker)
-   * [Running jobs from the command line](#running-jobs-from-the-command-line)
-   * [Running jobs through the API](#running-jobs-through-the-api)
+  * [Server](#server)
+  * [Worker](#worker)
+  * [Running jobs from the command line](#running-jobs-from-the-command-line)
+  * [Running jobs through the API](#running-jobs-through-the-api)
 * [Building Jobs](#building-jobs)
+  * [The Job Class](#the-job-class)
+    * [Job Options](#job-options)
+    * [Before, After, On Failure and On Success](#before-after-on-failure-and-on-success)
 * [Loading Additional Code](#loading-additional-code)
 * [Configuration](#configuration)
+  * [Worker Configuration](#worker-configuration)
 
 ---
 
+Follow development progress:  
+[![Waffle.io - Columns and their card count](https://badge.waffle.io/DannyBen/jobly.svg?columns=all&style=flat-square)](https://waffle.io/DannyBen/jobly)
+
 Installation
 --------------------------------------------------
 
@@ -126,8 +140,11 @@ subfolder inside it. All your job classes go in this folder (configurable).
 
 All job classes will be loaded by any of Jobly's commands.
 
+
+### The Job Class
+
 A job class is a simple Ruby class inheriting from 
-`[Jobly::Job](/lib/jobly/job.rb)`.
+[`Jobly::Job`](/lib/jobly/job.rb).
 
 The only requirement is that your class implements an `execute` method that
 optionally accepts keyword arguments (recommended), or a hash.
@@ -144,12 +161,71 @@ end
 ```
 
 Note that these classes are simply Jobly-flavored sidekiq jobs, with these
-differences:
+key differences:
 
 - You need to implement `execute` instead of `perform`
 - Job arguments are defined as keyword arguments, instead of positional 
   arguments.
 
+#### Job Options
+
+The `Jobly::Job` class supports these options:
+
+| Key         | Default   | Purpose       
+|-------------|-----------|---------------
+| `queue`     | `default` | set the name of the queue for this job.
+| `retries`   |  `5`      | number of times to retry on failure.
+| `backtrace` |  `5`      | number of backtrace lines to show in case of failures. Can be `true`, `false` or a number of lines to save.
+
+For example:
+
+```ruby
+class Deploy < Jobly::Job
+  queue 'critical'
+  backtrace 10
+  retries 3
+  
+  def execute
+    puts "Deploying"
+  end
+end
+```
+
+
+#### Before, After, On Failure and On Success
+
+The `Jobly::Job` class supports these callback methods:
+
+| Method       | Description 
+|--------------|-------------
+| `before`     | Executes before the job starts
+| `on_success` | Executes after the job finishes, and only if it succeeds
+| `on_failure` | Executes after the job finishes, and only if it fails
+| `after`      | Executes after the job finishes, regardless of success or failure
+
+Each callback method can either be a block or a symbol that points to a local
+method. WHen using a block, you will have the `params` variable available, with
+all the parameteres sent to the job.
+
+For example:
+
+```ruby
+class Greet < Jobly::Job
+  before do
+    logger.info "Starting with #{params[:message]}"
+  end
+
+  after :reboot_computer
+  
+  def execute(message: "Hello")
+    puts message
+  end
+
+  def reboot_computer
+    system "reboot"
+  end
+end
+```
 
 
 Loading Additional Code
@@ -173,3 +249,19 @@ Configuring Jobly can be done by one of two methods:
 See this [example config file](/examples/02-full/config/jobly.rb) for a full
 annotated configuration example and a list of options with their respective
 environment variables.
+
+
+### Worker Configuration
+
+For advanced configuration of the sidekiq worker, beyond what the 
+`jobly worker` command provides, you can place YAML files in the config 
+folder and point the workers to their config file with
+`jobly worker --config name`.
+
+These files are simply [sidekiq configuration files][1].
+
+See the [worker-config](/examples/06-worker-config) example for more 
+information.
+
+
+[1]: https://github.com/mperham/sidekiq/wiki/Advanced-Options

data/lib/jobly.rb

@@ -2,6 +2,7 @@ require 'requires'
 require 'byebug' if ENV['BYEBUG']
 
 requires 'jobly/refinements'
+requires 'jobly/job_extensions'
 require 'jobly/exceptions'
 require 'jobly/sidekiq'
 require 'jobly/module_functions'

data/lib/jobly/commands/worker.rb

@@ -2,18 +2,40 @@ module Jobly
   module Commands
     class WorkerCmd < Base
       summary "Start a job worker"
-      usage "jobly worker [--concurrency COUNT]"
+      usage "jobly worker [-c COUNT -C PATH (-q NAME)...]"
       usage "jobly worker (-h|--help)"
       option "-c, --concurrency COUNT", "Number of parallel jobs [default: 4]"
+      option "-C, --config PATH", "Specify a path to a YAML config file. The provided path should be relative to the global config_path directory and without the yml extension"
+      option "-q, --queue NAME[,WEIGHT]", "Specify one or more queues that this worker should handle"
+
+      example "jobly worker --concurrency 10"
+      example "jobly worker -q critical -q default -q low"
+      example "jobly worker --config primary"
 
       def run
-        concurrency = args['--concurrency']
         say "Starting sidekiq"
-        exec "sidekiq --environment #{Jobly.environment} --concurrency #{concurrency} --require #{boot_file}"
+        exec "sidekiq #{options_from_args}"
       end
 
     private
 
+      def options_from_args
+        result = []
+        result << "--environment #{Jobly.environment}"
+        result << "--require \"#{boot_file}\""
+        result << "--concurrency #{args['--concurrency']}" if args['--concurrency']
+
+        if args['--config']
+          config_file = "#{Jobly.config_path}/#{args['--config']}.yml"
+          raise ArgumentError, "Config not found: #{config_file}" unless File.exist? config_file
+          result << "--config \"#{config_file}\""
+        end
+        
+        args['--queue'].each { |q| result << "--queue #{q}" }
+
+        result.join ' '
+      end
+
       def boot_file
         @boot_file ||= File.expand_path '../boot.rb', __dir__
       end

data/lib/jobly/job.rb

@@ -2,15 +2,58 @@ module Jobly
   class Job
     include Sidekiq::Worker
     include Sidekiq::Status::Worker
-    sidekiq_options retry: 5
+    include JobExtensions::OptionAccessors
+    include JobExtensions::Actions
+    using KeywordArgs
 
+    sidekiq_options retry: 5, backtrace: 5
+    attr_reader :params
+
+    class << self
+      # Allow inheriting jobs to use `execute_async` instead of 
+      # `perform_async` for consistency with `execute`
+      alias_method :execute_async, :perform_async
+
+      # Allow calling a job with `JobName.execute` instead of 
+      # `JobName.new.execute`, for consistency.
+      def execute(*args)
+        new.execute *args
+      end
+
+      # Allow calling a job with `JobName.perform` instead of 
+      # `JobName.new.perform`, for consistency.
+      def perform(*args)
+        new.perform *args
+      end
+
+    end
+
+    # This is the method sidekiq will call. We capture this call and convert
+    # the hash argument which was converted to array on sidekiq's side, back
+    # to a hash so we can forward to the job's `execute` method, which may 
+    # implement keyword args.
     def perform(params={})
-      params = params.to_h.transform_keys(&:to_sym)
-      params.empty? ? execute : execute(params)
+      @params = params
+      run_actions :before
+
+      begin
+        params.empty? ? execute : execute(params.to_kwargs)
+        run_actions :success
+
+      rescue
+        run_actions :failure
+        raise
+      
+      ensure
+        run_actions :after
+      
+      end
     end
 
+    # Inheriting classes must implement this method only.
     def execute(params={})
       raise NotImplementedError
     end
+
   end
 end

data/lib/jobly/job_extensions/actions.rb

@@ -0,0 +1,55 @@
+module Jobly
+  module JobExtensions
+    module Actions
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def before(sym = nil, &block)
+          actions[:before] ||= []
+          actions[:before] << (sym || block)
+        end
+
+        def after(sym = nil, &block)
+          actions[:after] ||= []
+          actions[:after] << (sym || block)
+        end
+
+        def on_success(sym = nil, &block)
+          actions[:success] ||= []
+          actions[:success] << (sym || block)
+        end
+
+        def on_failure(sym = nil, &block)
+          actions[:failure] ||= []
+          actions[:failure] << (sym || block)
+        end
+
+        def actions
+          @actions ||= {}
+        end
+      end
+
+    protected
+
+      def actions
+        self.class.actions
+      end
+
+      def run_actions(list)
+        return unless actions[list]
+
+        actions[list].each do |action|
+          if action.is_a? Symbol
+            send action
+          else
+            instance_eval &action
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/jobly/job_extensions/option_accessors.rb

@@ -0,0 +1,29 @@
+module Jobly
+  module JobExtensions
+    module OptionAccessors
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+      
+      module ClassMethods
+        def options
+          sidekiq_options
+        end
+
+        def queue(name)
+          options['queue'] = name
+        end
+
+        def retries(count)
+          options['retry'] = count
+        end
+
+        def backtrace(count)
+          options['backtrace'] = count
+        end
+      end      
+
+    end
+  end
+end

data/lib/jobly/refinements/convert_to_typed.rb

@@ -18,6 +18,8 @@ module Jobly
 
     refine String do
       def convert_to_typed
+        return true  if ['true', 'yes'].include? self
+        return false if ['false', 'no'].include? self
         Integer self rescue self
       end
     end

data/lib/jobly/refinements/keyword_args.rb

@@ -0,0 +1,15 @@
+module Jobly
+  module KeywordArgs
+    refine Hash do
+      def to_kwargs
+        to_h.transform_keys &:to_sym
+      end
+    end
+
+    refine Array do
+      def to_kwargs
+        to_h.transform_keys &:to_sym
+      end
+    end
+  end
+end

data/lib/jobly/version.rb

@@ -1,3 +1,3 @@
 module Jobly
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jobly
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-09 00:00:00.000000000 Z
+date: 2019-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mister_bin
@@ -185,10 +185,13 @@ files:
 - lib/jobly/config.ru
 - lib/jobly/exceptions.rb
 - lib/jobly/job.rb
+- lib/jobly/job_extensions/actions.rb
+- lib/jobly/job_extensions/option_accessors.rb
 - lib/jobly/jobs.rb
 - lib/jobly/module_functions.rb
 - lib/jobly/refinements/argument_converters.rb
 - lib/jobly/refinements/convert_to_typed.rb
+- lib/jobly/refinements/keyword_args.rb
 - lib/jobly/server.rb
 - lib/jobly/sidekiq.rb
 - lib/jobly/version.rb