ruote-kit 2.1.10 → 2.1.11

data/.gitignore

@@ -1,8 +1,10 @@
 *.swp
 work*/
+ruote_work*/
 .DS_Store
 .yardoc
 doc/*
 pkg/*
 .bundle/*
 nbproject/*
+Gemfile.lock

data/CHANGELOG.txt

@@ -0,0 +1,10 @@
+
+= ruote-kit - CHANGELOG.txt
+
+
+== ruote-kit - 2.1.11    not yet released
+
+- RuoteKit.run_worker(storage) will not return (since it will let the worker
+  run in the current thread)
+- /participants resource
+

data/Gemfile

@@ -1,28 +1,43 @@
+
 # Dependencies for ruote-kit
+
 source :gemcutter
 
 # ruote-kit itself
+
 gem 'bundler'
 gem 'sinatra'
 gem 'sinatra-respond_to'
 gem 'haml'
 
+# more servers
+
+gem 'thin'
+  # for rackup -s thin
+
 # json support
 #
 # you should choose one of the following three or add another backend supported
 # by Rufus::Json (http://github.com/jmettraux/rufus-json/)
 #
-# gem 'json_pure' # safest all-around choice
-# gem 'yajl-ruby' # the fastest, but using c code
-# gem 'json'      # not bad, but using c code and sometimes broken
+# gem 'json_pure'  # safest all-around choice
+# gem 'yajl-ruby'  # the fastest, but using c code
+# gem 'json'       # not bad, but using c code and sometimes broken
+# gem 'json-jruby' # for jruby
 #
 # needed, uses one of the above as backend
-gem 'rufus-json', '>= 0.2.3'
+
+gem 'yajl-ruby', :require => 'yajl'
+gem 'rufus-json', '>= 0.2.5'
 
 # ruote
-gem 'ruote', '>= 2.1.10'
+
+gem 'ruote', '~> 2.1.11'
+#gem 'ruote', :git => 'git://github.com/jmettraux/ruote.git', :branch => 'ruote2.1'
+#gem 'ruote', :path => '~/w/ruote/'
 
 # Testing environment requirements
+
 group :test do
   gem 'rspec', :require => "spec"
   gem 'rack-test'
@@ -33,3 +48,4 @@ end
 group :build do
   gem 'jeweler'
 end
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2009-2010 Kenneth Kalmer (Internet Exchange CC, Clear Planet Information Solutions Pty Ltd)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,3 +1,4 @@
+
 = ruote-kit (RESTful ruote & middleware)
 
 * http://kit.rubyforge.org/ruote (soon)
@@ -13,41 +14,38 @@ Follow development:
 * http://opensourcery.co.za
 * @kennethkalmer on Twitter
 
-== Alpha Status
+== Dependencies
 
-ruote-kit is under heavy development and will likely change violently over the
-coming weeks (albeit for the better).
+ruote-kit uses Bundler[http://gembundler.com/] to setup and maintain its
+environment. Before running ruote-kit for the first time you need to install
+Bundler (gem install bundler) and then run:
 
-Dependencies you currently need are:
+  $ bundle install
 
-* bundler 0.9.5 or later (gem install bundler)
-* sinatra
-* sinatra-respond_to
-* haml
-* rufus-json[http://github.com/jmettraux/rufus-json] and a compatible backend
-* rspec (only to run the specs)
+Bundler will download all the required gems and install them for you.
 
-ruote-kit uses bundler to setup and maintain its environment. Before running
-ruote-kit for the first time you need to install bundler and then run:
+Have a look at the Gemfile if you want to see the various dependencies.
 
-  $ bundle install
+== Getting started quickly
 
-Bundler will download all the required gems and install them for you. To
-bundle the gems you can simply run 'bundle lock' and all the gems will be
-unpacked in .bundle
+=== Using the source
 
-== Getting started quickly
+* Get the source files using git
+    $ git clone http://github.com/kennethkalmer/ruote-kit.git && cd ruote-kit
+* Make sure every dependency is resolved
+    $ bundle install
+* Get going
+    $ rackup
 
-=== Using the RubyGem
+=== Using the RubyGem / Bundler
 
-* Install the gem and its dependencies
-    $ gem install ruote-kit
 * You'll need an empty directory
     $ mkdir my-ruote-kit && cd my-ruote-kit
 * There are two files needed in that directory: Gemfile and config.ru
   * Gemfile
       source :gemcutter
-      gem 'ruote-kit'
+      gem 'ruote', '~> 2.1.11'
+      gem 'ruote-kit', '~> 2.1.11'
   * config.ru
       begin
         # Try to require the preresolved locked set of gems.
@@ -60,32 +58,24 @@ unpacked in .bundle
       end
 
       # load json backend
-      require 'yajl-ruby'    # best choice as fastest, but uses a c module
+      require 'yajl-ruby'    # fastest, but uses a c module
       # require 'json_pure'  # should work everywhere
 
       require 'ruote-kit'
 
-      RuoteKit.configure do |config|
-        config.register { catchall }
+      RuoteKit.engine = Ruote::Engine.new(
+        Ruote::Worker.new(
+          Ruote::FsStorage.new('ruote_work')))
+
+      RuoteKit.engine.register do
+        catchall
       end
 
       use Rack::CommonLogger
       use Rack::Lint
 
       run RuoteKit::Application
-* Just to make sure every dependency is resolved
-    $ bundle check
-* If there are missing dependencies (there shouldn't be any if the gem
-  installation succeeded)
-    $ bundle install
-* Get going
-    $ rackup
-
-=== Using the source
-
-* Get the source files using git
-    $ git clone http://github.com/kennethkalmer/ruote-kit.git && cd ruote-kit
-* Make sure every dependency is resolved
+* Install all needed gems
     $ bundle install
 * Get going
     $ rackup
@@ -104,17 +94,12 @@ rack middleware stack without issues.
 
 Example:
 
-  RuoteKit.configure do |config|
-    # make changes if needed
-    # Register participants if needed
-    config.register do
-      participant :toto do |wi|
-        # ...
-      end
-      # register the catchall participant if needed
-      require 'ruote/part/storage_participant'
-      catchall Ruote::StorageParticipant
-    end
+  RuoteKit.engine = Ruote::Engine.new(
+    Ruote::Worker.new(
+      Ruote::FsStorage.new('ruote_work')))
+
+  RuoteKit.engine.register do
+    catchall
   end
 
 
@@ -127,23 +112,38 @@ See http://github.com/tosch/ruote-on-rails for an example Rails app.
 
 == Configuring ruote-kit & ruote
 
-ruote-kit can be configured using RuoteKit#configure, after which it will start
-the engine. From that point the engine is accessible through RuoteKit.engine.
+ruote-kit itself needs only little configuration, the only thing to do is to
+bind a ruote engine to use. That engine may be configured, see
+http://ruote.rubyforge.org/configuration.html for details.
 
-Without any configuration ruote-kit will use file system persistence, and save
-the work in a sub-folder of the current working directory named +work_<env>+,
-where +env+ is the RACK_ENV or RAILS_ENV.
+When using the source version, you'll have to edit the +config.ru+ file if you
+want to change the engine configuration. It defaults to use file system
+persistence and runs a
+worker[http://ruote.rubyforge.org/configuration.html#worker] within the engine.
+The persistence files will be stored in a sub directory called
+"ruote_work_#{ENV}".
+
+When using the gem version or plugging ruote-kit into your rack stack, you'll
+have to bind the ruote engine to use yourself. See the examples above.
 
 === Registration of participants
 
-ruote participants may be registered within the block given to
-RuoteKit#configure by the RuoteKit::Configuration#register method. It expects a
-block containing of +participant+ and one or less +catchall+ calls (see example
-above).
+ruote participants may be registered using the register method of the engine.
+It expects a block containing of +participant+ and one or less +catchall+ calls.
+
+  require 'ruote/part/no_op_participant'
+
+  RuoteKit.engine.register do
+    participant 'no-op', Ruote::NoOpParticipant
+    catchall
+  end
 
 Note that all +participant+ calls after a +catchall+ one are pretty useless:
 The catchall will eat all their cookies.
 
+If you want to learn more about ruote's participants, have a look at
+http://ruote.rubyforge.org/participants.html .
+
 == The +workitems+ resource
 
 The +workitems+ resource relies on the Ruote::StorageParticipant. You'll have to
@@ -153,25 +153,65 @@ the resource. Example:
   require 'ruote/part/storage_participant'
   RuoteKit.engine.register_participant :storage, Ruote::StorageParticipant
 
-You may also use the catchall participant provided by RuoteKit. It's named '.+',
+You may also use the catchall participant provided by ruote. It's named '.+',
 so it will catch all workitems for any participant mentioned in your workflow
 definitions which are not already caught by another (previously) registered
 participant. So make sure to register the catchall after your own participants.
 The catchall participant may be registered by calling +catchall+ within the
-block given to RuoteKit::Configuration#register (this will use
-Ruote::StorageParticipant as participant implementation, you may use any options
-of Ruote::Engine#register_participant to overwrite that default -- see the
-example above).
+block given to Ruote::Engine#register (this will use Ruote::StorageParticipant
+as participant implementation, you may use any options of
+Ruote::Engine#register_participant to overwrite that default -- see the example
+above).
 
 == Running workers
 
-If you're using ruote-kit as part of your rack stack you'll need to start at
-least one worker separately or the workflows won't be executed. You won't need
-more than one worker unless you are running hundreds of processes at the same
-time.
-
-To run a worker you need to setup a worker script similar to the rake example
-below:
+Always make sure to have a running ruote
+worker[http://ruote.rubyforge.org/configuration.html#worker] for your storage.
+The shipped config.ru takes care of that, but if you use the gem version or use
+ruote-kit as part of your rack stack, you'll need to make sure there is a
+running worker.
+
+Perhaps it's best to give some more explanations about the architecture of ruote
+here. Ruote's engine class is shallow, just a few methods that insert launch and
+reply orders in the storage and read it when querying for process statuses. You
+see: The storage is important, it is used as communications backend between the
+various parts of ruote. The engine class and the storage are not enough, though.
+The real work is done by one or more workers which query the storage for things
+to do (note: it is unlikely that you will ever need more than one worker for one
+ruote instance; ruote isn't fast, but it's faster than most human processes, so
+that you'll won't need more than one worker unless you are running hundreds of
+processes at the same time ).
+
+Ruote ships with one worker implementation (you won't need more) and various
+different storages. Have a look at
+http://ruote.rubyforge.org/configuration.html#storage for an overview.
+
+In the most examples above, the worker instance is bound to the engine which
+is given to RuoteKit.engine:
+
+  RuoteKit.engine = Ruote::Engine.new(
+    Ruote::Worker.new(
+      Ruote::FsStorage.new('ruote_work')))
+
+That is fine, especially when there is only one instance of the app running or
+the storage implementation supports multiple workers, because if there is more
+than one instance of the app running, there will be more than one worker
+operating on the same storage.
+
+If you want to use a storage implementation which doesn't support multiple
+workers (Ruote::FsStorage under Windows, for example), you should start a
+dedicated worker in its own instance. In config.ru (or whereever you configure
+the engine to be used by ruote-kit), instanciate the engine without a worker:
+
+  RuoteKit.engine = Ruote::Engine.new(
+    Ruote::FsStorage.new('ruote_work'))
+
+ruote-kit or your rack app will start with no problems, you may even launch
+processes, but they'll never show up under /_ruote/processes: There is no worker
+which processes the launch requests stored in the storage.
+
+To run a worker you need to setup a worker script similar to the rake task
+example below:
 
   require 'rake'
   require 'ruote-kit'
@@ -179,22 +219,22 @@ below:
   desc "Run a ruote-kit worker"
   task :ruote_kit_worker do
 
-    RuoteKit.configure do |config|
-      # Setup your configuration
-    end
-
-    RuoteKit.run_worker!
+    RuoteKit.run_worker(Ruote::FsStorage.new('ruote_work'))
   end
 
-This will only work correctly if using the default file system persistence.
-Support for ruote-couch[http://github.com/jmettraux/ruote-couch] is coming
-soon.
+Make sure to configure the storage in the same way as in the rest of the
+application or you won't get what you expect ;-)
+
+You also should consider using a separate worker instance when you're running
+ruote-kit or you're rack app in an environment like Passenger: You won't be sure
+the app runs all the time, so it's likely that scheduled events will be missed
+(better: triggered too late). If you don't want to start a separate worker
+process, configure Passenger in a way that your app won't be killed in a very
+long time and make sure your storage implementation supports multiple workers.
 
 == Feedback & bug reports
 
-Please bear in mind that the project is still in its alpha days. Keep bug reports
-and suggestions limited to the google group and #ruote channel, at least for the
-time being.
+Feedback and bug reports are welcome on the mailing-list[http://groups.google.com/group/openwferu-users], or on the #ruote IRC channel at Freenode.net.
 
 Please do not hesitate to come back with *any* feedback.
 
@@ -222,3 +262,15 @@ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+== libraries used
+
+- rack, http://rack.rubyforge.org/
+- sinatra, http://www.sinatrarb.com/
+- sinatra-respond_to, http://github.com/cehoffman/sinatra-respond_to
+- haml, http://haml-lang.com/
+- yajl-ruby, http://github.com/brianmario/yajl-ruby
+- jquery, http://jquery.com/
+
+many thanks to the authors and contributors
+

data/Rakefile

@@ -5,7 +5,7 @@ require "rubygems"
 require "bundler"
 Bundler.setup(:default, :test, :build)
 
-require 'lib/ruote-kit/version'
+require File.join(File.dirname(__FILE__), 'lib/ruote-kit/version')
 
 begin
   require 'jeweler'
@@ -15,25 +15,14 @@ begin
     gemspec.summary = 'ruote workflow engine, wrapped in a loving rack embrace'
     gemspec.description = 'ruote-kit is a RESTful Rack app for the ruote workflow engine'
     gemspec.email = 'kenneth.kalmer@gmail.com'
-    gemspec.homepage = 'http://github.com/kennethkalmer/ruote-kit'
-    gemspec.authors = ['kenneth.kalmer@gmail.com', 'John Mettraux']
+    gemspec.homepage = 'http://github.com/tosch/ruote-kit'
+    gemspec.authors = [ 'kenneth.kalmer@gmail.com', 'Torsten Schoenebaum', 'John Mettraux' ]
     gemspec.extra_rdoc_files.include '*.txt'
 
     gemspec.files.include 'lib/ruote-kit/public/**/*'
     gemspec.executables.clear
 
