rhoconnect 4.0.0.beta.12 → 4.0.0.beta.24

data/commands/rhoconnect/config.rb

@@ -1,14 +1,16 @@
 Execute.define_task do
   desc "config", "Config", :hide => true
   def config(settings_file=false)
+    require 'uri'
+    require 'yaml'
     if File.exist?(File.join('settings','settings.yml'))
-      settings = load_settings(File.join('settings','settings.yml'))
+      settings = YAML.load_file(File.join('settings','settings.yml'))
       rackup_config = "config.ru"
     elsif settings_file
-      settings = load_settings(settings_file)
+      settings = YAML.load_file(settings_file)
       rackup_config = File.join(File.dirname(__FILE__), '..', 'utilities', 'blank_app.ru')
     elsif File.exist?(File.join(ENV['HOME'], '.rhoconnect.yml'))
-      settings = load_settings(File.join(ENV['HOME'], '.rhoconnect.yml'))
+      settings = YAML.load_file(File.join(ENV['HOME'], '.rhoconnect.yml'))
       rackup_config = File.join(File.dirname(__FILE__), '..', 'utilities', 'blank_app.ru')
     else
       options = { :syncserver => "http://localhost:#{RHOCONNECT_PORT}",
@@ -16,7 +18,9 @@ Execute.define_task do
       settings = { :development => options, :test => options, :production => options }
       rackup_config = File.join(File.dirname(__FILE__), '..', 'utilities', 'blank_app.ru')
     end
-    settings = settings[Rhoconnect.environment]
+
+    environment = (ENV['RHO_ENV'] || ENV['RACK_ENV'] || :development).to_sym # FIXME:
+    settings = settings[environment]
     # syncserver settings
     uri = URI.parse(settings[:syncserver])
     port = uri.port unless port

data/commands/rhoconnect/get_token.rb

@@ -1,6 +1,7 @@
 Execute.define_task do
 desc "get-token", "Fetch current api token from rhoconnect"
   def get_token(save = true)
+    require 'rest_client'
     url = config[:syncserver]
     password = ''
     begin
@@ -15,7 +16,8 @@ desc "get-token", "Fetch current api token from rhoconnect"
     begin
       token = RestClient.post("#{url}/rc/v1/system/login",
         { :login => 'rhoadmin', :password => password }.to_json, :content_type => :json)
-    rescue
+    rescue Exception => e
+      puts e.message
       puts "Rhoconnect server is not running or invalid credentials."
       exit
     end

data/commands/rhoconnect/routes.rb

@@ -0,0 +1,34 @@
+Execute.define_task do
+  desc "routes", "Prints out routes defined in the application"
+  def routes
+    puts ""
+    puts "\tYour Application [#{Dir.pwd}] has the following routes map:"
+    puts ""
+    start_list = []
+    begin
+      redis_array = config[:redis]
+      redis_array.each do |redis_inst|
+        start_list << redis_inst unless RedisRunner.running?(redis_inst)
+      end
+      RedisRunner.startbg(start_list) unless start_list.empty?
+
+      require 'rhoconnect/application/init'
+      Rhoconnect::Server.set     :secret,      'temp_secret'
+      Rhoconnect.url_map.each do |root, controller|
+        puts "  #{controller.helpers.class.name}: #{root}"
+        controller.helpers.class.paths.each do |verb, paths|
+          paths.each do |path|
+            puts "    --> #{verb.to_s.upcase}\t #{path}"
+          end
+        end
+      end
+    rescue Exception => e
+      Rhoconnect.log "#{e.inspect}"
+    ensure
+      Rhoconnect.shutdown
+      # TODO: Something is wrong here on Windows!!!
+      # if I use RedisRunner.stop - process hangs for several seconds
+      system("rhoconnect redis-stop") unless start_list.empty?
+    end
+  end
+end

data/commands/rhoconnect/secret.rb

@@ -2,7 +2,7 @@ Execute.define_task do
   desc "secret", "Generate a cryptographically secure secret session key"
   def secret
     begin
-      require 'securerandom' 
+      require 'securerandom'
       puts SecureRandom.hex(64)
     rescue LoadError
       puts "Missing secure random generator.  Try running `rhoconnect secret` in a rails application instead."

data/commands/rhoconnect/set_admin_password.rb

@@ -17,8 +17,9 @@ Execute.define_task do
     elsif new_pass == new_pass_confirm
       puts ""
       url = config[:syncserver]
-      RestClient.put("#{url}/rc/v1/users/rhoadmin",
+      res = RestClient.put("#{url}/rc/v1/users/rhoadmin",
         { :attributes => { :new_password => new_pass }}.to_json, {:content_type => :json, 'X-RhoConnect-API-TOKEN' => token})
+      puts "Admin password is successfully updated" if res.code == 200
     else
       puts "\nNew password and confirmation must match."
     end

data/commands/rhoconnect/startbg.rb

@@ -8,10 +8,10 @@
 Execute.define_task do
   desc "startbg [CHILDNAME]", "Start rhoconnect server in bg mode (Rhostudio) - this is an internal command", :hide => true
   def startbg(childname=nil)
-    cmd = (jruby?) ? trinidad? : (thin? || mongrel? || report_missing_server)
+    cmd = "bundle exec rackup -s #{defined?(JRUBY_VERSION) ? 'puma' : 'thin'}"
     require 'win32/process' if windows?
-    
-    p1 = Process.fork {  
+
+    p1 = Process.fork {
       if windows?
         puts 'Starting rhoconnect ...'
         system "#{cmd} config.ru -P #{rhoconnect_pid}"
@@ -23,7 +23,7 @@ Execute.define_task do
       end
     }
     Process.detach(p1)
-    
+
     exit
   end #startbg
 end

data/commands/rhoconnect/stop.rb

@@ -5,12 +5,12 @@ Execute.define_task do
       File.delete "#{rhoconnect_pid}" if system("FOR /F %A in (#{rhoconnect_pid}) do taskkill /F /PID %A")
     else
       if File.exist?("#{rhoconnect_pid}")
-        pid = `cat #{rhoconnect_pid}` 
+        pid = `cat #{rhoconnect_pid}`
         puts "Sending a QUIT signal to process #{pid}"
         system "kill -3 #{pid}"
         3.times do
           sleep 1
-          return if !File.exist?("#{rhoconnect_pid}") 
+          return if !File.exist?("#{rhoconnect_pid}")
         end
 
         puts "Process #{pid} is still running. Sending a KILL signal to it ..."

data/commands/rhoconnect_console/console.rb

@@ -2,17 +2,17 @@ Execute.define_task do
 desc "console [environment]", "Run rhoconnect console"
   def console(environment=nil)
     ENV['RACK_ENV'] = environment || 'development'
-    application_file = (File.exist?(File.join(Dir.pwd, 'application.rb'))) ?
-      File.join(Dir.pwd, 'application.rb') :
-      File.join(File.dirname(__FILE__), '..', '..', 'generators', 'templates', 'application', 'application.rb')
+    controller_file = (File.exist?(File.join(Dir.pwd, 'controllers', 'ruby', 'application_controller.rb'))) ?
+      File.join(Dir.pwd, 'controllers', 'ruby', 'application_controller.rb') :
+      File.join(File.dirname(__FILE__), '..', '..', 'generators', 'templates', 'application', 'controllers', 'ruby', 'application_controller.rb')
 
-    redis_url = config[:redis]
     if RedisRunner.running?
       system "irb -rubygems -r #{File.join(File.dirname(__FILE__),'console_helper')} " +
         "-r #{File.join(File.dirname(__FILE__), '..', '..', 'lib', 'rhoconnect') } " +
-        "-r #{application_file}"
+        "-r #{File.join(File.dirname(__FILE__), '..', '..', 'lib', 'rhoconnect', 'server') } " +
+        "-r #{controller_file}"
     else
-      puts "Redis is not running on #{redis_url}. Please start it by running 'rhoconnect redis-start' command."
+      puts "Redis is not running. Please start it by running 'rhoconnect redis-start' command."
     end
   end
 end

data/commands/rhoconnect_spec/spec.rb

@@ -1,8 +1,9 @@
 Execute.define_task do
   begin
-    require 'rspec/core/rake_task'
     desc "spec", "Run source adapter specs"
     def spec
+      require 'rspec/core/rake_task'
+
       files = File.join('spec','**','*_spec.rb')
       pattern = FileList[files]
       rspec_opts = "-fn -b --color"

data/commands/rhoconnect_war/war.rb

@@ -2,6 +2,7 @@ Execute.define_task do
   desc "war", "Build executable WAR file to be used in Java App Servers"
   def war
     if jruby? then
+      require 'rake'
       puts "building the WAR file"
       if not File::exists? "config/warble.rb"
         puts "generating Warbler's config file"

data/commands/utilities/redis_runner.rb

@@ -65,13 +65,13 @@ class RedisRunner
   def self.startbg(redis_array)
     if windows?
       puts "Starting redis in a new window..."
-      system "start #{File.join(redis_home,'redis-server')} #{File.join(redis_home,'redis.conf')}" rescue
+      system "start \"\" #{File.join(redis_home,'redis-server')} #{File.join(redis_home,'redis.conf')}" rescue
         "redis-server not installed on your path, please install redis."
     else
       puts "Starting redis ..."
       redis_array.each do |cfg|
         host, port = cfg.split(':')[0..1]
-        system("redis-server --port #{port} &") if RedisRunner.local_ip?(host)
+        system("redis-server --port #{port} > /dev/null 2>&1 &") if RedisRunner.local_ip?(host)
       end
     end
   end

data/doc/data-partitioning.txt

@@ -9,25 +9,38 @@ The MD is referenced in RhoConnect by a corresponding partition.  Source adapter
 
 Likewise, app partitioning stores one copy of the source adapter MD for the entire application (all users and devices share the same data).  App partitioning can be particularly useful if you have source adapter models which retrieve large amounts of data that is fixed from user to user, for example a global product catalog.  Using app partitioning wherever possible ***greatly reduces*** the amount of data in redis.
 
-### User Partition
-User partitioning is the default mode for source adapters, however you can explicitly define it in `settings/settings.yml` with:
+### App Partition
+Enable app partitioning the same way:
 
     :::yaml
     :sources:
       Product:
       :poll_interval: 300
-      :partition_type: user
+      :partition_type: app
 
-### App Partition
-Enable app partitioning the same way:
+Now you have a single copy of the `Product` source adapter dataset for all users.
+
+### User Partition
+User partitioning is the default mode for source adapters, however you can explicitly define it in `settings/settings.yml` with:
 
     :::yaml
     :sources:
       Product:
       :poll_interval: 300
-      :partition_type: app
+      :partition_type: user
 
-Now you have a single copy of the `Product` source adapter dataset for all users.
+### Custom User partitioning
+Sometimes, different groups of users share the common source data. To leverage this, you can implement the following method in your Source Adapter Model to provide custom partition names for the users with shared data. In this case, RhoConnect will store the data for MD of the grouped users under your custom name, which will reduce the memory footprint in Redis. From this standpoint, `app` partition is the edge-case of the custom user partitioning where all users share the same data for the particular source. 
+
+To use the custom user partitioning, implement the following class method in your Source Adapter's model:
+
+    :::ruby
+    class Product < Rhoconnect::Model::Base
+      # group users by the first letter
+      def self.partition_name(user_id)
+        return user_id[0]
+      end
+    end
 
 ## Pass Through
 RhoConnect provides a simple way to keep data out of redis.  If you have sensitive data that you do not want saved in redis, add the `pass_through` option in settings/settings.yml for each source:

data/doc/extending-rhoconnect-server.txt

@@ -1,23 +1,52 @@
 Extending RhoConnect Application with custom routes
 ===
 
+Adding custom routes to a Controller
+---
+
 You can provide custom routes support in your RhoConnect application and utilize all the powerful features of the typical Sinatra app. To do this, simply define your routes in the corresponding controller class. Endpoint URL for your routes will be relative to the controller's root.
 
-The following example illustrates how to add a sample `my_custom_route' to the Product Controller:
+The following example illustrates how to add a sample `my_custom_route` to the Product Controller:
 
     :::ruby
-    class Product < Rhoconnect::Controller::Base
+    class ProductController < Rhoconnect::Controller::Base
       get '/my_custom_route', :login_required => true do
         send_file 'public/my_file.png'
       end
     end
 
-This route will have the following URL : GET '/app/v4/Product/my_custom_route'
+This route will have the following URL : GET '/app/v1/Product/my_custom_route'
 
-The above custom route implementation will respond to client's GET request, verifies the current_user (which will be extracted from the RHoConnect session cookie and checked for validity by the `:login_required` condition)
+The above custom route implementation will respond to client's GET request, verifies the current_user (which will be extracted from the RhoConnect session cookie and checked for validity by the `:login_required` condition)
 and returns a static PNG file (which can be later used in BLOB syncs) 
 
-Using the New Custom route in BLOB syncs
+Routes declaration order
+---
+
+At run-time all requests are being matched against the declared routes to find the appropriate route handler. Sinatra matches the routes sequentially in the order of their declaration until the first matching route signature is found. This can lead to a possibility where the declared route can hide subsequent routes. For example:
+
+    :::ruby
+    class ProductController < Rhoconnect::Controller::Base
+      register Rhoconnect::Handler::Sync
+
+      delete '/my_custom_route_delete', :login_required => true do
+        # do something here
+      end
+    end
+
+In the above example, user's custom route will never be called, because `register Rhoconnect::Handler::Sync` (which is responsible for [adding pre-defined SYNC routes](/rhoconnectapi/source-adapter-controller-api-ruby#register Rhoconnect::Handler::Sync)) will add `DELETE '/:id'` route.
+As a result, ProductController will have the following routes map:
+
+    * 1) DELETE '/:id'
+    * 2) DELETE '/my_custom_route_delete'
+
+At run-time, Controller will try to match `DELETE /my_custom_route_delete` with the FIRST appropriate route declaration - and, it will find that `DELETE '/:id'` is a good match. Controller will treat string `my_custom_route_delete` as an instance of an `:id` parameter.  So, the user-defined custom route will never be called - it is being hidden by the more-generic route that has been declared first in order.
+
+In summary, you should always specify more-specific routes first followed by the more-generic routes. In the above example, moving the custom route's declaration above the line 'register Rhoconnect::Handler::Sync' will make the custom route match happening before the parametrized route. Alternatively, you can write your routes using "as unique as possible" signatures, i.e. in the above example, declaring the route as `DELETE '/my/custom_route/delete'` will not match any other route declaration.
+
+NOTE: You can always see the routes that are available in your application using the `rhoconnect routes` command.
+
+Using custom routes in BLOB syncs
 ---
 
 After you create the new custom routes you can reference and use them from standard Rhodes applications.
@@ -52,11 +81,11 @@ Then, modify your RhoConnect source adapter model (in `rhoconnect_app/models/rub
 
       @result={}
       parsed.each do |item|
-        item["product"]["my_custom_field-rhoblob"] = "http://localhost:9292/app/v4/Product/my_custom_route"
+        item["product"]["my_custom_field-rhoblob"] = "http://localhost:9292/app/v1/Product/my_custom_route"
         @result[item["product"]["id"].to_s] = item["product"]
       end if parsed    
     end
 
 This way, your `my_custom_field` would be getting the BLOB image data from the custom route defined in your RhoConnect Source Adapter Controller.
 
-For more information on BLOB syncs, see [this section](http://docs.rhomobile.com/rhoconnect/blob-sync). 
+For more information on BLOB syncs, see [this section](/rhoconnect/blob-sync). 

data/doc/push-client-setup-rps.txt

@@ -91,13 +91,13 @@ You can also configure more advanced settings in RhoConnect push by creating a c
 	{
 		"httpSecure": "n",
 		"devAuthHost": "localhost",
-		"devAuthUrl": "/rc/v1/app/ans_login",
+		"devAuthUrl": "/rc/v1/app/rps_login",
 		"devAuthPort": "9292",
 		"userAuthHost": "localhost",
-		"userAuthUrl": "/rc/v1/app/ans_login",
+		"userAuthUrl": "/rc/v1/app/rps_login",
 		"userAuthPort": "9292",
 		"appAuthHost": "localhost",
-		"appAuthUrl": "/rc/v1/app/ans_login",
+		"appAuthUrl": "/rc/v1/system/rps_login",
 		"appAuthPort": "9292",
 		"ansResponseTimeout": "300000",
 		"ansServerPort": "8675",

data/doc/source-adapters-js.txt

@@ -55,6 +55,8 @@ Its purpose is to define the RhoConnect application HTTP end point and to regist
 The generated source adapter's model file (in this case, `models/product.js`) is similar to the code listing below:
 
     :::javascript
+    var rc = require('rhoconnect_helpers');
+
     var Product = function(){
 
       this.login = function(resp){
@@ -98,10 +100,20 @@ The generated source adapter's model file (in this case, `models/product.js`) is
         // TODO: Logout from the data source if necessary.
         resp.send(true);
       };
+
+      this.storeBlob = function(resp){
+        // TODO: Handle post requests for blobs here.
+        // Reference the blob object's path with resp.params.path.
+        new rc.Exception(
+          resp, "Please provide some code to handle blobs if you are using them."
+        );
+      };
     };
 
     module.exports = new Product();
 
+In this model you will need to implement the functions necessary for the create, query, update and delete sync operations.  Optionally you may implement functions for login, logoff and storeBlob (if your application uses blobs).
+
 ## Source Adapter API
 
 ### Source Adapter Controller API
@@ -131,7 +143,7 @@ You can write the following methods for your source adapter model. These methods
 * [getData](/rhoconnectapi/source-adapter-model-api-js#getdataresp-callback) - Get the model document data from Store.
 * [currentUser](/rhoconnectapi/source-adapter-model-api-js#currentuser) - Returns the current user who called the adapter's model.
 * [storeBlob](/rhoconnectapi/source-adapter-model-api-js#storeblob) - Save the incoming blob data into permanent storage for the future processing.
-
+* [partitionName](/rhoconnectapi/source-adapter-model-api-js#partitionname) - Provide a custom user partition for a model.
 
 ### Request API
 The [request object](/rhoconnectapi/source-adapter-request-api-js) contains information about the HTTP request the app is receiving.
@@ -157,6 +169,17 @@ RhoConnect provides a simple [redis interface](/rhoconnectapi/source-adapter-sto
 * [getData](/rhoconnectapi/source-adapter-store-api-js#getdatarespcallback) - Retrieve an array or hash from redis.
 * [putData](/rhoconnectapi/source-adapter-store-api-js#putdatarespcallback) - Add an array or hash to redis.
 
+## Exception API
+Use the following exception types in your JavaScript application to handle any error conditions.  Don't worry, if your application throws an uncaught exception, the base `RhoConnect::Model::Exception` will automatically be used.
+
+* [Exception](/rhoconnectapi/source-adapter-exception-api-js#exceptionresponse-message) - Raise a `RhoConnect::Model::Exception`.
+* [LoginException](/rhoconnectapi/source-adapter-exception-api-js#loginexceptionresponse-message) - Raise a `RhoConnect::Model::LoginException`.
+* [LogoffException](/rhoconnectapi/source-adapter-exception-api-js#logoffexceptionresponse-message) - Raise a `RhoConnect::Model::LogoffException`.
+* [ServerTimeoutException](/rhoconnectapi/source-adapter-exception-api-js#servertimeoutexceptionresponse-message) - Raise a `RhoConnect::Model::ServerTimeoutException`.
+* [ServerErrorException](/rhoconnectapi/source-adapter-exception-api-js#servererrorexceptionresponse-message) - Raise a `RhoConnect::Model::ServerErrorException`.
+* [ObjectConflictErrorException](/rhoconnectapi/source-adapter-exception-api-js#objectconflicterrorexceptionresponse-message) - Raise a `RhoConnect::Model::ObjectConflictErrorException`.
+
+
 ## Sample Model
 Here's a complete example of how the completed [product model might look](https://gist.github.com/larsburgess/87753882f3a4a366b48b):
 
@@ -196,7 +219,10 @@ Here's a complete example of how the completed [product model might look](https:
           host: host,
           path: '/products.json',
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' }
+          headers: { 
+            'Content-Type': 'application/json', 
+            'Content-Length': postData.length
+          }
         };
         var req = http.request(options, function(res){
           res.on('data', function(chunk){
@@ -220,7 +246,10 @@ Here's a complete example of how the completed [product model might look](https:
           host: host,
           path: '/products/' + objId + '.json',
           method: 'PUT',
-          headers: { 'Content-Type': 'application/json' }
+          headers: { 
+            'Content-Type': 'application/json',
+            'Content-Length': putData.length
+          }
         };
         var req = http.request(options, function(res){
           res.on('data', function(){});
@@ -258,6 +287,14 @@ Here's a complete example of how the completed [product model might look](https:
       this.logoff = function(resp){
         resp.send(true);
       };
+
+      this.storeBlob = function(resp){
+        // TODO: Handle post requests for blobs here.
+        // Reference the blob object's path with resp.params.path.
+        new rc.Exception(
+          resp, "Please provide some code to handle blobs if you are using them."
+        );
+      };
     };
 
-    module.exports = new Product();
+    module.exports = new Product();

data/doc/source-adapters.txt

@@ -130,6 +130,8 @@ During generation of the model, the `settings/settings.yml` file will be updated
 
 You can use the following methods and techniques inside of your source adapter controller.
 
+* [register Rhoconnect::EndPoint](/rhoconnectapi/source-adapter-controller-api-ruby#register Rhoconnect::EndPoint) - adds Controller into the application's URL Map.
+* [resgiter Rhoconnect::Handler::Sync](/rhoconnectapi/source-adapter-controller-api-ruby#register Rhoconnect::Handler::Sync) - adds SYNC routes to your Controller.
 * [@model](/rhoconnectapi/source-adapter-controller-api-ruby#@model) - Access to the source adapter's model instance.
 * [params,request,response](/rhoconnectapi/source-adapter-controller-api-ruby#sinatra-context) - Allows to use any standard Sinatra context objects.
 * [Sinatra framework](/rhoconnectapi/source-adapter-controller-api-ruby#sinatra-features) - Allows to use any standard Sinatra features.
@@ -148,6 +150,7 @@ You can write the following methods for your source adapter model. These methods
 * [current_user](/rhoconnectapi/source-adapter-model-api-ruby#currentuser) - Returns the current user which called the adapter's model.
 * [stash_result](/rhoconnectapi/source-adapter-model-api-ruby#stashresult) - Saves the current state of `@result` to redis and assigns it to `nil`.
 * [store_blob](/rhoconnectapi/source-adapter-model-api-ruby#store_blob) - Save the incoming blob data into permanent storage for the future processing.
+* [self.partition_name](/rhoconnectapi/source-adapter-model-api-ruby#self.partition_name) - Implement this class method to provide custom user partition.
 * [get_data](/rhoconnectapi/source-adapter-model-api-ruby#get_data) - Get the model document data from Store.
 
 ## Data Partitioning