Merge pull request aws#470 from aws/add-endpoint-forward-compat

Add support for "endpoint" for forward compat w/ v3

docs/configuration.rst

@@ -188,9 +188,9 @@ Options                   Description
 ``region``                Region name (e.g., 'us-east-1', 'us-west-1', 'us-west-2', 'eu-west-1', etc.).
                           See :ref:`specify_region`.
 
-``scheme``                URI Scheme of the base URL (e.g.. 'https', 'http') used when base_url is not supplied.
+``scheme``                URI Scheme of the base URL (e.g.. 'https', 'http') used when endpoint is not supplied.
 
-``base_url``              Allows you to specify a custom endpoint instead of have the SDK build one automatically from
+``endpoint``              Allows you to specify a custom endpoint instead of have the SDK build one automatically from
                           the region and scheme.
 
 ``signature``             Overrides the signature used by the client. Clients will always choose an appropriate default
@@ -263,7 +263,7 @@ Here's an example of creating an Amazon DynamoDB client that uses the ``us-west-
 Setting a custom endpoint
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can specify a completely customized endpoint for a client using the client's ``base_url`` option. If the client you
+You can specify a completely customized endpoint for a client using the client's ``endpoint`` option. If the client you
 are using requires a region, then must still specify the name of the region using the ``region`` option. Setting a
 custom endpoint can be useful if you're using a mock web server that emulates a web service, you're testing against a
 private beta endpoint, or you are trying to a use a new region not yet supported by the SDK.
