DEV Community: Rishi

Chatlings🐾 I Finally Shipped the Kids' Chat App I Abandoned a Year Ago

Rishi — Sun, 07 Jun 2026 10:47:33 +0000

This is a submission for the GitHub Finish-Up-A-Thon Challenge

What I Built

Chatlings is a serverless, real-time chat platform built specifically for children aged 8–14. Every message is screened by AI before anyone else sees it. Every image upload is scanned for inappropriate content. The whole thing runs on AWS and deploys with a single command.

Demo

🔗 Live app: https://d19ptumhqepwqw.cloudfront.net
📂 GitHub: https://github.com/TrickSumo/Chatlings

Where It Was Before This Hackathon

I had built the core of Chatlings using React frontend, WebSocket API, DynamoDB, Lambda functions, and Cognito auth. The features were there. What was missing was the infrastructure layer actually to ship it properly and make it production-ready.

Here's what was unfinished:

No IaC. There was no CDK stack. Deployment meant clicking through the AWS console, copying outputs by hand, writing .env manually, building, syncing to S3, and invalidating CloudFront. Overall, a 12-step, 1-2 hour process every single time.
Several DynamoDB bugs: chat history returning max 60 messages, broadcast making N individual reads per member instead of a BatchGetCommand, UnprocessedKeys silently dropped in group listing, and stale connection IDs never cleaned up on 410 Gone.
No test coverage. Lambda functions had zero tests.

The core app was there, including real-time chat, AI moderation, image sharing, and Cognito auth. This hackathon was about making it IaC-ready, one-command deployable, tested, and actually shippable.

The Comeback Story

1. One-Command Deployment

The main goal. I wrote a full AWS CDK stack covering every piece of infrastructure, including DynamoDB, S3, 14 Lambda functions, HTTP API Gateway, WebSocket API Gateway, CloudFront, Cognito and wrapped it in a deploy.sh script wired to npm run deploy.

npm run deploy

That one command now:

Runs cdk deploy and provisions the entire stack
Parses CDK outputs to get CloudFront domain, Cognito config, and S3 bucket
Writes Frontend/.env with the resolved values
Builds the React app and syncs it to S3
Invalidates the CloudFront cache

Before this, every deploy was manual. Copy outputs, write env vars, build, sync, invalidate. Now it's one command.

2. DynamoDB Fixes

Four bugs that had been quietly sitting in the Lambda code:

Newest messages first: ScanIndexForward defaults to ascending, so chat history was loading from the very beginning. Added ScanIndexForward: false + Limit: 60 + LastEvaluatedKey pagination.

BatchGetCommand instead of N reads: MessageAnalyzer was making one DynamoDB read per group member to fetch connection IDs. Replaced with a single BatchGetCommand + UnprocessedKeys retry loop:

UnprocessedKeys dropped: Same fix pattern applied to ListGroupsForUser. It was silently discarding groups when DynamoDB couldn't process the full batch in one shot.

Stale connection cleanup: When API Gateway returns 410 Gone (connection no longer exists), the handler now removes the stale connectionId from DynamoDB instead of letting them accumulate.

4. Test Coverage

Zero tests existed before this hackathon. I added 25 unit tests across 6 Lambda functions using Jest and aws-sdk-client-mock.

npm test

My Experience with GitHub Copilot

GitHub Copilot was most useful during the CDK and Lambda work. When I was setting up the CloudFront behaviors in cdk/lib/cloudfront.ts, Copilot autocompleted the OriginRequestPolicy import and the property name.

Used GitHub Copilot agent mode to generate mock and test cases for all lambda functions single-handedly. It worked just in a single attempt! 5mins!

The BatchGetCommand + UnprocessedKeys retry loop was a pattern I knew existed, but couldn't remember the exact shape of. Copilot's suggestion was nearly correct on the first try. I adjusted the retry condition, and it worked.

Where Copilot was less helpful: the signed-cookie CloudFront bug. That was a pure config-layer problem, and no amount of code generation helps when you need to understand why CloudFront strips headers by default. I had to read the AWS docs and reason through them myself.

Wrapping Up

Honestly, this hackathon was more fun than I expected. Chatlings had been sitting in my GitHub for a year, but having a deadline changed that completely.

Working with GitHub Copilot throughout made the process faster. When I was deep in CDK configuration or writing repetitive Lambda boilerplate, Copilot filled in the gaps so I could keep thinking about the problem instead of syntax.

Building Human-in-the-Loop E-Commerce Workflows with AWS Durable Lambda Functions

Rishi — Tue, 02 Jun 2026 10:46:27 +0000

QuantaSneaks is an AI-enabled shoe company famous for its x-factor worldwide. After the immense success of its predecessor, the revolutionary QuantaSneaks 1000 👟 is being launched in a weekend sale.

The social media campaign is set up, and there is no doubt that sales are going to be record high. However, the team is concerned that resellers might try to use bots to collect as many shoes as possible, and genuine customers might miss the deal.

To solve the issue, the lead architect decided to implement a human-in-the-loop workflow using newly launched shiny shiny durable lambda functions!

But what is this durable lambda?

AWS Durable Lambda Functions are like Step Functions inside a Lambda function. Durable Lambda execution spans across multiple Lambda invocations and uses a checkpoint-and-replay mechanism. It offers features like out-of-the-box infrastructure-level retries, concurrent code execution, and wait operations.

The wait operation is especially interesting here because it allows execution to pause (for up to one year) without incurring extra charges. Built on top of wait is the waitForCallback feature that we are going to use for human-in-the-loop workflows.

You can read more about Durable Lambda in Eric’s blog post.

What are we building?

The customer should be able to select the shoe size, place an order, and pay without any hassle. After payment, the order will remain on hold until someone from the fulfillment team approves it. A real human from the fulfillment team will use the AI-generated score to decide whether the order should be approved or not.

So the system must retry appropriately and gracefully restore the application to a consistent state in case of an unfixable error.

Key ingredients 🧺

DynamoDB (the storage): Used to store orderId, paymentUrl, callback info, and approval status.

uiLambda (user-facing lambda): Serves static UI and handles APIs to complete payment, approve order, and fetch status.

orderLambda (trigger): Intermediate function to start order processing workflow (optionally verify user details).

durableLambda (the orchestrator): Analyzes risk score, orchestrates payment, and human approval.

Workflow 👷🏼‍♀️👷🏼‍♂️👷🏼

The workflow is as follows:

Customer accesses the site URL and uiLambda serves the webpage.
When an order is placed, the orderLambda is triggered.
orderLambda creates orderId, stores it in DynamoDB, starts durable execution for orderId, and returns orderId to the customer.
The customer’s browser polls uiLambda for the payment URL corresponding to the orderId.
durableLambda uses AI to generate a risk score for an order and also calls the payment provider to generate the payment URL. Then, the waitForCallback operation starts, details are stored in DynamoDB, and it waits for callback approval.
The customer’s browser gets the payment URL, completes the payment by calling uiLambda. uiLambda approves the callback. An important thing here is that in production, the customer’s browser will talk to the payment provider, and the payment provider will resolve the callback.
Then the browser polls for the status update.
durableLambda starts a new waitForCallback for human approval, and the status is updated in DynamoDB based on the decision.
Finally, the customer’s browser reflects the decision and status.

Note: Here, security features like Cognito and API Gateway are intentionally skipped to keep focus on the durable workflow.

Project Code 💻

Complete code can be cloned from GitHub: https://github.com/TrickSumo/DurableLambdaCoruse/tree/main/8.%20QuantaSneaks%20Project

uiLambda:

import { handleHome } from './routes/home.js';
import { handleStatus, handlePoll } from './routes/status.js';
import { handlePayment, handlePay } from './routes/payment.js';
import { handleAdmin, handleApprove, handleReject } from './routes/admin.js';
import { serveAsset } from './lib/assets.js';

export const handler = async (event) => {
    const { view, action, asset } = event.queryStringParameters ?? {};
    const method = event.requestContext.http.method;

    if (asset)                          return serveAsset(asset);

    if (method === 'GET') {
        if (action === 'poll')          return await handlePoll(event);
        if (!view)                      return handleHome();
        if (view === 'status')          return handleStatus(event);
        if (view === 'payment')         return handlePayment(event);
        if (view === 'admin')           return await handleAdmin();
    }

    if (method === 'POST') {
        if (action === 'pay')           return await handlePay(event);
        if (action === 'approve')       return await handleApprove(event);
        if (action === 'reject')        return await handleReject(event);
    }

    return { statusCode: 404, body: 'Not found' };
};

