0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

後続処理を止めないDead Letter Queueの再投入契約

0
Posted at

Dead Letterへ隔離して正常な後続を継続するキュー設計

処理、分類、隔離、修正確認、再投入、readbackの流れ

はじめに

一件の不正payloadでconsumerが毎回停止すると、その後ろにある正常な仕事まで処理できません。例外を握りつぶしてskipすると、今度は失敗した一件が消えます。Dead Letter Queue(DLQ)はこの二択を避け、処理不能なitemを証拠付きで隔離する仕組みです。

ただし、DLQへ移しただけでは復旧していません。なぜ失敗したか、再投入できる条件は何か、元の順序を守る必要があるか、重複をどう防ぐか、成功を何で確認するかまで契約化する必要があります。

この記事ではPythonのqueue worker、dead letter schema、dependency単位の停止、requeue、dry-run、負試験を説明します。

retryとdead letterを分ける

一時エラーは短いretryで回復する可能性があります。schema不正、認証拒否、承認欠落のような恒久エラーは同じpayloadを繰り返しても直りません。

from enum import Enum

class FailureKind(str, Enum):
    TRANSIENT = "transient"
    PERMANENT = "permanent"
    UNKNOWN = "unknown"

def classify(error):
    if isinstance(error, (TimeoutError, RateLimitError, ServiceUnavailable)):
        return FailureKind.TRANSIENT
    if isinstance(error, (SchemaError, AuthError, ApprovalError)):
        return FailureKind.PERMANENT
    return FailureKind.UNKNOWN

transientはattempt budgetとdeadline内だけretryします。permanentは即DLQへ送ります。unknownは外部作用前と証明できなければReconciliationへ送り、未実行と決めつけません。

すべての例外をDLQへ入れる設計も危険です。503のたびに人手対応が必要になり、DLQが本来の「修正が必要なitem」を表さなくなります。

Dead Letter schemaに復旧条件を入れる

DLQ recordは元payloadの墓場ではなく、復旧作業票です。

{
  "schema": "dead-letter/v1",
  "dead_letter_id": "dlq_20260722_001",
  "message_id": "msg_0088",
  "route_id": "agent_memories_official",
  "payload_sha256": "1f8c...",
  "failure_kind": "permanent",
  "reason_code": "approval_missing",
  "attempts": 1,
  "first_failed_at": "2026-07-22T00:00:00Z",
  "last_failed_at": "2026-07-22T00:00:00Z",
  "requeue_condition": "fresh_alice_approval",
  "dependency_key": "article:example-slug",
  "external_effect_id": null
}

payload全文、secret、Cookie、Authorization headerは保存しません。元payloadは安全なartifact storageへ置き、DLQ recordはpathとhashで参照します。

dependency_keyは停止範囲を決めます。同じ親投稿に紐づく子リプは親が確定するまで進めませんが、別articleや別routeの仕事は継続できます。

queue全体ではなくdependencyを止める

FIFOを厳密に守る必要がない独立jobなら、失敗itemを隔離して後続を処理します。

def consume(batch, handler, dlq):
    outcomes = []
    blocked_dependencies = set()
    for item in batch:
        if item.dependency_key in blocked_dependencies:
            outcomes.append(skip(item, "dependency_blocked"))
            continue
        try:
            outcomes.append(handler(item))
        except Exception as error:
            kind = classify(error)
            if kind is FailureKind.TRANSIENT and item.retry_budget > 0:
                outcomes.append(schedule_retry(item, error))
                continue
            dlq.append(to_dead_letter(item, error, kind))
            blocked_dependencies.add(item.dependency_key)
            outcomes.append(isolate(item, error))
    return outcomes

ここでblocked_dependenciesをroute全体へ広げないことがポイントです。article Aのapproval不足でarticle Bのread-only分析まで止めません。

一方、銀行取引のようにglobal orderが業務invariantなら、後続継続は危険です。その場合はpartition keyを設計し、同じpartitionだけ止めます。独立性は実装都合で決めず、外部作用の関係から決めます。

requeueは元messageをそのまま戻さない

失敗原因が直った後も、古いpayloadが現在の承認やrouteと一致するとは限りません。再投入前にpreconditionを再検査します。

