sidekiq-symbols 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 895afbd3618b031afb0839dbc36c10b90a4eb03a
-  data.tar.gz: a7df359e07d804c62fc6c7313cb04550dd990bdf
+  metadata.gz: c1954164e938224ab274441208d5036c6976bd1f
+  data.tar.gz: 11d6e29155f5ced734b6928da6054f4c66355e1e
 SHA512:
-  metadata.gz: adb7baeb660624f770caedc595e38bcca55a7ed1ffedb076ecf6ca1760d7860ba05a64d5de7eba1734e6239f3d8349f3a98c8af0f916566c76cf799f1b266ac3
-  data.tar.gz: b2a086137d07ce88edc86834e4843c6c685c6334b29a1193b841c4b1a90ec690d77e250e70a8e704914645127c7d41038239f999fce19adfab98605eec96489b
+  metadata.gz: 68c7be9b66e74d61e0d754fa6d901c3ba3d9a494d6abcb95c59d620aa04421e104e077a35929036dadc476346e2698f044702e6b629c80d8bbca1c34fa7c659d
+  data.tar.gz: e88beb69b21bbee8a0cc41c8fbbbbd9be023a68ad3efc7eb9407215f086dda7887ea605904dfdb4846c8e831db4c1081228c0b92e4a1d984e776d0fb73804c65

data/Appraisals

@@ -0,0 +1,19 @@
+appraise "sidekiq-2-x" do
+  gem "sidekiq", "~> 2.0"
+end
+
+appraise "sidekiq-3-x" do
+  gem "sidekiq", "~> 3.0"
+end
+
+appraise "sidekiq-4-x" do
+  gem "sidekiq", "~> 4.0"
+end
+
+appraise "sidekiq-5-x" do
+  gem "sidekiq", "~> 4.0"
+end
+
+appraise "sidekiq-edge" do
+  gem "sidekiq", github: "mperham/sidekiq"
+end

data/README.md