orderLambda:

import { DynamoDBClient, PutItemCommand } from '@aws-sdk/client-dynamodb';
import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';
import { randomUUID } from 'crypto';

const dynamo = new DynamoDBClient({});
const lambda = new LambdaClient({});

const TABLE = process.env.ORDERS_TABLE ?? 'quantasneaks';
const DURABLE_LAMBDA_ARN = process.env.DURABLE_LAMBDA_ARN;
const UI_LAMBDA_URL = process.env.UI_LAMBDA_URL;

function parseBody(event) {
    const raw = event.isBase64Encoded
        ? Buffer.from(event.body, 'base64').toString('utf-8')
        : event.body ?? '';
    const contentType = event.headers?.['content-type'] ?? '';
    if (contentType.includes('application/json')) return JSON.parse(raw);
    return Object.fromEntries(new URLSearchParams(raw));
}

export const handler = async (event) => {
    const body = parseBody(event);
    const orderId = randomUUID();
    const size = body.size ?? 'unknown';

    await dynamo.send(new PutItemCommand({
        TableName: TABLE,
        Item: {
            orderId: { S: orderId },
            status: { S: 'processing' },
            size: { S: size },
            createdAt: { S: new Date().toISOString() }
        }
    }));

    await lambda.send(new InvokeCommand({
        FunctionName: DURABLE_LAMBDA_ARN,
        InvocationType: 'Event',
        Payload: Buffer.from(JSON.stringify({ orderId, size }))
    }));

    return {
        statusCode: 302,
        headers: { Location: `${UI_LAMBDA_URL}?view=status&orderId=${orderId}` }
    };
};

durableLambda:

import { withDurableExecution } from '@aws/durable-execution-sdk-js';
import { updateOrder } from './lib/dynamo.js';

export const handler = withDurableExecution(async (event, context) => {
    const { orderId } = event;

    const compensations = [];

    const analysis = await context.step('llm-analysis', () => callLLM(orderId));

    try {

        // Optional inventory reservation step could go here, with compensation to release inventory if payment isn't completed

        const { paymentId } = await context.waitForCallback(
            'payment',
            async (callbackId) => {
                await updateOrder(orderId, {
                    status: { S: 'awaiting_payment' },
                    riskLevel: { S: analysis.riskLevel },
                    riskReason: { S: analysis.reason },
                    paymentCallbackId: { S: callbackId }
                });
            },
            { timeout: { hours: 1 } }
        );

        compensations.push({
            name: 'refund-payment',
            fn: () => refundPayment(paymentId)
        });

        await context.waitForCallback(
            'admin-approval',
            async (callbackId) => {
                await updateOrder(orderId, {
                    status: { S: 'awaiting_approval' },
                    approvalCallbackId: { S: callbackId }
                });
            },
            { timeout: { hours: 24 } }
        );

        await context.step('ship-order', () =>
            updateOrder(orderId, { status: { S: 'shipped' } })
        );

        await context.step('send-confirmation', () => sendConfirmationEmail(orderId));

        return { orderId, status: 'shipped' };

    } catch (error) {
        for (const comp of compensations.reverse()) {
            await context.step(comp.name, () => comp.fn());
        }

        await context.step('compensate', () =>
            updateOrder(orderId, { status: { S: 'compensated' } })
        );

        return { orderId, status: 'compensated' };
    }
});


async function refundPayment(paymentId) {
    console.log(`Refunding payment ${paymentId}`);
}

async function sendConfirmationEmail(orderId) {
    console.log(`Confirmation email sent for order ${orderId}`);
}

async function callLLM(orderId) {
    const levels = ['low', 'medium', 'high'];
    const riskLevel = levels[Math.floor(Math.random() * levels.length)];
    const reasons = {
        low: 'Account history looks legitimate',
        medium: 'New account with limited purchase history',
        high: 'Multiple claim attempts detected from same origin'
    };
    return { riskLevel, reason: reasons[riskLevel] };
}

Conclusion

And that’s it!
We are now ready for the sale🥳

Hope this blog post gave you a good understanding of how to implement an e-commerce workflow with humans in the loop using Durable Lambda. If you have any feedback or suggestions, let’s discuss in the comments. Thanks!

Implementing Saga Pattern With Lambda Durable Function

Rishi — Mon, 25 May 2026 15:08:48 +0000

When you hit the “Place Order” button, that event triggers a series of steps, including inventory reservation, payment processing, and shipping initialization. Now, suppose your card is charged by the payment service (Stripe 🤔), but the API call to the third-party shipping service failed.

Modern systems don’t live inside a single database anymore. You can’t just rollback everything like a normal database transaction. In this era of distributed services, Saga patterns solve the problem of distributed rollback.

What is the Saga Pattern?

Saga is a sequence of steps carried out in a workflow. For each successful step, there exists a compensating step. As the saga progresses, these steps are stored in a list. Down the lane, if any step fails, all compensating steps are executed in reverse order.

Saga Pattern with AWS Durable Lambda Functions

Because of built-in checkpoints and replay mechanisms, AWS Lambda functions are perfect for implementing the saga pattern.

Each step of the saga can be wrapped in a durable step, allowing independent retry strategies. After each successful step, durable function checkpoints state; hence, on retry, already completed steps are not executed again.

To implement forward steps and compensation, all that we need is a try-catch block. The idea is simple: keep moving forward in the try block. If any step fails, compensating steps run in the catch block.

import {
  withDurableExecution,
  DurableContext,
  createRetryStrategy,
  JitterStrategy,
} from '@aws/durable-execution-sdk-js';
import { randomUUID } from 'crypto';

//Types

interface OrderEvent {
  orderId: string;
  customerId: string;
  items: Array<{ sku: string; qty: number; price: number }>;
  paymentMethod: { type: string; token: string };
  shippingAddress: { street: string; city: string; zip: string };
}

// Custom Error Classes
// Used by retryableErrorTypes - SDK checks instanceof, so real classes are needed

class NetworkError extends Error {
  name = 'NetworkError';
}

class PaymentDeclinedError extends Error {
  name = 'PaymentDeclinedError';
}

// Retry Strategies

/**
 * Exponential backoff with jitter - for external API calls.
 * Attempts: 1s → 2s → 4s → 8s → 16s (random jitter added to avoid thundering herd)
 * Only retries NetworkError - other errors won't be retried.
 */
const apiRetryStrategy = createRetryStrategy({
  maxAttempts: 5,
  initialDelay: { seconds: 1 },
  maxDelay: { seconds: 30 },
  backoffRate: 2.0,
  jitter: JitterStrategy.FULL,
  retryableErrorTypes: [NetworkError], // ← class constructor, not string
});

/**
 * Custom retry for payment - retries network errors but NOT declined cards.
 * Uses a function instead of createRetryStrategy for fine-grained control.
 */
const paymentRetryStrategy = (error: Error, attemptCount: number) => {
  // retryableErrorTypes equivalent - never retry a declined card
  if (error instanceof PaymentDeclinedError) {
    return { shouldRetry: false };
  }

  // maxAttempts: 5 equivalent
  if (attemptCount >= 5) {
    return { shouldRetry: false };
  }

  // initialDelay(1s) + backoffRate(2.0) + maxDelay(30s) + jitter(FULL) equivalent
  const baseDelay = 1 * Math.pow(2.0, attemptCount - 1); // exponential: 1s → 2s → 4s → 8s → 16s
  const capped = Math.min(baseDelay, 30);                 // maxDelay: never exceed 30s
  const jittered = Math.random() * capped;                // FULL jitter: random between 0 and capped
  const seconds = Math.max(1, Math.round(jittered));      // minimum 1s, rounded to whole second

  return { shouldRetry: true, delay: { seconds } };
};

// Handler