-    gemspec.add_dependency 'bundler', '>=0.9.5'
-    gemspec.add_dependency 'sinatra', '>=0.9.4'
-    gemspec.add_dependency 'sinatra-respond_to', '>=0.4.0'
-    gemspec.add_dependency 'haml', '>= 2.2.5'
-    gemspec.add_dependency 'rufus-json', '>= 0.2.3'
-    gemspec.add_dependency 'ruote', '>= 2.1.10'
-    gemspec.add_development_dependency 'rake'
-    gemspec.add_development_dependency 'rspec'
-    gemspec.add_development_dependency 'jeweler'
-    gemspec.add_development_dependency 'webrat'
-    gemspec.add_development_dependency 'test-unit', '~> 1.2.3'
-    gemspec.add_development_dependency 'rack-test'
+    gemspec.add_bundler_dependencies
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/TODO.txt

@@ -0,0 +1,12 @@
+
+[o] fix re_apply issue https://gist.github.com/e68fcb4eef2ee66b9081
+[o] pagination for /workitems
+[o] pagination for /processes
+[o] pagination for /errors
+[o] PUT /expressions fluo-editor integration
+
+[ ] error : replay_at_error OK but reply too
+[ ] expression : re_apply OK but reply too
+
+[ ] If-Match etag
+

