@exabugs/dynamodb-client 1.14.1 → 1.15.0

package/docs/DYNAMODB_ACCESS.md

@@ -1,9 +1,19 @@
 # DynamoDB へのアクセスのガードレール
 
-## 原則
+## アーキテクチャ（全文。他の文書は、これを要約して参照する）
 
-dynamodb-client を使った DynamoDB の操作は、**Records（サーバー）の 1 か所**で行う。クライアントは、通常の操作の API（`DynamoClient`）を呼ぶだけ。**例外を作らない。**
-例外（Lambda が本体テーブルを直接読み書きするなど）は、監査ログ（ADR 0004）のような横断機能の穴になる。
+**DynamoDB の操作は、dynamodb-client（Records）の 1 か所で行う。**
+
+- クライアント（BFF、管理画面、media の Lambda、運用スクリプト）は、**ビジネスのリクエスト**を受け、dynamodb-client の API（Records）への操作に展開する。通常の操作の API は `DynamoClient`。**media のアップロードの処理も、ビジネスのリクエストの一つ**であり、BFF など他のクライアントと区別しない。
+- DynamoDB の操作の制御（認可、監査、シャドーの維持、観測、容量）は、Records の **1 か所**で行う。全クライアントが Records に依存する、同じ構造である。
+- **例外を作らない。** 例外（Lambda が本体テーブルを直接読み書きするなど）は、監査ログ（ADR 0004）のような横断機能の穴になる。直接アクセスは、ガードレール（ESLint と IAM の検査。許可リスト）で禁止する。
+- **対象外**（別テーブル `notices` など）は、構造が違う内部用のテーブルで、ビジネスのデータではない。「例外」ではない。
+
+### 書き方の規則
+
+設計書・ADR では、Records への依存や HTTP 1 回分の遅延を、「限界」「問題」として書かない。**アーキテクチャの帰結（設計上の性質）**として書く。Records にリソースごとの認可がない、という既知の制約は、この構造とは独立に、別に書く（[AUTHORIZATION.md](AUTHORIZATION.md)）。
+
+関連: [ADR 0005](adr/0005-writes-through-records.md)（書き込みを Records に通す。「0. アーキテクチャ（前提）」）。
 
 ## 検査
 
@@ -128,7 +138,7 @@ ESLint は、エディタでも違反をその場で示す。CLI は ESLint の
 
 ## 許可リストの種別と約束
 
-- **恒久（permanent）**: 構造上必要な例外。このライブラリでは、Records の本体、Records が使う共有部品、別テーブル `notices`（`src/notify/store.ts`。内部用で、本体テーブルではない。理由は ADR 0005〔提案中〕）
+- **恒久（permanent）**: 構造上必要な例外。このライブラリでは、Records の本体、Records が使う共有部品、別テーブル `notices`（`src/notify/store.ts`）。`notices` は例外ではなく原則の**対象外**（構造が違う別テーブルで、通知の重複抑制・流量制限の内部用。ビジネスのデータではない）。検査が IAM をテーブルごとに区別できないため permanent として載せる（ADR 0005）
 - **負債（debt）**: 期限つき。消す作業が決まっている
 
 運用の約束:
@@ -145,8 +155,6 @@ ESLint は、エディタでも違反をその場で示す。CLI は ESLint の
 
 ## 現状の負債
 
-| 場所                                                                                    | 内容                                                         | 消す作業                                                              |
-| --------------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------- |
-| `src/server/media/process-handler.ts`、`process-handler-dlq.ts`                         | Records の `handle*` を直接呼ぶ                              | media の Lambda を Records のクライアントにする（ADR 0005〔提案中〕） |
-| `terraform/media/main.tf` の `process_handler_dynamodb`、`process_handler_dlq_dynamodb` | media の Lambda に本体テーブルの権限                         | 同上                                                                  |
-| `src/dynamodb.ts`                                                                       | 本体と重複した未使用のクライアント生成（テストからのみ参照） | `src/dynamodb.ts` と `__tests__/dynamodb.test.ts` の削除              |
+| 場所              | 内容                                                         | 消す作業                                                 |
+| ----------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
+| `src/dynamodb.ts` | 本体と重複した未使用のクライアント生成（テストからのみ参照） | `src/dynamodb.ts` と `__tests__/dynamodb.test.ts` の削除 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.14.1",
+  "version": "1.15.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",

