magic-pocket-cli 0.32.1__tar.gz → 0.34.0__tar.gz

{magic_pocket_cli-0.32.1 → magic_pocket_cli-0.34.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: magic-pocket-cli
-Version: 0.32.1
+Version: 0.34.0
 Summary: CLI and deploy tools for magic-pocket.
 Requires-Python: >=3.10
 Requires-Dist: awscrt>=0.19.0
 Requires-Dist: click>=8.1.7
 Requires-Dist: deepdiff>=6.7.1
 Requires-Dist: jinja2>=3.1.3
-Requires-Dist: magic-pocket<0.33,>=0.32.1
+Requires-Dist: magic-pocket<0.35,>=0.34.0
 Requires-Dist: pathspec>=1.0.4
 Requires-Dist: python-on-whales>=0.68.0
 Requires-Dist: pyyaml>=6.0.1

{magic_pocket_cli-0.32.1 → magic_pocket_cli-0.34.0}/pocket_cli/cli/deploy_cli.py

@@ -23,6 +23,7 @@ from pocket_cli.resources.dsql import Dsql
 from pocket_cli.resources.neon import Neon
 from pocket_cli.resources.rds import Rds
 from pocket_cli.resources.s3 import S3
+from pocket_cli.resources.sqs_alert import echo_dead_letter_alert_warnings
 from pocket_cli.resources.tidb import TiDb
 from pocket_cli.resources.upstash import Upstash
 from pocket_cli.resources.vpc import Vpc
@@ -225,6 +226,9 @@ def _deploy_pipeline(context: Context, *, openpath=None, skip_frontend=False):
         deploy_frontend(context)
     # build 時の other-read 警告はログに埋もれて気付けないため最後に再掲する
     resummarize_world_read_warnings()
+    # DLQ アラートの email 購読が未確認のままだと通知が届かないため、
+    # deploy の最後に購読状態を確認して警告する
+    echo_dead_letter_alert_warnings(context)
     # デプロイ完了後の URL 表示
     url = _get_deploy_url(context)
     if url:

{magic_pocket_cli-0.32.1 → magic_pocket_cli-0.34.0}/pocket_cli/cli/status_cli.py

@@ -5,6 +5,7 @@ from pocket.resources.aws.secretsmanager import PocketSecretIsNotReady
 from pocket.utils import echo
 from pocket_cli.cli.deploy_cli import get_resources
 from pocket_cli.resources.container import Container
+from pocket_cli.resources.sqs_alert import echo_dead_letter_alert_statuses
 
 
 def show_status_message(resource):
@@ -56,3 +57,5 @@ def status(stage, show_info):
         show_status_message(resource)
         if show_info:
             show_info_message(resource)
+    # DLQ アラートの email 購読状態 (PendingConfirmation のままだと通知が届かない)
+    echo_dead_letter_alert_statuses(context)

magic_pocket_cli-0.34.0/pocket_cli/resources/sqs_alert.py

@@ -0,0 +1,94 @@
+"""SQS DLQ アラートの SNS email 購読状態の照会。
+
+SNS の email 購読は、宛先が確認メールのリンクを踏むまで ``PendingConfirmation``
+のままで、その間はアラームが鳴っても通知が届かない (「監視してあるつもり」の
+無監視)。deploy の最後と ``pocket status`` で購読状態を可視化し、未確認のまま
+放置されるのを防ぐ (KN1110)。
+"""
+
+from __future__ import annotations
+
+from typing import Literal, NamedTuple
+
+import boto3
+
+from pocket.context import Context
+from pocket.utils import echo
+
+SubscriptionState = Literal["Confirmed", "PendingConfirmation", "NotCreated"]
+
+
+class DeadLetterAlertStatus(NamedTuple):
+    topic_name: str
+    email: str
+    state: SubscriptionState
+
+
+def dead_letter_alert_statuses(context: Context) -> list[DeadLetterAlertStatus]:
+    """dead_letter_alert が enabled な handler ごとの email 購読状態を返す。
+
+    topic 未作成 (deploy 前 / 削除済み) は ``NotCreated``。購読が確認済みなら
+    ``Confirmed``、確認メール未対応なら ``PendingConfirmation``。
+    """
+    targets = [
+        (c.region, h.sqs.dead_letter_alert.topic_name, h.sqs.dead_letter_alert.email)
+        for c in context.container.values()
+        for h in c.handlers.values()
+        if h.sqs and h.sqs.dead_letter_alert
+    ]
+    if not targets:
+        return []
+    account_id = boto3.client("sts").get_caller_identity()["Account"]
+    statuses: list[DeadLetterAlertStatus] = []
+    for region, topic_name, email in targets:
+        sns = boto3.client("sns", region_name=region)
+        topic_arn = f"arn:aws:sns:{region}:{account_id}:{topic_name}"
+        try:
+            res = sns.list_subscriptions_by_topic(TopicArn=topic_arn)
+        except sns.exceptions.NotFoundException:
+            statuses.append(DeadLetterAlertStatus(topic_name, email, "NotCreated"))
+            continue
+        state: SubscriptionState = "NotCreated"
+        for sub in res["Subscriptions"]:
+            if sub["Protocol"] != "email" or sub["Endpoint"] != email:
+                continue
+            if sub["SubscriptionArn"] == "PendingConfirmation":
+                state = "PendingConfirmation"
+            else:
+                state = "Confirmed"
+            break
+        statuses.append(DeadLetterAlertStatus(topic_name, email, state))
+    return statuses
+
+
+def echo_dead_letter_alert_warnings(context: Context) -> None:
+    """未確認の購読を警告する (deploy の最後に呼ぶ)。
+
+    初回 deploy は宛先が確認メールを踏むまで必ず ``PendingConfirmation`` に
+    なるため、エラーではなく警告に留める (エラーにすると初回 deploy が
+    必ず落ちる)。確認済みなら何も出さない。
+    """
+    for status in dead_letter_alert_statuses(context):
+        if status.state == "Confirmed":
+            continue
+        if status.state == "PendingConfirmation":
+            echo.warning(
+                f"DLQ alert subscription for {status.email} ({status.topic_name}) "
+                "is still PendingConfirmation. Alarm notifications will NOT be "
+                "delivered until the confirmation link in the email is clicked."
+            )
+        else:
+            echo.warning(
+                f"DLQ alert subscription for {status.email} ({status.topic_name}) "
+                "was not found. Check the container stack deployment."
+            )
+
+
+def echo_dead_letter_alert_statuses(context: Context) -> None:
+    """購読状態を一覧表示する (``pocket status`` 用)。"""
+    for status in dead_letter_alert_statuses(context):
+        message = f"DLQ alert {status.topic_name} -> {status.email}: {status.state}"
+        if status.state == "Confirmed":
+            echo.success(message)
+        else:
+            echo.warning(message)

{magic_pocket_cli-0.32.1 → magic_pocket_cli-0.34.0}/pocket_cli/templates/cloudformation/container.yaml

@@ -400,6 +400,48 @@ Resources:
       # max 14 days
       MessageRetentionPeriod: "{{ handler.sqs.dead_letter_message_retention_period }}"
 
+  # {% if handler.sqs.dead_letter_alert %}
+  # DLQ 到達の通知 (dead_letter_alert 宣言時のみ)。email 購読は宛先が確認メールの
+  # リンクを踏むまで PendingConfirmation のままで通知が届かない点に注意
+  # (deploy 後の購読状態チェックと pocket status で可視化する)
+  "{{ handler.key|capitalize }}DeadLetterAlertTopic":
+    Type: AWS::SNS::Topic
+    Properties:
+      TopicName: "{{ handler.sqs.dead_letter_alert.topic_name }}"
+
+  "{{ handler.key|capitalize }}DeadLetterAlertSubscription":
+    Type: AWS::SNS::Subscription
+    Properties:
+      TopicArn:
+        Ref: "{{ handler.key|capitalize }}DeadLetterAlertTopic"
+      Protocol: email
+      Endpoint: "{{ handler.sqs.dead_letter_alert.email }}"
+
+  "{{ handler.key|capitalize }}DeadLetterAlarm":
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: "{{ handler.sqs.dead_letter_alert.alarm_name }}"
+      AlarmDescription: "Messages arrived in the dead-letter queue of {{ handler.sqs.name }}"
+      Namespace: "AWS/SQS"
+      MetricName: ApproximateNumberOfMessagesVisible
+      Dimensions:
+        - Name: QueueName
+          Value:
+            Fn::GetAtt: "{{ handler.key|capitalize }}DeadLetterQueue.QueueName"
+      Statistic: Maximum
+      Period: 300
+      EvaluationPeriods: 1
+      Threshold: 1
+      ComparisonOperator: GreaterThanOrEqualToThreshold
+      # DLQ が空の間はメトリクス欠測になりうるため、欠測 = 正常として扱う
+      TreatMissingData: notBreaching
+      AlarmActions:
+        - Ref: "{{ handler.key|capitalize }}DeadLetterAlertTopic"
+      # 復旧 (redrive / purge で DLQ が空に戻った) も通知する
+      OKActions:
+        - Ref: "{{ handler.key|capitalize }}DeadLetterAlertTopic"
+  # {% endif %}
+
   "{{ handler.key|capitalize }}SqsEventSourceMapping":
     DependsOn:
       - "{{ handler.key|capitalize }}SqsQueue"

{magic_pocket_cli-0.32.1 → magic_pocket_cli-0.34.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "magic-pocket-cli"
-version = "0.32.1"
+version = "0.34.0"
 description = "CLI and deploy tools for magic-pocket."
 requires-python = ">=3.10"
 dependencies = [
     # lib は同 minor に束縛する。0.x では minor が breaking の単位のため、
     # 上限なしだと cli を pin した消費者にも lib の破壊的変更が届いてしまう
-    "magic-pocket>=0.32.1,<0.33",
+    "magic-pocket>=0.34.0,<0.35",
     "click>=8.1.7",
     "jinja2>=3.1.3",
     "python-on-whales>=0.68.0",