rhoconnect 3.3.6 → 3.4.2

data/doc/rest-api.txt

@@ -97,24 +97,28 @@ Saves the url of the plugin's backend to the RhoConnect server.
 Retrieves stats for a given metric key:
 
 	:::ruby
-	RestClient.post(
+	RestClient.get(
 	  "#{server}/rc/v1/system/stats", 
-	  {
-		'X-RhoConnect-API-TOKEN' => @api_token, 
+	  { 
 		:params => {:metric => 'foo', 
 					:start => 0, 
 					:finish => -1} 
+	  },
+	  {
+		'X-RhoConnect-API-TOKEN' => @api_token
 	  }
 	)
 
 Retrieves a list of metric keys matching a given pattern.  This supports 'glob' or '*' style pattern matching.  For example, all metric keys associated with 'Product' source adapter methods:
 
 	:::ruby
-	RestClient.post(
+	RestClient.get(
 	  "#{server}/rc/v1/system/stats", 
 	  { 
-		'X-RhoConnect-API-TOKEN' => @api_token,
 		:params => {:names => 'sources:*:Product'}
+	  },
+	  {
+		'X-RhoConnect-API-TOKEN' => @api_token
 	  }
 	)
 	
@@ -490,7 +494,7 @@ Use this method only when you can ensure the integrity of the data.
 	)
 	
 #### `POST /app/v1/:source_name/fast_update`
-Push object updates to RhoConnect. This method doesn't involve pulling the existing data out of Redis. Instead it required user to provide the previous state of the data. This way, this method allows for very fast updates (since it just removes the previous data from set and adds new ones). However, no data integrity checks are performed. Therefore, this method must be used only if user can ensure the integrity of the data (i.e. previous state must exist, otherwise it won't be properly deleted). Also, this method can be used to perform fast appends and deletes for any of the object's attributes (However, you shoudn't use this method to remove all of the attributes, `fast_delete` should be used instead.)
+Push object updates to RhoConnect. This method doesn't involve pulling the existing data out of Redis. Instead it required user to provide the previous state of the data. This way, this method allows for very fast updates (since it just removes the previous data from set and adds new ones). However, no data integrity checks are performed. Therefore, this method must be used only if user can ensure the integrity of the data (i.e. previous state must exist, otherwise it won't be properly deleted). Also, this method can be used to perform fast appends and deletes for any of the object's attributes (However, you shouldn't use this method to remove all of the attributes, `fast_delete` should be used instead.)
 
 **NOTE: you may use [ping](/rhoconnect/push) to notify client after the update and trigger sync.**
 

data/doc/rhoconnect-calculator.txt

