@exabugs/dynamodb-client 1.10.0 → 1.11.0

package/docs/NOTIFY.md

@@ -0,0 +1,103 @@
+# 運用通知（`@exabugs/dynamodb-client/notify`）
+
+ログ（`warn` 以上）・CloudWatch アラーム・直接呼び出しを、管理者へ通知するための**部品**。配線（購読フィルタ・Lambda・Terraform・秘密の置き場）は、各アプリが行う。既存の挙動は変えない（サブパス `./notify` の追加のみ）。
+
+```text
+ログ(購読フィルタ) ─┐
+アラーム(EventBridge) ─┼→ 通知ハンドラ → Notice に正規化 → 重複抑制 → 流量制限 → Slack / メール
+直接呼び出し ────────┘
+```
+
+## ログの仕様
+
+JSON 1 行。`level`（`debug` / `info` / `warn` / `error` / `fatal`）、`message`、任意で `event`（機械可読の種別）、`resource` / `target`（対象）、`action` / `actions`（対策の案内）。**`warn` 以上は通知の対象**にする。
+
+- 既存の logger（`createLogger`）は変えていない。`fatal` は `logFatal(message, meta)` で出す
+- Lambda の実行基盤の失敗（`Task timed out` など）は、`fatal`（`LAMBDA_FAILURE`）として扱う
+- ログ行は 3 種類を読む。どれも、**アプリの JSON の `level` と各フィールドを優先**する（Lambda の外側の `level` は、`console.log` で出した warn が `INFO` になる）
+  1. アプリの JSON 1 行
+  2. Lambda のテキスト形式: `時刻<TAB>RequestId<TAB>INFO<TAB>{JSON}`
+  3. Lambda の JSON 形式（`log_format = JSON`）: `{"level":"INFO","requestId":…,"message":"{アプリの JSON 文字列}"}`
+- JSON でない行（`console.error` の文字列など）は、外側の `level` が `WARN` 以上のときだけ、`LOG_WARN` / `LOG_ERROR` として通知する
+- タイムアウト・クラッシュは、テキスト形式の行（`Task timed out after …` / `Runtime exited …` / `REPORT … Status: timeout`）と、JSON 形式のシステムログ（`platform.report` / `platform.runtimeDone` の `status`。Lambda のシステムログレベルを `INFO` 以上にしたときだけ出る）の両方を読む
+- Lambda の実行基盤の失敗（`Invoke Error` / `Unhandled Promise Rejection` / `Uncaught Exception` / `Task timed out` / `Runtime exited`）は `fatal`（`LAMBDA_FAILURE`）。stack は持ち出さない
+
+## Notice
+
+外部へ送るのは、許可したフィールドだけ（`level` / `event` / `message` / `app` / `env` / `target` / `action` / `occurredAt` / `suppressed`）。文字数を制限し、制御文字を除く。ログ全体は転送しない。
+
+## 重複抑制と流量制限
+
+指紋は `app#env#level#event#target`（level を含めるので、warn の窓が後の error を抑制しない）。`event` の無いログは、メッセージの先頭 60 文字を `target` にして、別々のエラーを 1 つにしない。専用の DynamoDB テーブル（パーティションキー `pk` 文字列、TTL 属性 `ttl`）に、条件付き更新で記録する。
+
+| level                            | 窓             |
+| -------------------------------- | -------------- |
+| `warn`                           | 3600 秒に 1 回 |
+| `error`                          | 600 秒に 1 回  |
+| `fatal` / `ok`（アラームの復旧） | 抑制しない     |
+
+- 同じバッチ（1 回の購読の呼び出し）の同じ指紋は 1 通にまとめ、件数（`suppressed`）を付ける。確保・計数もまとめて 1 回
+- 抑制した件数は、窓が明けた次の通知に付く（再発しない場合は報告されない）
+- アラームの状態変化（`ALARM:` で始まる `event`）は、変化したときにしか届かないので、抑制しない（ALARM → OK → ALARM を、すべて通知する）
+- 確保 → 送信 → **どのチャネルにも届かなかった通知は確保を解放する**（次の発生で、窓を待たずに通知できる。解放は自分の確保だけ。失敗した 1 件も件数に戻す）。例外で終わったときも同じ
+- `failOnAnyChannelError` で例外にしても、届いた通知の確保は残る（失敗したチャネルへは、再送や失敗先からの再実行でも届かない）。再試行を前提にせず、失敗はハンドラのログとアラームで知る
+- 宛先（管理者）の取得に失敗したら、そのチャネルの失敗として扱い、他のチャネルは送る
+- `event` の無いログは、メッセージの先頭 60 文字を指紋に使う。ID や数値を含むメッセージは毎回違う指紋になり、重複抑制が効かない（流量制限が頼り）。`event` を付けること
+- 全チャネルが失敗したら例外にする（Lambda の失敗先に流せる）。一部のチャネルだけの失敗は、`failedChannels` に入り、ハンドラ自身のログに出る（`failOnAnyChannelError: true` で、例外にもできる）
+- 流量制限: チャネルごとに、600 秒で 20 件まで。超えた最初のバッチにだけ、「省略」の 1 通を出す。省かれて、どのチャネルにも届かなかった通知の確保は解放する
+- `NotifyResult.sent` は、1 つ以上のチャネルに届いた通知の数（省略の通知は含まない）。`throttled` は、流量制限で省いた延べ数
+
+## チャネル
+
+- `createSlackChannel({ getWebhookUrl })` — チャンネル宛（Incoming Webhook）。URL が `https://hooks.slack.com/`（`urlPrefix` で変更可）で始まらなければ送らない。URL はエラーにもログにも出さない
+- `createEmailChannel({ from, send })` — 宛先は **Bcc だけ**に 50 件ずつまとめる（To に送信元を入れない。受信できないアドレスだとバウンスする）。`sesSender({ client, SendEmailCommand })` は、アプリが `@aws-sdk/client-sesv2` を静的に import して渡す（バンドラが依存を解決でき、Lambda のバンドルに含まれる）。他のリージョンの SES も指定できる。失敗の原因（SES のエラー名・メッセージ）はエラーに残り、宛先は出さない
+- `Channel` インターフェースを実装すれば、他の経路も足せる
+- 宛先（管理者）は `AdminDirectory.listEmails()`。スキーマは強制しない。結果は 300 秒キャッシュする
+
+## 使い方
+
+```ts
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+
+import {
+  DynamoNoticeStore,
+  createEmailChannel,
+  createNotifyHandler,
+  createSlackChannel,
+  sesSender,
+} from '@exabugs/dynamodb-client/notify';
+
+export const handler = createNotifyHandler({
+  app: 'myapp',
+  env: process.env.ENV_NAME ?? 'dev',
+  store: new DynamoNoticeStore(
+    DynamoDBDocumentClient.from(new DynamoDBClient({})),
+    process.env.NOTICE_TABLE!
+  ),
+  admins: {
+    listEmails: async () => [
+      /* 管理者のメール */
+    ],
+  },
+  channels: [
+    createSlackChannel({ getWebhookUrl: async () => /* SSM などから */ '' }),
+    createEmailChannel({
+      from: 'noreply@example.com',
+      send: sesSender({ client: new SESv2Client({ region: 'us-east-1' }), SendEmailCommand }),
+    }),
+  ],
+});
+```
+
+## 配線の注意（各アプリ）
+
+- **通知ハンドラのロググループは購読しない**（自分のログで無限ループになる）。失敗は Lambda の失敗先（SNS など）→ 固定の運用者のアドレスへ届ける
+- 購読フィルタは**広めの語句**にする。ハンドラが厳密に判定する（通知しない行は捨てる）。`log_format`（テキスト / JSON）で `level` の位置が変わり、`console.log` の warn は外側が `INFO` になるので、`level` の JSON フィルタは使わない:
+  `?warn ?error ?fatal ?WARN ?ERROR ?FATAL ?"Task timed out" ?"Runtime exited" ?Unhandled ?Uncaught ?"Invoke Error" ?"Status: timeout" ?"Status: error" ?timeout`
+- 一部のチャネルだけの失敗（Webhook の失効など）に気づくには、ハンドラ自身のログ（`通知の送信に失敗しました`）のメトリクスフィルタ → アラーム → SNS（固定の運用者のアドレス）を配線する。または `failOnAnyChannelError: true` にして、Lambda の失敗先に流す
+- 訓練は `dryRun: true`（送らず、store にも触れない。宛先つきの計画が `plan` に入る）
+- アラームは、ログを出さないもの（Lambda の Errors / Throttles、DynamoDB のスロットル、WAF など）に使う。ログと同じ事象（SPARSE_SCAN など）をアラームでも通知すると二重になる
+- Lambda の非同期の再試行は 0 にする（重複を避ける。失敗は失敗先で受ける）
+- SES の送信元ドメインは、検証と本番アクセスが済んだリージョンのものを使う

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",
@@ -41,7 +41,8 @@
     "docs/SCAN_WARNING.md",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/NOTIFY.md"
   ],
   "exports": {
     ".": {
@@ -117,7 +118,11 @@
       "types": "./dist/server/media/types.d.ts"
     },
     "./terraform": "./terraform/main.tf",
-    "./terraform/media": "./terraform/media/main.tf"
+    "./terraform/media": "./terraform/media/main.tf",
+    "./notify": {
+      "import": "./dist/notify/index.js",
+      "types": "./dist/notify/index.d.ts"
+    }
   },
   "peerDependencies": {
     "react-admin": "^5.0.0"