czar 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 471ebb54150c95923d569f6ce7d32072a17974e8
-  data.tar.gz: 4cf441e9b83e54c5cd5f558fa03018481f6f67a5
+  metadata.gz: 7ff3361aa69a60086e6d183164eb351347aa671b
+  data.tar.gz: 7e39e13e6b3d1db2961f1534dd7cf472aeacd779
 SHA512:
-  metadata.gz: 0362a5ee711c89fa76765e2585ada348990f7d9fa8ce30c5d478e20a4693153c8867d7cf72e0ee4df807ac686bc68feb6c213fcb1b3ba2d2a9d34439829c7893
-  data.tar.gz: fc23abaa9a1d2af589d2ab0515b43fd8a403b3cfb510ab9c00839752385ee38fd6d7187fb34793792b41123613e77613ff55514da08a1b6408964beddeca9416
+  metadata.gz: 9daac98d456d7015df0b4d73976a2fdd7be67126384ea0346a724ff18de9ec55d5988aaedc6634437c14b1cb69dc6dfbf1275dcb67f0986063b07d075af0eeed
+  data.tar.gz: bc90d90e5daad1b22bae48c6000dbf256546d808172da009616fda721de9b3a9d6f744d02222922af357a91a3ba27061ba224c37387eee54e45961fbec4eff47

data/README.md

@@ -1,23 +1,45 @@
 # Czar
 
 Czar is a framework for building applications around the Command
-pattern.  
+pattern.  However, it is intended that these commands will stop at
+various points during their lifetime, then resume again a bit later.
+Maybe in response to incoming web-requests, because there's a
+background timer in action, or simply because we are waiting on an
+external resource.
 
 Everything your application does is a Command of some kind; those
 commands may be simple actions, sequences of actions, sequences with
-decisions within them or series that trigger other commands.  
-
-The advantage of using commands within, for example, a Rails application
-is that you can then make your database model classes *passive* - that
-is they become purely data - and the interesting stuff is all handled by
-commands.  No more fat models with callbacks all over the place.  
-
-Plus using commands makes it easy to ensure that authorisation is done
-correctly (as each command is well-defined) and makes it trivial to add
-in logging and so on.  
+decisions within them or series that trigger other commands.  Czar is
+intended to make those commands explicit - when your user reads some
+data, makes a change to something or updates an item, each one of those
+is a command flowing through your system.  Representing them as their
+own individual objects simplifies authorisation and can mean your code
+is much simpler.  For example, in a Rails app, you would often rely on
+callbacks to trigger various actions on a given model.  But if you use a
+UpdatesGivenModel command, you can write some linear code to handle all
+updates, logging, after_update handlers, instead of piecing together a
+trail of callbacks.  And as you can build complex commands by
+aggregating multiple child commands, it also makes testing your app
+simpler, as well as making its processes more explicit.  
 
 Czar can allow commands to be persisted (with a in-memory and a Redis adapter for now).
 
+The original requirement for Czar was in an application that did an
+import of products from a CSV.  As this could be a very long-running
+task, each operation was put onto a background queue and the system was
+scaled by adding new worker processes.  Each product, as it was being imported,
+may have required several images to be imported from an FTP server; so
+there were many tasks that could all happen in parallel: reading the
+CSV, updating or adding individual products, searching for and importing
+images from the FTP server, attaching imported images to products.  
+
+So the ImportsCsv command would spawn several hundred ImportsProduct commands, 
+and dependent upon the data, each of those could spawn several 
+ImportsImageFromFtpServer and AttachesImageToProducts tasks.  But all the 
+user cares about is "when will the import be done?".  So the parent ImportsCsv command keeps track
+of its child tasks and, being persistent, can report its progress back
+to the web application.  
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -36,6 +58,7 @@ Or install it yourself as:
 
 The Command module represents an implementation of the Command pattern
 where each Command has an internal state machine and can optionally spawn child commands.
+
 At its simplest, a Command will be executed, moving it from "start" state to "complete" state. 
 For example:
 ```
@@ -53,12 +76,12 @@ class SimpleCommand
 end
 ```
 
-To use this, simply call SimpleCommand.new.execute - the command will perform #some_complex_calculation and then be marked as :complete
+To use this, simply call SimpleCommand.new.execute - the command will perform #some_complex_calculation and then be marked as :complete - we can then find out what happend by calling the #result method.
 
 By itself, this is pretty boring.  However, as we've got a simple state machine in there, we can do more interesting stuff; especially when a command is persistent.
 
 For example:
-
+```
 class DrivesACar
   include Czar::Command
 
@@ -71,7 +94,7 @@ class DrivesACar
     if has_reached_destination?
       mark_as :complete
     elsif traffic_light.colour == :green
-      mark_as :driving
+      mark_as :moving
     else 
       mark_as :stopped
     end
@@ -85,6 +108,7 @@ class DrivesACar
     # code goes here
   end
 end
+```
 
 In this case, we instantiate a DrivesACar command and store it somewhere.  Every now and then (in response to a timer, a cron job or some other trigger) we call execute, which looks at the command's internal state and chooses if it is moving or stopped.  Eventually, when we have reached our destination, the command is marked as complete. Also note, that as we do nothing when stopped, there's no need to define a stopped method.  
 
@@ -92,6 +116,7 @@ Commands can also trigger child commands, and are notified when the child comple
 
 For example: 
 
+```
 class CourierDeliversAParcel < Struct.new(:pickup_location, :dropoff_location)
   include Czar::Command
 
@@ -109,6 +134,7 @@ class CourierDeliversAParcel < Struct.new(:pickup_location, :dropoff_location)
     end
   end
 end
+```
 
 ## Contributing
 

data/lib/czar/command.rb

@@ -33,7 +33,7 @@ module Czar
 
     def mark_as state, params = {}
       @state = state.to_sym
-      @internal_state = params.dup
+      @internal_state = internal.merge(params)
       notify_parent if @state == :complete
     end
 

data/lib/czar/version.rb

@@ -1,3 +1,3 @@
 module Czar
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/test/czar/command_test.rb

@@ -101,6 +101,41 @@ describe Czar::Command do
     end
   end
 
+  describe "updating internal state" do
+    subject { internal_state_task.new }
+
+    it "ensures any internal state is maintained" do
+      subject.execute
+      subject.this.must_equal true
+      subject.execute
+      subject.that.must_equal true
+      subject.this.must_equal true
+    end
+
+    let(:internal_state_task) do 
+      Class.new do
+        include Czar::Command
+
+        def start
+          mark_as :doing_stuff, this: true
+        end
+
+        def doing_stuff
+          mark_as :done_stuff, that: true
+        end
+
+        def this
+          internal[:this]
+        end
+
+        def that 
+          internal[:that]
+        end
+      end
+
+    end
+  end
+
   describe "triggering child commands" do
     subject { parent_task.new }
 
@@ -126,10 +161,6 @@ describe Czar::Command do
           mark_as :waiting_for_child_to_complete
         end
 
-        def waiting_for_child_to_complete
-          sleep 0.1
-        end
-
         def child_task_completed child_task
           mark_as :complete
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: czar
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-16 00:00:00.000000000 Z
+date: 2014-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler