Lambda Web AdapterでSQSイベントを処理する

2025.12.16
Lambda Web AdapterでSQSイベントを処理する
この記事をシェアする

Lambda Web Adapterを使って、SQSのような非HTTPイベントをWebアプリで処理してみました。
HTTPリクエスト以外のイベントをどのように変換して扱うのか、部分的なバッチレスポンスの実装方法まで紹介します。

1. この記事の要約

  • Lambda Web Adapterは、SQSなどの非HTTPイベントもWebアプリで処理できる
  • イベントはPOST /eventsのHTTPリクエストに変換される
  • 部分的なバッチレスポンスは、レスポンスボディにbatchItemFailuresを設定して実現
  • レスポンスストリーミングモードはオフにする必要がある(デフォルトはオフ)

2. Lambda Web Adapterとは?

Lambda Web Adapter(LWA)は、任意のウェブアプリケーションをコード変更なしでAWS Lambda上で動作させるためのツールです。
Lambda Extensionとしてデプロイされ、LambdaへのイベントをHTTPリクエストに変換してWebアプリに転送します。

基本的な仕組みについては、前回の記事で詳しく解説しています。

また、builders.flashの記事と図がわかりやすく解説しています。

https://aws.amazon.com/jp/builders-flash/202301/lambda-web-adapter/

この図を見ると、ALB、API Gateway、CloudFront(+ Function URL)からのHTTPリクエストを処理する様子がわかります。
では、これ以外のイベントソース(例えばSQSのイベントソースマッピング)からのイベントは、どのように変換されるのでしょうか。

3. 非HTTPイベントとは?

非HTTPイベントとは、SQSやS3のようなHTTPリクエストではないイベントのことです。
LambdaはHTTPリクエスト以外にも、様々なAWSサービスからイベントを受け取れます。

主な非HTTPイベントソースの例です。

  • SQS(Simple Queue Service)
  • S3(Object Created/Deletedイベント)
  • DynamoDB Streams
  • EventBridge
  • SNS

これらのイベントは、それぞれ固有のJSON構造を持っています。

4. LWAによる非HTTPイベントの変換

4-1. 変換の仕組み

LWAは、非HTTPイベントを以下のルールでHTTPリクエストに変換します。

  • メソッド: POST固定
  • パス: /events(デフォルト)
  • ボディ: Lambdaが受け取ったイベントの内容がそのまま入る
  • ヘッダー: Content-Type: application/json

4-2. 実際の変換例

SQSイベントの場合、Webアプリのミドルウェアでログを出力すると、以下のようなHTTPリクエストに変換されていることがわかります。

{
    "method": "POST",
    "url": "http://127.0.0.1:3000/events",
    "headers": {
        "content-type": "application/json"
    },
    "requestBody": {
        "Records": [
            {
                "messageId": "XXX",
                "receiptHandle": "XXX",
                "body": "{\"data\": \"failure message\", \"shouldFail\": true}",
                "attributes": {
                    "ApproximateReceiveCount": "1",
                    "SentTimestamp": "XXX",
                    "SenderId": "XXX",
                    "ApproximateFirstReceiveTimestamp": "1765884146090"
                },
                "messageAttributes": {},
                "md5OfMessageAttributes": null,
                "md5OfBody": "d703a728d0e48d5496d87914cf5860c6",
                "eventSource": "aws:sqs",
                "eventSourceARN": "arn:aws:sqs:ap-northeast-1:XXX:tanstack-start-queue",
                "awsRegion": "ap-northeast-1"
            }
        ]
    }
}

このように、SQSとLambdaを普通に統合したときのeventの内容が、そのままHTTPリクエストのボディに入ります。

5. Webアプリでの実装方法

TanStack Startでの実装例を示しています。

5-1. 基本的な実装

WebアプリでPOST /eventsのルートを作成すれば、SQSイベントを受け取れます。
TanStack Startでの実装例です。

// /src/routes/events.ts
import { createFileRoute } from "@tanstack/react-router";
import { json } from "@tanstack/react-start";
import type { SQSEvent } from "aws-lambda";

export const Route = createFileRoute("/events")({
  server: {
    handlers: {
      POST: async ({ request }) => {
        try {
          // 簡易的にcastしているが、本来はvalidateすべき
          const event = (await request.json()) as SQSEvent;
          
          // イベント処理
          await processEvent(event);
          
          // 成功時は200を返す
          return json({}, { status: 200 });
        } catch (error) {
          // 失敗時は500を返す
          return json({}, { status: 500 });
        }
      },
    },
  },
});

5-2. 失敗のハンドリング

失敗を通知するには、AWS_LWA_ERROR_STATUS_CODES環境変数で失敗とみなすステータスコードを定義します。
例えば、以下のように設定します。

AWS_LWA_ERROR_STATUS_CODES=500,503

この設定により、ステータスコード500または503を返すと、Lambdaは実行失敗として扱われます。

6. 部分的なバッチレスポンスの実装

6-1. 部分的なバッチレスポンスとは?

SQSでは、複数のメッセージをバッチで受け取り、一部のメッセージだけ処理を失敗させることができます。
これを「部分的なバッチレスポンス」と呼びます。

詳細は以下の記事で解説されています。

https://qiita.com/omochi_1190/items/0e75c08970f290656b30

部分的なバッチレスポンスを使用すると、以下のメリットがあります。

  • 成功したメッセージは再処理されない
  • 失敗したメッセージだけがキューに戻される
  • 処理効率が向上する

6-2. レスポンスの形式

部分的なバッチレスポンスを返すには、レスポンスボディにbatchItemFailuresを設定します。

