X-Git-Url: https://git.m6w6.name/?p=m6w6%2Fseekat;a=blobdiff_plain;f=lib%2FAPI.php;h=3ed788a6af07b6ef00c0d52d8be25f9c88a96f52;hp=ba384c5ad4eb0d591ebc3a1aa671099b841214b9;hb=654d736df2c46ec2520f73e9089d06a44f2b9c50;hpb=5bb5547a9a7275ae61eff8e1a02cfa694e89feab diff --git a/lib/API.php b/lib/API.php index ba384c5..3ed788a 100644 --- a/lib/API.php +++ b/lib/API.php @@ -4,94 +4,58 @@ namespace seekat; use Countable; use Generator; -use http\{ - Client, - Client\Request, - Client\Response, - Header, - Message\Body, - QueryString, - Url -}; -use InvalidArgumentException; +use http\{Client, Client\Request, Message\Body, QueryString, Url}; +use Iterator; use IteratorAggregate; -use Psr\Log\{ - LoggerInterface, - NullLogger -}; -use seekat\{ - API\Call, - API\ContentType, - API\Invoker, - API\Iterator, - API\Links, - Exception\RequestException -}; -use React\Promise\{ - ExtendedPromiseInterface, - function reject, - function resolve -}; -use Throwable; -use UnexpectedValueException; +use Psr\Log\{LoggerInterface, NullLogger}; +use seekat\API\{Call, Consumer, ContentType, Future, Links}; +use seekat\Exception\InvalidArgumentException; class API implements IteratorAggregate, Countable { /** - * The current API endpoint URL - * @var Url + * API version */ - private $__url; + private int $version = 3; /** - * Logger - * @var LoggerInterface - */ - private $__log; - - /** - * The HTTP client - * @var Client + * Default headers to send out to the API endpoint */ - private $__client; + private array $headers; /** - * Default headers to send out to the API endpoint - * @var array + * Current endpoints links */ - private $__headers; + private ?Links $links = null; /** * Current endpoint data's Content-Type - * @var Header */ - private $__type; + private API\ContentType $type; /** * Current endpoint's data - * @var array|object - */ - private $__data; - - /** - * Current endpoints links - * @var Links */ - private $__links; + private mixed $data = null; /** * Create a new API endpoint root * + * @param Future $future pretending to fulfill promises * @param array $headers Standard request headers, defaults to ["Accept" => "application/vnd.github.v3+json"] * @param Url $url The API's endpoint, defaults to https://api.github.com * @param Client $client The HTTP client to use for executing requests * @param LoggerInterface $log A logger - */ - function __construct(array $headers = null, Url $url = null, Client $client = null, LoggerInterface $log = null) { - $this->__log = $log ?? new NullLogger; - $this->__url = $url ?? new Url("https://api.github.com"); - $this->__client = $client ?? new Client; - $this->__headers = (array) $headers + [ - "Accept" => "application/vnd.github.v3+json" + * @param Call\Cache\Service $cache A cache + */ + function __construct(private readonly Future $future, + array $headers = null, + private Url $url = new Url("https://api.github.com"), + private readonly Client $client = new Client, + private readonly LoggerInterface $logger = new NullLogger, + private readonly Call\Cache\Service $cache = new Call\Cache\Service\Hollow) { + $this->type = new ContentType($this->version, "json"); + $this->headers = (array) $headers + [ + "Accept" => $this->type->getContentType() ]; } @@ -101,22 +65,23 @@ class API implements IteratorAggregate, Countable { * @param string|int $seg The "path" element to ascend into * @return API Endpoint clone referring to {$parent}/{$seg} */ - function __get($seg) : API { - if (substr($seg, -4) === "_url") { - $url = new Url(uri_template($this->__data->$seg)); + function __get(string|int $seg) : API { + if (str_ends_with($seg, "_url")) { + $url = new Url(uri_template($this->data->$seg)); $that = $this->withUrl($url); - $seg = basename($that->__url->path); + $seg = basename($that->url->path); } else { $that = clone $this; - $that->__url->path .= "/".urlencode($seg); - $this->exists($seg, $that->__data); + $that->url->path .= "/".urlencode($seg); + $this->exists($seg, $that->data); } - $this->__log->debug(__FUNCTION__."($seg)", [ + $this->logger->debug("get($seg)", [ "url" => [ - (string) $this->__url, - (string) $that->__url + (string) $this->url, + (string) $that->url ], + "data" => $that->data ]); return $that; @@ -127,58 +92,62 @@ class API implements IteratorAggregate, Countable { * * @param string $method The API's "path" element to ascend into * @param array $args Array of arguments forwarded to \seekat\API::get() - * @return ExtendedPromiseInterface + * @return mixed promise */ - function __call(string $method, array $args) : ExtendedPromiseInterface { + function __call(string $method, array $args) { /* We cannot implement an explicit then() method, * because the Promise implementation might think * we're actually implementing Thenable, * which might cause an infinite loop. */ - if ($method === "then") { - return $this->get()->then(...$args); - } - + if ($method === "then" /* * very short-hand version: * ->users->m6w6->gists->get()->then(...) * vs: * ->users->m6w6->gists(...) */ - if (is_callable(current($args))) { - return $this->$method->get()->then(current($args)); + || is_callable(current($args))) { + return $this->future->handlePromise($this->get(), ...$args); } - /* standard access */ - if ($this->exists($method)) { - return $this->$method->get(...$args); - } + return (new Call($this, $method))($args); + } - /* fetch resource, unless already localized, and try for {$method}_url */ - return $this->$method->get(...$args)->otherwise(function(Throwable $error) use($method, $args) { - if ($this->exists($method."_url", $url)) { + /** + * Run the send loop through a generator + * + * @param callable|Generator $cbg A \Generator or a factory of a \Generator yielding promises + * @return mixed The promise of the generator's return value + * @throws InvalidArgumentException + */ + function __invoke(callable|Generator $cbg) { + $this->logger->debug(__METHOD__, [$cbg]); - $this->__log->info(__FUNCTION__."($method): ". $error->getMessage(), [ - "url" => (string) $this->__url - ]); + $consumer = new Consumer($this->getFuture(), function() { + $this->client->send(); + }); - $url = new Url(uri_template($url, (array) current($args))); - return $this->withUrl($url)->get(...$args); - } + invoke: + if ($cbg instanceof Generator) { + return $consumer($cbg); + } - $this->__log->error(__FUNCTION__."($method): ". $error->getMessage(), [ - "url" => (string) $this->__url - ]); + if (is_callable($cbg)) { + $cbg = $cbg($this); + goto invoke; + } - throw $error; - }); + throw new InvalidArgumentException( + "Expected callable or Generator, got ".typeof($cbg, true) + ); } /** * Clone handler ensuring the underlying url will be cloned, too */ function __clone() { - $this->__url = clone $this->__url; + $this->url = clone $this->url; } /** @@ -187,76 +156,116 @@ class API implements IteratorAggregate, Countable { * @return string */ function __toString() : string { - if (is_scalar($this->__data)) { - return (string) $this->__data; - } - - /* FIXME */ - return json_encode($this->__data); + return (string) $this->type->encode($this->data); } /** - * Import handler for the endpoint's underlying data + * Create an iterator over the endpoint's underlying data * - * \seekat\Call will call this when the request will have finished. + * @return Iterator + */ + function getIterator() : Iterator { + foreach ($this->data as $key => $cur) { + if ($this->__get($key)->exists("url", $url)) { + $url = new Url($url); + $val = $this->withUrl($url)->withData($cur); + } else { + $val = $this->__get($key)->withData($cur); + } + yield $key => $val; + } + } + + /** + * Count the underlying data's entries * - * @param Response $response - * @return API self - * @throws UnexpectedValueException - * @throws RequestException - * @throws \Exception + * @return int */ - function import(Response $response) : API { - $this->__log->info(__FUNCTION__.": ". $response->getInfo(), [ - "url" => (string) $this->__url + function count() : int { + if (is_array($this->data)) { + $count = count($this->data); + } else if ($this->data instanceof Countable) { + $count = count($this->data); + } else if (is_object($this->data)) { + $count = count((array) $this->data); + } else { + $count = 0; + } + $this->logger->debug("count()", [ + "of type" => typeof($this->data), + "count" => $count ]); + return $count; + } - if ($response->getResponseCode() >= 400) { - $e = new RequestException($response); + function getUrl() : Url { + return $this->url; + } - $this->__log->critical(__FUNCTION__.": ".$e->getMessage(), [ - "url" => (string) $this->__url, - ]); + function getLogger() : LoggerInterface { + return $this->logger; + } - throw $e; - } + function getFuture() : Future { + return $this->future; + } - if (!($type = $response->getHeader("Content-Type", Header::class))) { - $e = new RequestException($response); - $this->__log->error( - __FUNCTION__.": Empty Content-Type -> ".$e->getMessage(), [ - "url" => (string) $this->__url, - ]); - throw $e; - } + public function getClient(): Client { + return $this->client; + } - try { - $this->__type = new ContentType($type); - $this->__data = $this->__type->parseBody($response->getBody()); + public function getCache() : Call\Cache\Service { + return $this->cache; + } - if (($link = $response->getHeader("Link", Header::class))) { - $this->__links = new Links($link); - } - } catch (\Exception $e) { - $this->__log->error(__FUNCTION__.": ".$e->getMessage(), [ - "url" => (string) $this->__url - ]); + function getData() : mixed { + return $this->data; + } - throw $e; - } + /** + * Accessor to any hypermedia links + * + * @return null|Links + */ + function getLinks() : ?Links { + return $this->links; + } - return $this; + /** + * @return int + */ + function getVersion() : int { + return $this->version; } /** * Export the endpoint's underlying data * - * @param - * @return mixed + * @return array ["url", "data", "type", "links", "headers"] + */ + function export() : array { + $data = $this->data; + $url = clone $this->url; + $type = clone $this->type; + $links = $this->links ? clone $this->links : null; + $headers = $this->headers; + return compact("url", "data", "type", "links", "headers"); + } + + /** + * @param $export + * @return API */ - function export(&$type = null) { - $type = clone $this->__type; - return $this->__data; + function with($export) : API { + $that = clone $this; + if (is_array($export) || ($export instanceof \ArrayAccess)) { + isset($export["url"]) && $that->url = $export["url"]; + isset($export["data"]) && $that->data = $export["data"]; + isset($export["type"]) && $that->type = $export["type"]; + isset($export["links"]) && $that->links = $export["links"]; + isset($export["headers"]) && $that->headers = $export["headers"]; + } + return $that; } /** @@ -265,9 +274,9 @@ class API implements IteratorAggregate, Countable { * @param mixed $data * @return API clone */ - function withData($data) : API { + function withData(mixed $data) : API { $that = clone $this; - $that->__data = $data; + $that->data = $data; return $that; } @@ -278,8 +287,10 @@ class API implements IteratorAggregate, Countable { * @return API clone */ function withUrl(Url $url) : API { - $that = $this->withData(null); - $that->__url = $url; + $that = clone $this; + $that->url = $url; + $that->data = null; + #$that->links = null; return $that; } @@ -290,12 +301,12 @@ class API implements IteratorAggregate, Countable { * @param mixed $value * @return API clone */ - function withHeader(string $name, $value) : API { + function withHeader(string $name, mixed $value) : API { $that = clone $this; if (isset($value)) { - $that->__headers[$name] = $value; + $that->headers[$name] = $value; } else { - unset($that->__headers[$name]); + unset($that->headers[$name]); } return $that; } @@ -305,44 +316,31 @@ class API implements IteratorAggregate, Countable { * * Changes the returned endpoint's accept header to "application/vnd.github.v3.{$type}" * - * @param string $type The expected return data type, e.g. "raw", "html", etc. + * @param string $type The expected return data type, e.g. "raw", "html", ..., or a complete content type * @param bool $keepdata Whether to keep already fetched data * @return API clone */ function as(string $type, bool $keepdata = true) : API { - switch(substr($type, 0, 1)) { - case "+": - case ".": - case "": - break; - default: - $type = ".$type"; - break; - } - $vapi = ContentType::version(); - $that = $this->withHeader("Accept", "application/vnd.github.v$vapi$type"); + $ct = new ContentType($this->version, $type); + + $that = $ct->apply($this); + $that->type = $ct; + if (!$keepdata) { - $that->__data = null; + $that->data = null; } return $that; } /** - * Create an iterator over the endpoint's underlying data - * - * @return Iterator - */ - function getIterator() : Iterator { - return new Iterator($this); - } - - /** - * Count the underlying data's entries + * Perform a HEAD request against the endpoint's underlying URL * - * @return int + * @param mixed $args The HTTP query string parameters + * @param array $headers The request's additional HTTP headers + * @return mixed promise */ - function count() : int { - return count($this->__data); + function head($args = null, array $headers = null) { + return $this->request("HEAD", $args, null, $headers); } /** @@ -350,10 +348,10 @@ class API implements IteratorAggregate, Countable { * * @param mixed $args The HTTP query string parameters * @param array $headers The request's additional HTTP headers - * @return ExtendedPromiseInterface + * @return mixed promise */ - function get($args = null, array $headers = null) : ExtendedPromiseInterface { - return $this->__xfer("GET", $args, null, $headers); + function get($args = null, array $headers = null) { + return $this->request("GET", $args, null, $headers); } /** @@ -361,10 +359,10 @@ class API implements IteratorAggregate, Countable { * * @param mixed $args The HTTP query string parameters * @param array $headers The request's additional HTTP headers - * @return ExtendedPromiseInterface + * @return mixed promise */ - function delete($args = null, array $headers = null) : ExtendedPromiseInterface { - return $this->__xfer("DELETE", $args, null, $headers); + function delete($args = null, array $headers = null) { + return $this->request("DELETE", $args, null, $headers); } /** @@ -373,10 +371,10 @@ class API implements IteratorAggregate, Countable { * @param mixed $body The HTTP message's body * @param mixed $args The HTTP query string parameters * @param array $headers The request's additional HTTP headers - * @return ExtendedPromiseInterface + * @return mixed promise */ - function post($body = null, $args = null, array $headers = null) : ExtendedPromiseInterface { - return $this->__xfer("POST", $args, $body, $headers); + function post($body = null, $args = null, array $headers = null) { + return $this->request("POST", $args, $body, $headers); } /** @@ -385,10 +383,10 @@ class API implements IteratorAggregate, Countable { * @param mixed $body The HTTP message's body * @param mixed $args The HTTP query string parameters * @param array $headers The request's additional HTTP headers - * @return ExtendedPromiseInterface + * @return mixed promise */ - function put($body = null, $args = null, array $headers = null) : ExtendedPromiseInterface { - return $this->__xfer("PUT", $args, $body, $headers); + function put($body = null, $args = null, array $headers = null) { + return $this->request("PUT", $args, $body, $headers); } /** @@ -397,67 +395,10 @@ class API implements IteratorAggregate, Countable { * @param mixed $body The HTTP message's body * @param mixed $args The HTTP query string parameters * @param array $headers The request's additional HTTP headers - * @return ExtendedPromiseInterface - */ - function patch($body = null, $args = null, array $headers = null) : ExtendedPromiseInterface { - return $this->__xfer("PATCH", $args, $body, $headers); - } - - /** - * Accessor to any hypermedia links - * - * @return null|Links - */ - function links() { - return $this->__links; - } - - /** - * Perform a GET request against the link's "first" relation - * - * @return ExtendedPromiseInterface - */ - function first() : ExtendedPromiseInterface { - if ($this->links() && ($first = $this->links()->getFirst())) { - return $this->withUrl($first)->get(); - } - return reject($this->links()); - } - - /** - * Perform a GET request against the link's "prev" relation - * - * @return ExtendedPromiseInterface - */ - function prev() : ExtendedPromiseInterface { - if ($this->links() && ($prev = $this->links()->getPrev())) { - return $this->withUrl($prev)->get(); - } - return reject($this->links()); - } - - /** - * Perform a GET request against the link's "next" relation - * - * @return ExtendedPromiseInterface + * @return mixed promise */ - function next() : ExtendedPromiseInterface { - if ($this->links() && ($next = $this->links()->getNext())) { - return $this->withUrl($next)->get(); - } - return reject($this->links()); - } - - /** - * Perform a GET request against the link's "last" relation - * - * @return ExtendedPromiseInterface - */ - function last() : ExtendedPromiseInterface { - if ($this->links() && ($last = $this->links()->getLast())) { - return $this->withUrl($last)->get(); - } - return reject($this->links()); + function patch($body = null, $args = null, array $headers = null) { + return $this->request("PATCH", $args, $body, $headers); } /** @@ -466,45 +407,14 @@ class API implements IteratorAggregate, Countable { * @return API self */ function send() : API { - $this->__log->debug(__FUNCTION__.": start loop"); - while (count($this->__client)) { - $this->__client->send(); + $this->logger->debug("send: start loop"); + while (count($this->client)) { + $this->client->send(); } - $this->__log->debug(__FUNCTION__.": end loop"); + $this->logger->debug("send: end loop"); return $this; } - /** - * Run the send loop through a generator - * - * @param callable|Generator $cbg A \Generator or a factory of a \Generator yielding promises - * @return ExtendedPromiseInterface The promise of the generator's return value - * @throws InvalidArgumentException - */ - function __invoke($cbg) : ExtendedPromiseInterface { - $this->__log->debug(__FUNCTION__); - - $invoker = new Invoker($this->__client); - - if ($cbg instanceof Generator) { - return $invoker->iterate($cbg)->promise(); - } - - if (is_callable($cbg)) { - return $invoker->invoke(function() use($cbg) { - return $cbg($this); - })->promise(); - } - - throw InvalidArgumentException( - "Expected callable or Generator, got ".( - is_object($cbg) - ? "instance of ".get_class($cbg) - : gettype($cbg).": ".var_export($cbg, true) - ) - ); - } - /** * Check for a specific key in the endpoint's underlying data * @@ -513,28 +423,22 @@ class API implements IteratorAggregate, Countable { * @return bool */ function exists($seg, &$val = null) : bool { - if (is_array($this->__data) && array_key_exists($seg, $this->__data)) { - $val = $this->__data[$seg]; + if (is_array($this->data) && array_key_exists($seg, $this->data)) { + $val = $this->data[$seg]; $exists = true; - } elseif (is_object($this->__data) && property_exists($this->__data, $seg)) { - $val = $this->__data->$seg; + } elseif (is_object($this->data) && property_exists($this->data, $seg)) { + $val = $this->data->$seg; $exists = true; } else { $val = null; $exists = false; } - $this->__log->debug(__FUNCTION__."($seg) in ".( - is_object($this->__data) - ? get_class($this->__data) - : gettype($this->__data) - )." -> ".( - $exists - ? "true" - : "false" + $this->logger->debug(sprintf("exists(%s) in %s -> %s", + $seg, typeof($this->data, false), $exists ? "true" : "false" ), [ - "url" => (string) $this->__url, - "val" => $val, + "url" => (string) $this->url, + "val" => typeof($val, false), ]); return $exists; @@ -545,36 +449,35 @@ class API implements IteratorAggregate, Countable { * * @param string $method The HTTP request method * @param mixed $args The HTTP query string parameters - * @param mixed $body Thee HTTP message's body - * @param array $headers The request's additional HTTP headers - * @return ExtendedPromiseInterface - */ - private function __xfer(string $method, $args = null, $body = null, array $headers = null) : ExtendedPromiseInterface { - if (isset($this->__data)) { - $this->__log->debug(__FUNCTION__."($method) -> resolve", [ - "url" => (string) $this->__url, - "args" => $args, - "body" => $body, + * @param mixed $body The HTTP message's body + * @param ?array $headers The request's additional HTTP headers + * @return mixed promise + */ + private function request(string $method, $args = null, $body = null, array $headers = null) { + if (isset($this->data)) { + $this->logger->debug("request -> resolve", [ + "method" => $method, + "url" => (string) $this->url, + "args" => $args, + "body" => $body, "headers" => $headers, ]); - return resolve($this); + return $this->future->resolve($this); } - $url = $this->__url->mod(["query" => new QueryString($args)]); - $request = new Request($method, $url, ((array) $headers) + $this->__headers, - $body = is_array($body) ? json_encode($body) : ( - is_resource($body) ? new Body($body) : ( - is_scalar($body) ? (new Body)->append($body) : - $body))); + $url = $this->url->mod(["query" => new QueryString($args)]); + $request = new Request($method, $url, ((array) $headers) + $this->headers, + $body = $this->type->encode(is_resource($body) ? new Body($body) : $body)); - $this->__log->info(__FUNCTION__."($method) -> request", [ - "url" => (string) $this->__url, - "args" => $this->__url->query, + $this->logger->info("request -> deferred", [ + "method" => $method, + "url" => (string) $this->url, + "args" => $this->url->query, "body" => $body, "headers" => $headers, ]); - return (new Call($this, $this->__client, $request))->promise(); + return (new Call\Deferred($this, $request, $this->cache))(); } }