spaces.php

aws/Aws/Endpoint/EndpointProvider.php

@@ -0,0 +1,96 @@
+<?php
+namespace Aws\Endpoint;
+
+use Aws\Exception\UnresolvedEndpointException;
+
+/**
+ * Endpoint providers.
+ *
+ * An endpoint provider is a function that accepts a hash of endpoint options,
+ * including but not limited to "service" and "region" key value pairs. The
+ * endpoint provider function returns a hash of endpoint data, which MUST
+ * include an "endpoint" key value pair that represents the resolved endpoint
+ * or NULL if an endpoint cannot be determined.
+ *
+ * You can wrap your calls to an endpoint provider with the
+ * {@see EndpointProvider::resolve} function to ensure that an endpoint hash is
+ * created. If an endpoint hash is not created, then the resolve() function
+ * will throw an {@see Aws\Exception\UnresolvedEndpointException}.
+ *
+ *     use Aws\Endpoint\EndpointProvider;
+ *     $provider = EndpointProvider::defaultProvider();
+ *     // Returns an array or NULL.
+ *     $endpoint = $provider(['service' => 'ec2', 'region' => 'us-west-2']);
+ *     // Returns an endpoint array or throws.
+ *     $endpoint = EndpointProvider::resolve($provider, [
+ *         'service' => 'ec2',
+ *         'region'  => 'us-west-2'
+ *     ]);
+ *
+ * You can compose multiple providers into a single provider using
+ * {@see Aws\or_chain}. This function accepts providers as arguments and
+ * returns a new function that will invoke each provider until a non-null value
+ * is returned.
+ *
+ *     $a = function (array $args) {
+ *         if ($args['region'] === 'my-test-region') {
+ *             return ['endpoint' => 'http://localhost:123/api'];
+ *         }
+ *     };
+ *     $b = EndpointProvider::defaultProvider();
+ *     $c = \Aws\or_chain($a, $b);
+ *     $config = ['service' => 'ec2', 'region' => 'my-test-region'];
+ *     $res = $c($config);  // $a handles this.
+ *     $config['region'] = 'us-west-2';
+ *     $res = $c($config); // $b handles this.
+ */
+class EndpointProvider
+{
+    /**
+     * Resolves and endpoint provider and ensures a non-null return value.
+     *
+     * @param callable $provider Provider function to invoke.
+     * @param array    $args     Endpoint arguments to pass to the provider.
+     *
+     * @return array
+     * @throws UnresolvedEndpointException
+     */
+    public static function resolve(callable $provider, array $args = [])
+    {
+        $result = $provider($args);
+        if (is_array($result)) {
+            return $result;
+        }
+
+        throw new UnresolvedEndpointException(
+            'Unable to resolve an endpoint using the provider arguments: '
+            . json_encode($args) . '. Note: you can provide an "endpoint" '
+            . 'option to a client constructor to bypass invoking an endpoint '
+            . 'provider.');
+    }
+
+    /**
+     * Creates and returns the default SDK endpoint provider.
+     *
+     * @deprecated Use an instance of \Aws\Endpoint\Partition instead.
+     *
+     * @return callable
+     */
+    public static function defaultProvider()
+    {
+        return PartitionEndpointProvider::defaultProvider();
+    }
+
+    /**
+     * Creates and returns an endpoint provider that uses patterns from an
+     * array.
+     *
+     * @param array $patterns Endpoint patterns
+     *
+     * @return callable
+     */
+    public static function patterns(array $patterns)
+    {
+        return new PatternEndpointProvider($patterns);
+    }
+}

aws/Aws/Endpoint/Partition.php