{
    "batchItemFailures": [
        {
            "itemIdentifier": "失敗したメッセージID"
        }
    ]
}

6-3. 実装例

TanStack Startでの実装例です。

import { createFileRoute } from "@tanstack/react-router";
import { json } from "@tanstack/react-start";
import type { SQSEvent, SQSRecord } from "aws-lambda";

// Lambda部分的なバッチレスポンスの型定義
interface BatchItemFailure {
  itemIdentifier: string;
}

interface SQSBatchResponse {
  batchItemFailures: BatchItemFailure[];
}

export const Route = createFileRoute("/events")({
  server: {
    handlers: {
      POST: async ({ request }) => {
        try {
          const event = (await request.json()) as SQSEvent;

          logger.info({
            msg: "Received SQS event",
            recordCount: event.Records.length,
          });

          // 失敗したメッセージのIDを収集
          const batchItemFailures: BatchItemFailure[] = [];

          // 各メッセージを個別に処理
          // Promise.allSettledを使用して並列処理しつつ、エラーでも継続
          const results = await Promise.allSettled(
            event.Records.map(async (record: SQSRecord) => {
              try {
                await processSQSMessage(record);
                logger.info({
                  msg: "Message processed successfully",
                  messageId: record.messageId,
                });
                return { messageId: record.messageId, status: "success" };
              } catch (error) {
                logger.error({
                  msg: "Message processing failed",
                  messageId: record.messageId,
                  error: error instanceof Error ? error.message : String(error),
                });
                // 失敗したメッセージのIDを記録
                batchItemFailures.push({
                  itemIdentifier: record.messageId,
                });
                throw error;
              }
            }),
          );

          const successCount = results.filter(
            (r) => r.status === "fulfilled",
          ).length;
          const failureCount = results.filter(
            (r) => r.status === "rejected",
          ).length;

          logger.info({
            msg: "Processing complete",
            successCount,
            failureCount,
            totalCount: event.Records.length,
          });

          if (batchItemFailures.length > 0) {
            logger.warn({
              msg: "Returning failed messages",
              failedCount: batchItemFailures.length,
              failedMessageIds: batchItemFailures.map((f) => f.itemIdentifier),
            });
          }

          // batchItemFailuresを返す(空の配列でも可)
          // Lambda Web Adapterがこのレスポンスボディを使って
          // Lambdaのレスポンスを構築します
          const response: SQSBatchResponse = {
            batchItemFailures,
          };

          // 部分的な失敗でも200を返す
          return json(response, { status: 200 });
        } catch (error) {
          logger.error({
            msg: "Critical error processing SQS event",
            error: error instanceof Error ? error.message : String(error),
            stack: error instanceof Error ? error.stack : undefined,
          });

          // クリティカルエラーの場合は全メッセージを失敗として扱う
          return json(
            {
              status: "error",
              message: error instanceof Error ? error.message : "Unknown error",
            },
            { status: 500 },
          );
        }
      },
    },
  },
});

この実装のポイントは以下の通りです。

  • Promise.allSettledで各メッセージを並列処理
  • 失敗したメッセージのIDをbatchItemFailures配列に追加
  • 部分的な失敗でもステータスコード200を返す
  • レスポンスボディにbatchItemFailuresを含める

7. はまりポイント:レスポンスストリーミング

7-1. レスポンスストリーミングをオフにする

部分的なバッチレスポンスを使用する場合、Lambda Web Adapterのレスポンスストリーミングオプションはオフにする必要があります。

デフォルトではオフになっていますが、Dockerfileや環境変数で以下の設定になっていないか確認してください。

# この設定は避ける
AWS_LWA_INVOKE_MODE=response_stream

7-2. なぜオフにする必要があるのか?

おそらく、内部的にチャンク化されたレスポンスがLWAからLambdaに返されており、AWSがこれを正しく処理できないためと考えられます。

レスポンスストリーミングモードがオンの場合、以下のような問題が発生する可能性があります。

  • batchItemFailuresが正しくパースされない
  • 部分的なバッチレスポンスが機能しない
  • 予期しないエラーが発生する

7-3. オフにすることの影響

部分的なバッチレスポンスためにレスポンスストリーミングをオフにする必要がある点で、Lambda Web Adapterで非HTTPイベントを処理するのは非現実的な選択肢だな・・・と感じました。

最近のフロントエンドフレームワークはレスポンスストリーミングを前提にしていることが多く、レスポンスストリーミングをオフにすると、せっかくの機能や性能を活かせなくなってしまいます。

8. Lambda Web Adapterで非HTTPイベントを扱うメリットとデメリット

8-1. メリット

  • 既存のWebフレームワークの知識が活用できる
  • ミドルウェアが使える
  • テストがしやすい

8-2. デメリット

  • Lambda固有の機能が使いにくい
  • 部分的なバッチレスポンスためにレスポンスストリーミングをオフにする必要がある
  • 非HTTPイベントのルーティングは1個しか設定できない。
    • AWS_LWA_PASS_THROUGH_PATHで/events以外のパスでも処理できますが、あくまで1つ固定です。
    • つまり、SQSやS3などの複数のイベントソースと統合する場合、/eventsの中で処理を分岐する必要があります。
  • 設定の注意点が多い

さいごに

本記事では、Lambda Web Adapterを使って非HTTPイベント(SQS)をWebアプリで処理する方法を紹介しました。

本番で使うのは微妙かもしれませんが、一つのWebアプリ、一つのLambdaで、画面・APIだけでなく、イベント処理までを賄えるのは面白いですね。
PoCとかでは有用かもしれないです。

この記事をシェアする
著者:酒井亮太郎
シナモロール