package/terraform/media/README.md

@@ -38,8 +38,11 @@ module "media" {
   environment  = "dev"
   region       = "ap-northeast-1"
 
-  table_name = module.dynamodb.table_name
-  table_arn  = module.dynamodb.table_arn
+  # Records の IAM 版 Function URL とエイリアスの ARN（本体の出力）。media の Lambda は
+  # DynamoDB に直接触れず、Records を呼ぶ（ADR 0005）。table_name / table_arn / shadow_* は
+  # deprecated（1.16.0 で削除）で、渡しても無視される
+  records_iam_function_url = module.records.iam_function_url
+  records_iam_alias_arn = module.records.iam_alias_arn
 
   signing_public_key_param = "/my-project/dev/media/signing-public-key"
   image_policy_param       = "/my-project/dev/media/image-policy"

package/terraform/media/main.tf

@@ -104,6 +104,11 @@ resource "aws_sqs_queue" "process_handler_dlq" {
   name                      = "${local.name_prefix}-process-dlq"
   message_retention_seconds = 1209600 # 14日（SQS上限）
 
+  # Lambda（process-handler-dlq）のイベントソースになるキューの可視性タイムアウトは、関数の
+  # timeout 以上が必須（満たさないとマッピングの作成・更新が拒否される）。AWS の推奨は 6 倍
+  # （AWS Lambda 開発者ガイド「Amazon SQS でのイベントソースマッピング」、ADR 0005）
+  visibility_timeout_seconds = var.process_handler_dlq_timeout * 6
+
   tags = {
     Name = "${local.name_prefix}-process-dlq"
   }
@@ -180,19 +185,19 @@ resource "aws_iam_role_policy" "process_handler_s3" {
   })
 }
 