@@ -0,0 +1,237 @@
+<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>
+
+<script type='text/javascript'>
+$(function(){
+	var fileRef = document.createElement('script');
+	fileRef.setAttribute("type","text/javascript");
+	fileRef.setAttribute("src", "https://s3.amazonaws.com/rhoconnect-calc/raw_data.js");
+	document.body.appendChild(fileRef);
+});
+
+var totalAttrRange = new Array(5000,25000,50000,125000,250000,500000);
+var totalSyncsRange = new Array(1000,10000,100000,500000,1000000,10000000);
+var coefficient = 1.2;
+
+$('#calc-submit').live('click',function(e){
+	e.preventDefault();
+	var numObj   = $("#num_obj").val();
+	var numAttr  = $("#num_attr").val();
+	var numDvces = $("#num_devices").val();
+	var avgResp  = $("#avg_resp").val();
+	var syncFreq = $("#sync_freq").val();
+	var numObj   = $("#num_obj").val();
+	var numUp    = $("#num_up").val();
+	var res;
+	var cores;
+	var ram;
+	var key;
+	
+	var total_attr  = numObj * numAttr;
+	var total_syncs = numDvces * syncFreq;
+	
+	key = get_boundary('totalAttrRange',total_attr) + ":" + get_boundary('totalSyncsRange',total_syncs) + ':0:0';
+	res = raw_data[key];
+	ram = (total_attr/10000) * numDvces * 1.2* 0.001;
+	ram = Math.round(ram * 100)/100;
+	ram += " GB"; 
+	if(res == undefined){
+		cores = "data not available";
+		result   = ram + ",data not available";
+	}
+	else{
+		cores  = res;
+		result = ram + ", " + cores; 
+	}
+	
+	$("td#cores")[0].innerHTML = cores;
+	$("td#ram")[0].innerHTML   = ram;
+	$("#output").css("display","block");
+	$("#table-res").effect("highlight", {}, 1000);
+	$("input#entry_0").val(numObj);
+	$("input#entry_2").val(numAttr);
+	$("input#entry_3").val(numDvces);
+	$("input#entry_4").val(syncFreq);
+	$("input#entry_5").val(key);
+	$("input#entry_6").val(result);
+	$("input#entry_8").val(navigator.userAgent);
+	$.getJSON("http://h3manth.com/ip.php?callback=?",
+	    function(data){
+	       	$("input#entry_7").val(data.ip);
+			$('#submitme')[0].click();
+	 });
+	$.ajax({
+	  url: "http://h3manth.com/ip.php?callback=?",
+	  dataType: 'json',
+	  success: function(data){
+		$("input#entry_7").val(data.ip);
+		$('#submitme')[0].click();
+	  },
+	  error: function(){
+		$("input#entry_7").val("error getting ip");
+		$('#submitme')[0].click();
+	  }
+	});
+});
+function get_boundary(name,value){
+	var result = undefined;
+	value = parseInt(value);
+	arr   = eval(name);
+	
+    for(var i=0;i < arr.length;i++){
+		if(value < arr[i] * coefficient){
+			result = arr[i];
+			break;
+		}
+	}
+	
+	return result;
+}
+</script>
+RhoConnect Calculator
+==========
+The RhoConnect Calculator helps you estimate the number of processor cores and redis server RAM required to deploy a RhoConnect Production environment.
+
+1 core equals 1 processor (at 2 GHz) running two thin processes.
+
+<div id='output' class='pull-right' style='padding:25px 25px 0 0;display:none'>
+	Result:
+	<table id='table-res' class='table table=bordered'>
+	<tr>
+		<td>Number of Cores:</td><td id='cores'></td><td></td>
+	</tr>
+	<tr>
+		<td>Redis RAM:</td><td id='ram'></td><td id='ram_units'></td>
+	</tr>
+	</table>
+</div>
+<form id='calc-form' class='well form'>
+<label>Number of Objects</label>
+<input id='num_obj' type='number' class='input-xlarge' />
+<label>Number of Attributes per Object</label>
+<input id='num_attr' type='number' class='input-xlarge' />
+<label>Number of Devices</label>
+<input id='num_devices' type='number' class='input-xlarge' />
+<label>Sync Frequency</label>
+<div class='input-append'>
+<input id='sync_freq' id='appendInput' type='number' class='span2' size='16'/>
+<span class='add-on' style='margin-top:2px'>syncs per day</span>
+</div>
+<div style='display:none'>
+<label>Your Average Web Service Response Time</label>
+<input id='avg_resp' type='number' class='input-xlarge' value='0' disabled="disabled"/>
+<label>Number of Updates per Day</label>
+<input id='num_up' type='number' class='input-xlarge' disabled="disabled" value='0' /><br/>
+</div>
+<button id='calc-submit' type'submit' class='btn btn-primary'>Submit</button>
+</form>
+
+**NOTE: High Availability (HA) is not included into these numbers.  So if your environment must provide HA, you will need to include enough extra storage and processor capacity in case of hardware failure.**
+
+### Calculator Fields
+<ul>
+<li><b>Number of Objects</b> - The number of objects across all of your models.  If you have 10 models with 10 objects for each model, you would enter 100.</li>
+<li><b>Number of Attributes per Object</b> - The average number of attributes per object. E.g. if you have 2 objects, 1 with 10 attributes and 1 with 12 attributes, you would enter 11.</li>
+<li><b>Number of devices</b> - The total number of devices that will be using RhoConnect.</li>
+<li><b>Sync Frequency</b> - The average sync frequency per device. E.g if you have 2 devices where one syncs 10 times per day and one sync 12 times per day, you would enter 11.</li>
+</ul>
+
+### Result
+<ul>
+<li><b>Number of Cores</b> - The number of processor cores required (could be distributed across N number of servers).</li>
+<li><b>Redis RAM</b> – RAM required for the master Redis instance.  Currently only one master Redis instance can be defined.  A typical deployment involves one master Redis instance (with no disk persistence) and N number of read-slaves (with persistence).  Slave disk persistence would need at least 2X disk capacity where X is the master instance RAM requirement.</li>
+</ul>
+
+
+
+<script type="text/javascript">var submitted=false;</script>
+<iframe name="hidden_iframe" id="hidden_iframe" style="display:none;" onload="if(submitted){}"></iframe>
+<div style='display:none'>
+  <form id='gform' action="https://docs.google.com/a/rhomobile.com/spreadsheet/formResponse?formkey=dDBJeUVBQnNnTW1tWGZOSWNRbG84OFE6MQ&amp;ifq" method="post" target="hidden_iframe" onsubmit="submitted=true;" style='display:block'>
+  <br>
+  <div class="errorbox-good">
+    <div class="ss-item  ss-text">
+ 	  <div class="ss-form-entry">
+	    <label class="ss-q-title" for="entry_0">Number of Objects</label>
+  		<label class="ss-q-help" for="entry_0"></label>
+  		<input type="text" name="entry.0.single" value="" class="ss-q-short" id="entry_0">
+ 	  </div>
+     </div>
+  </div>
+  <br>
+  <div class="errorbox-good">
+    <div class="ss-item  ss-text">
+      <div class="ss-form-entry">
+        <label class="ss-q-title" for="entry_2">Number of Attributes</label>
+  	    <label class="ss-q-help" for="entry_2"></label>
+        <input type="text" name="entry.2.single" value="" class="ss-q-short" id="entry_2">
+      </div>
+    </div>
+  </div>
+  <br>
+  <div class="errorbox-good">
+    <div class="ss-item  ss-text">
+      <div class="ss-form-entry">
+        <label class="ss-q-title" for="entry_3">Number of Devices</label>
+  	    <label class="ss-q-help" for="entry_3"></label>
+        <input type="text" name="entry.3.single" value="" class="ss-q-short" id="entry_3">
+      </div>
+    </div>
+  </div>
+  <br>
+  <div class="errorbox-good">
+    <div class="ss-item  ss-text">
+      <div class="ss-form-entry">
+        <label class="ss-q-title" for="entry_4">Sync Freq</label>
+  	    <label class="ss-q-help" for="entry_4"></label>
+        <input type="text" name="entry.4.single" value="" class="ss-q-short" id="entry_4">
+      </div>
+    </div>
+  </div>
+  <br>
+  <div class="errorbox-good">
+    <div class="ss-item  ss-text">
+      <div class="ss-form-entry">
+        <label class="ss-q-title" for="entry_5">key</label>
+  	    <label class="ss-q-help" for="entry_5"></label>
+        <input type="text" name="entry.5.single" value="" class="ss-q-short" id="entry_5">
+      </div>
+    </div>
+  </div>
+  <br>
+  <div class="errorbox-good">
+    <div class="ss-item  ss-text">
+      <div class="ss-form-entry">
+        <label class="ss-q-title" for="entry_6">value</label>
+  	    <label class="ss-q-help" for="entry_6"></label>
+        <input type="text" name="entry.6.single" value="" class="ss-q-short" id="entry_6">
+      </div>
+    </div>
+  </div>
+  <br>
+  <div class="errorbox-good">
+    <div class="ss-item  ss-text">
+      <div class="ss-form-entry">
+        <label class="ss-q-title" for="entry_7">ip</label>
+  	    <label class="ss-q-help" for="entry_7"></label>
+        <input type="text" name="entry.7.single" value="" class="ss-q-short" id="entry_7">
+      </div>
+    </div>
+  </div>
+  <div class="errorbox-good">
+    <div class="ss-item  ss-text">
+      <div class="ss-form-entry">
+        <label class="ss-q-title" for="entry_8">User Agent</label>
+  	    <label class="ss-q-help" for="entry_8"></label>
+        <input type="text" name="entry.8.single" value="" class="ss-q-short" id="entry_8">
+      </div>
+    </div>
+  </div>
+  <input type="hidden" name="pageNumber" value="0">
+  <input type="hidden" name="backupCache" value="">
+  <div class="ss-item ss-navigate">
+	<div class="ss-form-entry">
+		<input type="submit" name="submit" value="Submit" id='submitme'>
+	</div>
+  </div>
+</form>
+</div>