data/config.ru

@@ -1,16 +1,21 @@
 
+# bundler
+
 begin
-  # Try to require the preresolved locked set of gems.
+  # try to require the preresolved locked set of gems.
   require ::File.expand_path('.bundle/environment', __FILE__)
 rescue LoadError
-  # Fall back on doing an unlocked resolve at runtime.
+  # fall back on doing an unlocked resolve at runtime.
   require 'rubygems'
   require 'bundler'
   Bundler.setup(:default)
 end
 
-# load json support
+
+# json
+#
 # try yajl-ruby first, and json after that
+
 begin
   require 'yajl'
 rescue LoadError
@@ -24,26 +29,29 @@ end
 
 require 'rufus-json'
 
-$:.unshift 'lib'
 
+# ruote-kit
+
+$:.unshift 'lib'
 require 'ruote-kit'
 
-# Chance to configure ruote-kit
-RuoteKit.configure do |config|
 
-  # storage mode
-  #config.mode = :transient
+# ruote
 
-  # run a worker
-  config.run_worker = true
+require 'ruote/storage/fs_storage'
 
-  config.register do
-    # With this rackup I bundle as catchall, making it easy to experiment
-    catchall
-  end
+RuoteKit.engine = Ruote::Engine.new(
+  Ruote::Worker.new(
+    Ruote::FsStorage.new(
+      "ruote_work_#{RuoteKit.env}")))
+
+RuoteKit.engine.register do
+  catchall
 end
 
 
