Merge pull request #19 from async-interop/dedicated-error-handler

Add PromiseErrorHandler to decouple the specification

Author: bwoebi

.gitignore

@@ -0,0 +1,2 @@
+/composer.lock
+/vendor/

.travis.yml

@@ -0,0 +1,26 @@
+language: php
+
+php:
+  - 5.4
+  - 5.5
+  - 5.6
+  - 7.0
+  - nightly
+  - hhvm
+
+matrix:
+  allow_failures:
+   - php: nightly
+  fast_finish: true
+
+cache:
+  directories:
+    - $HOME/.composer/cache
+
+install:
+  - composer install
+  - composer show -t
+
+script:
+  - php vendor/bin/parallel-lint --exclude vendor .
+  - php vendor/bin/phpunit --coverage-text

README.md

@@ -72,7 +72,7 @@ Any implementation MUST at least provide these two parameters. The implementatio
 
 > **NOTE:** The signature doesn't specify a type for `$error`. This is due to the new `Throwable` interface introduced in PHP 7. As this specification is PHP 5 compatible, we can use neither `Throwable` nor `Exception`.
 
-All registered callbacks MUST be executed in the order they were registered. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be rethrown in a callable passed to `Loop::defer` so `Loop::onError` can be properly invoked by the loop. `Loop` refers to the [global event loop accessor](https://github.com/async-interop/event-loop/blob/master/src/Loop.php). The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters.
+All registered callbacks MUST be executed in the order they were registered. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `Async\Interop\Promise\ErrorHandler::notify`. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters.
 
 If a `Promise` is resolved with another `Promise`, the `Promise` MUST keep in pending state until the passed `Promise` is resolved. Thus, the value of a `Promise` can never be a `Promise`.
 

composer.json

@@ -1,14 +1,24 @@
 {
     "name": "async-interop/promise",
-    "description": "Promise interface for implementing async operations",
+    "description": "A promise interface for interoperability in async operations.",
     "keywords": ["promise", "future", "awaitable", "async", "interop"],
     "license": "MIT",
     "require": {
-        "php": ">=5.4"
+        "php": ">=5.4.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^4|^5",
+        "jakub-onderka/php-parallel-lint": "^0.9.2",
+        "jakub-onderka/php-console-highlighter": "^0.3.2"
     },
     "autoload": {
         "psr-4": {
-            "Interop\\Async\\": "src/"
+            "Interop\\Async\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Interop\\Async\\Promise\\Test\\": "test"
         }
     }
-}
+}

phpunit.xml.dist

@@ -0,0 +1,15 @@
+<phpunit bootstrap="./vendor/autoload.php" colors="true">
+    <testsuites>
+        <testsuite name="Main Tests">
+            <directory>./test</directory>
+        </testsuite>
+        <testsuite name="PHPT Tests">
+            <directory suffix=".phpt">./test/phpt</directory>
+        </testsuite>
+    </testsuites>
+    <filter>
+        <whitelist addUncoveredFilesFromWhitelist="true">
+            <directory>./src</directory>
+        </whitelist>
+    </filter>
+</phpunit>

src/Promise/ErrorHandler.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace Interop\Async\Promise;
+
+use Interop\Async\Promise;
+
+/**
+ * Global error handler for promises.
+ *
+ * Callbacks passed to `Promise::when()` should never throw, but they might. Such errors have to be passed to this
+ * global error handler to make them easily loggable. These can't be handled gracefully in any way, so we just enable
+ * logging with this handler and ignore them otherwise.
+ *
+ * If handler is set or that handler rethrows, it will fail hard by triggering an E_USER_ERROR leading to script
+ * abortion.
+ */
+final class ErrorHandler
+{
+    /** @var callable|null */
+    private static $callback = null;
+
+    private function __construct()
+    {
+        // disable construction, only static helper
+    }
+
+    /**
+     * Set a new handler that will be notified on uncaught errors during promise resolution callback invocations.
+     *
+     * This callback can attempt to log the error or exit the execution of the script if it sees need. It receives the
+     * exception as first and only parameter.
+     *
+     * As it's already a last chance handler, the script will be aborted using E_USER_ERROR if the handler throws. Thus
+     * it's suggested to always wrap the body of your callback in a generic `try` / `catch` block, if you want to avoid
+     * that.
+     *
+     * @param callable|null $onError Callback to invoke on errors or `null` to reset.
+     *
+     * @return callable|null Previous callback.
+     */
+    public static function set(callable $onError = null)
+    {
+        $previous = self::$callback;
+        self::$callback = $onError;
+        return $previous;
+    }
+
+    /**
+     * Notifies the registered handler, that an exception occurred.
+     *
+     * This method MUST be called by every promise implementation if a callback passed to `Promise::when()` throws upon
+     * invocation. It MUST NOT be called otherwise.
+     */
+    public static function notify($error)
+    {
+        // No type declaration, because of PHP 5 + PHP 7 support.
+        if (!$error instanceof \Exception && !$error instanceof \Throwable) {
+            // We have this error handler specifically so we never throw from Promise::when, so it doesn't make sense to
+            // throw here. We just forward a generic exception to the registered handlers.
+            $error = new \Exception(sprintf(
+                "Promise implementation called %s with an invalid argument of type '%s'",
+                __METHOD__,
+                is_object($error) ? get_class($error) : gettype($error)
+            ));
+        }
+
+        if (self::$callback === null) {
+            trigger_error(
+                "An exception has been thrown from an Interop\\Async\\Promise::when handler, but no handler has been"
+                . " registered via Interop\\Async\\Promise\\ErrorHandler::set. A handler has to be registered to"
+                . " prevent exceptions from going unnoticed. Do NOT install an empty handler that just"
+                . " does nothing. If the handler is called, there is ALWAYS something wrong.\n\n" . (string) $error,
+                E_USER_ERROR
+            );
+
+            return;
+        }
+
+        try {
+            \call_user_func(self::$callback, $error);
+        } catch (\Exception $e) {
+            // We're already a last chance handler, throwing doesn't make sense, so use a real fatal
+            trigger_error(sprintf(
+                "An exception has been thrown from the promise error handler registered to %s::set().\n\n%s",
+                __CLASS__,
+                (string) $e
+            ), E_USER_ERROR);
+        } catch (\Throwable $e) {
+            // We're already a last chance handler, throwing doesn't make sense, so use a real fatal
+            trigger_error(sprintf(
+                "An exception has been thrown from the promise error handler registered to %s::set().\n\n%s",
+                __CLASS__,
+                (string) $e
+            ), E_USER_ERROR);
+        }
+    }
+}

