Merge pull request #79 in ZP/z-push from feature/ZP-739-heartbeat-lifetime-interval to develop

* commit '49b90a93':
  ZP-739 Use sprintf() in log message.
  ZP-739 The guideline of the project state that the private function must start by a lowercase. Released under the Affero GNU General Public License (AGPL) version 3.
  ZP-739 Enforce the maximum value for PING_HIGHER_BOUND_LIFETIME and PING_LOWER_BOUND_LIFETIME to 3540. Released under the Affero GNU General Public License (AGPL) version 3.
  ZP-739 Implemtent ping higher and lower bound. Released under the Affero GNU General Public License (AGPL) version 3.

src/config.php

@@ -69,6 +69,7 @@
      * true - use the complete email address.
      */
     define('USE_FULLEMAIL_FOR_LOGIN', false);
+
 /**********************************************************************************
  *  Default FileStateMachine settings
  */
@@ -218,6 +219,19 @@
     // NOTE: THIS IS AN EXPERIMENTAL FEATURE WHICH COULD PREVENT YOUR MOBILES FROM SYNCHRONIZING.
     define('USE_PARTIAL_FOLDERSYNC', false);
 
+    // The minimum accepted time in second that a ping command should last.
+    // It is strongly advised to keep this config to false. Some device
+    // might not be able to send a higher value than the one specificied here and thus
+    // unable to start a push connection.
+    // If set to false, there will be no lower bound to the ping lifetime.
+    // The minimum accepted value is 1 second. The maximum accepted value is 3540 seconds (59 minutes).
+    define('PING_LOWER_BOUND_LIFETIME', false);
+
+    // The maximum accepted time in second that a ping command should last.
+    // If set to false, there will be no higher bound to the ping lifetime.
+    // The minimum accepted value is 1 second. The maximum accepted value is 3540 seconds (59 minutes).
+    define('PING_HIGHER_BOUND_LIFETIME', false);
+
 /**********************************************************************************
  *  Backend settings
  */

src/lib/core/zpush.php

@@ -283,6 +283,22 @@ class ZPush {
             define('USE_PARTIAL_FOLDERSYNC', false);
         }
 
+        if (!defined('PING_LOWER_BOUND_LIFETIME')) {
+            define('PING_LOWER_BOUND_LIFETIME', false);
+        }
+        elseif(PING_LOWER_BOUND_LIFETIME !== false && (!is_int(PING_LOWER_BOUND_LIFETIME) || PING_LOWER_BOUND_LIFETIME < 1 || PING_LOWER_BOUND_LIFETIME > 3540)){
+            throw new FatalMisconfigurationException("The PING_LOWER_BOUND_LIFETIME value must be 'false' or a number between 1 and 3540 inclusively.");
+        }
+        if (!defined('PING_HIGHER_BOUND_LIFETIME')) {
+            define('PING_HIGHER_BOUND_LIFETIME', false);
+        }
+        elseif(PING_HIGHER_BOUND_LIFETIME !== false && (!is_int(PING_HIGHER_BOUND_LIFETIME) || PING_HIGHER_BOUND_LIFETIME < 1 || PING_HIGHER_BOUND_LIFETIME > 3540)){
+            throw new FatalMisconfigurationException("The PING_HIGHER_BOUND_LIFETIME value must be 'false' or a number between 1 and 3540 inclusively.");
+        }
+        if(PING_HIGHER_BOUND_LIFETIME !== false && PING_LOWER_BOUND_LIFETIME !== false && PING_HIGHER_BOUND_LIFETIME < PING_LOWER_BOUND_LIFETIME){
+            throw new FatalMisconfigurationException("The PING_HIGHER_BOUND_LIFETIME value must be greater or equal to PING_LOWER_BOUND_LIFETIME.");
+        }
+
         // the check on additional folders will not throw hard errors, as this is probably changed on live systems
         if (isset($additionalFolders) && !is_array($additionalFolders))
             ZLog::Write(LOGLEVEL_ERROR, "ZPush::CheckConfig() : The additional folders synchronization not available as array.");