+# rack middlewares, business as usual...
+
 use Rack::CommonLogger
 use Rack::Lint
 use Rack::ShowExceptions

data/lib/ruote-kit/application.rb

@@ -1,55 +1,79 @@
+
+# license is MIT, see LICENSE.txt
+
 require 'sinatra/respond_to'
 require 'haml'
 
-Sinatra::Application.register Sinatra::RespondTo
-
 module RuoteKit
   class Application < Sinatra::Application
 
-    # Delay these a bit
+    register Sinatra::RespondTo
+
+    # delay these a bit
+
     configure do
-      # We want to support Rails
-      if defined?( Rails )
+
+      # we want to support Rails
+
+      if defined?(Rails)
         set :environment, Rails.env
         disable :raise_errors unless Rails.env == 'development'
       end
-
-      RuoteKit.ensure_engine!
     end
 
-    set :views, File.join( File.dirname( __FILE__), 'views' )
+    set :limit, 100
+
+    set :views, File.join(File.dirname(__FILE__), 'views')
 
-    use Rack::Static, :urls => ['/_ruote/images', '/_ruote/javascripts', '/_ruote/stylesheets'], :root => File.join( File.dirname(__FILE__), 'public' )
-    use Rack::MethodOverride
+    use(
+      Rack::Static,
+      :urls => %w[ /_ruote/images /_ruote/javascripts /_ruote/stylesheets ],
+      :root => File.join(File.dirname(__FILE__), 'public'))
+    use(
+      Rack::MethodOverride)
+
+    Dir[File.join(File.dirname(__FILE__), 'helpers/*.rb')].each { |r| load r }
 
     helpers do
