Add support for endpoint discovery (#1239)

jderusse · web-flow · commit f29b9ee2762c · 2022-07-01T08:49:44.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## NOT RELEASED
 
+### Added
+
+- Added support for endpoint discovery
+
 ## 0.1.0
 
 First version
diff --git a/composer.json b/composer.json
@@ -14,7 +14,7 @@
         "php": "^7.2.5 || ^8.0",
         "ext-filter": "*",
         "ext-json": "*",
-        "async-aws/core": "^1.9",
+        "async-aws/core": "^1.16",
         "symfony/polyfill-uuid": "^1.0"
     },
     "autoload": {
diff --git a/src/Input/DescribeEndpointsRequest.php b/src/Input/DescribeEndpointsRequest.php
@@ -0,0 +1,57 @@
+<?php
+
+namespace AsyncAws\TimestreamQuery\Input;
+
+use AsyncAws\Core\Input;
+use AsyncAws\Core\Request;
+use AsyncAws\Core\Stream\StreamFactory;
+
+final class DescribeEndpointsRequest extends Input
+{
+    /**
+     * @param array{
+     *   @region?: string,
+     * } $input
+     */
+    public function __construct(array $input = [])
+    {
+        parent::__construct($input);
+    }
+
+    public static function create($input): self
+    {
+        return $input instanceof self ? $input : new self($input);
+    }
+
+    /**
+     * @internal
+     */
+    public function request(): Request
+    {
+        // Prepare headers
+        $headers = [
+            'Content-Type' => 'application/x-amz-json-1.0',
+            'X-Amz-Target' => 'Timestream_20181101.DescribeEndpoints',
+        ];
+
+        // Prepare query
+        $query = [];
+
+        // Prepare URI
+        $uriString = '/';
+
+        // Prepare Body
+        $bodyPayload = $this->requestBody();
+        $body = empty($bodyPayload) ? '{}' : json_encode($bodyPayload, 4194304);
+
+        // Return the Request
+        return new Request('POST', $uriString, $query, $headers, StreamFactory::create($body));
+    }
+
+    private function requestBody(): array
+    {
+        $payload = [];
+
+        return $payload;
+    }
+}
diff --git a/src/Result/DescribeEndpointsResponse.php b/src/Result/DescribeEndpointsResponse.php
@@ -0,0 +1,53 @@
+<?php
+
+namespace AsyncAws\TimestreamQuery\Result;
+
+use AsyncAws\Core\Response;
+use AsyncAws\Core\Result;
+use AsyncAws\TimestreamQuery\ValueObject\Endpoint;
+
+class DescribeEndpointsResponse extends Result
+{
+    /**
+     * An `Endpoints` object is returned when a `DescribeEndpoints` request is made.
+     */
+    private $endpoints;
+
+    /**
+     * @return Endpoint[]
+     */
+    public function getEndpoints(): array
+    {
+        $this->initialize();
+
+        return $this->endpoints;
+    }
+
+    protected function populateResult(Response $response): void
+    {
+        $data = $response->toArray();
+
+        $this->endpoints = $this->populateResultEndpoints($data['Endpoints']);
+    }
+
+    private function populateResultEndpoint(array $json): Endpoint
+    {
+        return new Endpoint([
+            'Address' => (string) $json['Address'],
+            'CachePeriodInMinutes' => (string) $json['CachePeriodInMinutes'],
+        ]);
+    }
+
+    /**
+     * @return Endpoint[]
+     */
+    private function populateResultEndpoints(array $json): array
+    {
+        $items = [];
+        foreach ($json as $item) {
+            $items[] = $this->populateResultEndpoint($item);
+        }
+
+        return $items;
+    }
+}
diff --git a/src/TimestreamQueryClient.php b/src/TimestreamQueryClient.php
@@ -15,9 +15,11 @@
 use AsyncAws\TimestreamQuery\Exception\ThrottlingException;
 use AsyncAws\TimestreamQuery\Exception\ValidationException;
 use AsyncAws\TimestreamQuery\Input\CancelQueryRequest;
+use AsyncAws\TimestreamQuery\Input\DescribeEndpointsRequest;
 use AsyncAws\TimestreamQuery\Input\PrepareQueryRequest;
 use AsyncAws\TimestreamQuery\Input\QueryRequest;
 use AsyncAws\TimestreamQuery\Result\CancelQueryResponse;
+use AsyncAws\TimestreamQuery\Result\DescribeEndpointsResponse;
 use AsyncAws\TimestreamQuery\Result\PrepareQueryResponse;
 use AsyncAws\TimestreamQuery\Result\QueryResponse;
 
@@ -53,11 +55,38 @@ public function cancelQuery($input): CancelQueryResponse
             'ThrottlingException' => ThrottlingException::class,
             'ValidationException' => ValidationException::class,
             'InvalidEndpointException' => InvalidEndpointException::class,
-        ]]));
+        ], 'requiresEndpointDiscovery' => true, 'usesEndpointDiscovery' => true]));
 
         return new CancelQueryResponse($response);
     }
 