@@ -1,20 +1,31 @@
+# sidekiq-symbols
+
 [![Build Status](https://travis-ci.org/aprescott/sidekiq-symbols.svg?branch=master)](https://travis-ci.org/aprescott/sidekiq-symbols)
 
-sidekiq-symbols gives you symbol keys for your `perform` method.
+sidekiq-symbols gives you symbol keys and Ruby keyword arguments for your Sidekiq jobs.
+
+### License
+
+Copyright (c) 2014 Adam Prescott, licensed under the MIT license. See LICENSE.
 
 ### Caveats
 
-I have not tested this in a production environment! The 0.x version is there for a reason!
+While there is an automated test suite, and I have smoke-tested manually, I have not thoroughly tested this in a production environment! The 0.x version is there for a reason!
 
-### To use
+### Installing
 
-Add
+With Bundler:
 
 ```ruby
-include Sidekiq::Symbols
+# in Gemfile
+gem "sidekiq-symbols"
 ```
 
-to your Sidekiq job class.
+Either `require "sidekiq-symbols"` or `require "sidekiq/symbols"`.
+
+### To use
+
+Include the `Sidekiq::Symbols` module in your job class:
 
 ```ruby
 class SomeJob
@@ -27,19 +38,41 @@ end
 
 ### What it does
 
-Because Sidekiq round-trips job arguments through JSON serialization-deserialization, a hash argument passed to `perform_async` which uses symbols won't actually be `fetch`able with symbol keys, because
+Consider this Sidekiq job:
 
 ```ruby
-perform_async(x: 1)
+class SomeJob
+  include Sidekiq::Worker
+
+  def perform(opts = {})
+    raise unless opts.has_key?(:x)
+  end
+end
+
+# used as:
+
+SomeJob.perform_async(x: 1)
 ```
 
-leads to when it gets pulled out of Redis.
+Because Sidekiq round-trips job arguments through JSON serialization-deserialization, this job will raise as the arguments are converted from
+
+```ruby
+{ x: 1 }
+```
+
+to
+
+```ruby
+{ "x" => 1 }
+```
+
+and then passes it to `perform`. So it will end up being called as:
 
 ```ruby
 perform("x" => 1)
 ```
 
-sidekiq-symbols forces `perform` to use symbols for all its keys, so that this works:
+sidekiq-symbols forces `perform` to work with symbols, not strings:
 
 ```ruby
 class SomeJob
@@ -47,14 +80,14 @@ class SomeJob
   include Sidekiq::Symbols
 
   def perform(arg, opts = {})
-    opts[:x] # this works
+    opts[:x] == 1 # this is true now!
   end
 end
 
 SomeJob.perform_async("foo", x: 1)
 ```
 
-Note that `perform_async("foo", "x" => 1)` here would leave `opts["x"] == nil` since you _must_ use `opts[:x]`.
+Note that this means you **cannot** use strings for this job! `perform_async("foo", "x" => 1)` here is converted to `perform("foo", x: 1)` because `Sidekiq::Symbols` is included.
 
 ### Keyword arguments
 
@@ -66,7 +99,62 @@ class SomeJob
   include Sidekiq::Symbols
 
   def perform(x: 1, y: 2)
-    # x and y are availalbe
+    # x and y are available
   end
 end
 ```
+
+### Beware subclasses!
+
+You may be tempted to add `include Sidekiq::Symbols` to a base class and inherit from that base class to get symbol support. **This will not work how you expect.**
+
+Specifically, this situation won't correctly symbolize keys:
+
+```ruby
+# does NOT work
+
+class BaseJob
+  include Sidekiq::Worker
+  include Sidekiq::Symbols
+end
+
+class FooJob < BaseJob
+  def perform
+    # ...
+  end
+end
+```
+
+As long as you stick to keeping `include Sidekiq::Symbols` on "leaf" classes (at the bottom of the inheritance chain), it should work.
+
+```ruby
+# does work
+
+class BaseJob
+  include Sidekiq::Worker
+end
+
+class FooJob < BaseJob
+  include Sidekiq::Symbols
+
+  def perform
+    # ...
+  end
+end
+```
+
+It is recommended that you test any job classes that use `Sidekiq::Symbols` and that also rely on subclassing.
+
+### Development
+
+Issues (bugs, questions, etc.) should be opened with [the GitHub project](https://github.com/aprescott/sidekiq-symbols).
+
+To contribute changes:
+
+1. Visit the [GitHub repository for `sidekiq-symbols`](https://github.com/aprescott/sidekiq-symbols).
+2. [Fork the repository](https://help.github.com/articles/fork-a-repo).
+3. Make new feature branch: `git checkout -b master new-feature` (do not add on top of `master`!)
+4. Implement the feature, along with tests.
+5. [Send a pull request](https://help.github.com/articles/fork-a-repo).
+
+Tests live in `spec/`. Run them with `rspec`. To run tests against various Sidekiq versions, use `appraisal rspec`. (See the [Appraisal](https://github.com/thoughtbot/appraisal) project and the `Appraisals` file for more details.)

data/gemfiles/sidekiq_2_x.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org/"
+
+gemspec path: "../"
+
+gem "sidekiq", "~> 2.0"

data/gemfiles/sidekiq_3_x.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org/"
+
+gemspec path: "../"
+
+gem "sidekiq", "~> 3.0"

data/gemfiles/sidekiq_4_x.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org/"
+
+gemspec path: "../"
+
+gem "sidekiq", "~> 4.0"

data/gemfiles/sidekiq_5_x.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org/"
+
+gemspec path: "../"
+
+gem "sidekiq", "~> 4.0"

data/gemfiles/sidekiq_edge.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org/"
+
+gemspec path: "../"
+
+gem "sidekiq", github: "mperham/sidekiq"

data/lib/sidekiq/symbols.rb

@@ -9,7 +9,7 @@ module Symbols
   module Symbolizer
     def perform(*args)
       symbolized_args = args.map do |arg|
-        if arg.is_a?(Hash)
+        if __sidekiq_symbols_should_process?(arg)
           __sidekiq_symbols_symbolize_keys(arg)
         else
           arg
@@ -21,12 +21,23 @@ module Symbols
     private
 
     def __sidekiq_symbols_symbolize_keys(arg)
-      h = {}
-      arg.each do |k, v|
-        k = k.to_sym if k.respond_to?(:to_sym)
-        h[k] = v.is_a?(Hash) ? __sidekiq_symbols_symbolize_keys(v) : v
+      case arg
+      when Hash
+        h = {}
+        arg.each do |k, v|
+          k = k.to_sym if k.respond_to?(:to_sym)
+          h[k] = __sidekiq_symbols_should_process?(v) ? __sidekiq_symbols_symbolize_keys(v) : v
+        end
+        h
+      when Array
+        arg.map { |v| __sidekiq_symbols_should_process?(v) ? __sidekiq_symbols_symbolize_keys(v) : v }
+      else
+        arg
       end
-      h
+    end
+
+    def __sidekiq_symbols_should_process?(arg)
+      arg.is_a?(Hash) || arg.is_a?(Array)
     end
   end
 end

data/sidekiq-symbols.gemspec

@@ -1,18 +1,19 @@
 Gem::Specification.new do |s|
   s.name         = "sidekiq-symbols"
-  s.version      = "0.1.1"
+  s.version      = "0.2.0"
   s.authors      = ["Adam Prescott"]
   s.email        = ["adam@aprescott.com"]
   s.homepage     = "https://github.com/aprescott/sidekiq-symbols"
-  s.summary      = "Symbolize your Sidekiq jobs."
-  s.description  = "Symbolize your Sidekiq jobs."
-  s.files        = Dir["{lib/**/*,spec/**/*}"] + %w[sidekiq-symbols.gemspec LICENSE Gemfile README.md]
+  s.summary      = "Give Sidekiq symbols and keyword arguments."
+  s.description  = "Forces Sidekiq jobs to use symbolized keys and enables keyword arguments."
+  s.files        = Dir["{lib/**/*,spec/**/*,gemfiles/*.gemfile}"] + %w[sidekiq-symbols.gemspec LICENSE Gemfile Appraisals README.md]
   s.require_path = "lib"
   s.test_files   = Dir["spec/*"]
   s.required_ruby_version = ">= 2.0.0"
   s.licenses = ["MIT"]
 
   s.add_dependency("sidekiq")
-  s.add_development_dependency("rspec", ">= 3.0")
+  s.add_development_dependency("rspec", ">= 3.3")
   s.add_development_dependency("pry-byebug")
+  s.add_development_dependency("appraisal")
 end

data/spec/examples.txt

@@ -0,0 +1,12 @@
+example_id                    | status | run_time        |
+----------------------------- | ------ | --------------- |
+./spec/symbols_spec.rb[1:1]   | passed | 0.00018 seconds |
+./spec/symbols_spec.rb[1:2]   | passed | 0.00028 seconds |
+./spec/symbols_spec.rb[1:3]   | passed | 0.00019 seconds |
+./spec/symbols_spec.rb[1:4]   | passed | 0.00019 seconds |
+./spec/symbols_spec.rb[1:5]   | passed | 0.00177 seconds |
+./spec/symbols_spec.rb[1:6]   | passed | 0.00019 seconds |
+./spec/symbols_spec.rb[1:7]   | passed | 0.0002 seconds  |
+./spec/symbols_spec.rb[1:8]   | passed | 0.0002 seconds  |
+./spec/symbols_spec.rb[1:9:1] | passed | 0.00024 seconds |
+./spec/symbols_spec.rb[1:10]  | passed | 0.00119 seconds |

data/spec/re_run_friendly_formatter.rb

@@ -1,30 +1,30 @@
 require "rspec/core/formatters/progress_formatter"
- 
+
 class ReRunFriendlyFormatter < RSpec::Core::Formatters::ProgressFormatter
   RSpec::Core::Formatters.register self, :dump_summary
- 
+
   def dump_summary(summary)
     super
- 
+
     failed_files = summary.failed_examples.map { |e| RSpec::Core::Metadata::relative_path(e.file_path) }.uniq
- 
+
     return if summary.failed_examples.empty? || failed_files.length > 10
- 
+
     output.puts
     output.puts "Rerun all failed examples:"
     output.puts
- 
+
     output.puts failure_colored("rspec #{summary.failed_examples.map { |e| RSpec::Core::Metadata::relative_path(e.location) }.join(" ")}")
- 
+
     output.puts
     output.puts "Rerun all files containing failures:"
     output.puts
- 
+
     output.puts failure_colored("rspec #{failed_files.join(" ")}")
   end
- 
+
   private
- 
+
   def failure_colored(str)
     RSpec::Core::Formatters::ConsoleCodes.wrap(str, :failure)
   end

data/spec/spec_helper.rb

@@ -4,18 +4,89 @@ require "sidekiq/testing"
 require "pry-byebug"
 
 RSpec.configure do |config|
-  config.expect_with :rspec do |c|
-    c.syntax = :expect
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
   end
 
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
   config.filter_run :focus
   config.run_all_when_everything_filtered = true
 
-  if config.files_to_run.one?
-    config.full_backtrace = true
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3#new__config_option_to_disable_rspeccore_monkey_patching
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = false
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+end
+
+# sidekiq test configuration
+RSpec.configure do |config|
+  config.before(:each) do |example_method|
+    # Clears out the jobs for tests using the fake testing
+    Sidekiq::Worker.clear_all
+  end
+
+  # use an around to allow each test to specify
+  # its own around block and override the testing
+  # context.
+  config.before(:each) do |example_method|
+    # Clears out the jobs for tests using the fake testing
+    Sidekiq::Worker.clear_all
   end
 
+  # use an around to allow each test to specify
+  # its own around block and override the testing
+  # context.
   config.around(:each) do |example|
-    Sidekiq::Testing.inline!(&example)
+    # acceptance tests run the jobs immediately.
+    if example.metadata[:type] == :feature || example.metadata[:sidekiq] == :inline
+      Sidekiq::Testing.inline!(&example)
+    else
+      Sidekiq::Testing.fake!(&example)
+    end
   end
 end

data/spec/symbols_spec.rb

@@ -1,12 +1,10 @@
-require "spec_helper"
-
-describe Sidekiq::Symbols do
+RSpec.describe Sidekiq::Symbols, sidekiq: :inline do
   class SampleJob
     include Sidekiq::Worker
     include Sidekiq::Symbols
 
     def perform(*args, **kwargs)
-      $find_a_better_way_than_this = [args, kwargs]
+      $perform_arg_signature = [args, kwargs]
     end
   end
 
@@ -15,14 +13,17 @@ describe Sidekiq::Symbols do
     include Sidekiq::Symbols
 
     def perform(x, opts = {})
-      $find_a_better_way_than_this = [x, opts]
+      $perform_arg_signature = [x, opts]
     end
   end
 
   def expect_transformation(klass, *input, arg_signature)
-    expect(klass.new.perform(*input)).to eq(arg_signature)
     klass.perform_async(*input)
-    expect($find_a_better_way_than_this).to eq(arg_signature)
+    expect($perform_arg_signature).to eq(arg_signature)
+  end
+
+  before do
+    $perform_arg_signature = nil
   end
 
   it "allows regular arguments" do
@@ -37,10 +38,85 @@ describe Sidekiq::Symbols do
     expect_transformation(SampleHashArgJob, 1, { "x" => 1 }, [1, x: 1])
   end
 
+  it "symbolizes hashes inside arrays" do
+    expect_transformation(SampleHashArgJob, 1, { "x" => [ { "y" => 2 } ] }, [1, x: [{y:2}]])
+  end
+
+  it "handles arrays containing a mix of types" do
+    expect_transformation(SampleHashArgJob, 1, { "x" => [{ "y" => 2 }, "not-a-hash", 123] }, [1, { x: [{ y: 2 }, "not-a-hash", 123] }])
+  end
+
+  it "symbolizes hashes inside arrays inside hashes inside arrays" do
+    input = [1, {"x" => [ { "y" => [ { "z" => 3 } ]  } ] }]
+    arg_signature = [1, { x: [ { y: [ { z: 3 } ] } ] }]
+    expect_transformation(SampleHashArgJob, *input, arg_signature)
+  end
+
+  it "symbolizes hashes inside arrays inside arrays" do
+    input = [1, {"x" => [ [ { "y" => 2 }, { "z" => 3 } ] ] }]
+    arg_signature = [1, { x: [ [ { y: 2 }, { z: 3 } ] ] }]
+    expect_transformation(SampleHashArgJob, *input, arg_signature)
+
+  end
+
   it "symbolizes all arguments to Sidekiq's perform" do
     input = [1, "x" => { "y" => 2, z: { "foo bar" => 0 } }]
     arg_signature = [[1], { x: { y: 2, z: { :"foo bar" => 0 } } }]
 
     expect_transformation(SampleJob, *input, arg_signature)
   end
+
+  describe "subclassing" do
+    class BaseJob
+      include Sidekiq::Worker
+    end
+
+    class SubclassFooJob < BaseJob
+      include Sidekiq::Symbols
+
+      def perform(x: -1)
+        $subclass_x = x
+      end
+    end
+
+    class SubclassBarJob < BaseJob
+      include Sidekiq::Symbols
+
+      def perform(y: -1)
+        $subclass_y = y
+      end
+    end
+
+    it "works on subclasses that do their own include" do
+      SubclassFooJob.perform_async(x: 1)
+      SubclassBarJob.perform_async(y: 2)
+
+      expect($subclass_x).to eq(1)
+      expect($subclass_y).to eq(2)
+    end
+  end
+
+  # 2.1+ introduced required keyword arguments, so this must be done with
+  # eval to sidestep syntax errors at parse time.
+  if RUBY_VERSION >= "2.1.0"
+    # Note that this test is asserting that perform_async raises, but in
+    # reality it will actually raise at the Sidekiq server level when the worker
+    # tries to perform the job.
+    #
+    # perform_async itself won't raise because of missing required keyword args
+    # in actual code.
+    eval <<-DEFEAT_THE_PARSER
+      class SampleRequiredKeywordArgsJob
+        include Sidekiq::Worker
+        include Sidekiq::Symbols
+
+        def perform(x:)
+        end
+      end
+
+      it "raises on missing required keyword args" do
+        expect { SampleRequiredKeywordArgsJob.perform_async }.to raise_error(ArgumentError)
+      end
+    DEFEAT_THE_PARSER
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq-symbols
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Adam Prescott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-04 00:00:00.000000000 Z
+date: 2017-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sidekiq
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -52,19 +52,40 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Symbolize your Sidekiq jobs.
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  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: Forces Sidekiq jobs to use symbolized keys and enables keyword arguments.
 email:
 - adam@aprescott.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- Appraisals
 - Gemfile
 - LICENSE
 - README.md
+- gemfiles/sidekiq_2_x.gemfile
+- gemfiles/sidekiq_3_x.gemfile
+- gemfiles/sidekiq_4_x.gemfile
+- gemfiles/sidekiq_5_x.gemfile
+- gemfiles/sidekiq_edge.gemfile
 - lib/sidekiq-symbols.rb
 - lib/sidekiq/symbols.rb
 - sidekiq-symbols.gemspec
+- spec/examples.txt
 - spec/re_run_friendly_formatter.rb
 - spec/spec_helper.rb
 - spec/symbols_spec.rb
@@ -88,11 +109,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
-summary: Symbolize your Sidekiq jobs.
+summary: Give Sidekiq symbols and keyword arguments.
 test_files:
-- spec/re_run_friendly_formatter.rb
 - spec/spec_helper.rb
+- spec/examples.txt
+- spec/re_run_friendly_formatter.rb
 - spec/symbols_spec.rb