export const handler = withDurableExecution(async (event: OrderEvent, context: DurableContext) => {
  context.logger.info('Order processing started', { orderId: event.orderId });

  // Saga compensations array tracks what to undo if something fails later
  const compensations: Array<{ name: string; fn: () => Promise<void> }> = [];

  try {

    // ── Step 1: Validate ────────────────────────────────────────────────────
    // Throws a plain Error for invalid input, "shouldRetry: false" strategy means it fails immediately without retry
    await context.step('validate-order', async () => {
      context.logger.info('Validating order');

      if (!event.orderId || !event.customerId) {
        throw new Error('Order missing required fields');
      }
      if (!event.items || event.items.length === 0) {
        throw new Error('Order has no items');
      }

      const total = event.items.reduce((sum, i) => sum + i.price * i.qty, 0);
      if (total <= 0) {
        throw new Error('Order total must be greater than zero');
      }

      return { valid: true, total };
    },
      { retryStrategy: () => ({ shouldRetry: false }) }
    );

    // ── Step 2: Reserve inventory ───────────────────────────────────────────
    // Retries with exponential backoff, inventory service may be temporarily busy
    const reservation = await context.step(
      'reserve-inventory',
      async () => {
        context.logger.info('Reserving inventory');
        return await callInventoryService(event.orderId, event.items);
      },
      { retryStrategy: apiRetryStrategy }
    );

    // Register compensation, if something fails later, cancel this reservation
    compensations.push({
      name: 'cancel-reservation',
      fn: async () => { await callInventoryService(event.orderId, event.items, 'cancel'); },
    });

    context.logger.info('Inventory reserved', { reservationId: reservation.id });

    // ── Step 3: Generate idempotency key ───────────────────────────────────
    // Key is generated ONCE inside a step then checkpointed and same value returned on every replay.
    // This is the recommended pattern for payment APIs that support idempotency keys.
    // WARNING: Never generate outside a step because it changes on replay, defeating deduplication.
    const idempotencyKey = await context.step('payment-idempotency-key', async () =>
      randomUUID()
    );

    // ── Step 4: Charge payment ──────────────────────────────────────────────
    // AtLeastOnce (default) + idempotency key = safe to retry.
    // Even if Lambda crashes after charge but before checkpoint, the retry sends
    // the same idempotency key - payment provider deduplicates and returns original result.
    // No double charge risk.
    const payment = await context.step(
      'charge-payment',
      async () => {
        context.logger.info('Charging payment', { idempotencyKey });
        return await callPaymentService(event.paymentMethod, getTotalAmount(event), idempotencyKey);
      },
      { retryStrategy: paymentRetryStrategy } // retries NetworkError safely
    );

    // Register compensation - if shipping fails, refund the payment
    compensations.push({
      name: 'refund-payment',
      fn: async () => {
        await callPaymentService(event.paymentMethod, getTotalAmount(event), idempotencyKey, 'refund', payment.id);
      },
    });

    context.logger.info('Payment charged', { paymentId: payment.id });

    // ── Step 4: Create shipment ─────────────────────────────────────────────
    // Retries with exponential backoff, shipping service may be temporarily down
    const shipment = await context.step(
      'create-shipment',
      async () => {
        context.logger.info('Creating shipment');
        return await callShippingService(event.orderId, event.shippingAddress, event.items);
      },
      { retryStrategy: apiRetryStrategy }
    );

    context.logger.info('Shipment created', { trackingId: shipment.trackingId });

    // ── Step 5: Send confirmation ───────────────────────────────────────────
    // Simple fixed-delay retry: email service is reliable, 3 attempts is enough
    await context.step(
      'send-confirmation',
      async () => {
        context.logger.info('Sending confirmation email');
        await callNotificationService(event.customerId, event.orderId, shipment.trackingId);
      },
      {
        retryStrategy: createRetryStrategy({
          maxAttempts: 3,
          initialDelay: { seconds: 2 },
          backoffRate: 1, // fixed delay, no backoff
        }),
      }
    );

    context.logger.info('Order processing complete', { orderId: event.orderId });

    return {
      success: true,
      orderId: event.orderId,
      reservationId: reservation.id,
      paymentId: payment.id,
      trackingId: shipment.trackingId,
    };

  } catch (error) {
    // ── Saga: undo completed steps in reverse order ─────────────────────────
    // Example: payment charged but shipping failed → refund payment, cancel reservation
    context.logger.error('Order failed, running compensations', {
      orderId: event.orderId,
      error: (error as Error).message,
    });

    for (const comp of compensations.reverse()) {
      try {
        // Each compensation is its own durable step, checkpointed and retried
        await context.step(comp.name, async () => comp.fn());
        context.logger.info(`Compensation done: ${comp.name}`);
      } catch (compError) {
        // Log but continue, try all compensations even if one fails
        context.logger.error(`Compensation failed: ${comp.name}`, compError);
      }
    }

    throw error; // re-throw so execution is marked FAILED in console
  }
});

// ─── Simulated Service Calls ──────────────────────────────────────────────────
// In real code these would call actual APIs. Here we simulate occasional failures
// to demonstrate retry behavior.

async function callInventoryService(
  orderId: string,
  items: OrderEvent['items'],
  action = 'reserve'
): Promise<{ id: string }> {
  // 20% chance of network failure - demonstrates retry kicking in
  if (Math.random() < (3 / 5)) throw new NetworkError('Inventory service timeout');
  return { id: `RES-${orderId}-${Date.now()}` };
}

async function callPaymentService(
  method: OrderEvent['paymentMethod'],
  amount: number,
  idempotencyKey: string,
  action = 'charge',
  paymentId?: string
): Promise<{ id: string }> {
  if (method.token === 'DECLINED') throw new PaymentDeclinedError('Card declined');
  if (Math.random() < (2 / 3)) throw new NetworkError('Payment gateway timeout');
  return { id: `PAY-${idempotencyKey}` };
}

async function callShippingService(
  orderId: string,
  address: OrderEvent['shippingAddress'],
  items: OrderEvent['items']
): Promise<{ trackingId: string }> {
  if (Math.random() < (2 / 3)) throw new NetworkError('Shipping service unavailable');
  return { trackingId: `TRACK-${orderId}-${Date.now()}` };
}

async function callNotificationService(
  customerId: string,
  orderId: string,
  trackingId: string
): Promise<void> {
  console.log(`Confirmation sent to ${customerId} for order ${orderId}, tracking: ${trackingId}`);
}

function getTotalAmount(event: OrderEvent): number {
  return event.items.reduce((sum, i) => sum + i.price * i.qty, 0);
}

Let’s run the code!

Copy and paste the above code into the durable Lambda code editor. Then use the commands below to invoke the lambda with different payloads

Success scenario:-

aws lambda invoke \
  --function-name durable-parallel-test:prod \
  --payload '{"orderId":"ORD-001","customerId":"CUST-123","items":[{"sku":"ITEM-1","qty":2,"price":25}],"paymentMethod":{"type":"card","token":"tok_valid"},"shippingAddress":{"street":"123 Main St","city":"Seattle","zip":"98101"}}' \
  --cli-binary-format raw-in-base64-out \
  response.json && cat response.json

Fail scenario:-

aws lambda invoke \
  --function-name durable-parallel-test:prod \
  --payload '{"orderId":"ORD-002","customerId":"CUST-123","items":[{"sku":"ITEM-1","qty":1,"price":50}],"paymentMethod":{"type":"card","token":"DECLINED"},"shippingAddress":{"street":"123 Main St","city":"Seattle","zip":"98101"}}' \
  --cli-binary-format raw-in-base64-out \
  response.json && cat response.json

Invalid input:

aws lambda invoke \
  --function-name durable-parallel-test:prod \
  --payload '{"orderId":"","customerId":"","items":[],"paymentMethod":{"type":"card","token":"tok"},"shippingAddress":{"street":"","city":"","zip":""}}' \
  --cli-binary-format raw-in-base64-out \
  response.json && cat response.json

Conclusion

Saga patterns make rollback to a consistent state very simple in distributed transactions. And with lambda durable functions’ checkpointing and retry capability, it is easy-peasy to implement. Thanks for reading😊

Why You Should Avoid Promise.all() In AWS Lambda Durable Function

Rishi — Mon, 11 May 2026 09:43:33 +0000

Consider the example below:

const userPromise = context.step(async () => fetchUser());
const orderPromise = context.step(async () => fetchOrders());
const [user, orders] = await Promise.all([userPromise, orderPromise]);

The above example can produce non-deterministic behaviours because the SDK assigns each operation a number to track it in the checkpoint log. If two operations start at the same time, their numbers can be assigned in different orders on different runs. On replay, the SDK might match the wrong checkpoint to the wrong step.

