Add first version of interface and a promise implementation

Author: joelwurtz

composer.json

@@ -10,7 +10,11 @@
         }
     ],
     "require": {
-        "php": "^5.4 || ^7.0"
+        "php": "^5.4 || ^7.0",
+        "async-interop/promise": "^0.2.0",
+        "psr/http-message": "^1.0",
+        "php-http/httplug": "^1.1",
+        "async-interop/event-loop": "^0.3.0"
     },
     "require-dev": {
         "phpspec/phpspec": "^2.4",

src/HttpAsyncClient.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Http\Client\Async;
+
+use Interop\Async\Promise;
+use Psr\Http\Message\RequestInterface;
+
+interface HttpAsyncClient
+{
+    /**
+     * Sends a PSR-7 request in an asynchronous way.
+     *
+     * Exceptions related to processing the request are available from the returned Promise.
+     *
+     * @param RequestInterface $request
+     *
+     * @return Promise An async interop Promise which resolves a PSR-7 Response or fails with an Http\Client\Exception.
+     *
+     * @throws \Exception If processing the request is impossible (eg. bad configuration).
+     */
+    public function sendAsyncRequest(RequestInterface $request);
+}

src/Promise/Future.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace Http\Client\Async\Promise;
+
+use Http\Client\Exception;
+use Interop\Async\Loop;
+use Interop\Async\Promise;
+use Psr\Http\Message\ResponseInterface;
+
+class Future implements Promise
+{
+    const STATE_PENDING = 'pending';
+    const STATE_SUCCEEDED = 'succeeded';
+    const STATE_FAILED = 'failed';
+
+    /** @var array An array of callable which will be called when the promise is resolved */
+    private $callbackQueue = [];
+
+    /** @var ResponseInterface response keeped in case of the promise is used after being resolved */
+    private $response;
+
+    /** @var Exception exception which is keeped in case of the promise is used after being resolved */
+    private $exception;
+
+    /** @var string Current state of the promise */
+    private $state = self::STATE_PENDING;
+
+    /**
+     * Resolve the promise with a success : PSR 7 Response
+     *
+     * @param ResponseInterface $response
+     *
+     * @throws \Exception
+     */
+    public function success(ResponseInterface $response)
+    {
+        if ($this->state !== self::STATE_PENDING) {
+            throw new \Exception('Promise already resolved');
+        }
+
+        $this->state = self::STATE_SUCCEEDED;
+        $this->response = $response;
+
+        foreach ($this->callbackQueue as $onResolved) {
+            $this->resolve(function () use ($onResolved, $response) {
+                $onResolved($response, null);
+            });
+        }
+    }
+
+    /**
+     * Resolve the promise with a failure : Http\Client\Exception
+     *
+     * @param Exception $exception
+     *
+     * @throws \Exception
+     */
+    public function failure(Exception $exception)
+    {
+        if ($this->state !== self::STATE_PENDING) {
+            throw new \Exception('Promise already resolved');
+        }
+
+        $this->state = self::STATE_FAILED;
+        $this->exception = $exception;
+
+        foreach ($this->callbackQueue as $onResolved) {
+            $this->resolve(function () use ($onResolved, $exception) {
+                $onResolved(null, $exception);
+            });
+        }
+    }
+
+    /**
+     * Internal resolution
+     *
+     * @param $callback
+     */
+    private function resolve($callback) {
+        try {
+            $callback();
+            // @Todo find a way to avoid using the loop as it force sync user to have an
+            // event loop implementation
+        } catch (\Throwable $exception) {
+            Loop::defer(static function () use ($exception) {
+                throw $exception;
+            });
+        } catch (\Exception $exception) {
+            Loop::defer(static function () use ($exception) {
+                throw $exception;
+            });
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function when(callable $onResolved)
+    {
+        if ($this->state === self::STATE_PENDING) {
+            $this->callbackQueue[] = $onResolved;
+        }
+
+        if ($this->state === self::STATE_SUCCEEDED) {
+            $this->resolve(function () use ($onResolved) {
+                $onResolved($this->response, null);
+            });
+        }
+
+        if ($this->state === self::STATE_FAILED) {
+            $this->resolve(function () use ($onResolved) {
+                $onResolved(null, $this->exception);
+            });
+        }
+    }
+}