la_maquina 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e3e37589f3930b79eecc19e0743e9b6b1fcf1d9f
-  data.tar.gz: c332e847878318ab3db7c764f7f19738b41d2338
+  metadata.gz: cfe629f6f7df101c2c54c842e0fdbd8c05e0f663
+  data.tar.gz: 0f7cacda20c45ae5a0bad8db868cecc60ad4a455
 SHA512:
-  metadata.gz: 22aad45ed90d3542aedb927e47399297c0369fd17fcf6b786958704a75a62c1382832f99525987c477856c24f595e95c1ee9ad2b2bbc6a094a4e70c0ff0885ab
-  data.tar.gz: ae9ddc8d32213ca73d940d3eea5abb1dce9e984f4423be28bf4750d432c0d4a03d53e5b4db7f8f9bc6b5b5adfce687e44873dba279735036b7b883a872fa54a0
+  metadata.gz: 18482c2158276e90c16d474ae744f2431d6ced0a3a2ff4111914016becf9fdbd2330ba86837fdf732ce14b793cdb7bebe7c482916a26a8330dbaea8f983e1458
+  data.tar.gz: 7b2626cbb36fac8bed0e69b4418a33be3a63d5f996cefb924b616d7ac3f21ce7e343a8907005454a7b62a7f98c548c87a98116372accab23bbb077084adb1355

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    la_maquina (0.0.3)
+    la_maquina (0.1.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,31 +1,96 @@
 # La Maquina
 
-Model graph traversal 
+Non-database-based arbitrary updates of `belongs_to` associated ActiveRecord models. 
 
-## Installation
+Let's say you have 2 models
+```ruby
+class DannyTrejo < ActiveRecord::Base
+  has_many :machetes
+end
+```
+and
+```ruby
+class Machete < ActiveRecord::Base
+  belongs_to :danny_trejo
+end
+```
+and you want to let `DannyTrejo` know when a `Machete` has been updated, but you don't want to use `ActiveRecord`'s `touch`, you can use this gem to execute arbitrary code when `Machete` updates.
 
-Add this line to your application's Gemfile:
+## Example
 
-    gem 'la_maquina'
+Using the example above, let's say that when a `Machete` is added, we want its corresponding `DannyTrejo` object to be reindexed by Solr, using the Sunspot interface. With a little bit of config magic, described at the end of this document, we have this:
 
-And then execute:
+```ruby
+class DannyTrejo < ActiveRecord::Base
+  has_many :machetes
 
-    $ bundle
+  searchable do 
+    double  :machete_sharpness, multiple: true do
+      machetes.map(&:sharpness)
+    end
+  end
+end
+```
 
-Or install it yourself as:
+```ruby
+class Machete < ActiveRecord::Base
+  belongs_to :danny_trejo
 
-    $ gem install la_maquina
+  include LaMaquina::Notifier
+  notifies_about :danny_trejo
+end
+```
 
 ## Usage
 
+There are 4 main components to this gem: 
+
+* `notifies_about`: defines the association (eg `Machete` -> `DannyTrejo`)
+* Pistons: the plugins that define the behavior (eg `DannyTrejo.find(id).solr_index!`)
+* ErrorNotifier: defines what you do with the errors once they come up
+* DependencyMap: define the mapping between the notifier and notified classes. *OPTIONAL*
 
+### notifies_about options
+
+`notifies_about target, options ` is an interface that and mirrors ActiveRecord associations.
+to use it, in your `ActiveRecord::Base` model
+```ruby
+include LaMaquina::Notifier
+```
+It can either notify LaMaquina about the object itself with `notifies_about :self`, or about a `belongs_to` association with the following options:
+
+* `:through`: same as rails. Note: expects the through object belongs_to the target object
+* `:polymorphic`: same as rails. Note: expects rails default target `_type` and targe `_id` fields to be present
+* `:class_name`: takes a modulized camelcased string name of the target class
+* `:class`: takes a class constant of the target class type
+* `:using`: this allows you to send update messages through a ruby interface (eg [JsonApiClient](https://github.com/chingor13/json_api_client)). The interface has to respond to `notify( params = {} )`.
+  The params are as follows: 
+  * `:notified_class`: demodulized snake_cased name of class that is notified about (eg "danny_trejo")
+  * `notified_id`: the id of thje object that's being notified about. So if `Machete`(8) belongs to `DannyTrejo`(1), it will be 1
+  * `notifier_class`: demodulized snake_cased name of the notifier class (eg "machete")
+  **Note:** This requires the receiving side to call `LaMaquina::Engine.notify( notifier_class, id, notified_class = "" )`, so you'll have something like 
+  ```ruby
+  class LaMaquinaController < ApplicationController
+    def notify
+      notified_class  = params[:notified_class]
+      notified_id     = params[:notified_id]
+      notifier_class  = params[:notifier_class]
+
+      LaMaquina::Engine.notify notifier_class, id, notified_class
+
+      render json: {success: true}
+    end
+  end
+  ```
+Note: `class` and `class_name` options aren't stricly checked; they're formatted and sent through
 
 ### Pistons
 
-Once the `Engine` is called it fires the `Piston`s, the behavior of which is entirely up to you. 
+A piston is a plugin that can be fired on update. 
 
-So, let's say, we have a couple objects that look like:
+Once a model with a `notifies_about :whatever` gets updated and a commit happens, it will fire off a call to wherever LaMaquina is installed (either locally, or on another server if you're notifying through `JsonApiClient` or similar). Once LaMaquina::Engine receives the call it will fire all of its pistons in no particualr order.
 
+So using the example from above:
 ```ruby
 class DannyTrejo < ActiveRecord::Base
   has_many :machetes
@@ -45,15 +110,14 @@ class Machete < ActiveRecord::Base
   notifies_about :danny_trejo
 end
 ```
-and we want to let `DannyTrejo` know when his `Machete` has been updated so that we can reindex him.
+We want to set up a piston that will reindex `DannyTrejo` on `Machete` update. 
 
-`Machete` is set up to fire on update, so we'll set up a listener Piston that looks like this:
 
 ```ruby
 class SunspotPiston < LaMaquina::Piston::Base
   class << self
     def fire!( notified_class, id, notifier_class = "" )
-      indexed_class(notified_class).find(id).index!
+      indexed_class(notified_class).find(id).solr_index!
     end
 
     private
@@ -65,26 +129,78 @@ class SunspotPiston < LaMaquina::Piston::Base
 end
 
 ```
-Which finds the klass, does a find on it and fires off [Sunspot](https://github.com/sunspot/sunspot#reindexing-objects) `index!` 
+All it needs to do is respond ot `fire!( notified_class, id, notifier_class = "" )` and what happend from there is entirely up to you.
 
-### Setup
 
-The setup is pretty straightforward: you do all the setting up in `config/initializers/la_maquina.rb`. 
+The piston above doesn't use `notifier_class`, but that comes in quite handy should you want to do complex manipulations.For example, if you have a model that has several associations that respond to `complex_code` and you want to cache that code under a composite cache key of "#{top_object}/#{association}:#{id}", you can do something like:
+
+```ruby
+class CompositeCachePison < LaMaquina::Piston::Base
+  class << self
+    class_attribute :redis, :map
+
+    def fire!( notified_class, id, notifier_class )
+      key = "#{notified_class}/#{notifier_class}:#{id}"
+
+      klass = map.mapping_for notified_class
+      object = klass.find(id)
 
-The 3 things you have to do are: set up the pistons(if they need configuring), install them, and configure the error_handler.
-For example, if you're using the CachePiston and need to set up Redis, here's how your `la_maquina.rb` will look
+      # because notifier_class is already snaked we can just send it as an association
+      result = object.send(notifier_class).complex_code
+
+      redis.set key, result
+    end
+
+    # explained below
+    self.map = LaMaquina::DependencyMap::ConstantMap.new
+  end
+```
+
+### DependencyMap
+
+`DependencyMap` is a way to abstract away the dependency structure from the gem and the piston (like you have in the first piston example). 
+
+The interface looks like 
 
 ```ruby
-LaMaquina::Piston::CachePiston.redis = Redis::Namespace.new(:cache_piston, redis: Redis.new)
-LaMaquina::Engine.install LaMaquina::Piston::CachePiston, TestPiston
-LaMaquina.error_notifier = LaMaquina::ErrorNotifier::HoneybadgerNotifier
+class Map < LaMaquina::DependencyMap::Base
+  # defined in Base
+  # initialize( yaml_path = nil)
+
+  def mapping_for(*args)
+    # your code here
+  end
+
+  # also defined in Base
+  # attr_accessor :map
+end
+```
+LaMaquina comes with 2 default maps: `ConstantMap` and `YamlMap`.
+
+`LaMaquina::DependencyMap::ConstantMap` takes a string and tries to constantize it. It's not strictly speaking a map, but it works as you would expect: 
+```ruby
+map = LaMaquina::DependencyMap::ConstantMap.new
+map.mapping_for "danny_trejo" # => DannyTrejo(id: integer, ...)
+```
+`LaMaquina::DependencyMap::YamlMap` get initialized with a yaml path, parses the yaml and spits out a dependency at any depth, meaning:
+```yml
+# map.yml
+danny_trejo:
+  machete: 
+    1: favorite
+    2: dull
 ```
-#### ErrorNotifier
-LaMaquina by default comes with an `ErrorNotifier::Base` that will explode in a very unhelpful manner. To override it, you need to change it in the config above and roll a new `ErrorNotifier` that responds to `notify(error, details)`. For example, if you're using Honeybadger, you can use the included `LaMaquina::ErrorNotifiers::HoneybadgerNotifier, which looks like:
+```ruby
+map = LaMaquina::DependencyMap::YamlMap.new "#{Rail.root}/config/map.yml"
+map.mapping_for "danny_trejo", "machete", 1 # => "favorite"
+```
+
+### ErrorNotifier
+LaMaquina by default comes with an `ErrorNotifier::Base` that will explode in a very unhelpful manner. To override it, you need to change it in the config above and roll a new `ErrorNotifier` that responds to `notify(error, details)`. For example, if you're using Honeybadger, you can use the included `LaMaquina::ErrorNotifiers::HoneybadgerNotifier`, which looks like:
 ```ruby
 class HoneybadgerNotifier < LaMaquina::ErrorNotifier::Base
   self.notify(error = nil, details = {})
-    Honeybadger.notify( :error_class => "CacheMachineError: #{error.class.name}",
+    Honeybadger.notify( :error_class => "LaMaquinaError: #{error.class.name}",
                         :error_message => error.message,
                         :parameters => details
                       )
@@ -96,6 +212,39 @@ If you *don't* care about your exceptions and want to ignore them, there's a not
 LaMaquina::Cinegual.error_notifier = LaMaquina::ErrorNotifier::SilentNotifier
 ```
 
+## Setup
+
+The setup is pretty straightforward: you do all the setting up in `config/initializers/la_maquina.rb`. 
+
+The things you have to do are: set up the pistons(if they need configuring), install them, and configure the error_handler.
+For example, if you're using the CompositeCachePison and need to set up Redis, here's how your `la_maquina.rb` will look
+
+```ruby
+CompositeCachePison.redis = Redis::Namespace.new(:cache_piston, redis: Redis.new)
+# you would initialize the map here, not in the piston
+CompositeCachePison.map = LaMaquina::DependencyMap::ConstantMap.new
+
+LaMaquina::Engine.install CompositeCachePison
+
+LaMaquina.error_notifier = LaMaquina::ErrorNotifier::HoneybadgerNotifier
+```
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'la_maquina'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install la_maquina
+
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/la_maquina/fork )

data/lib/la_maquina/error_notifier/honeybadger_notifier.rb

@@ -2,7 +2,7 @@ module LaMaquina
   module ErrorNotifier
     class HoneybadgerNotifier < LaMaquina::ErrorNotifier::Base
       def notify(error, details = {})
-        Honeybadger.notify( :error_class => "CacheMachineError: #{error.class.name}",
+        Honeybadger.notify( :error_class => "LaMaquinaError: #{error.class.name}",
                             :error_message => error.message,
                             :parameters => details
                           )

data/lib/la_maquina/version.rb

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

data/test/dummy/config/la_maquina/dependency_maps/deep_map.yml

@@ -0,0 +1,7 @@
+admin:
+  trait: trait
+
+guest:
+  trait:
+    - a
+    - b

data/test/unit/dependency_maps/yamp_map_test.rb

@@ -23,4 +23,10 @@ class YamlMapTest < ActiveSupport::TestCase
     assert 'admin', @map.mapping_for(:admin)
     assert :admin, @map.mapping_for(:admin)
   end
+
+  def test_can_go_to_any_depth
+    map = LaMaquina::DependencyMap::YamlMap.new( Rails.root + 'config/la_maquina/dependency_maps/deep_map.yml' )
+    assert_equal "trait", map.mapping_for( "admin", "trait" )
+    assert_equal "b", map.mapping_for( "guest", "trait", 1 )
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: la_maquina
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Greg Orlov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-04 00:00:00.000000000 Z
+date: 2015-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -113,6 +113,7 @@ files:
 - test/dummy/config/initializers/session_store.rb
 - test/dummy/config/initializers/wrap_parameters.rb
 - test/dummy/config/la_maquina/dependency_maps/bad_map.yml
+- test/dummy/config/la_maquina/dependency_maps/deep_map.yml
 - test/dummy/config/la_maquina/dependency_maps/sunspot_piston.yml
 - test/dummy/config/locales/en.yml
 - test/dummy/config/routes.rb
@@ -206,6 +207,7 @@ test_files:
 - test/dummy/config/initializers/session_store.rb
 - test/dummy/config/initializers/wrap_parameters.rb
 - test/dummy/config/la_maquina/dependency_maps/bad_map.yml
+- test/dummy/config/la_maquina/dependency_maps/deep_map.yml
 - test/dummy/config/la_maquina/dependency_maps/sunspot_piston.yml
 - test/dummy/config/locales/en.yml
 - test/dummy/config/routes.rb