The safe way to run things concurrently is to use parallel or map with the Durable Lambda SDK.

Understanding AtMostOncePerRetry vs AtLeastOncePerRetry in AWS Durable Lambda

Rishi — Sun, 10 May 2026 14:44:00 +0000

For a durable Lambda function, standard errors at any step are checkpointed and handled during the next replay by retry-strategy configurations.

However, there can be scenarios where a durable step starts execution but fails to complete, while also leaving no ERROR checkpoint behind. A common example is a Lambda execution timeout.

In such cases, step semantics become important because they define how the workflow should behave when the system cannot determine whether the step completed successfully or not.

There are two types of semantics available:

AtLeastOncePerRetry (Default)

For a step, the SDK initiates a START checkpoint (by calling the internal checkpoint API) and proceeds to code execution without waiting for the checkpoint response.

Now, if Lambda is interrupted mid-execution (timeout, OOM, sandbox crash), the step has no completion checkpoint. On the next replay, the SDK cannot determine that the step completed successfully and runs it again (more on it in the source code exploration section).

This is safe for idempotent operations where running the same operation twice is safe, like database read/upsert or an operation with an idempotency key.

AtMostOncePerRetry

Here, the SDK waits for the START checkpoint initialization before executing the code. If Lambda is interrupted mid-execution, the START checkpoint exists, but the completion checkpoint does not.

On the next replay, SDK detects the START checkpoint (step started execution but not ended) and skips the step. Also, it makes sure to throw StepInterruptedError that will bubble up, allowing the retry strategy to decide what happens next.

Neither guarantees the step runs exactly once across the entire workflow!

At first glance, AtMostOncePerRetry looks perfect for an idempotent operation. However, the documentation clearly states that both semantics apply per retry attempt, not across the entire workflow.

This means AtMostOncePerRetry guarantees that the step will run only once within a single attempt. But if the retry strategy is configured and StepInterruptedError is retryable, a new attempt begins, and the step runs again in that new attempt.

How to make sure that the step runs exactly once in the entire workflow?

To guarantee the step runs exactly once end-to-end, you must combine AtMostOncePerRetry with a no-retry strategy:

await context.step(
  'charge-payment',
  async () => paymentService.charge(amount, cardToken),
  {
    semantics: StepSemantics.AtMostOncePerRetry,
    retryStrategy: () => ({ shouldRetry: false })
  }
);

Now it is perfectly safe for operations that are not safe to repeat 👏🏼

Experiment Time🔬

Let us understand how these semantics behave with the help of CloudWatch logs.

Start by creating a durable Lambda function with an execution time of 1 minute. To simulate a timeout, change the timeout setting of the lambda to 3 seconds. Now, inside a durable step, run an operation that keeps executing for 10 seconds.

This setup will intentionally interrupt the Lambda execution before the step completes, helping us observe how AtLeastOncePerRetry and AtMostOncePerRetry behave during replay.

Code:-

import { withDurableExecution, StepSemantics } from '@aws/durable-execution-sdk-js';

export const handler = withDurableExecution(async (event, context) => {

  console.log("Execution started.");


  await context.step('Step #1', (stepCtx) => {
    stepCtx.logger.info('Hello from step #1');
  });

  const message = await context.step('Step #2', async () => {
    context.logger.info('inside step 2');
    await new Promise(resolve => setTimeout(resolve, 10000)); // 10 seconds
    return 'Hello from Durable Lambda!';
  }, {
    // semantics: StepSemantics.AtMostOncePerRetry,
    // retryStrategy: () => ({ shouldRetry: false })
  });

  const response = {
    statusCode: 200,
    body: JSON.stringify(message),
  };
  return response;
});

Scenario 1: AtLeastOncePerRetry (Default) and shouldRetry as true (default)

If we pass no semantics and retry, this is the default case. And it results in an infinite loop (until duration execution timeout), ie, the function keeps running for the whole 1 minute.

Reason?

On the first try, the lambda times out at the promise line without logging any error in the checkpoint. On the next invocation, since semantics is AtLeastOncePerRetry, the step runs again till the lambda timeout. It keeps repeating on and on and on and on...

Log analysis:

The first column is the lambda invocation ID, the second is the attempt count to run the step, third is the log to show the code executed.

Clearly, we can see that across all invocations, the code in step 2 got executed.

Since the Lambda times out before throwing any error, the retry strategy is never invoked, so the attempt counter never increments beyond 1.

A replay is not the same as a retry attempt!
Lambda may invoke the function multiple times during replay while still staying within the same retry attempt. Retry attempts increment only when the retry strategy schedules a new attempt after a checkpointed error.

Scenario 2: AtLeastOncePerRetry (Default) and shouldRetry as false

Similar to the previous case, the error is never thrown, and the retry strategy is never invoked. Because of AtLeastOncePerRetry semantics, the step executes again during every replay because no completion checkpoint exists.

Clearly, if semantics is AtLeastOncePerRetry and lambda is interrupted mid-execution (timeout in our case) without a proper step end/error checkpoint, the retry strategy is of no use.

shouldRetry: false only works when an error is actually thrown. A Lambda timeout halts the process silently, and no error is thrown, so the retry strategy is never called.

Scenario 3: AtMostOncePerRetry and shouldRetry as true (default)

Things become interesting here! Code of step 2 is executed on every second invocation.

What is happening here?

On first invocation, step 2 code executed, but the lambda timeout, hence no FINISH/ERROR checkpoint.

On second invocation, since the AtMostOncePerRetry semantic is used, step2 execution is skipped and StepInterruptedError is thrown. This time, no timeout; instead, a proper error bubbled out.
Now things are under the control of the retry strategy. Since the default retry strategy is true, attempt 2 is scheduled. Notice "ATTEMPT" here, that is very important.

On the third invocation, step 2 code is executed. Because AtMostOncePerRetry guarantees per ATTEMPT, not across the workflow. Lambda times out, and the process repeats....

Thanks to Kiro for explaining this confusing behaviour to me 😊

Notice this time, there is no infinite loop. Things are in control of the retry strategy because AtMostOncePerRetry emitted the error StepInterruptedError.

Scenario 4: AtMostOncePerRetry and shouldRetry as false

Finally, the scenario we've all been waiting for!

On first invocation, the lambda timed out inside step 2.

On the second invocation, StepInterruptedError is thrown, and step 2 is not executed. Since the retry strategy returns shouldRetry: false, no new attempt. And that's how we achieved "exactly once execution of step".

Let Us Inspect Source Code 🕵🏼

In our observations, we noticed that the retry strategy has no effect in the case of a lambda timeout with AtLeastOncePerRetry. Also, AtLeastOncePerRetry does not wait for the START checkpoint to finish.

But then a question came to my mind… Why does AtLeastOncePerRetry not wait for the START checkpoint?

I got my answer after looking at the code of the Lambda Durable SDK (step handler). There, we can clearly see that the durable SDK checks if the START checkpoint already exists only for AtMostOncePerRetry. If yes, the retry strategy is checked. But in the case of AtLeastOncePerRetry, no checking is done, and executeStepLogic() is called.

So the answer is: AtLeastOncePerRetry does not wait for the START checkpoint because it does not need to!

For AtLeastOncePerRetry, it does not care about the START checkpoint. The only thing it cares about is whether the step is COMPLETED. If not, run it. There will be no retry, same attempt with multiple invocations/replays until the step succeeds at least once. That’s how it got its name, “AtLeastOncePerRetry” 💪🏼

On the other hand, AtMostOncePerRetry gives the vibe of a sincere student. It waits for the START checkpoint to finish because it needs it (like a good student needing notes during exams 😄).

When a lambda timeout happens with step completion, AtMostOncePerRetry first checks whether the START checkpoint exists. If it does, it then consults the retry strategy:

If the retry strategy says “don’t retry,” it immediately stops and bubbles out StepInterruptedError.
If retryDecision.shouldRetry is true, it checkpoints the StepInterruptedError and schedules a retry.

This is what ensures at-most-once execution per retry attempt.

Conclusion

So in this post, we understood how semantics and retry strategy work in a durable lambda function.

The most important thing to remember is that a replay is not the same as a retry attempt. A Lambda function may replay multiple times within the same attempt if execution gets interrupted before proper checkpointing.

AtLeastOncePerRetry prioritizes progress and eventual completion, making it suitable for idempotent operations.