-resource "aws_iam_role_policy" "process_handler_dynamodb" {
-  name = "dynamodb-access"
+resource "aws_iam_role_policy" "process_handler_records" {
+  name = "records-invoke"
   role = aws_iam_role.process_handler.id
 
+  # DynamoDB には直接触れず、Records の IAM 版 Function URL を呼ぶ（ADR 0005）
   policy = jsonencode({
     Version = "2012-10-17"
     Statement = [
       {
         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/*"]
+        # 2025 年 10 月以降の新しい Function URL（AWS_IAM）は両方の権限が必要（AWS 公式ドキュメント urls-auth、ADR 0005）
+        Action   = ["lambda:InvokeFunction", "lambda:InvokeFunctionUrl"]
+        Resource = var.records_iam_alias_arn
       }
     ]
   })
@@ -265,20 +270,16 @@ resource "aws_lambda_function" "process_handler" {
 
   environment {
     variables = {
-      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
+      REGION             = var.region
+      RECORDS_IAM_URL    = var.records_iam_function_url
+      IMAGE_POLICY_PARAM = var.image_policy_param
     }
   }
 
   depends_on = [
     aws_cloudwatch_log_group.process_handler,
     aws_iam_role_policy.process_handler_s3,
-    aws_iam_role_policy.process_handler_dynamodb,
+    aws_iam_role_policy.process_handler_records,
     aws_iam_role_policy.process_handler_ssm,
   ]
 
@@ -388,17 +389,19 @@ resource "aws_iam_role_policy" "process_handler_dlq_s3" {
   })
 }
 
-resource "aws_iam_role_policy" "process_handler_dlq_dynamodb" {
-  name = "dynamodb-access"
+resource "aws_iam_role_policy" "process_handler_dlq_records" {
+  name = "records-invoke"
   role = aws_iam_role.process_handler_dlq.id
 
+  # DynamoDB には直接触れず、Records の IAM 版 Function URL を呼ぶ（ADR 0005）
   policy = jsonencode({
     Version = "2012-10-17"
     Statement = [
       {
-        Effect   = "Allow"
-        Action   = ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:BatchGetItem"]
-        Resource = [var.table_arn, "${var.table_arn}/index/*"]
+        Effect = "Allow"
+        # 2025 年 10 月以降の新しい Function URL（AWS_IAM）は両方の権限が必要（AWS 公式ドキュメント urls-auth、ADR 0005）
+        Action   = ["lambda:InvokeFunction", "lambda:InvokeFunctionUrl"]
+        Resource = var.records_iam_alias_arn
       }
     ]
   })
@@ -431,24 +434,20 @@ resource "aws_lambda_function" "process_handler_dlq" {
   architectures = ["arm64"]
   handler       = "media-process-handler-dlq.handler"
 
-  timeout     = 30
+  timeout     = var.process_handler_dlq_timeout
   memory_size = 256
 
   environment {
     variables = {
-      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
+      REGION          = var.region
+      RECORDS_IAM_URL = var.records_iam_function_url
     }
   }
 
   depends_on = [
     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_records,
     aws_iam_role_policy.process_handler_dlq_s3,
   ]
 

package/terraform/media/variables.tf

@@ -15,14 +15,37 @@ variable "region" {
   type        = string
 }
 
+variable "records_iam_function_url" {
+  description = "Records の IAM 認証版の Function URL（本体の出力 iam_function_url。認証なし版の URL ではない）。media の Lambda はこれを SigV4 署名で呼び、DynamoDB には直接触れない（ADR 0005）"
+  type        = string
+
+  # IAM 版と認証なし版は URL では区別できないので、形だけ検査する
+  validation {
+    condition     = can(regex("^https://[a-z0-9]+\\.lambda-url\\.[a-z0-9-]+\\.on\\.aws/$", var.records_iam_function_url))
+    error_message = "Records の IAM 認証版の Function URL（dynamodb_client_api_iam_function_url）を渡すこと。形式: https://<id>.lambda-url.<region>.on.aws/（末尾は /）。"
+  }
+}
+
+variable "records_iam_alias_arn" {
+  description = "Records の IAM 版エイリアスの ARN（本体の出力 iam_alias_arn）。lambda:InvokeFunctionUrl と lambda:InvokeFunction の許可の対象（ADR 0005）"
+  type        = string
+
+  validation {
+    condition     = can(regex("^arn:aws[a-z-]*:lambda:[a-z0-9-]+:[0-9]{12}:function:[^:]+:[^:]+$", var.records_iam_alias_arn))
+    error_message = "Records の IAM 版エイリアスの ARN（dynamodb_client_api_iam_alias_arn。…:function:<名前>:<エイリアス> の修飾つき）を渡すこと。"
+  }
+}
+
 variable "table_name" {
-  description = "呼び出し側の既存DynamoDBテーブル名（mediaリソースを相乗りさせる）"
+  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
   type        = string
+  default     = ""
 }
 
 variable "table_arn" {
-  description = "呼び出し側の既存DynamoDBテーブルARN"
+  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
   type        = string
+  default     = ""
 }
 
 variable "image_cache_ttl_days" {
@@ -37,29 +60,27 @@ variable "allowed_upload_origins" {
   default     = []
 }
 
-# 呼び出し側の既存テーブルに相乗りするため、process-handlerが生成するShadow Recordsの
-# 形式は呼び出し側の既存Lambda（records等）の設定と一致させる必要がある
-# （詳細: docs/media-design.md「環境変数の一致」）。既定値は本体（terraform/variables.tf）と揃える。
+# 以下の shadow_* は deprecated（1.16.0 で削除。ADR 0005）。Records 経由になったため無視される。
 variable "shadow_created_at_field" {
-  description = "作成日時フィールド名（呼び出し側の既存設定と一致させること）"
+  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
   type        = string
   default     = "createdAt"
 }
 
 variable "shadow_updated_at_field" {
-  description = "更新日時フィールド名（呼び出し側の既存設定と一致させること）"
+  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
   type        = string
   default     = "updatedAt"
 }
 
 variable "shadow_string_max_bytes" {
-  description = "プリミティブ型の最大バイト数（呼び出し側の既存設定と一致させること）"
+  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
   type        = number
   default     = 100
 }
 
 variable "shadow_number_padding" {
-  description = "数値のパディング桁数（呼び出し側の既存設定と一致させること）"
+  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
   type        = number
   default     = 15
 }
@@ -115,3 +136,9 @@ variable "route53_zone_id" {
   type        = string
   default     = null
 }
+
+variable "process_handler_dlq_timeout" {
+  description = "process-handler-dlq Lambdaのタイムアウト（秒）。Records の読み取り・書き込みのクライアント timeout（各 15 秒）と HeadObject が収まる値にする"
+  type        = number
+  default     = 60
+}