@exabugs/dynamodb-client 1.5.3 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",
@@ -91,6 +91,10 @@
       "import": "./dist/server/media/presign.js",
       "types": "./dist/server/media/presign.d.ts"
     },
+    "./server/media/upload-handler": {
+      "import": "./dist/server/media/upload-handler.js",
+      "types": "./dist/server/media/upload-handler.d.ts"
+    },
     "./server/media-process-handler": {
       "import": "./dist/server/media-process-handler.cjs",
       "types": "./dist/server/media/process-handler.d.ts"

package/terraform/media/README.md

@@ -17,7 +17,10 @@
 - CloudFront Distribution（`/master/*`はS3直接配信、`/resize/*`はmedia-handler経由、両方とも署名付きURL必須）
 - CloudFront Public Key / Key Group（署名鍵は呼び出し側がSSM Parameter Storeに別途登録する）
 
-**含まないもの**: presign/署名URL発行用のLambda。「誰にpresign/署名URLを発行してよいか」の認可判断はアプリごとに異なるため、呼び出し側は既存のHTTP APIレイヤー（認証・権限チェック済み）から `../../src/server/media/presign.ts`・`sign.ts` を直接呼び出して自前のLambda/ルートに組み込んでください。
+**含まないもの**: presign/署名URL発行用のLambdaリソース。「誰にpresign/署名URLを発行してよいか」の認可判断はアプリごとに、かつ同一アプリ内でもクライアント（モバイル/管理画面等）ごとに異なるため、Terraformでは画一的なリソースとして定義できません。呼び出し側は次のいずれかの方法で自前にデプロイしてください:
+
+- 既存のHTTP APIレイヤー（認証・権限チェック済み）から `../../src/server/media/presign.ts`・`sign.ts` を直接呼び出す
+- 対応する既存HTTPレイヤーが無いクライアント向けには `../../src/server/media/upload-handler.ts` の `createUploadHandler()` を使い、専用の小さなLambdaとして自前でバンドル・デプロイする
 
 ## 前提条件
 

package/terraform/media/main.tf

@@ -3,10 +3,15 @@
 # 詳細設計: ../../docs/media-design.md
 # 決定事項・トレードオフ: ../../docs/adr/0002-media-design.md
 #
-# 本モジュールは upload-handler（presign/sign発行）のLambdaを含まない。
-# 「誰にpresign/署名URLを発行するか」の認可判断はアプリごとに異なるため、呼び出し側は
-# 既存のHTTP APIレイヤー（認証・権限チェック済み）から `../../src/server/media/presign.ts`・
-# `sign.ts` を直接呼び出して自前のLambda/ルートに組み込むこと。
+# 本モジュールは upload-handler（presign/sign発行）のLambdaリソースを含まない。
+# 「誰にpresign/署名URLを発行するか」の認可判断はアプリごとに、かつ同一アプリ内でも
+# クライアント（モバイル/管理画面等）ごとに異なるため、Terraformでは画一的な
+# リソースとして定義できない。呼び出し側は次のいずれかの方法で自前にデプロイすること:
+#   (a) 既存のHTTP APIレイヤー（認証・権限チェック済み）から
+#       `../../src/server/media/presign.ts`・`sign.ts` を直接呼び出す
+#   (b) 対応する既存HTTPレイヤーが無いクライアント（例: 別の認証方式を使う管理画面）向けには
+#       `../../src/server/media/upload-handler.ts` の `createUploadHandler()` を使い、
+#       専用の小さなLambdaとして自前でバンドル・デプロイする
 
 locals {
   name_prefix = "${var.project_name}-${var.environment}-media"
@@ -51,6 +56,22 @@ resource "aws_s3_bucket_lifecycle_configuration" "media" {
   }
 }
 
+# ブラウザ（管理画面等）からpresigned POSTで直接S3へアップロードする場合に必要。
+# 無いとプリフライトリクエストが失敗しアップロードが全滅する
+# （モバイルアプリ（React Native）はCORSの対象外のため影響しない）。
+resource "aws_s3_bucket_cors_configuration" "media" {
+  count = length(var.allowed_upload_origins) > 0 ? 1 : 0
+
+  bucket = aws_s3_bucket.media.id
+
+  cors_rule {
+    allowed_methods = ["POST"]
+    allowed_origins = var.allowed_upload_origins
+    allowed_headers = ["*"]
+    max_age_seconds = 3000
+  }
+}
+
 # CloudFront OAC経由のアクセスのみ許可。Resourceはmaster/*に限定し、
 # raw/*・cache/*をバケットポリシー経由で公開しない（cache/*はmedia-handlerの実行ロール経由のみ）
 resource "aws_s3_bucket_policy" "media" {
@@ -158,8 +179,10 @@ resource "aws_iam_role_policy" "process_handler_dynamodb" {
     Version = "2012-10-17"
     Statement = [
       {
-        Effect   = "Allow"
-        Action   = ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:BatchGetItem", "dynamodb:Query"]
+        Effect = "Allow"
+        # DeleteItem: updateMany（handleUpdateOneの内部実装）はTransactWriteの中で
+        # 更新前の古いShadow Recordを削除する処理を含むため、2回目以降の更新に必須
+        Action   = ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:BatchGetItem", "dynamodb:Query"]
         Resource = [var.table_arn, "${var.table_arn}/index/*"]
       }
     ]
@@ -233,9 +256,13 @@ resource "aws_lambda_function" "process_handler" {
 
   environment {
     variables = {
-      REGION             = var.region
-      TABLE_NAME         = var.table_name
-      IMAGE_POLICY_PARAM = var.image_policy_param
+      REGION                  = var.region
+      TABLE_NAME              = var.table_name
+      IMAGE_POLICY_PARAM      = var.image_policy_param
+      SHADOW_CREATED_AT_FIELD = var.shadow_created_at_field
+      SHADOW_UPDATED_AT_FIELD = var.shadow_updated_at_field
+      SHADOW_STRING_MAX_BYTES = var.shadow_string_max_bytes
+      SHADOW_NUMBER_PADDING   = var.shadow_number_padding
     }
   }
 
@@ -254,6 +281,11 @@ resource "aws_lambda_function" "process_handler" {
 resource "aws_lambda_function_event_invoke_config" "process_handler" {
   function_name          = aws_lambda_function.process_handler.function_name
   maximum_retry_attempts = 2
+  # 既定の6時間だと、リトライが尽きてDLQ経由でfailedが書き込まれるまで
+  # 呼び出し側のポーリングが長時間ブロックされ得る。短く設定し、クライアントの
+  # タイムアウト判断（詳細: docs/media-design.md「ポーリングが区別すべき状態」）
+  # と整合させる。
+  maximum_event_age_in_seconds = 300
 
   destination_config {
     on_failure {
@@ -326,6 +358,27 @@ resource "aws_iam_role_policy" "process_handler_dlq_sqs" {
   })
 }
 
+resource "aws_iam_role_policy" "process_handler_dlq_s3" {
+  name = "s3-access"
+  role = aws_iam_role.process_handler_dlq.id
+
+  # failedレコードにownerId等のアプリ固有メタデータを含めるため、raw/{fileId}を
+  # HeadObjectで再取得する（process-handler-dlq.ts）。この権限が無いとHeadObjectが
+  # 常にAccessDeniedになり、fail-soft設計により静かに失敗し続ける
+  # （メタデータ無しのfailedレコードが書き込まれ、権限スコープ付きポーリングで
+  # 読めないままクライアントが無限ポーリングする問題が再発する）。
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect   = "Allow"
+        Action   = ["s3:GetObject"]
+        Resource = "${aws_s3_bucket.media.arn}/raw/*"
+      }
+    ]
+  })
+}
+
 resource "aws_iam_role_policy" "process_handler_dlq_dynamodb" {
   name = "dynamodb-access"
   role = aws_iam_role.process_handler_dlq.id
@@ -335,7 +388,7 @@ resource "aws_iam_role_policy" "process_handler_dlq_dynamodb" {
     Statement = [
       {
         Effect   = "Allow"
-        Action   = ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:BatchGetItem"]
+        Action   = ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:BatchGetItem"]
         Resource = [var.table_arn, "${var.table_arn}/index/*"]
       }
     ]
@@ -374,8 +427,12 @@ resource "aws_lambda_function" "process_handler_dlq" {
 
   environment {
     variables = {
-      REGION     = var.region
-      TABLE_NAME = var.table_name
+      REGION                  = var.region
+      TABLE_NAME              = var.table_name
+      SHADOW_CREATED_AT_FIELD = var.shadow_created_at_field
+      SHADOW_UPDATED_AT_FIELD = var.shadow_updated_at_field
+      SHADOW_STRING_MAX_BYTES = var.shadow_string_max_bytes
+      SHADOW_NUMBER_PADDING   = var.shadow_number_padding
     }
   }
 
@@ -383,6 +440,7 @@ resource "aws_lambda_function" "process_handler_dlq" {
     aws_cloudwatch_log_group.process_handler_dlq,
     aws_iam_role_policy.process_handler_dlq_sqs,
     aws_iam_role_policy.process_handler_dlq_dynamodb,
+    aws_iam_role_policy.process_handler_dlq_s3,
   ]
 
   tags = {
@@ -534,7 +592,7 @@ resource "aws_lambda_function_url" "media_handler" {
 }
 
 resource "aws_lambda_permission" "cloudfront_invoke_media_handler" {
-  statement_id           = "AllowCloudFrontInvoke"
+  statement_id           = "AllowCloudFrontInvokeFunctionUrl"
   action                 = "lambda:InvokeFunctionUrl"
   function_name          = aws_lambda_function.media_handler.function_name
   principal              = "cloudfront.amazonaws.com"
@@ -542,6 +600,21 @@ resource "aws_lambda_permission" "cloudfront_invoke_media_handler" {
   function_url_auth_type = "AWS_IAM"
 }
 
+# AWSはFunction URL + OAC経由の呼び出しに対してDual Auth（lambda:InvokeFunctionUrl
+# とlambda:InvokeFunctionの両方の許可）を正式に要求する（移行猶予期間は2026-11-01
+# まで）。lambda:InvokeFunctionUrlだけの許可では、猶予期間終了後に/resize/*が
+# 全件403になる（詳細: docs/adr/0002-media-design.md）。
+# invoked_via_function_url=true により、この許可をFunction URL経由の呼び出しに
+# 限定する（AWS推奨の条件キー）。
+resource "aws_lambda_permission" "cloudfront_invoke_media_handler_function" {
+  statement_id             = "AllowCloudFrontInvokeFunction"
+  action                   = "lambda:InvokeFunction"
+  function_name            = aws_lambda_function.media_handler.function_name
+  principal                = "cloudfront.amazonaws.com"
+  source_arn               = aws_cloudfront_distribution.media.arn
+  invoked_via_function_url = true
+}
+
 # ============================================================
 # CloudFront配信（署名付きURL必須、/master/*・/resize/*の2ビヘイビア）
 # ============================================================

package/terraform/media/variables.tf

@@ -31,6 +31,39 @@ variable "image_cache_ttl_days" {
   default     = 30
 }
 
+variable "allowed_upload_origins" {
+  description = "presigned POSTでのブラウザアップロードを許可するオリジン（例: Admin UIのドメイン）。空配列の場合はCORS設定自体を作らない（モバイルのみの利用等、ブラウザアップロードが不要な場合）"
+  type        = list(string)
+  default     = []
+}
+
+# 呼び出し側の既存テーブルに相乗りするため、process-handlerが生成するShadow Recordsの
+# 形式は呼び出し側の既存Lambda（records等）の設定と一致させる必要がある
+# （詳細: docs/media-design.md「環境変数の一致」）。既定値は本体（terraform/variables.tf）と揃える。
+variable "shadow_created_at_field" {
+  description = "作成日時フィールド名（呼び出し側の既存設定と一致させること）"
+  type        = string
+  default     = "createdAt"
+}
+
+variable "shadow_updated_at_field" {
+  description = "更新日時フィールド名（呼び出し側の既存設定と一致させること）"
+  type        = string
+  default     = "updatedAt"
+}
+
+variable "shadow_string_max_bytes" {
+  description = "プリミティブ型の最大バイト数（呼び出し側の既存設定と一致させること）"
+  type        = number
+  default     = 100
+}
+
+variable "shadow_number_padding" {
+  description = "数値のパディング桁数（呼び出し側の既存設定と一致させること）"
+  type        = number
+  default     = 15
+}
+
 variable "signing_public_key_param" {
   description = "CloudFront署名用の公開鍵（PEM形式）を保持するSSM Parameter名。値そのものは呼び出し側が別途登録する"
   type        = string