docs(idempotency): bring your own persistent store

docs/snippets/idempotency/advancedBringYourOwnPersistenceLayer.ts

@@ -0,0 +1,130 @@
+import {
+  IdempotencyItemAlreadyExistsError,
+  IdempotencyItemNotFoundError,
+  IdempotencyRecordStatus,
+} from '@aws-lambda-powertools/idempotency';
+import { IdempotencyRecordOptions } from '@aws-lambda-powertools/idempotency/types';
+import {
+  IdempotencyRecord,
+  BasePersistenceLayer,
+} from '@aws-lambda-powertools/idempotency/persistence';
+import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
+import { Transform } from '@aws-lambda-powertools/parameters';
+import {
+  ProviderClient,
+  ProviderItemAlreadyExists,
+} from './advancedBringYourOwnPersistenceLayerProvider';
+import type { ApiSecret, ProviderItem } from './types';
+
+class CustomPersistenceLayer extends BasePersistenceLayer {
+  #collectionName: string;
+  #client?: ProviderClient;
+
+  public constructor(config: { collectionName: string }) {
+    super();
+    this.#collectionName = config.collectionName;
+  }
+
+  protected async _deleteRecord(record: IdempotencyRecord): Promise<void> {
+    await (
+      await this.#getClient()
+    ).delete(this.#collectionName, record.idempotencyKey);
+  }
+
+  protected async _getRecord(
+    idempotencyKey: string
+  ): Promise<IdempotencyRecord> {
+    try {
+      const item = await (
+        await this.#getClient()
+      ).get(this.#collectionName, idempotencyKey);
+
+      return new IdempotencyRecord({
+        ...(item as unknown as IdempotencyRecordOptions),
+      });
+    } catch (error) {
+      throw new IdempotencyItemNotFoundError();
+    }
+  }
+
+  protected async _putRecord(record: IdempotencyRecord): Promise<void> {
+    const item: Partial<ProviderItem> = {
+      status: record.getStatus(),
+    };
+
+    if (record.inProgressExpiryTimestamp !== undefined) {
+      item.in_progress_expiration = record.inProgressExpiryTimestamp;
+    }
+
+    if (this.isPayloadValidationEnabled() && record.payloadHash !== undefined) {
+      item.validation = record.payloadHash;
+    }
+
+    const ttl = record.expiryTimestamp
+      ? Math.floor(new Date(record.expiryTimestamp * 1000).getTime() / 1000) -
+        Math.floor(new Date().getTime() / 1000)
+      : this.getExpiresAfterSeconds();
+
+    let existingItem: ProviderItem | undefined;
+    try {
+      existingItem = await (
+        await this.#getClient()
+      ).put(this.#collectionName, record.idempotencyKey, item, {
+        ttl,
+      });
+    } catch (error) {
+      if (error instanceof ProviderItemAlreadyExists) {
+        if (
+          existingItem &&
+          existingItem.status !== IdempotencyRecordStatus.INPROGRESS &&
+          (existingItem.in_progress_expiration || 0) < Date.now()
+        ) {
+          throw new IdempotencyItemAlreadyExistsError(
+            `Failed to put record for already existing idempotency key: ${record.idempotencyKey}`
+          );
+        }
+      }
+    }
+  }
+
+  protected async _updateRecord(record: IdempotencyRecord): Promise<void> {
+    const value: Partial<ProviderItem> = {
+      data: JSON.stringify(record.responseData),
+      status: record.getStatus(),
+    };
+
+    if (this.isPayloadValidationEnabled()) {
+      value.validation = record.payloadHash;
+    }
+
+    await (
+      await this.#getClient()
+    ).update(this.#collectionName, record.idempotencyKey, value);
+  }
+
+  async #getClient(): Promise<ProviderClient> {
+    if (this.#client) return this.#client;
+
+    const secretName = process.env.API_SECRET;
+    if (!secretName) {
+      throw new Error('API_SECRET environment variable is not set');
+    }
+
+    const apiSecret = await getSecret<ApiSecret>(secretName, {
+      transform: Transform.JSON,
+    });
+
+    if (!apiSecret) {
+      throw new Error(`Could not retrieve secret ${secretName}`);
+    }
+
+    this.#client = new ProviderClient({
+      apiKey: apiSecret.apiKey,
+      defaultTtlSeconds: this.getExpiresAfterSeconds(),
+    });
+
+    return this.#client;
+  }
+}
+
+export { CustomPersistenceLayer };

