leonidas 0.0.1

data/CHANGELOG

@@ -0,0 +1 @@
+v0.0.1 initial library

data/Gemfile

@@ -0,0 +1,15 @@
+source :rubygems
+
+gem 'rack'
+gem 'echoe'
+gem 'sinatra'
+
+gem 'debugger'
+gem 'rake'
+gem 'rspec'
+gem 'jasmine'
+gem 'jasmine-headless-webkit'
+
+gem 'json'
+
+gem 'keystone', git: "git://github.com/jpeace/keystone.git"

data/Gemfile.lock

@@ -0,0 +1,105 @@
+GIT
+  remote: git://github.com/jpeace/keystone.git
+  revision: 54627ade405d8b3307e349f36bab6e87b75fae84
+  specs:
+    keystone (0.0.1)
+      closure-compiler
+      coffee-script
+      sass
+      sinatra
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    allison (2.0.3)
+    childprocess (0.3.9)
+      ffi (~> 1.0, >= 1.0.11)
+    closure-compiler (1.1.8)
+    coffee-script (2.2.0)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.6.2)
+    columnize (0.3.6)
+    debugger (1.5.0)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.2.0)
+      debugger-ruby_core_source (~> 1.2.0)
+    debugger-linecache (1.2.0)
+    debugger-ruby_core_source (1.2.0)
+    diff-lcs (1.2.4)
+    echoe (4.6.3)
+      allison (>= 2.0.3)
+      gemcutter (>= 0.7.0)
+      rake (>= 0.9.2)
+      rdoc (>= 3.6.1)
+      rubyforge (>= 2.0.4)
+    execjs (1.4.0)
+      multi_json (~> 1.0)
+    ffi (1.8.1)
+    gemcutter (0.7.1)
+    hike (1.2.2)
+    jasmine (1.3.2)
+      jasmine-core (~> 1.3.1)
+      rack (~> 1.0)
+      rspec (>= 1.3.1)
+      selenium-webdriver (>= 0.1.3)
+    jasmine-core (1.3.1)
+    jasmine-headless-webkit (0.8.4)
+      coffee-script
+      jasmine-core (~> 1.1)
+      multi_json
+      rainbow
+      sprockets (~> 2)
+    json (1.7.7)
+    json_pure (1.7.7)
+    multi_json (1.7.2)
+    rack (1.5.2)
+    rack-protection (1.5.0)
+      rack
+    rainbow (1.1.4)
+    rake (10.0.4)
+    rdoc (4.0.1)
+      json (~> 1.4)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    rubyforge (2.0.4)
+      json_pure (>= 1.1.7)
+    rubyzip (0.9.9)
+    sass (3.2.8)
+    selenium-webdriver (2.32.1)
+      childprocess (>= 0.2.5)
+      multi_json (~> 1.0)
+      rubyzip
+      websocket (~> 1.0.4)
+    sinatra (1.4.2)
+      rack (~> 1.5, >= 1.5.2)
+      rack-protection (~> 1.4)
+      tilt (~> 1.3, >= 1.3.4)
+    sprockets (2.9.3)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    tilt (1.4.0)
+    websocket (1.0.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  debugger
+  echoe
+  jasmine
+  jasmine-headless-webkit
+  json
+  keystone!
+  rack
+  rake
+  rspec
+  sinatra

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Tim Shelburne
+
+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/Manifest

@@ -0,0 +1,63 @@
+CHANGELOG
+Gemfile
+Gemfile.lock
+LICENSE
+Manifest
+README.md
+Rakefile
+assets/scripts/coffee/leonidas/client.coffee
+assets/scripts/coffee/leonidas/commander.coffee
+assets/scripts/coffee/leonidas/commands/command.coffee
+assets/scripts/coffee/leonidas/commands/organizer.coffee
+assets/scripts/coffee/leonidas/commands/processor.coffee
+assets/scripts/coffee/leonidas/commands/stabilizer.coffee
+assets/scripts/coffee/leonidas/commands/synchronizer.coffee
+assets/scripts/js/lib/jquery.js
+bin/leonidas.js
+config/assets.rb
+lib/leonidas.rb
+lib/leonidas/app/app.rb
+lib/leonidas/app/connection.rb
+lib/leonidas/app/repository.rb
+lib/leonidas/commands/aggregator.rb
+lib/leonidas/commands/command.rb
+lib/leonidas/commands/handler.rb
+lib/leonidas/commands/processor.rb
+lib/leonidas/dsl/configuration_expression.rb
+lib/leonidas/memory_layer/memory_registry.rb
+lib/leonidas/persistence_layer/persister.rb
+lib/leonidas/persistence_layer/state_builder.rb
+lib/leonidas/persistence_layer/state_loader.rb
+lib/leonidas/routes/sync.rb
+lib/leonidas/symbols.rb
+spec/jasmine/jasmine.yml
+spec/jasmine/runner.html
+spec/jasmine/support/classes.coffee
+spec/jasmine/support/helpers.coffee
+spec/jasmine/support/mocks.coffee
+spec/jasmine/support/objects.coffee
+spec/jasmine/support/requirements.coffee
+spec/jasmine/tests/client_spec.coffee
+spec/jasmine/tests/commander_spec.coffee
+spec/jasmine/tests/commands/command_spec.coffee
+spec/jasmine/tests/commands/organizer_spec.coffee
+spec/jasmine/tests/commands/processor_spec.coffee
+spec/jasmine/tests/commands/stabilizer_spec.coffee
+spec/jasmine/tests/commands/synchronizer_spec.coffee
+spec/rspec/spec_helper.rb
+spec/rspec/support/classes/app.rb
+spec/rspec/support/classes/commands.rb
+spec/rspec/support/classes/persistence.rb
+spec/rspec/support/config.rb
+spec/rspec/support/mocks.rb
+spec/rspec/support/objects.rb
+spec/rspec/unit/app/app_spec.rb
+spec/rspec/unit/app/repository_spec.rb
+spec/rspec/unit/commands/aggregator_spec.rb
+spec/rspec/unit/commands/command.rb
+spec/rspec/unit/commands/processor_spec.rb
+spec/rspec/unit/dsl/configuration_expression_spec.rb
+spec/rspec/unit/leonidas_spec.rb
+spec/rspec/unit/memory_layer/memory_registry_spec.rb
+spec/rspec/unit/persistence_layer/persister_spec.rb
+spec/rspec/unit/persistence_layer/state_loader_spec.rb

data/README.md

@@ -0,0 +1,213 @@
+# Leonidas
+
+leonidas.js handles generalized web application concurrency through basic command operations. It handles synchronizing application state by sending serialized lists of local commands and retrieving commands processed on external commands to and from a server with AJAX. 
+
+Leonidas.rb is an integration built to support Leonidas commands on the server-side, in both memory and persistent states. There are also two default Sinatra endpoints provided at Leonidas::Routes::SyncApp for an immediate integration with leonidas.js.
+
+## Terminology
+
+### General
+
+* Command - Any granular action taken within an application
+* Command Handler - An class representing an action taken on the application state in response to a command 
+* Stable Command - A command that happened before or at the minimum timestamp of all client connections to the app 
+* Locked State - The state of an application when only stable commands have been run
+* Active State - The state of an application when all available commands have been run
+
+### Javascript
+
+* Client - A wrapper around the client-side application state, representing a single client connection to the server
+* Commander - The command abstraction, used to start and stop syncing, and issue commands
+
+### Ruby
+
+* App - A server side application which keeps track of state and client connections
+* Connection - The server side implementation of a client containing a list of commands 
+* Repository - The mechanism for retrieving an active application
+* Persister - A class responsible for providing the methods necessary to persist an app in a particular system
+* State Builder - A class responsible for rebuilding the state of a persisted application to be loaded into memory
+
+## Configuration
+
+### Javascript
+
+No configuration is needed on the client side.
+
+### Ruby
+
+Persistence of commands in your system will be handled in the server side command handlers, but if your application details need to be persisted, there are only two functions necessary to configure Leonidas:
+
+* persister\_class\_is(persister\_class) - The class responsible for handling persisting the application will be passed into this function
+
+* add\_app\_state\_builder(builder\_class) - For every application you need to support, you will likely need a custom state builder to generate the appropriate state for that application
+
+And example config would resemble the following:
+
+    persister_class_is SaveMyTransgressions
+
+    add_app_state_builder Builders::PeasantStateBuilder
+    add_app_state_builder Buidlers::AristocraticStateBuilder
+
+## Usage
+
+### Javascript
+
+First, create at least one handler for commands in your system (I'm going to use Coffeescript, because it's so nice):
+
+    class PeasantHitHandler
+
+      constructor: (@app)-> # this is temporary - I would much rather be passing in @peasants, but object duplication in Javascript is tricky
+
+      handles: (command)->
+        command.name == "peasant-hit"
+
+      run: (command)->
+        peasantId = command.data.peasantId
+        ... find peasant in @app.state by peasantId
+        peasant.status = "humbled"
+
+Then, you can create a Commander (I would suggest using the default configuration, unless you need custom functionality in the nitty gritty):
+
+    var supremeRuler = Commander.default("app name", [ new PeasantHitHandler() ], "http://mydomain.com/my/sync/url")
+
+Now you can start and stop syncing and issue commands to your hearts content:
+
+    supremeRuler.startSync() # not the funniest line... oh well
+    supremeRuler.issueCommand("peasant-hit", { peasantId: 10 })
+
+This will automatically be handled and synced with your server, most importantly so that you will know if any ruthless rulers from other clients have been hitting your peasants.
+
+### Ruby
+
+As always, the server side is a bit more complicated.
+
+First, you should create at least one command handler. Note that the handler will have the logic necessary to persist your changes - the mechanism for running commands is agnostic, so all persistence options are supported:
+    
+    class PeasantHitHandler
+      include Leonidas::Commands::Handler # this just ensures that all necessary functions are available
+
+      def initialize(app) # similar problem - have to make sure object references work properly
+        @app = app
+      end
+
+      def handles?(command)
+        command.name == "peasant-hit"
+      end
+
+      def run(command)
+        peasant_id = command.data.peasantId # probably camel-cased - it came from js, after all
+        ... # find peasant in @app.current_state.peasants by peasant_id
+        peasant.status = :humbled
+      end
+
+      def persist(command)
+        ... # persistence logic - up to you, homie
+      end
+    end
+
+Then, you can create an App:
+
+    class PeasantSubjugationApp
+      include Leonidas::App::App # this is the neat part that gives you a Leonidas App
+
+      def initialize
+        @name = "Kingdom-Zamunda" # this name must be unique amongst all your apps
+        @persist_state = true # this means that commands with be persisted when they are run
+        @locked_state = { peasants: [ ... ] } # this is the stable state of your application
+        @active_state = { peasants: [ ... ] } # this is the active state (memory only, never persisted) of your application 
+        @connections = [ ] # an empty list of connections when an app is first built
+        @processor = Leonidas::Commands::Processor.new([ PeasantHitHandler.new(self) ]) # a processor initialized with the necessary command handlers
+      end
+
+    end
+
+This is enough to have a functioning Leonidas app - of course, it's likely you will need customization to handle the semantic details of your state.
+
+Now you want to run your app and rule your kingdom (from an endpoint in Sinatra):
+
+    include Leonidas::App::AppRepository # I recommend using the mixin, it makes the function available
+
+    get "/rule-zamunda" do
+      app = PeasantSubjugationApp.new
+      app_repository.watch app # now the app is being stored and referenced from memory
+      ...
+    end
+
+Eventually you need to load your app:
+    
+    ...
+    get "/i-want-to-rule-zamunda-too" do
+      app = app_repository.find "Kingdom-Zamunda"
+      ...
+      haml :see_your_kingdom
+    end
+
+Great! We now have an app running in memory, updating state, and if you did well, communicating to the client(s) at regular intervals.
+
+But what if you (a) need to restart the machine and lose all of your state from memory, or (b) want to revive an old closed application? This is where a persistent application comes into play. A persistent application means simply that you have stored your application details, active connections, and commands in some sort of database. In order to reopen an application that has been closed, or restore an application to memory from disk, we need to be able to load the app from the database via a generalized solution. 
+
+Enter the persister:
+
+    class SaveMyTransgressions
+      include Leonidas::PersistenceLayer::AppPersister # this guarantees that the static Persister can use your class
+
+      def load(app_name)
+        ... # your read / build logic (note that you don't need to worry hear about app state)
+      end
+
+      def persist(app_name)
+        ... # your write logic
+      end
+
+      def delete(app)
+        ... # your remove logic
+      end
+    end
+
+The gist of filling out this class is to allow communication between your database and code to read / write app details (name, persist_state, connections) and connection details (id, last_update, active / inactive commands).
+
+Once you have created your app persister, your application skeleton can be loaded - this just leaves catching the state up with whatever was current. All you need to do in this case is make sure you build the previous locked state of the application. All commands that happened after that locked state will be run again in memory to return your application to a live state.
+
+Create your application's state builder:
+
+    module Builders
+
+      class PeasantStateBuilder
+        include Leonidas::PersistenceLayer::StateBuilder # this lets the state factory use this builder
+
+        def handles?(app)
+          app.is_a? PeasantSubjugationApp
+        end
+
+        def build_stable_state(app)
+          ... # return the peasants to the fields, so to speak
+        end
+
+      end
+
+    end
+
+Lastly, if you want to use the Sinatra endpoints provided by Leonidas for automatically syncing between your clients and server, the Rack app is available:
+
+    map "/path/you/like" do
+      run Leonidas::Routes::SyncApp
+    end
+
+This will mean the frontend syncUrl you pass in Commander.default would look something like "http://yourdomain.com/path/you/like/[your-app-name]"
+
+Voilá, your app should be good to go.
+
+## If (and when) it isn't
+
+Please feel free to contribute, or submit issues to the tracker!
+
+
+
+
+
+
+
+
+
+
+

data/Rakefile

@@ -0,0 +1,42 @@
+$: << File.expand_path("#{File.dirname(__FILE__)}/lib")
+
+require 'leonidas'
+
+require 'rspec/core/rake_task'
+require 'jasmine-headless-webkit'
+require 'keystone'
+require 'echoe'
+
+Echoe.new("leonidas") do |p|
+  p.author = "Tim Shelburne"
+  p.email = "shelburt02@gmail.com"
+  p.url = "https://github.com/tshelburne/leonidas"
+
+  p.ignore_pattern = FileList[".gitignore"]
+  p.development_dependencies = [ "jasmine", "jasmine-headless-webkit" ]
+end
+
+desc "Default"
+task default: :'test:rspec'
+
+namespace :test do
+
+	desc "Run Rspec tests"
+  RSpec::Core::RakeTask.new(:rspec) do |t|
+    t.rspec_opts = "-dcfd --require rspec/spec_helper"
+  end
+
+	desc "Run Jasmine tests"
+	Jasmine::Headless::Task.new(jasmine: :assets) do |t|
+	  t.colors = true
+	  t.keep_on_error = true
+	  t.jasmine_config = './spec/jasmine/jasmine.yml'
+	end
+	
+end
+
+desc "Build assets"
+Keystone::RakeTask.new :assets do |t|
+  t.config_file = "config/assets.rb"
+  t.output_path = 'bin'
+end