+    /**
+     * DescribeEndpoints returns a list of available endpoints to make Timestream API calls against. This API is available
+     * through both Write and Query.
+     *
+     * @see https://docs.aws.amazon.com/timestream/latest/developerguide/API_DescribeEndpoints.html
+     * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-query.timestream-2018-11-01.html#describeendpoints
+     *
+     * @param array{
+     *   @region?: string,
+     * }|DescribeEndpointsRequest $input
+     *
+     * @throws InternalServerException
+     * @throws ValidationException
+     * @throws ThrottlingException
+     */
+    public function describeEndpoints($input = []): DescribeEndpointsResponse
+    {
+        $input = DescribeEndpointsRequest::create($input);
+        $response = $this->getResponse($input->request(), new RequestContext(['operation' => 'DescribeEndpoints', 'region' => $input->getRegion(), 'exceptionMapping' => [
+            'InternalServerException' => InternalServerException::class,
+            'ValidationException' => ValidationException::class,
+            'ThrottlingException' => ThrottlingException::class,
+        ]]));
+
+        return new DescribeEndpointsResponse($response);
+    }
+
     /**
      * A synchronous operation that allows you to submit a query with parameters to be stored by Timestream for later
      * running. Timestream only supports using this operation with the `PrepareQueryRequest$ValidateOnly` set to `true`.
@@ -86,7 +115,7 @@ public function prepareQuery($input): PrepareQueryResponse
             'ThrottlingException' => ThrottlingException::class,
             'ValidationException' => ValidationException::class,
             'InvalidEndpointException' => InvalidEndpointException::class,
-        ]]));
+        ], 'requiresEndpointDiscovery' => true, 'usesEndpointDiscovery' => true]));
 
         return new PrepareQueryResponse($response);
     }
@@ -127,11 +156,16 @@ public function query($input): QueryResponse
             'ThrottlingException' => ThrottlingException::class,
             'ValidationException' => ValidationException::class,
             'InvalidEndpointException' => InvalidEndpointException::class,
-        ]]));
+        ], 'requiresEndpointDiscovery' => true, 'usesEndpointDiscovery' => true]));
 
         return new QueryResponse($response, $this, $input);
     }
 
+    protected function discoverEndpoints(?string $region): array
+    {
+        return $this->describeEndpoints($region ? ['@region' => $region] : [])->getEndpoints();
+    }
+
     protected function getAwsErrorFactory(): AwsErrorFactoryInterface
     {
         return new JsonRpcAwsErrorFactory();
diff --git a/src/ValueObject/Endpoint.php b/src/ValueObject/Endpoint.php
@@ -0,0 +1,48 @@
+<?php
+
+namespace AsyncAws\TimestreamQuery\ValueObject;
+
+use AsyncAws\Core\EndpointDiscovery\EndpointInterface;
+
+/**
+ * Represents an available endpoint against which to make API calls against, as well as the TTL for that endpoint.
+ */
+final class Endpoint implements EndpointInterface
+{
+    /**
+     * An endpoint address.
+     */
+    private $address;
+
+    /**
+     * The TTL for the endpoint, in minutes.
+     */
+    private $cachePeriodInMinutes;
+
+    /**
+     * @param array{
+     *   Address: string,
+     *   CachePeriodInMinutes: string,
+     * } $input
+     */
+    public function __construct(array $input)
+    {
+        $this->address = $input['Address'] ?? null;
+        $this->cachePeriodInMinutes = $input['CachePeriodInMinutes'] ?? null;
+    }
+
+    public static function create($input): self
+    {
+        return $input instanceof self ? $input : new self($input);
+    }
+
+    public function getAddress(): string
+    {
+        return $this->address;
+    }
+
+    public function getCachePeriodInMinutes(): int
+    {
+        return $this->cachePeriodInMinutes;
+    }
+}
diff --git a/tests/Unit/Input/DescribeEndpointsRequestTest.php b/tests/Unit/Input/DescribeEndpointsRequestTest.php
@@ -0,0 +1,28 @@
+<?php
+
+namespace AsyncAws\TimestreamQuery\Tests\Unit\Input;
+
+use AsyncAws\Core\Test\TestCase;
+use AsyncAws\TimestreamQuery\Input\DescribeEndpointsRequest;
+
+class DescribeEndpointsRequestTest extends TestCase
+{
+    public function testRequest(): void
+    {
+        $input = new DescribeEndpointsRequest([
+
+        ]);
+
+        // see https://docs.aws.amazon.com/timestream/latest/developerguide/API_Operations_Amazon_Timestream_Query.html/API_DescribeEndpoints.html
+        $expected = '
+            POST / HTTP/1.0
+            Content-Type: application/x-amz-json-1.0
+            x-amz-target: Timestream_20181101.DescribeEndpoints
+
+            {
+            }
+        ';
+
+        self::assertRequestEqualsHttpRequest($expected, $input->request());
+    }
+}
diff --git a/tests/Unit/Result/DescribeEndpointsResponseTest.php b/tests/Unit/Result/DescribeEndpointsResponseTest.php
@@ -0,0 +1,35 @@
+<?php
+
+namespace AsyncAws\TimestreamQuery\Tests\Unit\Result;
+
+use AsyncAws\Core\EndpointDiscovery\EndpointInterface;
+use AsyncAws\Core\Response;
+use AsyncAws\Core\Test\Http\SimpleMockedResponse;
+use AsyncAws\Core\Test\TestCase;
+use AsyncAws\TimestreamQuery\Result\DescribeEndpointsResponse;
+use Psr\Log\NullLogger;
+use Symfony\Component\HttpClient\MockHttpClient;
+
+class DescribeEndpointsResponseTest extends TestCase
+{
+    public function testDescribeEndpointsResponse(): void
+    {
+        // see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeEndpoints.html
+        $response = new SimpleMockedResponse('{
+           "Endpoints": [
+              {
+                 "Address": "www.aws.com",
+                 "CachePeriodInMinutes": 1234
+              }
+           ]
+        }');
+
+        $client = new MockHttpClient($response);
+        $result = new DescribeEndpointsResponse(new Response($client->request('POST', 'http://localhost'), $client, new NullLogger()));
+
+        self::assertCount(1, $result->getEndpoints());
+        self::assertInstanceOf(EndpointInterface::class, $result->getEndpoints()[0]);
+        self::assertSame('www.aws.com', $result->getEndpoints()[0]->getAddress());
+        self::assertSame(1234, $result->getEndpoints()[0]->getCachePeriodInMinutes());
+    }
+}
diff --git a/tests/Unit/TimestreamQueryClientTest.php b/tests/Unit/TimestreamQueryClientTest.php
@@ -3,6 +3,7 @@
 namespace AsyncAws\TimestreamQuery\Tests\Unit;
 
 use AsyncAws\Core\Credentials\NullProvider;