data/doc/rhoconnect-redis-stack.txt

@@ -254,6 +254,41 @@ You are charged for the stack that you have created, by the hour. When you no lo
 
 <img src="http://rhodocs.s3.amazonaws.com/rhoconnect-redis-aws/delete-stack.png" alt="Delete Stack" />
 
+## High Availability/Failover for Redis server
+
+The described architecture has a weak spot: a single point of failure (SPOF). If the Redis server is down or stops responding, then the entire Rhoconnect stack stops functioning. To address this issue, we need to implement failover — the continuation of a service after the failure of one or more of its components. Redis provides a very simple solution to 
+configure master-slave replication that allows slave Redis servers to be exact copies of master servers. 
+So if the master server goes down, we can issue a `SLAVEOF NO ONE` command to the slave and then switch RhoConnect apps to use the slave that is now the master. 
+
+The following is a one possible scenario of how it might be done on the Amazon cloud.
+
+Redis High Availability proposal:
+
+* RhoConnect applications do not send queries directly to the Redis server, but communicate with the Redis Elastic Load Balancer (RELB).
+* RELB has 2 monitor servers, both running Haproxy and Monit services. RELB responsibility is to do a health check of monitor servers and to distribute incoming traffic to TCP proxy service.
+* Each monitor machine has a TCP proxy which relays its traffic to the master redis server.
+* Monit service role is to detect failure of redis servers and start recovery process.
+* Monit checks redises on a regular basis. It runs a failover script `/home/ubuntu/failover` if there is an failure to get a valid response upon performing a PING command three times in a row.
+* Failover script does automatic slave -> master promotion in the case of master failure, and reconfigures Haproxy service to relay traffic to the new master redis. It spins up a new Redis EC2 instance and sets it as slave on the new master.
+* The failover script uses AWS `simpleBD` service to store current redis servers configuration (master/slave/backup). So,
+if another instance of monitor server detects failure and calls the failover script, it will know the current status of the redis servers
+and will wait until the recovery process that was initiated by another Monit service is over. Finally, the failover script reconfigures and restarts the Monit service to track a new pair of master/slave redis servers.
+* 1 Redis master
+* 1 Redis slave
+
+The URL for the CloudFormation template that implements the described proposal is available here 
+[https://s3-us-west-1.amazonaws.com/rhoconnect-ca-deploy/rhoconnect-ha.txt](https://s3-us-west-1.amazonaws.com/rhoconnect-ca-deploy/rhoconnect-ha.txt)
+and can be used for evaluation purposes. 
+
+The template will create a sample scalable rhoconnect stack with 2 elastic load balancers and 5 EC2 instances.
+
+* RhoConnect Load Balancer
+* 1 EC2 instance of RhoConnect application  
+* Redis Load Balancer
+* 2 EC2 instances of monitor servers (Haproxy/Monit) 
+* 2 EC2 instances of redis servers (master/slave)
+
+
 
 
 

data/doc/session-and-configuration.txt

@@ -0,0 +1,24 @@
+Session and configuration
+===
+
+RhoConnect persists user session in a cookie which is handled by client executable. But some client may have an issue accessing a session cookie value due to platform security features involved.
+
+At this moment well-known clients with such restrictions are Rhoconnect.js, Rhodes and ObjectiveC client on WinPhone7 platform.
+
+To overcome cookie issue the *XDomainSessionWrapper* Rack middleware has been implemented and included to the RhoConnect distribution.
+You can find it inside RhoConnect gem in *lib/rhoconnect/middleware/x_domain_session_wrapper.rb* file.
+
+## How to use
+
+To use this workaround just put these lines in config.ru file right before *Rhoconnect::Server* settings:
+
+    :::ruby
+    require 'rhoconnect/x_domain_session_wrapper'
+    use XDomainSessionWrapper, \
+        :session_cookie => 'rhoconnect_session', \
+        :api_uri_regexp => /\A\/(api\/)?application/, \
+        :login_uri_regexp => /\A\/(api\/)?application\/clientlogin/
+
+It just a sample, use real base URL values there. By default it configured just for URLs based on */api/application* pattern, not */application*.
+
+**NOTE: Without mentioned configuration you may have login errors for Rhoconnect.js client and Rhodes application on WinPhone7 platform if your application points RhoConnect server as 'http://some-address.com/application'.

data/doc/settings.txt

@@ -10,39 +10,45 @@ Application-wide settings are specified per deployment environment (`:test`, `:d
 Each of the environment categories must have the following entries:
 	
 	:::yaml
-	:syncserver: <url> - application's base url
-	:redis: <url> - Redis url
-	:licensefile: <filename> - application's license file
-	
-In addition, the following settings can be specified:
+	:syncserver: <url>
+	:redis: <url>
+	:licensefile: <filename>
+
+`:syncserver`: application's base url.
+
+`:redis`: Redis url.
+
+`:licensefile`: application's license file.
+
+In addition, you can specify the following settings:
 
 	:::yaml
-	:poll_interval_default: <secs> - default sync poll interval setting for source adapters.
-									 This setting is used as a default if source doesn't specify
-									 its own value. Also, it is applied to dynamic adapters
-									 as a default sync poll interval.
-	:bulk_sync_poll_interval: <secs> - poll interval setting for bulk data sync
-	
+	:connection_pool_size: <number_of_redis_connections>
+	:connection_pool_timeout: <secs>
+	:redis_timeout: <secs>
+	:poll_interval_default: <secs>
+	:bulk_sync_poll_interval: <secs>
 	:c2dm_username: <google's email>
 	:c2dm_passwd: <passwd>                       
-	:authtoken: <authtoken>          - these settings are used specifically for Android push notifications.
-									   In order to push messages to the Android device, your server needs to 
-									   obtain Google's C2DM authentication token associated with the trusted google account.
-									   For this purpose, you can specify C2DM Google account's username/password combo 
-									   via the `:c2dm_username` and `:c2dm_passwd` settings.
-									   At run-time, the system will use these credentials to obtain 
-									   the C2DM token and store it in the Redis for the future use.
-									   Once the token is expired, the system will automatically 
-									   connect to the Google C2DM service to renew the token.
-
-									   Alternatively, you can use `:authtoken` setting to specify 
-									   the pre-defined authentication token. This token MUST be related to the role-based google account 
-									   registered for your application. See [the rhodes push instructions](/rhodes/device-caps#push-notifications) 
-									   for more details. To retrieve this token, use sample script [c2dm.rb](http://github.com/rhomobile/rhodes/blob/master/bin/c2dm.rb). 
-									   Uncomment last two lines and put your google account specific data, then run it. 
-									   It will print token to stdout.
-									   This approach, however, will not allow the server to connect 
-									   to the C2DM service and renew the token once it is expired.
+	:authtoken: <authtoken>
+
+`:connection_pool_size`: By default, RhoConnect maintains multiple concurrent connections to Redis organized in Connection Pool. This setting allows you to specify the size of the pool. By default, RhoConnect starts with five (5) Redis connections.
+
+`:connection_pool_timeout`: The timeout value for the Redis Connection Pool, in seconds. Specifies how much time a request will wait for an available Redis connection. Default is 30 seconds.
+
+`:redis_timeout:` - timeout setting for Redis commands. Default is 30 seconds.
+
+`:poll_interval_default`: default sync poll interval setting for source adapters, in seconds. This setting is used as a default if source doesn't specify its own value. Also, it is applied to dynamic adapters as a default sync poll interval.
+
+`:bulk_sync_poll_interval`: poll interval setting for bulk data sync, in seconds.
+
+`:c2dm_username`: The email address for the C2DM Google account.
+
+`:c2dm_passwd`: The password for the C2DM Google account.
+
+`:authtoken`: these settings are used specifically for Android push notifications. In order to push messages to the Android device, your server needs to obtain Google's C2DM authentication token associated with the trusted google account. For this purpose, you can specify C2DM Google account's username/password combo via the `:c2dm_username` and `:c2dm_passwd` settings. At run-time, the system will use these credentials to obtain the C2DM token and store it in the Redis for the future use. Once the token is expired, the system will automatically connect to the Google C2DM service to renew the token.
+
+Alternatively, you can use the `:authtoken` setting to specify the pre-defined authentication token. This token MUST be related to the role-based google account registered for your application. See [the rhodes push instructions](/rhodes/device-caps#push-notifications) for more details. To retrieve this token, use sample script [c2dm.rb](http://github.com/rhomobile/rhodes/blob/master/bin/c2dm.rb). Uncomment last two lines and put your google account specific data, then run it. It will print token to stdout. This approach, however, will not allow the server to connect to the C2DM service and renew the token once it is expired.
 
 ## Source settings
 
@@ -50,15 +56,19 @@ All source-specific settings are specified under the corresponding source name e
 Typical source settings include:
 
 	:::yaml
-	:poll_interval: <secs> - source's sync poll interval.
-	:force_default: <true|false> - if specified, this setting forces to use 
-								   default application poll interval
-								   even if source has its own setting.
-    :partition_type: <app|user> - default partition type for the source
-    :priority: <num> - these settings are used to determine the order the models 
-                       are processed and synchronized. They might be useful when 
-                       there are a set of linked together sources and client need
-                       to know in which order to process them. 
-                       Priority starts from lower value 1. If priorities are not
-                       specified, then there are no guarantee that models will be 
-                       listed and processed in natural order.  
+	:poll_interval: <secs>
+	:force_default: <true|false>
+    :partition_type: <app|user>
+    :priority: <num>  
+
+`:poll_interval`: source's sync poll interval in seconds.
+
+`:force_default`: true or false. If specified, this setting forces use of the default application poll interval even if source has its own setting.
+
+`:partition_type`: app or user. default partition type for the source.
+
+`:priority:` A priority number used to determine the order in which the models are processed and synchronized. This is useful when there are a set of linked together sources and the client needs to know in which order to process them.  Priority starts from lower value 1. If priorities are not specified, then there is no guarantee that models will be listed and processed in natural order.  
+
+
+
+