AtMostOncePerRetry prioritizes avoiding duplicate side effects within a retry attempt, making it useful for non-idempotent operations like payments or notifications. However, by itself, it still does not guarantee exactly-once execution across the entire workflow.

To achieve true end-to-end exactly-once execution, AtMostOncePerRetry must be combined with a no-retry strategy.

Hopefully, this post helped clarify one of the most confusing parts of the Durable Execution SDK 😄

Turn WebSockets into Async/Await Requests (AWS WebSocket API Gateway + Lambda)

Rishi — Sun, 03 May 2026 09:46:46 +0000

Some time ago, I was building a chat application using AWS Websocket API gateway. Things were going smoothly. I created a WebSocket API Gateway, added $connect, $disconnect, and sendMessage/addGroup routes. From the frontend (React) side, everything was fire-and-forget. You send a message, and the onMessageHandler takes care of it 💪🏼

But then a new requirement of uploading files using S3 signed URLs came up. That's where I needed the Async/Await promise pattern. Now, one option was to create an HTTP API gateway and use it. But that meant a new connection, a new authorizer, and more setup. At that moment, I wished there was a way to use this existing WebSocket connection to get the signed URL ⭐

And that’s how this library "ws-await" was born!

It lets you:

establish a WebSocket connection
send normal fire-and-forget messages
send messages and wait for the response using async/await
handle reconnection with exponential backoff
auto-send heartbeat messages to keep the connection alive

How does it work?

For the async/await pattern, messages from the frontend are sent with a unique requestId. The client keeps a map of pending promises. On the lambda side, the backend reads the requestId and sends it back in the response.

Received messages are analyzed for requestId, and if requestId matches the id of any pending promise in the map, that promise is resolved. If a promise sits idle in the map for a period of more than ~30 seconds, it is rejected.

Steps to use:

Step 1: Install the library in your React project

npm install @tricksumo/ws-await zustand

Step 2: Import createSocket() and establish the connection. Then call ws.send("action") for fire and forget messages and await ws.request("action") for async/await pattern.

import { createSocket } from '@tricksumo/ws-await'
import { useEffect } from 'react'
const ws = createSocket({
  url: 'wss://id.execute-api.us-east-1.amazonaws.com/prod',
})
function App() {
  useEffect(() => {
    ws.connect()
    return () => {
      ws.disconnect()
    }
  }, [])
  const handleGetSignedURL = async () => {
  try {
    const response = await ws.request('getSignedURL', { fileType: 'image/png' })
    console.log('Signed URL:', response)
  } catch (err) {
    console.error('Request failed:', err)
  }
}
  return (
      <div>
        <button onClick={handleGetSignedURL}>
          Click to get signed URL
        </button>
      </div>
  )
}

export default App

Step 3: Your Lambda must echo the requestId back in its response.

export const handler = async (event) => {

  const { requestId, fileName, fileType } = JSON.parse(event.body || '{}')

  const signedUrl = await getPresignedUrl(fileName, fileType)

  return {
    statusCode: 200,
    body: JSON.stringify({
      signedUrl,
      requestId, // ← REQUIRED: echo it back or the Promise never resolves
    }),
  }

}

Reading the connection state in the frontend.

import { useSocket } from '@tricksumo/ws-await'

function StatusBar() {
  const { isConnected, isConnecting, error } = useSocket()

  if (isConnecting) return <p>Connecting...</p>
  if (!isConnected)  return <p>Disconnected — {error?.message}</p>
  return <p>Connected</p>
}

Conclusion

Initially, this logic was part of my chat application named Chatlings. But I thought it might help others, so I extracted it to create my first ever library 🙌🏼

Complete Guide to AWS KMS: Encryption, Key Management & Serverless Projects

Rishi — Mon, 07 Jul 2025 05:51:56 +0000

AWS Key Management Service (KMS) is used to create, manage, and audit cryptographic keys. In this hands-on course, we'll break down core KMS concepts and implement two mini projects to bring theory into practice.

Prerequisites

To follow the mini-projects confidently, you should know how to build a basic serverless CRUD app:

Course Structure – What Will You Learn? 🌿

Encryption Fundamentals
What is encryption, and types of encryption?
KMS Key Types
KMS keys are categorized based on structure (symmetric/asymmetric) and ownership (AWS-owned, AWS-managed, customer-managed).
Envelope Encryption
What is envelope encryption, and why is it essential for scalable secure storage?
How is envelope encryption used with AWS customer-managed symmetric keys?
KMS Access Control & Service Integration
How KMS integrates with AWS services like S3, Lambda, and Secrets Manager.

How to control access using IAM policies, key policy, and grants.
Key Rotation & Auditing
Mini Projects
- 🔐Password Manager – Encrypt and store credentials in DynamoDB using KMS
- 🔑JWT Auth Server – Use KMS asymmetric keys to sign and verify JWTs

Chatlings🐾 AI Moderated Serverless Chat App For Kids!🌿

Rishi — Tue, 01 Jul 2025 14:33:41 +0000

Chatlings 🐾 is a serverless, real-time chat platform designed for children aged 8–14. It ensures content safety using AI moderation and a delightful, kid-friendly design.

Just like ducklings 🦆 follow their guide while learning to explore the world, Chatlings helps young users explore digital conversations safely and responsibly.

✨ Key Features

💬 Real-time Group Chat
Users can create or join public or private groups. Seamless text and image messages using WebSocket and serverless architecture.

🧠 Smart Moderation with AI
All text messages are moderated by Amazon Bedrock's Nova model for abuse and toxic language. Using AWS Rekognition, uploaded images are scanned for safety, instantly blocking unsafe or adult content.

🤖 AskBot The Friendly Chat Assistant
Got a question or stuck on something? Just tag @askbot in your group chat. AskBot uses the latest AWS Nova model to help kids solve doubts safely and quickly.

Chatlings🐾 Architecture

Chatlings is a serverless app built using:-

AWS Lambda, DynamoDB, S3, Bedrock, Rekognition and API Gateway for backend.
Cognito userpool and Lambda authorizer for authentication.
React, Zustand and other frontend tools for delightful interface.

The application is exposed using CloudFront CDN. The default CDN behaviour points to the React frontend. React app redirects the user to the Cognito login page, and after successful OAuth2.0 login flow, getSignedCookies API call happens to get CloudFront signed cookies. These cookies are used to access images handled by “/media*” behaviour.

After that app loads and websocket connection ($connect) is established. ACCESS_TOKEN verification is done in the same step with the help of Lambda authorizer. Then, depending on user interaction, action messages are sent to the Websockets API gateway, and processing happens.

1. Create/Join Group action
When any user creates a group, the lambda function is triggered, and group metadata is stored in DynamoDB. On join group action, groupCode is verified and records are created.

2. Text Message Moderation
When user sends message using sendMessage action, first of all, lambda verifies if user belongs to the group. After that, message is stored in DynamoDB and user receives immediate feedback.

Then DynamoDB stream triggers another lambda that looks for new INSERT message operations and uses Bedrock Nova model to moderate the message. If the message is toxic, content is removed from DynamoDB. The same lambda function notifies all active connections (that are part of this group) about this message.

3. Image Message Moderation
User triggers generateS3PreSignedURL action and uploads image file to S3. File upload to S3 triggers the imageAnalyzer Lambda function that uses Rekognition to verify image content. If the image is not suitable for kids, it is deleted immediately and only flag is stored in DynamoDB. Else, image URL is stored in DynamoDB.

INSERT operation in DynamoDB table again triggers messageAnalyzer lambda, but it sends notification only for image files.

4. CloudFront Signed Cookies
Access to image files is restricted with the help of CloudFront signed cookies that were created just after successful login.

5. AskBot AI Assistant
When user mentions @askbot in the message, the askbot route is triggered, which calls Nova model to answer the question. Both user’s query and model’s response are stored in DynamoDB table. Again, the INSERT operation triggers moderation followed by notification of both messages.

6. DynamoDB Single Table Design
All data is stored in a single DynamoDB table that is designed keeping access pattern in mind instead of the structure of the data. Table schema is as follows:-

Conclusion
Chatlings🐾 helps kids interact with friends while staying protected by cutting-edge AI moderation. All of this is powered by a fully serverless, event-driven architecture built on AWS.

GitHub:- https://github.com/TrickSumo/Chatlings