docs/snippets/idempotency/advancedBringYourOwnPersistenceLayerProvider.ts

@@ -0,0 +1,44 @@
+import type { ProviderItem } from './types';
+
+/**
+ * This is a mock implementation of an SDK client for a generic key-value store.
+ */
+class ProviderClient {
+  public constructor(_config: { apiKey: string; defaultTtlSeconds: number }) {
+    // ...
+  }
+
+  public async delete(_collectionName: string, _key: string): Promise<void> {
+    // ...
+  }
+
+  public async get(
+    _collectionName: string,
+    _key: string
+  ): Promise<ProviderItem> {
+    // ...
+    return {} as ProviderItem;
+  }
+
+  public async put(
+    _collectionName: string,
+    _key: string,
+    _value: Partial<ProviderItem>,
+    _options: { ttl: number }
+  ): Promise<ProviderItem> {
+    // ...
+    return {} as ProviderItem;
+  }
+
+  public async update(
+    _collectionName: string,
+    _key: string,
+    _value: Partial<ProviderItem>
+  ): Promise<void> {
+    // ...
+  }
+}
+
+class ProviderItemAlreadyExists extends Error {}
+
+export { ProviderClient, ProviderItemAlreadyExists };

docs/snippets/idempotency/advancedBringYourOwnPersistenceLayerUsage.ts

@@ -0,0 +1,53 @@
+import type { Context } from 'aws-lambda';
+import { randomUUID } from 'node:crypto';
+import { CustomPersistenceLayer } from './advancedBringYourOwnPersistenceLayer';
+import {
+  IdempotencyConfig,
+  makeIdempotent,
+} from '@aws-lambda-powertools/idempotency';
+import type { Request, Response, SubscriptionResult } from './types';
+
+const persistenceStore = new CustomPersistenceLayer({
+  collectionName: 'powertools',
+});
+const config = new IdempotencyConfig({
+  expiresAfterSeconds: 60,
+});
+
+const createSubscriptionPayment = makeIdempotent(
+  async (
+    _transactionId: string,
+    event: Request
+  ): Promise<SubscriptionResult> => {
+    // ... create payment
+    return {
+      id: randomUUID(),
+      productId: event.productId,
+    };
+  },
+  {
+    persistenceStore,
+    dataIndexArgument: 1,
+    config,
+  }
+);
+
+export const handler = async (
+  event: Request,
+  context: Context
+): Promise<Response> => {
+  config.registerLambdaContext(context);
+
+  try {
+    const transactionId = randomUUID();
+    const payment = await createSubscriptionPayment(transactionId, event);
+
+    return {
+      paymentId: payment.id,
+      message: 'success',
+      statusCode: 200,
+    };
+  } catch (error) {
+    throw new Error('Error creating payment');
+  }
+};

docs/snippets/idempotency/makeIdempotentJmes.ts