+use AsyncAws\Core\Test\Http\SimpleMockedResponse;
 use AsyncAws\Core\Test\TestCase;
 use AsyncAws\TimestreamQuery\Input\CancelQueryRequest;
 use AsyncAws\TimestreamQuery\Input\PrepareQueryRequest;
@@ -17,7 +18,12 @@ class TimestreamQueryClientTest extends TestCase
 {
     public function testCancelQuery(): void
     {
-        $client = new TimestreamQueryClient([], new NullProvider(), new MockHttpClient());
+        $client = new TimestreamQueryClient([], new NullProvider(), new MockHttpClient([new SimpleMockedResponse('{
+          "Endpoints": [{
+            "Address": "www.aws.com",
+            "CachePeriodInMinutes": 1234
+          }]
+        }'), new SimpleMockedResponse('{}')]));
 
         $input = new CancelQueryRequest([
             'QueryId' => 'qwertyuiop',
@@ -30,7 +36,12 @@ public function testCancelQuery(): void
 
     public function testPrepareQuery(): void
     {
-        $client = new TimestreamQueryClient([], new NullProvider(), new MockHttpClient());
+        $client = new TimestreamQueryClient([], new NullProvider(), new MockHttpClient([new SimpleMockedResponse('{
+          "Endpoints": [{
+            "Address": "www.aws.com",
+            "CachePeriodInMinutes": 1234
+          }]
+        }'), new SimpleMockedResponse('{}')]));
 
         $input = new PrepareQueryRequest([
             'QueryString' => 'SELECT * FROM db.tbl ORDER BY time DESC LIMIT 10',
@@ -45,7 +56,12 @@ public function testPrepareQuery(): void
 
     public function testQuery(): void
     {
-        $client = new TimestreamQueryClient([], new NullProvider(), new MockHttpClient());
+        $client = new TimestreamQueryClient([], new NullProvider(), new MockHttpClient([new SimpleMockedResponse('{
+          "Endpoints": [{
+            "Address": "www.aws.com",
+            "CachePeriodInMinutes": 1234
+          }]
+        }'), new SimpleMockedResponse('{}')]));
 
         $input = new QueryRequest([
             'ClientToken' => 'qwertyuiop',
