v2: Updates

* Simplifies & beautifies everything
* Introduces a new Class system.
* Errors are defaulted to AWS's handler.
* New function names & more efficient handling.
* Should fix a majority of the errors.

Please read the README for more!

aws/Aws/EndpointDiscovery/Configuration.php

@@ -0,0 +1,48 @@
+<?php
+namespace Aws\EndpointDiscovery;
+
+class Configuration implements ConfigurationInterface
+{
+    private $cacheLimit;
+    private $enabled;
+
+    public function __construct($enabled, $cacheLimit = 1000)
+    {
+        $this->cacheLimit = filter_var($cacheLimit, FILTER_VALIDATE_INT);
+        if ($this->cacheLimit == false || $this->cacheLimit < 1) {
+            throw new \InvalidArgumentException(
+                "'cache_limit' value must be a positive integer."
+            );
+        }
+
+        // Unparsable $enabled flag errs on the side of disabling endpoint discovery
+        $this->enabled = filter_var($enabled, FILTER_VALIDATE_BOOLEAN);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function isEnabled()
+    {
+        return $this->enabled;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getCacheLimit()
+    {
+        return $this->cacheLimit;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function toArray()
+    {
+        return [
+            'enabled' => $this->isEnabled(),
+            'cache_limit' => $this->getCacheLimit()
+        ];
+    }
+}

aws/Aws/EndpointDiscovery/ConfigurationInterface.php

@@ -0,0 +1,30 @@
+<?php
+namespace Aws\EndpointDiscovery;
+
+/**
+ * Provides access to endpoint discovery configuration options:
+ * 'enabled', 'cache_limit'
+ */
+interface ConfigurationInterface
+{
+    /**
+     * Checks whether or not endpoint discovery is enabled.
+     *
+     * @return bool
+     */
+    public function isEnabled();
+
+    /**
+     * Returns the cache limit, if available.
+     *
+     * @return string|null
+     */
+    public function getCacheLimit();
+
+    /**
+     * Returns the configuration as an associative array
+     *
+     * @return array
+     */
+    public function toArray();
+}

aws/Aws/EndpointDiscovery/ConfigurationProvider.php

@@ -0,0 +1,240 @@
+<?php
+namespace Aws\EndpointDiscovery;
+
+use Aws\AbstractConfigurationProvider;
+use Aws\CacheInterface;
+use Aws\ConfigurationProviderInterface;
+use Aws\EndpointDiscovery\Exception\ConfigurationException;
+use GuzzleHttp\Promise;
+use GuzzleHttp\Promise\PromiseInterface;
+
+/**
+ * A configuration provider is a function that returns a promise that is
+ * fulfilled with a {@see \Aws\EndpointDiscovery\ConfigurationInterface}
+ * or rejected with an {@see \Aws\EndpointDiscovery\Exception\ConfigurationException}.
+ *
+ * <code>
+ * use Aws\EndpointDiscovery\ConfigurationProvider;
+ * $provider = ConfigurationProvider::defaultProvider();
+ * // Returns a ConfigurationInterface or throws.
+ * $config = $provider()->wait();
+ * </code>
+ *
+ * Configuration providers can be composed to create configuration using
+ * conditional logic that can create different configurations in different
+ * environments. You can compose multiple providers into a single provider using
+ * {@see Aws\EndpointDiscovery\ConfigurationProvider::chain}. This function
+ * accepts providers as variadic arguments and returns a new function that will
+ * invoke each provider until a successful configuration is returned.
+ *
+ * <code>
+ * // First try an INI file at this location.
+ * $a = ConfigurationProvider::ini(null, '/path/to/file.ini');
+ * // Then try an INI file at this location.
+ * $b = ConfigurationProvider::ini(null, '/path/to/other-file.ini');
+ * // Then try loading from environment variables.
+ * $c = ConfigurationProvider::env();
+ * // Combine the three providers together.
+ * $composed = ConfigurationProvider::chain($a, $b, $c);
+ * // Returns a promise that is fulfilled with a configuration or throws.
+ * $promise = $composed();
+ * // Wait on the configuration to resolve.
+ * $config = $promise->wait();
+ * </code>
+ */
+class ConfigurationProvider extends AbstractConfigurationProvider
+    implements ConfigurationProviderInterface
+{
+    const DEFAULT_ENABLED = false;
+    const DEFAULT_CACHE_LIMIT = 1000;
+    const ENV_ENABLED = 'AWS_ENDPOINT_DISCOVERY_ENABLED';
+    const ENV_ENABLED_ALT = 'AWS_ENABLE_ENDPOINT_DISCOVERY';
+    const ENV_PROFILE = 'AWS_PROFILE';
+
+    public static $cacheKey = 'aws_cached_endpoint_discovery_config';
+
+    protected static $interfaceClass = ConfigurationInterface::class;
+    protected static $exceptionClass = ConfigurationException::class;
+
+    /**
+     * Create a default config provider that first checks for environment
+     * variables, then checks for a specified profile in the environment-defined
+     * config file location (env variable is 'AWS_CONFIG_FILE', file location
+     * defaults to ~/.aws/config), then checks for the "default" profile in the
+     * environment-defined config file location, and failing those uses a default
+     * fallback set of configuration options.
+     *
+     * This provider is automatically wrapped in a memoize function that caches
+     * previously provided config options.
+     *
+     * @param array $config
+     *
+     * @return callable
+     */
+    public static function defaultProvider(array $config = [])
+    {
+        $configProviders = [self::env()];
+        if (
+            !isset($config['use_aws_shared_config_files'])
+            || $config['use_aws_shared_config_files'] != false
+        ) {
+            $configProviders[] = self::ini();
+        }
+        $configProviders[] = self::fallback($config);
+
+        $memo = self::memoize(
+            call_user_func_array('self::chain', $configProviders)
+        );
+
+        if (isset($config['endpoint_discovery'])
+            && $config['endpoint_discovery'] instanceof CacheInterface
+        ) {
+            return self::cache($memo, $config['endpoint_discovery'], self::$cacheKey);
+        }
+
+        return $memo;
+    }
+
+    /**
+     * Provider that creates config from environment variables.
+     *
+     * @param $cacheLimit
+     * @return callable
+     */
+    public static function env($cacheLimit = self::DEFAULT_CACHE_LIMIT)
+    {
+        return function () use ($cacheLimit) {
+            // Use config from environment variables, if available
+            $enabled = getenv(self::ENV_ENABLED);
+            if ($enabled === false || $enabled === '') {
+                $enabled = getenv(self::ENV_ENABLED_ALT);
+            }
+            if ($enabled !== false && $enabled !== '') {
+                return Promise\promise_for(
+                    new Configuration($enabled, $cacheLimit)
+                );
+            }
+
+            return self::reject('Could not find environment variable config'
+                . ' in ' . self::ENV_ENABLED);
+        };
+    }
+
+    /**
+     * Fallback config options when other sources are not set. Will check the
+     * service model for any endpoint discovery required operations, and enable
+     * endpoint discovery in that case. If no required operations found, will use
+     * the class default values.
+     *
+     * @param array $config
+     * @return callable
+     */
+    public static function fallback($config = [])
+    {
+        $enabled = self::DEFAULT_ENABLED;
+        if (!empty($config['api_provider'])
+            && !empty($config['service'])
+            && !empty($config['version'])
+        ) {
+            $provider = $config['api_provider'];
+            $apiData = $provider('api', $config['service'], $config['version']);
+            if (!empty($apiData['operations'])) {
+                foreach ($apiData['operations'] as $operation) {
+                    if (!empty($operation['endpointdiscovery']['required'])) {
+                        $enabled = true;
+                    }
+                }
+            }
+        }
+
+        return function () use ($enabled) {
+            return Promise\promise_for(
+                new Configuration(
+                    $enabled,
+                    self::DEFAULT_CACHE_LIMIT
+                )
+            );
+        };
+    }
+
+    /**
+     * Config provider that creates config using a config file whose location
+     * is specified by an environment variable 'AWS_CONFIG_FILE', defaulting to
+     * ~/.aws/config if not specified
+     *
+     * @param string|null $profile  Profile to use. If not specified will use
+     *                              the "default" profile.
+     * @param string|null $filename If provided, uses a custom filename rather
+     *                              than looking in the default directory.
+     * @param int         $cacheLimit
+     *
+     * @return callable
+     */
+    public static function ini(
+        $profile = null,
+        $filename = null,
+        $cacheLimit = self::DEFAULT_CACHE_LIMIT
+    ) {
+        $filename = $filename ?: (self::getDefaultConfigFilename());
+        $profile = $profile ?: (getenv(self::ENV_PROFILE) ?: 'default');
+
+        return function () use ($profile, $filename, $cacheLimit) {
+            if (!is_readable($filename)) {
+                return self::reject("Cannot read configuration from $filename");
+            }
+            $data = \Aws\parse_ini_file($filename, true);
+            if ($data === false) {
+                return self::reject("Invalid config file: $filename");
+            }
+            if (!isset($data[$profile])) {
+                return self::reject("'$profile' not found in config file");
+            }
+            if (!isset($data[$profile]['endpoint_discovery_enabled'])) {
+                return self::reject("Required endpoint discovery config values 
+                    not present in INI profile '{$profile}' ({$filename})");
+            }
+
+            return Promise\promise_for(
+                new Configuration(
+                    $data[$profile]['endpoint_discovery_enabled'],
+                    $cacheLimit
+                )
+            );
+        };
+    }
+
+    /**
+     * Unwraps a configuration object in whatever valid form it is in,
+     * always returning a ConfigurationInterface object.
+     *
+     * @param  mixed $config
+     * @return ConfigurationInterface
+     * @throws \InvalidArgumentException
+     */
+    public static function unwrap($config)
+    {
+        if (is_callable($config)) {
+            $config = $config();
+        }
+        if ($config instanceof PromiseInterface) {
+            $config = $config->wait();
+        }
+        if ($config instanceof ConfigurationInterface) {
+            return $config;
+        } elseif (is_array($config) && isset($config['enabled'])) {
+            if (isset($config['cache_limit'])) {
+                return new Configuration(
+                    $config['enabled'],
+                    $config['cache_limit']
+                );
+            }
+            return new Configuration(
+                $config['enabled'],
+                self::DEFAULT_CACHE_LIMIT
+            );
+        }
+
+        throw new \InvalidArgumentException('Not a valid endpoint_discovery '
+            . 'configuration argument.');
+    }
+}

aws/Aws/EndpointDiscovery/EndpointDiscoveryMiddleware.php

@@ -0,0 +1,420 @@
+<?php
+namespace Aws\EndpointDiscovery;
+
+use Aws\AwsClient;
+use Aws\CacheInterface;
+use Aws\CommandInterface;
+use Aws\Credentials\CredentialsInterface;
+use Aws\Exception\AwsException;
+use Aws\Exception\UnresolvedEndpointException;
+use Aws\LruArrayCache;
+use Aws\Middleware;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\UriInterface;
+
+class EndpointDiscoveryMiddleware
+{
+    /**
+     * @var CacheInterface
+     */
+    private static $cache;
+    private static $discoveryCooldown = 60;
+
+    private $args;
+    private $client;
+    private $config;
+    private $discoveryTimes = [];
+    private $nextHandler;
+    private $service;
+
+    public static function wrap(
+        $client,
+        $args,
+        $config
+    ) {
+        return function (callable $handler) use (
+            $client,
+            $args,
+            $config
+        ) {
+            return new static(
+                $handler,
+                $client,
+                $args,
+                $config
+            );
+        };
+    }
+
+    public function __construct(
+        callable $handler,
+        AwsClient $client,
+        array $args,
+        $config
+    ) {
+        $this->nextHandler = $handler;
+        $this->client = $client;
+        $this->args = $args;
+        $this->service = $client->getApi();
+        $this->config = $config;
+    }
+
+    public function __invoke(CommandInterface $cmd, RequestInterface $request)
+    {
+        $nextHandler = $this->nextHandler;
+        $op = $this->service->getOperation($cmd->getName())->toArray();
+
+        // Continue only if endpointdiscovery trait is set
+        if (isset($op['endpointdiscovery'])) {
+            $config = ConfigurationProvider::unwrap($this->config);
+            $isRequired = !empty($op['endpointdiscovery']['required']);
+
+            if ($isRequired && !($config->isEnabled())) {
+                throw new UnresolvedEndpointException('This operation '
+                    . 'requires the use of endpoint discovery, but this has '
+                    . 'been disabled in the configuration. Enable endpoint '
+                    . 'discovery or use a different operation.');
+            }
+
+            // Continue only if enabled by config
+            if ($config->isEnabled()) {
+                if (isset($op['endpointoperation'])) {
+                    throw new UnresolvedEndpointException('This operation is '
+                        . 'contradictorily marked both as using endpoint discovery '
+                        . 'and being the endpoint discovery operation. Please '
+                        . 'verify the accuracy of your model files.');
+                }
+
+                // Original endpoint may be used if discovery optional
+                $originalUri = $request->getUri();
+
+                $identifiers = $this->getIdentifiers($op);
+
+                $cacheKey = $this->getCacheKey(
+                    $this->client->getCredentials()->wait(),
+                    $cmd,
+                    $identifiers
+                );
+
+                // Check/create cache
+                if (!isset(self::$cache)) {
+                    self::$cache = new LruArrayCache($config->getCacheLimit());
+                }
+
+                if (empty($endpointList = self::$cache->get($cacheKey))) {
+                    $endpointList = new EndpointList([]);
+                }
+                $endpoint = $endpointList->getActive();
+
+                // Retrieve endpoints if there is no active endpoint
+                if (empty($endpoint)) {
+                    try {
+                        $endpoint = $this->discoverEndpoint(
+                            $cacheKey,
+                            $cmd,
+                            $identifiers
+                        );
+                    } catch (\Exception $e) {
+                        // Use cached endpoint, expired or active, if any remain
+                        $endpoint = $endpointList->getEndpoint();
+
+                        if (empty($endpoint)) {
+                            return $this->handleDiscoveryException(
+                                $isRequired,
+                                $originalUri,
+                                $e,
+                                $cmd,
+                                $request
+                            );
+                        }
+                    }
+                }
+
+                $request = $this->modifyRequest($request, $endpoint);
+
+                $g = function ($value) use (
+                    $cacheKey,
+                    $cmd,
+                    $identifiers,
+                    $isRequired,
+                    $originalUri,
+                    $request,
+                    &$endpoint,
+                    &$g
+                ) {
+                    if ($value instanceof AwsException
+                        && (
+                            $value->getAwsErrorCode() == 'InvalidEndpointException'
+                            || $value->getStatusCode() == 421
+                        )
+                    ) {
+                        return $this->handleInvalidEndpoint(
+                            $cacheKey,
+                            $cmd,
+                            $identifiers,
+                            $isRequired,
+                            $originalUri,
+                            $request,
+                            $value,
+                            $endpoint,
+                            $g
+                        );
+                    }
+                    
+                    return $value;
+                };
+
+                return $nextHandler($cmd, $request)->otherwise($g);
+            }
+        }
+
+        return $nextHandler($cmd, $request);
+    }
+
+    private function discoverEndpoint(
+        $cacheKey,
+        CommandInterface $cmd,
+        array $identifiers
+    ) {
+        $discCmd = $this->getDiscoveryCommand($cmd, $identifiers);
+        $this->discoveryTimes[$cacheKey] = time();
+        $result = $this->client->execute($discCmd);
+
+        if (isset($result['Endpoints'])) {
+            $endpointData = [];
+            foreach ($result['Endpoints'] as $datum) {
+                $endpointData[$datum['Address']] = time()
+                    + ($datum['CachePeriodInMinutes'] * 60);
+            }
+            $endpointList = new EndpointList($endpointData);
+            self::$cache->set($cacheKey, $endpointList);
+            return $endpointList->getEndpoint();
+        }
+
+        throw new UnresolvedEndpointException('The endpoint discovery operation '
+            . 'yielded a response that did not contain properly formatted '
+            . 'endpoint data.');
+    }
+
+    private function getCacheKey(
+        CredentialsInterface $creds,
+        CommandInterface $cmd,
+        array $identifiers
+    ) {
+        $key = $this->service->getServiceName() . '_' . $creds->getAccessKeyId();
+        if (!empty($identifiers)) {
+            $key .= '_' . $cmd->getName();
+            foreach ($identifiers as $identifier) {
+                $key .= "_{$cmd[$identifier]}";
+            }
+        }
+
+        return $key;
+    }
+
+    private function getDiscoveryCommand(
+        CommandInterface $cmd,
+        array $identifiers
+    ) {
+        foreach ($this->service->getOperations() as $op) {
+            if (isset($op['endpointoperation'])) {
+                $endpointOperation = $op->toArray()['name'];
+                break;
+            }
+        }
+
+        if (!isset($endpointOperation)) {
+            throw new UnresolvedEndpointException('This command is set to use '
+                . 'endpoint discovery, but no endpoint discovery operation was '
+                . 'found. Please verify the accuracy of your model files.');
+        }
+
+        $params = [];
+        if (!empty($identifiers)) {
+            $params['Operation'] = $cmd->getName();
+            $params['Identifiers'] = [];
+            foreach ($identifiers as $identifier) {
+                $params['Identifiers'][$identifier] = $cmd[$identifier];
+            }
+        }
+        $command = $this->client->getCommand($endpointOperation, $params);
+        $command->getHandlerList()->appendBuild(
+            Middleware::mapRequest(function (RequestInterface $r) {
+                return $r->withHeader(
+                    'x-amz-api-version',
+                    $this->service->getApiVersion()
+                );
+            }),
+            'x-amz-api-version-header'
+        );
+
+        return $command;
+    }
+
+    private function getIdentifiers(array $operation)
+    {
+        $inputShape = $this->service->getShapeMap()
+            ->resolve($operation['input'])
+            ->toArray();
+        $identifiers = [];
+        foreach ($inputShape['members'] as $key => $member) {
+            if (!empty($member['endpointdiscoveryid'])) {
+                $identifiers[] = $key;
+            }
+        }
+        return $identifiers;
+    }
+
+    private function handleDiscoveryException(
+        $isRequired,
+        $originalUri,
+        \Exception $e,
+        CommandInterface $cmd,
+        RequestInterface $request
+    ) {
+        // If no cached endpoints and discovery required,
+        // throw exception
+        if ($isRequired) {
+            $message = 'The endpoint required for this service is currently '
+                . 'unable to be retrieved, and your request can not be fulfilled '
+                . 'unless you manually specify an endpoint.';
+            throw new AwsException(
+                $message,
+                $cmd,
+                [
+                    'code' => 'EndpointDiscoveryException',
+                    'message' => $message
+                ],
+                $e
+            );
+        }
+
+        // If discovery isn't required, use original endpoint
+        return $this->useOriginalUri(
+            $originalUri,
+            $cmd,
+            $request
+        );
+    }
+
+    private function handleInvalidEndpoint(
+        $cacheKey,
+        $cmd,
+        $identifiers,
+        $isRequired,
+        $originalUri,
+        $request,
+        $value,
+        &$endpoint,
+        &$g
+    ) {
+        $nextHandler = $this->nextHandler;
+        $endpointList = self::$cache->get($cacheKey);
+        if ($endpointList instanceof EndpointList) {
+
+            // Remove invalid endpoint from cached list
+            $endpointList->remove($endpoint);
+
+            // If possible, get another cached endpoint
+            $newEndpoint = $endpointList->getEndpoint();
+        }
+        if (empty($newEndpoint)) {
+
+            // If no more cached endpoints, make discovery call
+            // if none made within cooldown for given key
+            if (time() - $this->discoveryTimes[$cacheKey]
+                < self::$discoveryCooldown
+            ) {
+
+                // If no more cached endpoints and it's required,
+                // fail with original exception
+                if ($isRequired) {
+                    return $value;
+                }
+
+                // Use original endpoint if not required
+                return $this->useOriginalUri(
+                    $originalUri,
+                    $cmd,
+                    $request
+                );
+            }
+
+            $newEndpoint = $this->discoverEndpoint(
+                $cacheKey,
+                $cmd,
+                $identifiers
+            );
+        }
+        $endpoint = $newEndpoint;
+        $request = $this->modifyRequest($request, $endpoint);
+        return $nextHandler($cmd, $request)->otherwise($g);
+    }
+
+    private function modifyRequest(RequestInterface $request, $endpoint)
+    {
+        $parsed = $this->parseEndpoint($endpoint);
+        if (!empty($request->getHeader('User-Agent'))) {
+            $userAgent = $request->getHeader('User-Agent')[0];
+            if (strpos($userAgent, 'endpoint-discovery') === false) {
+                $userAgent = $userAgent . ' endpoint-discovery';
+            }
+        } else {
+            $userAgent = 'endpoint-discovery';
+        }
+
+        return $request
+            ->withUri(
+                $request->getUri()
+                    ->withHost($parsed['host'])
+                    ->withPath($parsed['path'])
+            )
+            ->withHeader('User-Agent', $userAgent);
+    }
+
+    /**
+     * Parses an endpoint returned from the discovery API into an array with
+     * 'host' and 'path' keys.
+     *
+     * @param $endpoint
+     * @return array
+     */
+    private function parseEndpoint($endpoint)
+    {
+        $parsed = parse_url($endpoint);
+
+        // parse_url() will correctly parse full URIs with schemes
+        if (isset($parsed['host'])) {
+            return $parsed;
+        }
+
+        // parse_url() will put host & path in 'path' if scheme is not provided
+        if (isset($parsed['path'])) {
+            $split = explode('/', $parsed['path'], 2);
+            $parsed['host'] = $split[0];
+            if (isset($split[1])) {
+                $parsed['path'] = $split[1];
+            } else {
+                $parsed['path'] = '';
+            }
+            return $parsed;
+        }
+
+        throw new UnresolvedEndpointException("The supplied endpoint '"
+            . "{$endpoint}' is invalid.");
+    }
+
+    private function useOriginalUri(
+        UriInterface $uri,
+        CommandInterface $cmd,
+        RequestInterface $request
+    ) {
+        $nextHandler = $this->nextHandler;
+        $endpoint = $uri->getHost() . $uri->getPath();
+        $request = $this->modifyRequest(
+            $request,
+            $endpoint
+        );
+        return $nextHandler($cmd, $request);
+    }
+}

aws/Aws/EndpointDiscovery/EndpointList.php

@@ -0,0 +1,85 @@
+<?php
+namespace Aws\EndpointDiscovery;
+
+class EndpointList
+{
+    private $active;
+    private $expired = [];
+
+    public function __construct(array $endpoints)
+    {
+        $this->active = $endpoints;
+        reset($this->active);
+    }
+
+    /**
+     * Gets an active (unexpired) endpoint. Returns null if none found.
+     *
+     * @return null|string
+     */
+    public function getActive()
+    {
+        if (count($this->active) < 1) {
+            return null;
+        }
+        while (time() > current($this->active)) {
+            $key = key($this->active);
+            $this->expired[$key] = current($this->active);
+            $this->increment($this->active);
+            unset($this->active[$key]);
+            if (count($this->active) < 1) {
+                return null;
+            }
+        }
+        $active = key($this->active);
+        $this->increment($this->active);
+        return $active;
+    }
+
+    /**
+     * Gets an active endpoint if possible, then an expired endpoint if possible.
+     * Returns null if no endpoints found.
+     *
+     * @return null|string
+     */
+    public function getEndpoint()
+    {
+        if (!empty($active = $this->getActive())) {
+            return $active;
+        }
+        return $this->getExpired();
+    }
+
+    /**
+     * Removes an endpoint from both lists.
+     *
+     * @param string $key
+     */
+    public function remove($key)
+    {
+        unset($this->active[$key]);
+        unset($this->expired[$key]);
+    }
+
+    /**
+     * Get an expired endpoint. Returns null if none found.
+     *
+     * @return null|string
+     */
+    private function getExpired()
+    {
+        if (count($this->expired) < 1) {
+            return null;
+        }
+        $expired = key($this->expired);
+        $this->increment($this->expired);
+        return $expired;
+    }
+
+    private function increment(&$array)
+    {
+        if (next($array) === false) {
+            reset($array);
+        }
+    }
+}

aws/Aws/EndpointDiscovery/Exception/ConfigurationException.php

@@ -0,0 +1,14 @@
+<?php
+namespace Aws\EndpointDiscovery\Exception;
+
+use Aws\HasMonitoringEventsTrait;
+use Aws\MonitoringEventsInterface;
+
+/**
+ * Represents an error interacting with configuration for endpoint discovery
+ */
+class ConfigurationException extends \RuntimeException implements
+    MonitoringEventsInterface
+{
+    use HasMonitoringEventsTrait;
+}