function canRequeue(letter: DeadLetter, current: CurrentState): RequeueDecision {
  if (letter.payloadSha256 !== current.payloadSha256) {
    return { ok: false, reason: "payload_changed_requires_new_message" };
  }
  if (!current.approvalValid || current.approvedHash !== letter.payloadSha256) {
    return { ok: false, reason: "fresh_approval_required" };
  }
  if (current.routeId !== letter.routeId || !current.accountIdentityMatch) {
    return { ok: false, reason: "route_or_account_mismatch" };
  }
  if (current.expiresAt <= new Date()) {
    return { ok: false, reason: "payload_expired" };
  }
  return { ok: true, reason: "preconditions_satisfied" };
}

本文が変わった場合、同じdead letterを上書きして戻さず、新しいmessage IDとhashを発行します。旧DLQ recordはsuperseded_byで紐づけ、なぜ使わなかったかを残します。

requeue時にはdead_letter_idから一意なidempotency keyを作り、複数担当が同時に戻してもqueueへ一件だけ入るようにします。

再投入の順序と期限を管理する

復旧itemをqueue先頭へ戻すと、古い情報が最新itemより先に公開される可能性があります。優先度は業務ルールで決めます。

def choose_requeue_slot(letter, schedule, now):
    if parse_time(letter.expires_at) <= now:
        return Decision("drop", "expired")
    if letter.requires_original_order:
        return schedule.after_dependency(letter.dependency_key)
    return schedule.next_available(
        after=now,
        minimum_gap_minutes=letter.minimum_gap_minutes,
    )

日次記事なら公開cadenceを守り、次の空き枠へ移します。速報なら期限切れとしてdropし、作り直しキューへ送ります。親子messageは親のreadback後に子を再投入します。

dropも黙って削除しません。dropped_expired、superseded、manual_actionとしてterminal Receiptを残し、在庫数や後続scheduleを更新します。

DLQをatomicかつ追跡可能にする

元queueから削除してからDLQ保存に失敗するとitemが消えます。可能なら同じtransaction内でmoveし、ファイルベースならDLQ保存完了後に元messageをackします。

BEGIN;
INSERT INTO dead_letters (
  dead_letter_id, message_id, route_id, payload_sha256, reason_code, state
) VALUES (?, ?, ?, ?, ?, 'isolated');
UPDATE queue_messages SET state = 'dead_lettered' WHERE message_id = ? AND state = 'processing';
COMMIT;

affected rowが1であることを確認します。0ならlease喪失、2以上ならschema破壊です。transactionが使えない外部queueではoutbox patternやdedupe keyで同等の保証を作ります。

監視はDLQ件数だけでなく、最古age、reason別件数、requeue可能件数、manual action件数を見ます。一件増えた時と復旧した時に通知し、毎run同じ警告を繰り返しません。

負試験で「消失」と「全停止」を作る

DLQ設計は障害注入で検証します。

def test_permanent_failure_does_not_stop_independent_items():
    items = [item("a", dep="article:a"), item("b", dep="article:b")]
    handler.fail("a", ApprovalError())
    result = consume(items, handler, dlq)
    assert result[0].status == "isolated"
    assert result[1].status == "success"
    assert len(dlq) == 1

def test_dlq_write_failure_does_not_ack_source_message():
    dlq.fail_next_write()
    with pytest.raises(StorageError):
        consume([item("a")], handler_that_fails, dlq)
    assert source_queue.state("a") == "processing"

追加で、同じdependencyの後続skip、別dependency継続、payload変更後requeue拒否、期限切れdrop、二重requeue、lease expiry、unknown外部effect、DLQ record破損を試します。dry-runは対象letter、判定、予定slotを出しますが、queue writeと外部writeは0にします。

完了条件は、message消失0、独立後続成功、同一dependency順序維持、requeue重複0、最終readback一致です。

まとめ

Dead Letter Queueは失敗itemを横へ移すだけの箱ではありません。failure分類、復旧条件、dependency boundary、payload hash、承認、期限、requeue idempotency、readbackを持つ復旧契約です。

恒久エラー一件を隔離し、正常な後続を継続しながら、原因が直った時だけ安全に再投入する。これにより「全部止める」と「失敗を捨てる」の間を実装できます。AIエージェントの記憶にも、dead letterの理由と次の条件を残せば、別セッションや別担当が同じ事故を繰り返さず復旧できます。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?