test/phpt/error_handler_001.phpt

@@ -0,0 +1,16 @@
+--TEST--
+ErrorHandler::notify() fatals without a handler
+--FILE--
+<?php
+
+require __DIR__ . "/../../vendor/autoload.php";
+
+Interop\Async\Promise\ErrorHandler::notify(new Exception);
+
+?>
+--EXPECTF--
+Fatal error: An exception has been thrown from an Interop\Async\Promise::when handler, but no handler has been registered via Interop\Async\Promise\ErrorHandler::set. A handler has to be registered to prevent exceptions from going unnoticed. Do NOT install an empty handler that just does nothing. If the handler is called, there is ALWAYS something wrong.
+
+%s in %s:%d
+Stack trace:
+#0 {main} in %s on line %d

test/phpt/error_handler_002.phpt

@@ -0,0 +1,13 @@
+--TEST--
+ErrorHandler::notify() does not fatal with a handler
+--FILE--
+<?php
+
+require __DIR__ . "/../../vendor/autoload.php";
+
+Interop\Async\Promise\ErrorHandler::set(function () { print "1"; });
+Interop\Async\Promise\ErrorHandler::notify(new Exception);
+
+?>
+--EXPECT--
+1

test/phpt/error_handler_003.phpt

@@ -0,0 +1,18 @@
+--TEST--
+ErrorHandler::notify() fatals after handlers have been removed with ErrorHandler::set(null)
+--FILE--
+<?php
+
+require __DIR__ . "/../../vendor/autoload.php";
+
+Interop\Async\Promise\ErrorHandler::set(function () { print "1"; });
+Interop\Async\Promise\ErrorHandler::set(null);
+Interop\Async\Promise\ErrorHandler::notify(new Exception);
+
+?>
+--EXPECTF--
+Fatal error: An exception has been thrown from an Interop\Async\Promise::when handler, but no handler has been registered via Interop\Async\Promise\ErrorHandler::set. A handler has to be registered to prevent exceptions from going unnoticed. Do NOT install an empty handler that just does nothing. If the handler is called, there is ALWAYS something wrong.
+
+%s in %s:%d
+Stack trace:
+#0 {main} in %s on line %d

test/phpt/error_handler_004.phpt

@@ -0,0 +1,17 @@
+--TEST--
+ErrorHandler::notify() converts non-exception to exception
+--FILE--
+<?php
+
+require __DIR__ . "/../../vendor/autoload.php";
+
+Interop\Async\Promise\ErrorHandler::notify(42);
+
+?>
+--EXPECTF--
+Fatal error: An exception has been thrown from an Interop\Async\Promise::when handler, but no handler has been registered via Interop\Async\Promise\ErrorHandler::set. A handler has to be registered to prevent exceptions from going unnoticed. Do NOT install an empty handler that just does nothing. If the handler is called, there is ALWAYS something wrong.
+
+%SException%SPromise implementation called Interop\Async\Promise\ErrorHandler::notify with an invalid argument of type 'integer'%S in %s:%d
+Stack trace:
+#0 %s(%d): Interop\Async\Promise\ErrorHandler::notify(%S)
+#1 {main} in %s on line %d