@@ -0,0 +1,183 @@
+<?php
+namespace Aws\Endpoint;
+
+use ArrayAccess;
+use Aws\HasDataTrait;
+use InvalidArgumentException as Iae;
+
+/**
+ * Default implementation of an AWS partition.
+ */
+final class Partition implements ArrayAccess, PartitionInterface
+{
+    use HasDataTrait;
+
+    /**
+     * The partition constructor accepts the following options:
+     *
+     * - `partition`: (string, required) The partition name as specified in an
+     *   ARN (e.g., `aws`)
+     * - `partitionName`: (string) The human readable name of the partition
+     *   (e.g., "AWS Standard")
+     * - `dnsSuffix`: (string, required) The DNS suffix of the partition. This
+     *   value is used to determine how endpoints in the partition are resolved.
+     * - `regionRegex`: (string) A PCRE regular expression that specifies the
+     *   pattern that region names in the endpoint adhere to.
+     * - `regions`: (array, required) A map of the regions in the partition.
+     *   Each key is the region as present in a hostname (e.g., `us-east-1`),
+     *   and each value is a structure containing region information.
+     * - `defaults`: (array) A map of default key value pairs to apply to each
+     *   endpoint of the partition. Any value in an `endpoint` definition will
+     *   supersede any values specified in `defaults`.
+     * - `services`: (array, required) A map of service endpoint prefix name
+     *   (the value found in a hostname) to information about the service.
+     *
+     * @param array $definition
+     *
+     * @throws Iae if any required options are missing
+     */
+    public function __construct(array $definition)
+    {
+        foreach (['partition', 'regions', 'services', 'dnsSuffix'] as $key) {
+            if (!isset($definition[$key])) {
+                throw new Iae("Partition missing required $key field");
+            }
+        }
+
+        $this->data = $definition;
+    }
+
+    public function getName()
+    {
+        return $this->data['partition'];
+    }
+
+    public function isRegionMatch($region, $service)
+    {
+        if (isset($this->data['regions'][$region])
+            || isset($this->data['services'][$service]['endpoints'][$region])
+        ) {
+            return true;
+        }
+
+        if (isset($this->data['regionRegex'])) {
+            return (bool) preg_match(
+                "@{$this->data['regionRegex']}@",
+                $region
+            );
+        }
+
+        return false;
+    }
+
+    public function getAvailableEndpoints(
+        $service,
+        $allowNonRegionalEndpoints = false
+    ) {
+        if ($this->isServicePartitionGlobal($service)) {
+            return [$this->getPartitionEndpoint($service)];
+        }
+
+        if (isset($this->data['services'][$service]['endpoints'])) {
+            $serviceRegions = array_keys(
+                $this->data['services'][$service]['endpoints']
+            );
+
+            return $allowNonRegionalEndpoints
+                ? $serviceRegions
+                : array_intersect($serviceRegions, array_keys(
+                    $this->data['regions']
+                ));
+        }
+
+        return [];
+    }
+
+    public function __invoke(array $args = [])
+    {
+        $service = isset($args['service']) ? $args['service'] : '';
+        $region = isset($args['region']) ? $args['region'] : '';
+        $scheme = isset($args['scheme']) ? $args['scheme'] : 'https';
+        $data = $this->getEndpointData($service, $region);
+
+        return [
+            'endpoint' => "{$scheme}://" . $this->formatEndpoint(
+                    isset($data['hostname']) ? $data['hostname'] : '',
+                    $service,
+                    $region
+                ),
+            'signatureVersion' => $this->getSignatureVersion($data),
+            'signingRegion' => isset($data['credentialScope']['region'])
+                ? $data['credentialScope']['region']
+                : $region,
+            'signingName' => isset($data['credentialScope']['service'])
+                ? $data['credentialScope']['service']
+                : $service,
+        ];
+    }
+
+    private function getEndpointData($service, $region)
+    {
+
+        $resolved = $this->resolveRegion($service, $region);
+        $data = isset($this->data['services'][$service]['endpoints'][$resolved])
+            ? $this->data['services'][$service]['endpoints'][$resolved]
+            : [];
+        $data += isset($this->data['services'][$service]['defaults'])
+            ? $this->data['services'][$service]['defaults']
+            : [];
+        $data += isset($this->data['defaults'])
+            ? $this->data['defaults']
+            : [];
+
+        return $data;
+    }
+
+    private function getSignatureVersion(array $data)
+    {
+        static $supportedBySdk = [
+            's3v4',
+            'v4',
+            'anonymous',
+        ];
+
+        $possibilities = array_intersect(
+            $supportedBySdk,
+            isset($data['signatureVersions'])
+                ? $data['signatureVersions']
+                : ['v4']
+        );
+
+        return array_shift($possibilities);
+    }
+
+    private function resolveRegion($service, $region)
+    {
+        if ($this->isServicePartitionGlobal($service)) {
+            return $this->getPartitionEndpoint($service);
+        }
+
+        return $region;
+    }
+
+    private function isServicePartitionGlobal($service)
+    {
+        return isset($this->data['services'][$service]['isRegionalized'])
+            && false === $this->data['services'][$service]['isRegionalized']
+            && isset($this->data['services'][$service]['partitionEndpoint']);
+    }
+
+    private function getPartitionEndpoint($service)
+    {
+        return $this->data['services'][$service]['partitionEndpoint'];
+    }
+
+    private function formatEndpoint($template, $service, $region)
+    {
+        return strtr($template, [
+            '{service}' => $service,
+            '{region}' => $region,
+            '{dnsSuffix}' => $this->data['dnsSuffix'],
+        ]);
+    }
+}

aws/Aws/Endpoint/PartitionEndpointProvider.php