src/lib/request/ping.php

@@ -154,6 +154,10 @@ class Ping extends RequestProcessor {
             if(!self::$decoder->getElementEndTag())
                 return false;
 
+            if(!$this->lifetimeBetweenBound($sc->GetLifetime())){
+                $pingstatus = SYNC_PINGSTATUS_HBOUTOFRANGE;
+                ZLog::Write(LOGLEVEL_DEBUG, sprintf("HandlePing(): ping lifetime not between bound (higher bound:'%d' lower bound:'%d' current lifetime:'%d'. Returning SYNC_PINGSTATUS_HBOUTOFRANGE.", PING_HIGHER_BOUND_LIFETIME, PING_LOWER_BOUND_LIFETIME, $sc->GetLifetime()));
+            }
             // save changed data
             foreach ($sc as $folderid => $spa)
                 $sc->SaveCollection($spa);
@@ -165,8 +169,13 @@ class Ping extends RequestProcessor {
                 $pingstatus = SYNC_PINGSTATUS_FAILINGPARAMS;
                 ZLog::Write(LOGLEVEL_DEBUG, "HandlePing(): no pingable folders found and no initialization data sent. Returning SYNC_PINGSTATUS_FAILINGPARAMS.");
             }
+            elseif(!$this->lifetimeBetweenBound($sc->GetLifetime())){
+                $pingstatus = SYNC_PINGSTATUS_FAILINGPARAMS;
+                ZLog::Write(LOGLEVEL_DEBUG, sprintf("HandlePing(): ping lifetime not between bound (higher bound:'%d' lower bound:'%d' current lifetime:'%d'. Returning SYNC_PINGSTATUS_FAILINGPARAMS.", PING_HIGHER_BOUND_LIFETIME, PING_LOWER_BOUND_LIFETIME, $sc->GetLifetime()));
+            }
         }
 
+
         // Check for changes on the default LifeTime, set interval and ONLY on pingable collections
         try {
             if (!$pingstatus && empty($fakechanges)) {
@@ -220,9 +229,41 @@ class Ping extends RequestProcessor {
                 }
                 self::$encoder->endTag();
             }
+            elseif($pingstatus == SYNC_PINGSTATUS_HBOUTOFRANGE){
+                self::$encoder->startTag(SYNC_PING_LIFETIME);
+                if($sc->GetLifetime() > PING_HIGHER_BOUND_LIFETIME){
+                    self::$encoder->content(PING_HIGHER_BOUND_LIFETIME);
+                }
+                else{
+                    self::$encoder->content(PING_LOWER_BOUND_LIFETIME);
+                }
+                self::$encoder->endTag();
+            }
         }
+
         self::$encoder->endTag();
 
         return true;
     }
+
+    /**
+     * Return true if the ping lifetime is between the specified bound (PING_HIGHER_BOUND_LIFETIME and PING_LOWER_BOUND_LIFETIME). If no bound are specified, it returns true.
+     *
+     * @param int       $lifetime
+     *
+     * @access private
+     * @return boolean
+     */
+    private function lifetimeBetweenBound($lifetime){
+        if(PING_HIGHER_BOUND_LIFETIME !== false && PING_LOWER_BOUND_LIFETIME !== false){
+            return ($lifetime <= PING_HIGHER_BOUND_LIFETIME && $lifetime >= PING_LOWER_BOUND_LIFETIME);
+        }
+        if(PING_HIGHER_BOUND_LIFETIME !== false){
+            return $lifetime <= PING_HIGHER_BOUND_LIFETIME;
+        }
+        if(PING_LOWER_BOUND_LIFETIME !== false){
+            return $lifetime >= PING_LOWER_BOUND_LIFETIME;
+        }
+        return true;
+    }
 }