Implement DynamoDB TransactWriteItem (#1262)

Author: GrahamCampbell

composer.json

@@ -14,7 +14,8 @@
         "php": "^7.2.5 || ^8.0",
         "ext-filter": "*",
         "ext-json": "*",
-        "async-aws/core": "^1.9"
+        "async-aws/core": "^1.9",
+        "symfony/polyfill-uuid": "^1.0"
     },
     "conflict": {
         "symfony/http-client": "<4.4.16,<5.1.7"

src/DynamoDbClient.php

@@ -16,14 +16,17 @@
 use AsyncAws\DynamoDb\Enum\TableClass;
 use AsyncAws\DynamoDb\Exception\ConditionalCheckFailedException;
 use AsyncAws\DynamoDb\Exception\DuplicateItemException;
+use AsyncAws\DynamoDb\Exception\IdempotentParameterMismatchException;
 use AsyncAws\DynamoDb\Exception\InternalServerErrorException;
 use AsyncAws\DynamoDb\Exception\ItemCollectionSizeLimitExceededException;
 use AsyncAws\DynamoDb\Exception\LimitExceededException;
 use AsyncAws\DynamoDb\Exception\ProvisionedThroughputExceededException;
 use AsyncAws\DynamoDb\Exception\RequestLimitExceededException;
 use AsyncAws\DynamoDb\Exception\ResourceInUseException;
 use AsyncAws\DynamoDb\Exception\ResourceNotFoundException;
+use AsyncAws\DynamoDb\Exception\TransactionCanceledException;
 use AsyncAws\DynamoDb\Exception\TransactionConflictException;
+use AsyncAws\DynamoDb\Exception\TransactionInProgressException;
 use AsyncAws\DynamoDb\Input\BatchGetItemInput;
 use AsyncAws\DynamoDb\Input\BatchWriteItemInput;
 use AsyncAws\DynamoDb\Input\CreateTableInput;
@@ -36,6 +39,7 @@
 use AsyncAws\DynamoDb\Input\PutItemInput;
 use AsyncAws\DynamoDb\Input\QueryInput;
 use AsyncAws\DynamoDb\Input\ScanInput;
+use AsyncAws\DynamoDb\Input\TransactWriteItemsInput;
 use AsyncAws\DynamoDb\Input\UpdateItemInput;
 use AsyncAws\DynamoDb\Input\UpdateTableInput;
 use AsyncAws\DynamoDb\Input\UpdateTimeToLiveInput;
@@ -53,6 +57,7 @@
 use AsyncAws\DynamoDb\Result\ScanOutput;
 use AsyncAws\DynamoDb\Result\TableExistsWaiter;
 use AsyncAws\DynamoDb\Result\TableNotExistsWaiter;
+use AsyncAws\DynamoDb\Result\TransactWriteItemsOutput;
 use AsyncAws\DynamoDb\Result\UpdateItemOutput;
 use AsyncAws\DynamoDb\Result\UpdateTableOutput;
 use AsyncAws\DynamoDb\Result\UpdateTimeToLiveOutput;
@@ -72,6 +77,7 @@
 use AsyncAws\DynamoDb\ValueObject\StreamSpecification;
 use AsyncAws\DynamoDb\ValueObject\Tag;
 use AsyncAws\DynamoDb\ValueObject\TimeToLiveSpecification;
+use AsyncAws\DynamoDb\ValueObject\TransactWriteItem;
 
 class DynamoDbClient extends AbstractApi
 {
@@ -568,6 +574,47 @@ public function tableNotExists($input): TableNotExistsWaiter
         return new TableNotExistsWaiter($response, $this, $input);
     }
 
+    /**
+     * `TransactWriteItems` is a synchronous write operation that groups up to 25 action requests. These actions can target
+     * items in different tables, but not in different Amazon Web Services accounts or Regions, and no two actions can
+     * target the same item. For example, you cannot both `ConditionCheck` and `Update` the same item. The aggregate size of
+     * the items in the transaction cannot exceed 4 MB.
+     *
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html
+     * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-dynamodb-2012-08-10.html#transactwriteitems
+     *
+     * @param array{
+     *   TransactItems: TransactWriteItem[],
+     *   ReturnConsumedCapacity?: ReturnConsumedCapacity::*,
+     *   ReturnItemCollectionMetrics?: ReturnItemCollectionMetrics::*,
+     *   ClientRequestToken?: string,
+     *   @region?: string,
+     * }|TransactWriteItemsInput $input
+     *
+     * @throws ResourceNotFoundException
+     * @throws TransactionCanceledException
+     * @throws TransactionInProgressException
+     * @throws IdempotentParameterMismatchException
+     * @throws ProvisionedThroughputExceededException
+     * @throws RequestLimitExceededException
+     * @throws InternalServerErrorException
+     */
+    public function transactWriteItems($input): TransactWriteItemsOutput
+    {
+        $input = TransactWriteItemsInput::create($input);
+        $response = $this->getResponse($input->request(), new RequestContext(['operation' => 'TransactWriteItems', 'region' => $input->getRegion(), 'exceptionMapping' => [
+            'ResourceNotFoundException' => ResourceNotFoundException::class,
+            'TransactionCanceledException' => TransactionCanceledException::class,
+            'TransactionInProgressException' => TransactionInProgressException::class,
+            'IdempotentParameterMismatchException' => IdempotentParameterMismatchException::class,
+            'ProvisionedThroughputExceededException' => ProvisionedThroughputExceededException::class,
+            'RequestLimitExceeded' => RequestLimitExceededException::class,
+            'InternalServerError' => InternalServerErrorException::class,
+        ]]));
+
+        return new TransactWriteItemsOutput($response);
+    }
+
     /**
      * Edits an existing item's attributes, or adds a new item to the table if it does not already exist. You can put,
      * delete, or add attribute values. You can also perform a conditional update on an existing item (insert a new

src/Enum/ReturnValuesOnConditionCheckFailure.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace AsyncAws\DynamoDb\Enum;
+
+/**
+ * Use `ReturnValuesOnConditionCheckFailure` to get the item attributes if the `ConditionCheck` condition fails. For
+ * `ReturnValuesOnConditionCheckFailure`, the valid values are: NONE and ALL_OLD.
+ */
+final class ReturnValuesOnConditionCheckFailure
+{
+    public const ALL_OLD = 'ALL_OLD';
+    public const NONE = 'NONE';
+
+    public static function exists(string $value): bool
+    {
+        return isset([
+            self::ALL_OLD => true,
+            self::NONE => true,
+        ][$value]);
+    }
+}

src/Exception/IdempotentParameterMismatchException.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace AsyncAws\DynamoDb\Exception;
+
+use AsyncAws\Core\Exception\Http\ClientException;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+/**
+ * DynamoDB rejected the request because you retried a request with a different payload but with an idempotent token
+ * that was already used.
+ */
+final class IdempotentParameterMismatchException extends ClientException
+{
+    protected function populateResult(ResponseInterface $response): void
+    {
+        $data = $response->toArray(false);
+
+        if (null !== $v = (isset($data['message']) ? (string) $data['message'] : null)) {
+            $this->message = $v;
+        }
+    }
+}

src/Exception/TransactionCanceledException.php

@@ -0,0 +1,170 @@
+<?php
+
+namespace AsyncAws\DynamoDb\Exception;
+
+use AsyncAws\Core\Exception\Http\ClientException;
+use AsyncAws\DynamoDb\ValueObject\AttributeValue;
+use AsyncAws\DynamoDb\ValueObject\CancellationReason;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+/**
+ * The entire transaction request was canceled.
+ * DynamoDB cancels a `TransactWriteItems` request under the following circumstances:.
+ *
+ * - A condition in one of the condition expressions is not met.
+ * - A table in the `TransactWriteItems` request is in a different account or region.
+ * - More than one action in the `TransactWriteItems` operation targets the same item.
+ * - There is insufficient provisioned capacity for the transaction to be completed.
+ * - An item size becomes too large (larger than 400 KB), or a local secondary index (LSI) becomes too large, or a
+ *   similar validation error occurs because of changes made by the transaction.
+ * - There is a user error, such as an invalid data format.
+ *
+ * DynamoDB cancels a `TransactGetItems` request under the following circumstances:
+ *
+ * - There is an ongoing `TransactGetItems` operation that conflicts with a concurrent `PutItem`, `UpdateItem`,
+ *   `DeleteItem` or `TransactWriteItems` request. In this case the `TransactGetItems` operation fails with a
+ *   `TransactionCanceledException`.
+ * - A table in the `TransactGetItems` request is in a different account or region.
+ * - There is insufficient provisioned capacity for the transaction to be completed.
+ * - There is a user error, such as an invalid data format.
+ *
+ * > If using Java, DynamoDB lists the cancellation reasons on the `CancellationReasons` property. This property is not
+ * > set for other languages. Transaction cancellation reasons are ordered in the order of requested items, if an item
+ * > has no error it will have `None` code and `Null` message.
+ *
+ * Cancellation reason codes and possible error messages:
+ *
+ * - No Errors:
+ *
+ *   - Code: `None`
+ *   - Message: `null`
+ *
+ * - Conditional Check Failed:
+ *
+ *   - Code: `ConditionalCheckFailed`
+ *   - Message: The conditional request failed.
+ *
+ * - Item Collection Size Limit Exceeded:
+ *
+ *   - Code: `ItemCollectionSizeLimitExceeded`
+ *   - Message: Collection size exceeded.
+ *
+ * - Transaction Conflict:
+ *
+ *   - Code: `TransactionConflict`
+ *   - Message: Transaction is ongoing for the item.
+ *
+ * - Provisioned Throughput Exceeded:
+ *
+ *   - Code: `ProvisionedThroughputExceeded`
+ *   - Messages:
+ *
+ *     - The level of configured provisioned throughput for the table was exceeded. Consider increasing your
+ *       provisioning level with the UpdateTable API.
+ *
+ *       > This Message is received when provisioned throughput is exceeded is on a provisioned DynamoDB table.
+ *
+ *     - The level of configured provisioned throughput for one or more global secondary indexes of the table was
+ *       exceeded. Consider increasing your provisioning level for the under-provisioned global secondary indexes with
+ *       the UpdateTable API.
+ *
+ *       > This message is returned when provisioned throughput is exceeded is on a provisioned GSI.
+ *
+ *
+ *
+ * - Throttling Error:
+ *
+ *   - Code: `ThrottlingError`
+ *   - Messages:
+ *
+ *     - Throughput exceeds the current capacity of your table or index. DynamoDB is automatically scaling your table or
+ *       index so please try again shortly. If exceptions persist, check if you have a hot key:
+ *       https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-design.html.
+ *
+ *       > This message is returned when writes get throttled on an On-Demand table as DynamoDB is automatically scaling
+ *       > the table.
+ *
+ *     - Throughput exceeds the current capacity for one or more global secondary indexes. DynamoDB is automatically
+ *       scaling your index so please try again shortly.
+ *
+ *       > This message is returned when when writes get throttled on an On-Demand GSI as DynamoDB is automatically
+ *       > scaling the GSI.
+ *
+ *
+ *
+ * - Validation Error:
+ *
+ *   - Code: `ValidationError`
+ *   - Messages:
+ *
+ *     - One or more parameter values were invalid.
+ *     - The update expression attempted to update the secondary index key beyond allowed size limits.
+ *     - The update expression attempted to update the secondary index key to unsupported type.
+ *     - An operand in the update expression has an incorrect data type.
+ *     - Item size to update has exceeded the maximum allowed size.
+ *     - Number overflow. Attempting to store a number with magnitude larger than supported range.
+ *     - Type mismatch for attribute to update.
+ *     - Nesting Levels have exceeded supported limits.
+ *     - The document path provided in the update expression is invalid for update.
+ *     - The provided expression refers to an attribute that does not exist in the item.
+ */
+final class TransactionCanceledException extends ClientException
+{
+    /**
+     * A list of cancellation reasons.
+     */
+    private $cancellationReasons;
+
+    /**
+     * @return CancellationReason[]
+     */
+    public function getCancellationReasons(): array
+    {
+        return $this->cancellationReasons;
+    }
+
+    protected function populateResult(ResponseInterface $response): void
+    {
+        $data = $response->toArray(false);
+
+        if (null !== $v = (isset($data['message']) ? (string) $data['message'] : null)) {
+            $this->message = $v;
+        }
+        $this->cancellationReasons = empty($data['CancellationReasons']) ? [] : $this->populateResultCancellationReasonList($data['CancellationReasons']);
+    }
+
+    /**
+     * @return array<string, AttributeValue>
+     */
+    private function populateResultAttributeMap(array $json): array
+    {
+        $items = [];
+        foreach ($json as $name => $value) {
+            $items[(string) $name] = AttributeValue::create($value);
+        }
+
+        return $items;
+    }
+
+    private function populateResultCancellationReason(array $json): CancellationReason
+    {
+        return new CancellationReason([
+            'Item' => !isset($json['Item']) ? null : $this->populateResultAttributeMap($json['Item']),
+            'Code' => isset($json['Code']) ? (string) $json['Code'] : null,
+            'Message' => isset($json['Message']) ? (string) $json['Message'] : null,
+        ]);
+    }
+
+    /**
+     * @return CancellationReason[]
+     */
+    private function populateResultCancellationReasonList(array $json): array
+    {
+        $items = [];
+        foreach ($json as $item) {
+            $items[] = $this->populateResultCancellationReason($item);
+        }
+
+        return $items;
+    }
+}

src/Exception/TransactionInProgressException.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace AsyncAws\DynamoDb\Exception;
+
+use AsyncAws\Core\Exception\Http\ClientException;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+/**
+ * The transaction with the given request token is already in progress.
+ */
+final class TransactionInProgressException extends ClientException
+{
+    protected function populateResult(ResponseInterface $response): void
+    {
+        $data = $response->toArray(false);
+
+        if (null !== $v = (isset($data['message']) ? (string) $data['message'] : null)) {
+            $this->message = $v;
+        }
+    }
+}