@@ -0,0 +1,77 @@
+<?php
+namespace Aws\Endpoint;
+
+class PartitionEndpointProvider
+{
+    /** @var Partition[] */
+    private $partitions;
+    /** @var string */
+    private $defaultPartition;
+
+    public function __construct(array $partitions, $defaultPartition = 'aws')
+    {
+        $this->partitions = array_map(function (array $definition) {
+            return new Partition($definition);
+        }, array_values($partitions));
+        $this->defaultPartition = $defaultPartition;
+    }
+
+    public function __invoke(array $args = [])
+    {
+        $partition = $this->getPartition(
+            isset($args['region']) ? $args['region'] : '',
+            isset($args['service']) ? $args['service'] : ''
+        );
+
+        return $partition($args);
+    }
+
+    /**
+     * Returns the partition containing the provided region or the default
+     * partition if no match is found.
+     *
+     * @param string $region
+     * @param string $service
+     *
+     * @return Partition
+     */
+    public function getPartition($region, $service)
+    {
+        foreach ($this->partitions as $partition) {
+            if ($partition->isRegionMatch($region, $service)) {
+                return $partition;
+            }
+        }
+
+        return $this->getPartitionByName($this->defaultPartition);
+    }
+
+    /**
+     * Returns the partition with the provided name or null if no partition with
+     * the provided name can be found.
+     *
+     * @param string $name
+     *
+     * @return Partition|null
+     */
+    public function getPartitionByName($name)
+    {
+        foreach ($this->partitions as $partition) {
+            if ($name === $partition->getName()) {
+                return $partition;
+            }
+        }
+    }
+
+    /**
+     * Creates and returns the default SDK partition provider.
+     *
+     * @return PartitionEndpointProvider
+     */
+    public static function defaultProvider()
+    {
+        $data = \Aws\load_compiled_json(dirname(__FILE__) . '/../data/endpoints.json');
+
+        return new self($data['partitions']);
+    }
+}

aws/Aws/Endpoint/PartitionInterface.php

@@ -0,0 +1,56 @@
+<?php
+namespace Aws\Endpoint;
+
+/**
+ * Represents a section of the AWS cloud.
+ */
+interface PartitionInterface
+{
+    /**
+     * Returns the partition's short name, e.g., 'aws,' 'aws-cn,' or
+     * 'aws-us-gov.'
+     *
+     * @return string
+     */
+    public function getName();
+
+    /**
+     * Determine if this partition contains the provided region. Include the
+     * name of the service to inspect non-regional endpoints
+     *
+     * @param string $region
+     * @param string $service
+     *
+     * @return bool
+     */
+    public function isRegionMatch($region, $service);
+
+    /**
+     * Return the endpoints supported by a given service.
+     *
+     * @param string    $service                    Identifier of the service
+     *                                              whose endpoints should be
+     *                                              listed (e.g., 's3' or 'ses')
+     * @param bool      $allowNonRegionalEndpoints  Set to `true` to include
+     *                                              endpoints that are not AWS
+     *                                              regions (e.g., 'local' for
+     *                                              DynamoDB or
+     *                                              'fips-us-gov-west-1' for S3)
+     * 
+     * @return string[]
+     */
+    public function getAvailableEndpoints(
+        $service,
+        $allowNonRegionalEndpoints = false
+    );
+
+    /**
+     * A partition must be invokable as an endpoint provider.
+     *
+     * @see EndpointProvider
+     * 
+     * @param array $args
+     * @return array
+     */
+    public function __invoke(array $args = []);
+}

aws/Aws/Endpoint/PatternEndpointProvider.php

@@ -0,0 +1,51 @@
+<?php
+namespace Aws\Endpoint;
+
+/**
+ * Provides endpoints based on an endpoint pattern configuration array.
+ */
+class PatternEndpointProvider
+{
+    /** @var array */
+    private $patterns;
+
+    /**
+     * @param array $patterns Hash of endpoint patterns mapping to endpoint
+     *                        configurations.
+     */
+    public function __construct(array $patterns)
+    {
+        $this->patterns = $patterns;
+    }
+
+    public function __invoke(array $args = [])
+    {
+        $service = isset($args['service']) ? $args['service'] : '';
+        $region = isset($args['region']) ? $args['region'] : '';
+        $keys = ["{$region}/{$service}", "{$region}/*", "*/{$service}", "*/*"];
+
+        foreach ($keys as $key) {
+            if (isset($this->patterns[$key])) {
+                return $this->expand(
+                    $this->patterns[$key],
+                    isset($args['scheme']) ? $args['scheme'] : 'https',
+                    $service,
+                    $region
+                );
+            }
+        }
+
+        return null;
+    }
+
+    private function expand(array $config, $scheme, $service, $region)
+    {
+        $config['endpoint'] = $scheme . '://'
+            . strtr($config['endpoint'], [
+                '{service}' => $service,
+                '{region}'  => $region
+            ]);
+
+        return $config;
+    }
+}