-      include RuoteKit::Helpers::EngineHelpers
-      include RuoteKit::Helpers::FormHelpers
-      include RuoteKit::Helpers::LaunchItemParser
-      include RuoteKit::Helpers::NavigationHelpers
+      include RuoteKit::Helpers::LinkHelpers
+      include RuoteKit::Helpers::JsonHelpers
+      include RuoteKit::Helpers::MiscHelpers
       include RuoteKit::Helpers::RenderHelpers
+      include RuoteKit::Helpers::PaginationHelpers
     end
 
     before do
-      # We allow the Accept header to be set to 'application/json'
-      format :json if env["HTTP_ACCEPT"] && env["HTTP_ACCEPT"] == "application/json"
+
+      # we allow the Accept header to be set to 'application/json'
+
+      if env['HTTP_ACCEPT'] && env['HTTP_ACCEPT'] == 'application/json'
+        format :json
+      end
     end
 
-    unless defined?( Rails )
-      # Handle 404's ourselves when not in Rails
+    unless defined?(Rails)
+
+      # handle 404s ourselves when not in Rails
+
       not_found do
-        resource_not_found
+        http_error(404)
       end
     end
 
     get '/_ruote/?' do
+
       respond_to do |format|
-        format.html { haml :index }
-        format.json { json :misc, "ruote-kit" => "welcome", "version" => RuoteKit::VERSION }
+
+        format.html do
+          haml :index
+        end
+        format.json do
+          json :misc, 'ruote-kit' => 'welcome', 'version' => RuoteKit::VERSION
+        end
       end
     end
 
-    Dir[ File.dirname(__FILE__) + '/resources/*.rb' ].each { |r| load r }
+    Dir[File.join(File.dirname(__FILE__), 'resources/*.rb')].each { |r| load r }
   end
 end