Thanks for reading, hope you enjoyed, Thanks 🌿

Creating Fruit Tetris🍎Using Amazon Q Developer CLI

Rishi — Sat, 14 Jun 2025 09:21:58 +0000

This weekend I'm having fun with Amazon Q CLI. Using Q CLI, created this game called Fruit Tetris (one of first ever games that I played eons ago on a flip-flop mobile probably running on Symbian Java).

It took me more time to install CLI itself than to create this awesome 2D game. Before we dive into the instructions, let's play the game. Use the up/down/arrow key to control, move and rotate the blocks.

Installing Amazon Q CLI

There are already great tutorials available for Linux and Windows, so I will not reiterate here. Make sure "Virtualization" is enabled in your computer (that is something you can look for in the boot menu settings) and just follow the instructions, it is easy peasy 🫛

How To Create The Game

Once Q CLI is installed and login is done, run "q chat" command (restart the terminal if "q" command is not recognized).

Give instructions for your favorite game that you want to create and it will be ready within minutes! Reiterate, add, and improve after that🚀

Here are the instructions that I gave:-

I want to create a Tetris game where blocks are fruits, and when 3 fruits are accumulated, they are destroyed.
Each block should be made of the same fruits. Also, blocks should be destroyed only when 6 fruits are the same.
There is some bug... fruits are disappearing even if 6 are not touching each other. Even if the overall count is 6, fruits are being destroyed.
Is it possible to support controls for Android?

You should also try it out, it is fun😃

Spring Pokédex - Explore! Identify! Appreciate!

Rishi — Fri, 06 Jun 2025 14:24:07 +0000

Spring is the season of nature’s greenery, blooming flowers, and buzzing insects. There are millions and trillions of species of flora and fauna. Often, we come across something mesmerizing but don’t know what it is!

To solve this mystery, Spring Pokédex comes to the rescue. This blog post dives into how the Spring Pokédex works and the architecture behind it.

UX Workflow - A Magical Experience 🌿

Ashley, a budding AWS engineer, went to the park on a beautiful spring day. While strolling around, she noticed a reddish-pink flower with a unique, shooting fragrance. She had never seen this flower and wondered what is the name of this species. Suddenly, she recalled that her friend Brock had once mentioned that an app named Spring Pokédex is handy in these situations.

She quickly opened the application, created an account, and logged in without any issues. Thanks to AWS Cognito for handling user management.

After that, she clicked on the “Scan Now” button and took a photo of the plant. The image started uploading and a notification confirmed the successful upload. A short while later, a notification popped up: “Creature Identified!”. Ashley screamed with joy! As she tapped the notification, the screen displayed 🌸Frangipani (Plumeria).

Behind the scenes, the image was securely uploaded using S3-Presigned URLs, and a real-time notification system (powered by Momento Topics) awaited the results.

She clicked on the “Share” button and a unique shareable link was generated (powered by Momento Cache) which she quickly sent to Brock.

Later that day, after reaching home, Ashley thought “What if other users could access the images she uploaded? 🤔”. Curious, she opened her laptop and tried to access the image she uploaded but this time as another user. To her surprise, it did not work, access was denied!
Why? Because access to files has been protected using CloudFront signed cookies.

Ashley was seriously impressed. Her curiosity sparked, and she wanted to dive deeper into the architecture behind the application. She wondered if any documentation was available online — and luckily, there was.

Spring Pokédex Architecture: High-Lvl Overview 🔮

Let’s see what really powers the magic of Spring Pokédex🪄

Bit Scary, isn’t it? Well, let us break it down into small workflows.

1. CloudFront CDN And Its Behaviours

The application is delivered through AWS CloudFront distribution. And it has 3 behaviors pointing to 3 different origins.

The first behaviour matches “/api*” in the URL and points to the AWS API gateway (protected by Cognito authorizer).

The second behaviour looks for the path pattern “/images” and points to the “images” folder of the application bucket. This behaviour restricts view access using signedCookies and signedURLs.

If none of the above behaviour match, the default behaviour serves the React application from the “dist” folder of the S3 bucket (using origin access identity OAI).

2. What Happens When App Loads?

If the user is not authenticated, redirection happens to Cognito managed login. After successful authentication, the user is redirected to the callback URL of the application with authorization_code that is used to request ACCESS_TOKEN (as part of the oAuth2.0 protocol).

