@exabugs/dynamodb-client 1.14.1 → 1.16.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/docs/RECORDS_CLIENT.md

@@ -0,0 +1,45 @@
+# Records クライアントのヘルパー
+
+Lambda などのサーバー側から Records（IAM 版 Function URL）を呼ぶ定型を、ライブラリが持つ（[ADR 0006](adr/0006-library-owns-table-operations.md)）。`@exabugs/dynamodb-client/client/iam` から import する。
+
+| 関数                                 | 用途                                                                                         |
+| ------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `createRecordsClient(options?)`      | `DynamoClient` の生成と `connect()`。`connect()` の呼び忘れを防ぐ                            |
+| `withCollection(name, fn, options?)` | 作る → `fn(collection)` → 確実に close。Lambda の 1 回の呼び出しで使い切る                   |
+| `lazyCollection(name, options?)`     | 最初の使用時に 1 回だけ接続し、コンテナ内で再利用。失敗はキャッシュしない。`.reset()` で破棄 |
+| `createAdminDirectory(options?)`     | `@exabugs/dynamodb-client/notify`。`admins` の全件から通知の宛先（メール）を返す             |
+
+`options`: `url`（省略時は環境変数 `RECORDS_IAM_URL`）、`region`（省略時は `AWS_REGION`、無ければ `REGION`）、`timeout`（ms。Records の Lambda の timeout より短くする）。
+
+`createAdminDirectory` の主なオプション: `recipientFields`（宛先を取るフィールド。既定 `['id']`、`['email','id']` で `email ?? id`）、`maxAdmins`（既定 200。件数が超えたら例外、ちょうどは成功）、`sortById`（id 昇順で読む）、`source`（`authorizedCollection` の `list` と同じ形。権限チェック層を通すアプリが渡す。指定すると自前で接続しない）。
+
+## Lambda での使い方
+
+コンテナで使い回す（コールドスタートで 1 回だけ接続）:
+
+```ts
+import { lazyCollection } from '@exabugs/dynamodb-client/client/iam';
+
+const venues = lazyCollection<VenueRecord>('venues', { timeout: 15_000 });
+
+export const handler = async () => {
+  const active = await (await venues()).find({ status: 'active' }).toArray();
+  // ...
+};
+```
+
+呼び出しごとに使い切る:
+
+```ts
+import { withCollection } from '@exabugs/dynamodb-client/client/iam';
+
+await withCollection<WeatherRecord>('weather', (weather) =>
+  weather.updateOne({ id }, { $set: data }, { upsert: true })
+);
+```
+
+asanowa の `functions/weather` の `getDynamoClient`（`new DynamoClient` + `connect()` + `db()` のキャッシュ）は、`lazyCollection` の 1 行になる。
+
+## テスト
+
+`DynamoClient` を丸ごとモックすると `connect()` の呼び忘れを見逃す。本物の `DynamoClient` を使い、`fetch` だけ差し替える（`vi.stubGlobal('fetch', ...)`。例: `__tests__/client/recordsClient.test.ts`）。コレクションを差し替えたいときは、`lazyCollection` の戻り値の関数をアプリ側のモジュールに閉じ込め、そのモジュールをモックする。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.14.1",
+  "version": "1.16.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",
@@ -43,7 +43,8 @@
     "LICENSE",
     "CHANGELOG.md",
     "docs/NOTIFY.md",
-    "docs/DYNAMODB_ACCESS.md"
+    "docs/DYNAMODB_ACCESS.md",
+    "docs/RECORDS_CLIENT.md"
   ],
   "exports": {
     ".": {

package/terraform/media/README.md

@@ -38,8 +38,10 @@ 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）
+  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,25 @@ variable "region" {
   type        = string
 }
 
-variable "table_name" {
-  description = "呼び出し側の既存DynamoDBテーブル名（mediaリソースを相乗りさせる）"
+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 "table_arn" {
-  description = "呼び出し側の既存DynamoDBテーブルARN"
+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 "image_cache_ttl_days" {
@@ -37,33 +48,6 @@ variable "allowed_upload_origins" {
   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
@@ -115,3 +99,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
+}