Merge pull request #415 in ZP/z-push from...

Merge pull request #415 in ZP/z-push from feature/ZP-1093-add-service-unavailable-exception to develop

* commit '749311a1':
  ZP-1095 Use ServiceUnavailableException when Kopano is unavailable.
  ZP-1093 Added ServiceUnavailableException to class loader, updated config description, don't show legal information if service is unavailable, check if config value is greater than zero, throw ServiceUnavailableException if states need to be upgraded.
  ZP-1093 Add service unavailable exception. Released under the Affero GNU General Public License (AGPL) version 3.

src/backend/kopano/kopano.php

@@ -176,7 +176,7 @@ class BackendKopano implements IBackend, ISearchProvider {
             if (mapi_last_hresult()) {
                 ZLog::Write(LOGLEVEL_ERROR, sprintf("KopanoBackend->Logon(): login failed with error code: 0x%X", mapi_last_hresult()));
                 if (mapi_last_hresult() == MAPI_E_NETWORK_ERROR)
-                    throw new HTTPReturnCodeException("Error connecting to KC (login)", 503, null, LOGLEVEL_INFO);
+                    throw new ServiceUnavailableException("Error connecting to KC (login)");
             }
         }
         catch (MAPIException $ex) {
@@ -193,7 +193,7 @@ class BackendKopano implements IBackend, ISearchProvider {
         $this->defaultstore = $this->openMessageStore($this->mainUser);
 
         if (mapi_last_hresult() == MAPI_E_FAILONEPROVIDER)
-            throw new HTTPReturnCodeException("Error connecting to KC (open store)", 503, null, LOGLEVEL_INFO);
+            throw new ServiceUnavailableException("Error connecting to KC (open store)");
 
         if($this->defaultstore === false)
             throw new AuthenticationRequiredException(sprintf("KopanoBackend->Logon(): User '%s' has no default store", $user));

src/config.php

@@ -272,6 +272,14 @@
     define('SYNC_TIMEOUT_MEDIUM_DEVICETYPES', "SAMSUNGGTI");
     define('SYNC_TIMEOUT_LONG_DEVICETYPES',   "iPod, iPad, iPhone, WP, WindowsOutlook");
 
+    // Time in seconds the device should wait whenever the service is unavailable,
+    // e.g. when a backend service is unavailable.
+    // Z-Push sends a "Retry-After" header in the response with the here defined value.
+    // It is up to the device to respect or not this directive so even if this option is set,
+    // the device might not wait requested time frame.
+    // Number of seconds before retry, to disable set to: false
+    define('RETRY_AFTER_DELAY', 300);
+
 /**********************************************************************************
  *  Backend settings
  */

src/lib/core/zpush.php

@@ -344,6 +344,13 @@ class ZPush {
             throw new FatalMisconfigurationException("The PING_HIGHER_BOUND_LIFETIME value must be greater or equal to PING_LOWER_BOUND_LIFETIME.");
         }
 
+        if (!defined('RETRY_AFTER_DELAY')) {
+            define('RETRY_AFTER_DELAY', 300);
+        }
+        elseif (RETRY_AFTER_DELAY !== false && (!is_int(RETRY_AFTER_DELAY) || RETRY_AFTER_DELAY < 1))  {
+            throw new FatalMisconfigurationException("The RETRY_AFTER_DELAY value must be 'false' or a number greater than 0.");
+        }
+
         // Check KOE flags
         if (!defined('KOE_CAPABILITY_GAB')) {
             define('KOE_CAPABILITY_GAB', false);
@@ -456,7 +463,7 @@ class ZPush {
 
             if (ZPush::$stateMachine->GetStateVersion() !== ZPush::GetLatestStateVersion()) {
                 if (class_exists("TopCollector")) self::GetTopCollector()->AnnounceInformation("Run migration script!", true);
-                throw new HTTPReturnCodeException(sprintf("The state version available to the %s is not the latest version - please run the state upgrade script. See release notes for more information.", get_class(ZPush::$stateMachine), 503));
+                throw new ServiceUnavailableException(sprintf("The state version available to the %s is not the latest version - please run the state upgrade script. See release notes for more information.", get_class(ZPush::$stateMachine)));
             }
         }
         return ZPush::$stateMachine;

src/lib/core/zpushdefs.php

@@ -1002,6 +1002,7 @@ define("HTTP_CODE_200", 200);
 define("HTTP_CODE_401", 401);
 define("HTTP_CODE_449", 449);
 define("HTTP_CODE_500", 500);
+define("HTTP_CODE_503", 503);
 
 define("WINDOW_SIZE_MAX", 512);
 

src/lib/exceptions/serviceunavailableexception.php

+<?php
+/***********************************************
+ * File      :   serviceunavailableexception.php
+ * Project   :   Z-Push
+ * Descr     :   Exception sending a '503 Service Unavailable' to the mobile.
+ *
+ * Created   :   09.08.2016
+ *
+ * Copyright 2007 - 2016 Zarafa Deutschland GmbH
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation with the following additional
+ * term according to sec. 7:
+ *
+ * According to sec. 7 of the GNU Affero General Public License, version 3,
+ * the terms of the AGPL are supplemented with the following terms:
+ *
+ * "Zarafa" is a registered trademark of Zarafa B.V.
+ * "Z-Push" is a registered trademark of Zarafa Deutschland GmbH
+ * The licensing of the Program under the AGPL does not imply a trademark license.
+ * Therefore any rights, title and interest in our trademarks remain entirely with us.
+ *
+ * However, if you propagate an unmodified version of the Program you are
+ * allowed to use the term "Z-Push" to indicate that you distribute the Program.
+ * Furthermore you may use our trademarks where it is necessary to indicate
+ * the intended purpose of a product or service provided you use it in accordance
+ * with honest practices in industrial or commercial matters.
+ * If you want to propagate modified versions of the Program under the name "Z-Push",
+ * you may only do so if you have a written permission by Zarafa Deutschland GmbH
+ * (to acquire a permission please contact Zarafa at trademark@zarafa.com).
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Consult LICENSE file for details
+ ************************************************/
+
+class ServiceUnavailableException extends HTTPReturnCodeException {
+	protected $defaultLogLevel = LOGLEVEL_INFO;
+	protected $httpReturnCode = HTTP_CODE_503;
+	protected $httpReturnMessage = "Service Unavailable";
+	protected $httpHeaders = array();
+	protected $showLegal = false;
+
+	public function __construct($message = "", $code = 0, $previous = NULL, $logLevel = false) {
+		parent::__construct($message, $code, $previous, $logLevel);
+		if (RETRY_AFTER_DELAY !== false) {
+			$this->httpHeaders[] = 'Retry-After: ' . RETRY_AFTER_DELAY;
+		}
+	}
+}
\ No newline at end of file

src/vendor/composer/autoload_classmap.php

@@ -112,6 +112,7 @@ return array(
     'Search' => $baseDir . '/lib/request/search.php',
     'SearchProvider' => $baseDir . '/lib/default/searchprovider.php',
     'SendMail' => $baseDir . '/lib/request/sendmail.php',
+    'ServiceUnavailableException' => $baseDir . '/lib/exceptions/serviceunavailableexception.php',
     'Settings' => $baseDir . '/lib/request/settings.php',
     'SimpleMutex' => $baseDir . '/lib/default/simplemutex.php',
     'SqlStateMachine' => $baseDir . '/backend/sqlstatemachine/sqlstatemachine.php',

src/vendor/composer/autoload_static.php

@@ -119,6 +119,7 @@ class ComposerStaticInitd6749fc2fb9944bbe86b2b7d79a7852f
         'Search' => __DIR__ . '/../..' . '/lib/request/search.php',
         'SearchProvider' => __DIR__ . '/../..' . '/lib/default/searchprovider.php',
         'SendMail' => __DIR__ . '/../..' . '/lib/request/sendmail.php',
+        'ServiceUnavailableException' => __DIR__ . '/../..' . '/lib/exceptions/serviceunavailableexception.php',
         'Settings' => __DIR__ . '/../..' . '/lib/request/settings.php',
         'SimpleMutex' => __DIR__ . '/../..' . '/lib/default/simplemutex.php',
         'SqlStateMachine' => __DIR__ . '/../..' . '/backend/sqlstatemachine/sqlstatemachine.php',