@@ -12,7 +12,7 @@ const persistenceStore = new DynamoDBPersistenceLayer({
 });
 
 const createSubscriptionPayment = async (
-  user: string,
+  _user: string,
   productId: string
 ): Promise<SubscriptionResult> => {
   // ... create payment

docs/snippets/idempotency/samples/makeIdempotentJmes.json

@@ -0,0 +1,30 @@
+{
+  "version": "2.0",
+  "routeKey": "ANY /createpayment",
+  "rawPath": "/createpayment",
+  "rawQueryString": "",
+  "headers": {
+    "Header1": "value1",
+    "X-Idempotency-Key": "abcdefg"
+  },
+  "requestContext": {
+    "accountId": "123456789012",
+    "apiId": "api-id",
+    "domainName": "id.execute-api.us-east-1.amazonaws.com",
+    "domainPrefix": "id",
+    "http": {
+      "method": "POST",
+      "path": "/createpayment",
+      "protocol": "HTTP/1.1",
+      "sourceIp": "ip",
+      "userAgent": "agent"
+    },
+    "requestId": "id",
+    "routeKey": "ANY /createpayment",
+    "stage": "$default",
+    "time": "10/Feb/2021:13:40:43 +0000",
+    "timeEpoch": 1612964443723
+  },
+  "body": "{\"user\":\"xyz\",\"productId\":\"123456789\"}",
+  "isBase64Encoded": false
+}

docs/snippets/idempotency/samples/workingWIthIdempotencyRequiredKeyError.json

@@ -0,0 +1,7 @@
+{
+  "user": {
+    "uid": "BB0D045C-8878-40C8-889E-38B3CB0A61B1",
+    "name": "foo",
+    "productId": 10000
+  }
+}

docs/snippets/idempotency/samples/workingWIthIdempotencyRequiredKeySuccess.json

@@ -0,0 +1,7 @@
+{
+  "user": {
+    "uid": "BB0D045C-8878-40C8-889E-38B3CB0A61B1",
+    "name": "Foo"
+  },
+  "productId": 10000
+}

docs/snippets/idempotency/samples/workingWithBatch.json

@@ -0,0 +1,26 @@
+{
+  "Records": [
+    {
+      "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
+      "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
+      "body": "Test message.",
+      "attributes": {
+        "ApproximateReceiveCount": "1",
+        "SentTimestamp": "1545082649183",
+        "SenderId": "AIDAIENQZJOLO23YVJ4VO",
+        "ApproximateFirstReceiveTimestamp": "1545082649185"
+      },
+      "messageAttributes": {
+        "testAttr": {
+          "stringValue": "100",
+          "binaryValue": "base64Str",
+          "dataType": "Number"
+        }
+      },
+      "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
+      "eventSource": "aws:sqs",
+      "eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
+      "awsRegion": "us-east-2"
+    }
+  ]
+}

docs/snippets/idempotency/templates/tableCdk.ts

@@ -0,0 +1,30 @@
+import { Stack, type StackProps } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
+import { Runtime } from 'aws-cdk-lib/aws-lambda';
+import { AttributeType, BillingMode, Table } from 'aws-cdk-lib/aws-dynamodb';
+
+export class IdempotencyStack extends Stack {
+  public constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const table = new Table(this, 'idempotencyTable', {
+      partitionKey: {
+        name: 'id',
+        type: AttributeType.STRING,
+      },
+      timeToLiveAttribute: 'expiration',
+      billingMode: BillingMode.PAY_PER_REQUEST,
+    });
+
+    const fnHandler = new NodejsFunction(this, 'helloWorldFunction', {
+      runtime: Runtime.NODEJS_18_X,
+      handler: 'handler',
+      entry: 'src/index.ts',
+      environment: {
+        IDEMPOTENCY_TABLE_NAME: table.tableName,
+      },
+    });
+    table.grantReadWriteData(fnHandler);
+  }
+}

docs/snippets/idempotency/templates/tableSam.yaml

@@ -0,0 +1,31 @@
+Transform: AWS::Serverless-2016-10-31
+Resources:
+  IdempotencyTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      AttributeDefinitions:
+        - AttributeName: id
+          AttributeType: S
+      KeySchema:
+        - AttributeName: id
+          KeyType: HASH
+      TimeToLiveSpecification:
+        AttributeName: expiration
+        Enabled: true
+      BillingMode: PAY_PER_REQUEST
+
+  HelloWorldFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Runtime: python3.11
+      Handler: app.py
+      Policies:
+        - Statement:
+            - Sid: AllowDynamodbReadWrite
+              Effect: Allow
+              Action:
+                - dynamodb:PutItem
+                - dynamodb:GetItem
+                - dynamodb:UpdateItem
+                - dynamodb:DeleteItem
+              Resource: !GetAtt IdempotencyTable.Arn