@@ -278,7 +278,7 @@ Here's an example of creating an Amazon DynamoDB client that uses a completely c
 
     // Create a client that that contacts a completely customized base URL
     $client = DynamoDbClient::factory(array(
-        'base_url' => 'http://my-custom-url',
+        'endpoint' => 'http://my-custom-url',
         'region'   => 'my-region-1',
         'key'      => 'abc',
         'secret'   => '123'

docs/service-cloudsearchdomain.rst

@@ -23,11 +23,11 @@ Similar to the way other service clients are used, you can instantiate the ``Clo
 
     $client = CloudSearchDomainClient::factory(array(
         'profile'  => '<profile in your aws credentials file>',
-        'base_url' => '<your cloudsearch domain endpoint>'
+        'endpoint' => '<your cloudsearch domain endpoint>'
     ));
 
 The ``CloudSearchDomainClient`` is unlike other clients, because it does not require you to provide a region. Instead,
-you must provide the ``base_url`` option, which represents the domain's endpoint. Domain endpoints are unique to each
+you must provide the ``endpoint`` option, which represents the domain's endpoint. Domain endpoints are unique to each
 domain, and you can get it using the `DescribeDomains operation
 <http://docs.aws.amazon.com/aws-sdk-php/latest/class-Aws.CloudSearch.CloudSearchClient.html#_describeDomains>`_ of the
 :doc:`Amazon CloudSearch configuration client<service-cloudsearch>`.
@@ -49,13 +49,13 @@ all clients so that you only have to specify your settings once.
     // Get the client from the builder
     $client = $aws->get('CloudSearchDomain');
 
-**Note:** This assumes that your configuration file has been setup to include the ``base_url`` option for the
+**Note:** This assumes that your configuration file has been setup to include the ``endpoint`` option for the
 CloudSearch Domain service. If it is not, you can provide it manually when calling ``get()``.
 
 .. code-block:: php
 
     $client = $aws->get('cloudsearchdomain', array(
-        'base_url' => '<your cloudsearch domain endpoint>'
+        'endpoint' => '<your cloudsearch domain endpoint>'
     ));
 
 For more information about configuration files, see :doc:`configuration`.

src/Aws/CloudSearch/CloudSearchClient.php

@@ -95,8 +95,8 @@ public static function factory($config = array())
      */
     public function getDomainClient($domainName, array $config = array())
     {
-        // Determine the Domain client's base_url
-        $config['base_url'] = $this->describeDomains(array(
+        // Determine the Domain client's endpoint
+        $config['endpoint'] = $this->describeDomains(array(
             'DomainNames' => array($domainName)
         ))->getPath('DomainStatusList/0/SearchService/Endpoint');
 

src/Aws/CloudSearchDomain/CloudSearchDomainClient.php

@@ -3,7 +3,6 @@
 namespace Aws\CloudSearchDomain;
 
 use Aws\Common\Client\AbstractClient;
-use Aws\Common\Credentials\CredentialsInterface;
 use Aws\Common\Enum\ClientOptions as Options;
 use Aws\Common\Exception\BadMethodCallException;
 use Guzzle\Common\Collection;
@@ -26,7 +25,7 @@ class CloudSearchDomainClient extends AbstractClient
     /**
      * Factory method to create a new Amazon CloudSearch Domain client using an array of configuration options.
      *
-     * You must provide the `base_url` option for this client, but credentials and `region` are not needed.
+     * You must provide the `endpoint` option for this client, but credentials and `region` are not needed.
      *
      * @param array|Collection $config Client configuration data
      *

src/Aws/CloudSearchDomain/CloudSearchDomainClientBuilder.php

@@ -5,13 +5,11 @@
 use Aws\Common\Client\ClientBuilder;
 use Aws\Common\Client\ThrottlingErrorChecker;
 use Aws\Common\Client\UserAgentListener;
-use Aws\Common\Credentials\Credentials;
 use Aws\Common\Enum\ClientOptions as Options;
 use Aws\Common\Exception\ExceptionListener;
 use Aws\Common\Exception\InvalidArgumentException;
 use Aws\Common\Exception\NamespaceExceptionFactory;
 use Aws\Common\Exception\Parser\JsonQueryExceptionParser;
-use Aws\Common\Signature\SignatureV4;
 use Guzzle\Common\Collection;
 use Guzzle\Http\Url;
 use Guzzle\Plugin\Backoff\BackoffPlugin;
@@ -41,18 +39,21 @@ public function build()
             $this->configRequirements
         );
 
-        // Make sure base_url is correctly set
-        if (!($baseUrl = $config->get(Options::BASE_URL))) {
+        $endpoint = $config['endpoint'] ?: $config[Options::BASE_URL];
+
+        // Make sure endpoint is correctly set
+        if (!$endpoint) {
             throw new InvalidArgumentException('You must provide the endpoint for the CloudSearch domain.');
-        } elseif (strpos($baseUrl, 'http') !== 0) {
-            $config->set(Options::BASE_URL, Url::buildUrl(array(
-                'scheme' => $config->get(Options::SCHEME),
-                'host'   => $baseUrl,
-            )));
+        }
+
+        if (strpos($endpoint, 'http') !== 0) {
+            $endpoint = $config[Options::SCHEME] . '://' . $endpoint;
+            $config['endpoint'] = $endpoint;
+            $config[Options::BASE_URL] = $endpoint;
         }
 
         // Determine the region from the endpoint
-        $endpoint = Url::factory($config->get(Options::BASE_URL));
+        $endpoint = Url::factory($endpoint);
         list(,$region) = explode('.', $endpoint->getHost());
         $config[Options::REGION] = $config[Options::SIGNATURE_REGION] = $region;
 

src/Aws/Common/Client/ClientBuilder.php

@@ -380,37 +380,8 @@ protected function updateConfigFromDescription(Collection $config)
             $this->setIteratorsConfig($iterators);
         }
 
-        // Make sure a valid region is set
-        $region = $config->get(Options::REGION);
-        $global = $description->getData('globalEndpoint');
-
-        if (!$global && !$region) {
-            throw new InvalidArgumentException(
-                'A region is required when using ' . $description->getData('serviceFullName')
-            );
-        } elseif ($global && !$region) {
-            $region = 'us-east-1';
-            $config->set(Options::REGION, 'us-east-1');
-        }
-
-        if (!$config->get(Options::BASE_URL)) {
-            $endpoint = call_user_func(
-                $config->get('endpoint_provider'),
-                array(
-                    'scheme'  => $config->get(Options::SCHEME),
-                    'region'  => $region,
-                    'service' => $config->get(Options::SERVICE)
-                )
-            );
-            $config->set(Options::BASE_URL, $endpoint['endpoint']);
-
-            // Set a signature if one was not explicitly provided.
-            if (!$config->hasKey(Options::SIGNATURE)
-                && isset($endpoint['signatureVersion'])
-            ) {
-                $config->set(Options::SIGNATURE, $endpoint['signatureVersion']);
-            }
-        }
+        $this->handleRegion($config);
+        $this->handleEndpoint($config);
 
         return $description;
     }
@@ -475,4 +446,51 @@ protected function getCredentials(Collection $config)
 
         return $credentials;
     }
+
+    private function handleRegion(Collection $config)
+    {
+        // Make sure a valid region is set
+        $region = $config[Options::REGION];
+        $description = $config[Options::SERVICE_DESCRIPTION];
+        $global = $description->getData('globalEndpoint');
+
+        if (!$global && !$region) {
+            throw new InvalidArgumentException(
+                'A region is required when using ' . $description->getData('serviceFullName')
+            );
+        } elseif ($global && !$region) {
+            $config[Options::REGION] = 'us-east-1';
+        }
+    }
+
+    private function handleEndpoint(Collection $config)
+    {
+        // Alias "endpoint" with "base_url" for forwards compatibility.
+        if ($config['endpoint']) {
+            $config[Options::BASE_URL] = $config['endpoint'];
+            return;
+        }
+
+        if ($config[Options::BASE_URL]) {
+            return;
+        }
+
+        $endpoint = call_user_func(
+            $config['endpoint_provider'],
+            array(
+                'scheme'  => $config[Options::SCHEME],
+                'region'  => $config[Options::REGION],
+                'service' => $config[Options::SERVICE]
+            )
+        );
+
+        $config[Options::BASE_URL] = $endpoint['endpoint'];
+
+        // Set a signature if one was not explicitly provided.
+        if (!$config->hasKey(Options::SIGNATURE)
+            && isset($endpoint['signatureVersion'])
+        ) {
+            $config->set(Options::SIGNATURE, $endpoint['signatureVersion']);
+        }
+    }
 }

src/Aws/Common/Client/DefaultClient.php

@@ -42,8 +42,8 @@ class DefaultClient extends AbstractClient
      * Region and endpoint options (Some services do not require a region while others do. Check the service specific user guide documentation for details):
      *
      * - region: Region name (e.g. 'us-east-1', 'us-west-1', 'us-west-2', 'eu-west-1', etc...)
-     * - scheme: URI Scheme of the base URL (e.g. 'https', 'http') used when base_url is not supplied
-     * - base_url: Allows you to specify a custom endpoint instead of building one from the region and scheme
+     * - scheme: URI Scheme of the base URL (e.g. 'https', 'http') used when endpoint is not supplied
+     * - endpoint: Allows you to specify a custom endpoint instead of building one from the region and scheme
      *
      * Generic client options:
      *