After that, a request to “/api/getSignedCookies” is made to get CloudFront signed cookies for “/images/cognitoUserId/*” folder of S3, ie. users can access images uploaded by them only.

Also, a request is made to “/api/getDisposableToken” endpoint to get the Momento disposable token. Lambda function with valid Momento credentials sits behind the API and acts as a disposable token vending machine.

Momento token contains view-only scopes for Momento Topic named “pubsub-cache:cogintoUserId” and cache named “shared-cache”. Frontend uses the Momento disposable token to subscribe to the topic.

3. Discover Nature - One Scan At A Time!

The user clicks on the “Scan Now” button and selects (captures using the camera) an image to upload. Frontend makes a request to “/api/getSignedURL” endpoint to get signedURL and upload the image. Once the image is uploaded, frontend reflects the status as “Processing” and waits for a status update message on the Momento topic.

The image is uploaded to AWS S3 as “/images/cognito-user-id/image.png” and triggers the SpringScanner AWS Lambda function. The Lambda function generates a CloudFront signed URL for the image and calls OpenAI API using it.

On success, lambda stores data in the DynamoDB table and also publishes a success message to the Momento topic. On failure or crash of lambda function, the event goes to SQS queue (Dead-Letter Queue) and triggers DLQ handler lambda function that publishes failure message to the topic.

Frontend listens for these messages and shows details to the user in realtime. Mometo topic helps to achieve this without having any websockets connection.

4. Check History Or Share Your Discovery

At the time of the scan, data is stored in a DynamoDB table where userId is the partition key and S3ObjectKey is the sort key. History of scans for a user can be fetched by querying dynamo table using userId (/scanHistory endpoint).

When the user decides to share the scan with someone, api call to “/shareScan” endpoint is made. Using the userId from lambda event and scanId received as part of API payload, a DynamoDB call retrieves the scan details.

Since image access is allowed only for the original uploader, the imageUrl can’t be shared directly. To solve this, a CloudFront signed URL is generated with a validity of 24 hours.

This signed URL and the scan details are stored in a Momento cache with a unique identifier. That identifier becomes part of the shareable URL. Both the cache entry and the signed URL have a TTL of 24 hours, so the shared scan remains accessible to others for one day only.

5. Rate Limiting The Scans

Momento cache is also used to limit how many scan operations a user can perform in a single day.

For each user, a cache key like “userid-date-today” is created, and its value is incremented with every image upload (this logic is integrated into the getSignedURL Lambda function).

Once the max threshold is reached, the API returns a 429 Too Many Requests, and the frontend blocks further uploads.

6. Securing The Secrets

The Lambda functions use sensitive credentials like the Momento API key, OpenAI API key, and the CloudFront private key. These secrets should never be stored directly in code.

One option is to store them in Lambda environment variables and encrypt them using a KMS customer-managed key for additional security. But a more secure and flexible approach is to store secrets in AWS SSM Parameter Store or AWS Secrets Manager.

To simplify secret access in Lambda, middy middleware is used. Middy helps to inject secrets from SSM or Secrets Manager into function’s context.

🐼 Final Thoughts
Ashley closed her laptop with a smile. What started as a simple curiosity in the park turned into a deep dive into modern serverless event-driven architecture.

GitHub:- https://github.com/TrickSumo/Spring-Pokedex

Thanks for reading, and I hope you enjoyed Spring Pokédex project 🌱

AWS Serverless CRUD App Tutorial Using Lambda, API Gateway, DynamoDB, Cognito and Cloudfront CDN

Rishi — Tue, 08 Apr 2025 14:40:16 +0000

In this tutorial, we will use AWS services to create a serverless application for a coffee shop. The user (coffee shop owner in this case) can authenticate using AWS Cognito and manage inventory (perform CRUD operations).

Github Repo: https://github.com/TrickSumo/AWS-CRUD-Serverless

Architecture Overview

We will use DynamoDB to store data and lambda functions (with lambda layer) to process API gateway requests. API gateway will be secured by Cognito and exposed with the help of Cloudfront CDN. React frontend will also be configured with Cognito UserPool and hosted on S3 and Cloudfront.

Optionally, Cloudflare and AWS Certificate Manager can be used to add a custom domain to Cloudront distribution.

Step 1 – Create DynamoDB Table

Head over to the AWS console and navigate to the DynamoDB section. Then create a new table with table name as “CoffeeShop” and partiton key as “coffeeId”.

Create a new item (coffee) in the table and fill attributes like coffeeId, name, price, and availability. It will be helpful to test connectivity to DynamoDB.

{
"coffeeId": "c123",
"name": "new cold coffee",
"price": 456,
"available": true
}

Step 2 – Create IAM Role For Lambda Function

Create a new IAM role with permissions to create CloudWatch logs and CRUD access to the “CoffeeShop” DynamoDB table. Let us call this IAM role as “CoffeeShopRole” and its a generic role for all our lambda functions.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "dynamodb:PutItem",
                "dynamodb:DeleteItem",
                "dynamodb:GetItem",
                "dynamodb:Scan",
                "dynamodb:UpdateItem"
            ],
            "Resource": "arn:aws:dynamodb::<DYNAMODB_TABLE_NAME>"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

Step 3: Create Lambda Layer And Lambda Functions

First, create a Node.js Lambda layer that includes the DynamoDB library and common utility functions. It will help us avoid redundant installations of the same dependencies across multiple Lambdas.

mkdir nodejs
cd nodejs
npm init
npm i @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
touch utils.mjs

Now create a utils.mjs file to keep the code for DynamoDB client initialization and createResponse function.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
    DynamoDBDocumentClient,
    ScanCommand,
    GetCommand,
    PutCommand,
    UpdateCommand,
    DeleteCommand
} from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

const createResponse = (statusCode, body) => {
    return {
        statusCode,
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(body),
    };
};

export {
    docClient,
    createResponse,
    ScanCommand,
    GetCommand,
    PutCommand,
    UpdateCommand,
    DeleteCommand
};

Then, create a zip of the content and upload it in a new lambda layer. According to convention, the folder where we keep all these dependencies must be named “nodejs”. Apart from that, the name of the zip file and lambda layer can be anything.

In our case, let us create zip named “layer.zip” and upload it to the Lambda layer named “Dynamo-Layer”

cd ..
zip -r layer.zip nodejs

Now create four lambda functions and attach this layer (Dynamo-Layer) and IAM Role (CoffeeShopRole) to them.

// getCoffee Function

import { docClient, GetCommand, ScanCommand, createResponse } from '/opt/nodejs/utils.mjs'; // Import from Layer

const tableName = process.env.tableName || "CoffeeShop";

export const getCoffee = async (event) => {
    const { pathParameters } = event;
    const { id } = pathParameters || {};

    try {
        let command;
        if (id) {
            command = new GetCommand({
                TableName: tableName,
                Key: {
                    "coffeeId": id,
                },
            });
        }
        else {
            command = new ScanCommand({
                TableName: tableName,
            });
        }
        const response = await docClient.send(command);
        return createResponse(200, response);
    }
    catch (err) {
        console.error("Error fetching data from DynamoDB:", err);
        return createResponse(500, { error: err.message });
    }

}

// createCoffee Function

import { docClient, PutCommand, createResponse } from '/opt/nodejs/utils.mjs'; // Import from Layer

const tableName = process.env.tableName || "CoffeeShop";

export const createCoffee = async (event) => {
    const { body } = event;
    const { coffeeId, name, price, available } = JSON.parse(body || "{}");

    console.log("valuies", coffeeId, name, price, available);


    if (!coffeeId || !name || !price || available === undefined) {
        return createResponse(409, { error: "Missing required attributes for the item: coffeeId, name, price, or available." });
    }

    const command = new PutCommand({
        TableName: tableName,
        Item: {
            coffeeId,
            name,
            price,
            available
        },
        ConditionExpression: "attribute_not_exists(coffeeId)",
    });

    try {
        const response = await docClient.send(command);
        return createResponse(201, { message: "Item Created Successfully!", response });
    }
    catch (err) {
        if (err.message === "The conditional request failed")
            return createResponse(409, { error: "Item already exists!" });
        else
            return createResponse(500, {
                error: "Internal Server Error!",
                message: err.message,
            });
    }

}

// updateCoffee Function

import { docClient, UpdateCommand, createResponse } from '/opt/nodejs/utils.mjs'; // Import from Layer

const tableName = process.env.tableName || "CoffeeShop";

export const updateCoffee = async (event) => {
    const { pathParameters, body } = event;

    const coffeeId = pathParameters?.id;
    if (!coffeeId)
        return createResponse(400, { error: "Missing coffeeId" });

    const { name, price, available } = JSON.parse(body || "{}");
    if (!name && !price && available === undefined)
        return createResponse(400, { error: "Nothing to update!" })

    let updateExpression = `SET  ${name ? "#name = :name, " : ""}${price ? "price = :price, " : ""}${available ? "available = :available, " : ""}`.slice(0, -2);

    try {

        const command = new UpdateCommand({
            TableName: tableName,
            Key: {
                coffeeId,
            },
            UpdateExpression: updateExpression,
            ...(name && {
                ExpressionAttributeNames: {
                    "#name": "name", // name is a reserved keyword in DynamoDB
                },
            }),
            ExpressionAttributeValues: {
                ...(name && { ":name": name }),
                ...(price && { ":price": price }),
                ...(available && { ":available": available }),
            },
            ReturnValues: "ALL_NEW", // returns updated value as response
            ConditionExpression: "attribute_exists(coffeeId)", // ensures the item exists before updating
        });

        const response = await docClient.send(command);
        console.log(response);
        return response;

    }
    catch (err) {
        if (err.message === "The conditional request failed")
            return createResponse(404, { error: "Item does not exists!" });
        return createResponse(500, {
            error: "Internal Server Error!",
            message: err.message,
        });
    }
}

// deleteCoffee Function

import { docClient, DeleteCommand, createResponse } from '/opt/nodejs/utils.mjs'; // Import from Layer

const tableName = process.env.tableName || "CoffeeShop";

export const deleteCoffee = async (event) => {
    const { pathParameters } = event;
    const coffeeId = pathParameters?.id;
    if (!coffeeId)
        return createResponse(400, { error: "Missing coffeeId" });

    try {
        const command = new DeleteCommand({
            TableName: tableName,
            Key: {
                coffeeId,
            },
            ReturnValues: "ALL_OLD", // returns deleted value as response
            ConditionExpression: "attribute_exists(coffeeId)", // ensures the item exists before deleting
        });

        const response = await docClient.send(command);
        return createResponse(200, { message: "Item Deleted Successfully!", response });
    }
    catch (err) {
        if (err.message === "The conditional request failed")
            return createResponse(404, { error: "Item does not exists!" });
        return createResponse(500, {
            error: "Internal Server Error!",
            message: err.message,
        });
    }
}

Step 4: Create API Gateway To Expose Lambda Functions

Create an HTTP API Gateway and add five routes pointing to the above lambda functions.

GET /coffee -> getCoffee lambda function
GET /coffee/{id} -> getCoffee lambda function
POST /coffee -> createCoffee lambda function
PUT /coffee/{id} -> updateCoffee lambda function
DELETE /coffee/{id} -> deleteCoffee lambda function

At this point, you should be able to use all APIs using Postman or Thunderclient.

Step 5: Create Cognito UserPool And API Gateway Authorizer

Create a cognito UserPool with a public client (SPA App) and use it as a JWT authorizer for API gateway for all the routes.

Step 6: Setup React Application And Upload Build To S3 Bucket

Create a new React app and configure it with Cognito. You can copy files from here: https://github.com/TrickSumo/AWS-CRUD-Serverless/tree/main/FrontendWithAuth

Create a new S3 bucket, build the React app, and upload the “dist” folder to the S3 bucket.

Step 7: Create Cloudfront Distribution With Behaviors For S3 And API Gateway

Create a new Cloudfront distribution with S3 as the origin and use OAC to access the private bucket (make sure to update bucket policy).

Create another origin pointing to API gateway and create a new behaviour to redirect “/coffee*” routes to this new origin.

Step 8: Attach Custom Domain Name To CDN (Optional)

Edit CDN settings to add an alternate domain name. Use AWS Certificate Manager to issue an SSL certificate (to verify domain ownership, CNAME record method can be used).

Create a new CNAME record from the domain name control panel to point to the Cloudfront distribution URL.

Done 🥳

Step 9: Clean Up All Resources

Now it’s time to clear all resources. Delete CDN, DynamoDB, API Gateway, Lambdas (with Layer), IAM Role, ACM certificate, and Cognito UserPool.

Hope you enjoyed the tutorial! Thanks 🙂

AWS KMS Deep Dive - The Mystery Of Envelope Encryption

Rishi — Sun, 23 Mar 2025 15:45:00 +0000

AWS Key Management Service (KMS) allows you to create/manage encryption keys that are used to encrypt/decrypt and sign/verify data. AWS internally uses KMS across many services for encryption, so even if you’re not familiar with it, there’s a high chance you’ve already used it while working with other services (like while creating an S3 bucket!).

In this post, we will explore how KMS uses envelope encryption, understand different KMS key types, and finally do hands-on with KMS using AWS CLI commands.

Let’s start with the story of Pandora to get a gist of envelope encryption.

Pandora And The Envelope Encryption

The story goes like this, Zeus (king of Olympus) gave Pandora a box and asked her to never open it at any cost. But curious Pandora got curious and opened it anyway.

Zeus could have given Pandora a locked box with a key and asked to not open it. In this scenario, Pandora might lose the key. Or she might open the locked box and claim she doesn’t know who did it.

Zeus can also try to lock the box using his own key and give only the box to Pandora. In this case, Zeus would be responsible for keeping the key safe. Also, someone might steal the key from Zeus and open the box.

To solve these problems, Zeus could have used envelope encryption. First, he locks the box using a unique key. Then, instead of giving her the raw key, he encrypts it using his lightning bolt weapon⚡(his strongest secret). Now, he gives Pandora both the locked box and the encrypted key. This ensures:

Pandora can’t open the box without Zeus’ help (Zeus must decrypt the key first to unlock the box).
If Pandora loses the key, no one else can use it.
To unlock the box, Pandora must call Zeus to decrypt the key. Later, she can’t deny granting access by claiming she doesn’t know who opened the box.

Envelope Encryption

The above story is an example of envelope encryption, where the key used to encrypt the message (Pandora’s box of hope in our story) is encrypted itself (often using a more secret key ⚡). Then both the encrypted object (box) and encrypted key are stored together.

It is called envelope encryption because the key used for locking the box is wrapped (enveloped/encrypted) by a super-secure master key. Then both locked object and encrypted key are packed into a single structure (thus forming an envelope).

The purpose of encrypting a key with another key (multiple layers of keys) is to provide centralized key management and auditing while ensuring that the primary key is never exposed in an unencrypted form. Check out the article on FreeCodeCamp on how envelope encryption helps to manage encryption at scale.

KMS Key Types

Based on ownership, KMS offers three key types –

AWS Owned Keys (free) =>These keys provide default encryption for most of the services. You might have seen the SSE-S3 option while creating an S3 bucket. Everything is handled in the background and these keys are not visible anywhere. No visibility on audit trails or key rotation.
AWS Managed Keys (free) => These keys are also to be used by AWS services only (aws/s3 or aws/rds). However, customers can see key policies and CloudTrail events for AWS-managed keys. Everything else is managed by AWS.
Customer Managed Keys ($1/month) => You (customer) own this key and can view audit trails and rotate on demand (Careful! Each key rotation adds $1/month to the bill since all versions are retained). If you want to call KMS API to create a key and use it in your applications, this is the type that you need.

Based on cryptographic structure, a key can be symmetric or asymmetric. For the rest of the tutorial, we will focus on customer-managed symmetric KMS keys.

Envelope Encryption In Action – KMS Workflow

Fair warning before we proceed forward, you are going to encounter a lot of keys. Be prepared!

Step1: Key Creation

When a customer-managed KMS key is created, AWS uses HSM (hardware security module) hardware to create HSM Backing Key (HBK⚡). Since it’s not possible to keep HBK in memory of HSM forever, it must be exported to durable storage. But HBK cannot leave the HSM unencrypted. So, HBK is encrypted using HSM-managed domain keys to generate an EKT (Exported Key Token) and stored in a database. Then our newly created KMS key points to this EKT.

Yes, a KMS key (also called customer master key CMK) does not contain actual key material. Instead, it acts as a pointer to the EKT (which is an encrypted version of the HBK itself)!

Step2: Envelope Encryption

When the user (or services like S3) requests a data key (also called Data Encryption Key but we will call it data key because the term DEK is needed for another key – I promised too many keys ☺️) from KMS to encrypt an object, it also tells which KMS key to use (either by specifying key id or key alias). As we know, the KMS key serves as a pointer to the EKT. So EKT is taken to HSM and converted back to HBK (HSM Backing Key ⚡). After that, HBK is combined with Nonce (random number) to create a Derived Encryption Key (DEK).

Inside the HSM, a data key is also generated (also called Customer Data Key CDK or Data Encryption Key). This key will be used to lock the box (encrypt the object). Then the data key is encrypted using DEK (derived encryption key) and both the plaintext data key and encrypted data key are sent to the user (or service). For now, DEK will be discarded by HSM. Remember, the DEK encrypts the data key, which in turn encrypts the object.

Now user can encrypt a file/object using the plaintext data key and immediately discard it. Then store the encrypted file and encrypted data key together.

Step3: Envelope Decryption?

In storage, we have an encrypted object and encrypted data key. To decrypt the object, we again need the plaintext data key but we deleted it just after encrypting the file/object (even S3 would also have done the same).

To get the plaintext data key, we send the encrypted data key to KMS as part of the decrypt API. AWS HSM extracts the KMS key ID/alias and nonce from the encrypted data key. From the KMS key, EKT is traced and HBK is calculated.

With HBK and nonce, the system regenerates the DEK (which was originally used to encrypt the data key). Then DEK is used to decrypt the data key and the plaintext data key is returned to the user.

Finally, the plaintext data key can be utilized to decrypt the encrypted file/object.

KMS Hands-On Using AWS CLI – Less Than 4KB File Size

For files smaller than 4KB, no need to request a data key. Just call encrypt/decrypt API and KMS will take care of all other things internally.

Create a symmetric KMS customer-managed key with Alias “learn”. Make sure to have encrypt and decrypt privileges for your AWS user.
Open AWS CLI (top right in console), and create a file named myFile.txt.
Call KMS encrypt command
aws kms encrypt --key-id alias/learn --plaintext fileb://myFile.txt --output text --query CiphertextBlob --region ap-south-1 | base64 -d > myFile.encrypted
Now you should be able to see a new encrypted file myFile.encrypted.
To decrypt the file, use the KMS decrypt command
aws kms decrypt --ciphertext-blob fileb://myFile.encrypted --output text --query Plaintext --region ap-south-1 | base64 -d
In CLI, you should be able to see the original text of myFile.txt.

KMS Hands-On Using AWS CLI – More Than 4KB File Size

For files bigger than 4KB, we can call GenerateDataKey API to get the data key and encrypted data key.

Get data key
aws kms generate-data-key --key-id alias/learn --key-spec AES_256 > data_key.json
Store both data keys
jq -r '.Plaintext' data_key.json | base64 --decode > data_key_plaintext jq -r '.CiphertextBlob' data_key.json | base64 -d > data_key_encrypted
Encrypt the “test.txt” file and delete the plaintext data key
openssl enc -aes-256-cbc -pbkdf2 -salt -in test.txt -out test.encrypted -pass file:data_key_plaintext && rm data_key_plaintext
For decrypting the file, decrypt the encrypted data key
aws kms decrypt --ciphertext-blob fileb://data_key_encrypted --output text --query Plaintext --region ap-south-1 | base64 --decode > data_key_plaintext
Then decrypt the locked file
openssl enc -d -aes-256-cbc -pbkdf2 -salt -in test.encrypted -out test.decrypted.txt -pass file:data_key_plaintext

KMS Use Cases – Project Ideas

Here are a few ideas to play with KMS:-

Password manager using KMS and DynamoDB.
JWT-based authentication – KMS can be used to sign and verify JWTs.
Use KMS to implement passkeys using FIDO2.0.

Share your ideas in the comments!

Conclusion – KMS is Not Scary Anymore!

Hope this tutorial helped you to understand the ins and outs of AWS KMS. Let me know your feedback and thoughts. Thanks 🙂