冪等

どのようなものか

ある操作を何度実行しても、一度実行したのと効果が同じなら、冪等である
といいます。この性質を冪等性（idempotence、idempotency）と呼びます。
数学に由来する言葉で、関数をその結果へ再び適用しても変わらず、
f(f(x))がf(x)と等しくなる場合を指します。すでに切り下げた数を、もう
一度切り下げても、同じ数になります。

ソフトウェアでは、二回目を試すと分かりやすくなります。値を設定する操
作は、二回目も、すでにある値を書くため冪等です。値へ加える操作は、再
び加えるため、そうではありません。

```sql
i-- 冪等：2回目も同じ値を設定する		engineer.company	70
UPDATE accounts SET plan = 'pro' WHERE id = 42;

i-- 非冪等：2回目にさらに10を加える		engineer.company	70
UPDATE accounts SET credits = credits + 10 WHERE id = 42;
```

HTTPが、この言葉を最も厳密に定義します。RFC
9110は、複数の同一要求を送ったときの、意図されたサーバーへの効果が、
一回だけ送ったときと同じなら、そのメソッドを冪等とし、PUT、DELETE、
安全なメソッドGET、HEAD、OPTIONS、TRACEを挙げます。定義には、重要な
細部が二つあります。対象は、クライアントが求めた効果なので、サーバー
は、各要求を別々に記録しても構いません。また、応答は変わっても構いま
せん。同じリソースへの二回目のDELETEが、最初の200に対し404を返して
も、どちらもリソースがなくなるため、冪等です。PATCHは一覧の外です。
RFC
5789は、安全でも冪等でもないとしますが、クライアントは、If-Matchヘッ
ダーへ強いETagを付けて条件付きにすることで、特定のPATCHを冪等に送れ
ます。一回目がリソースを変えた後では、繰り返したコピーを拒否するため
です。

二つの約束のうち、安全のほうが厳しいものです。RFC
9110でいう安全なメソッドは、本質的に読み取り専用です。そのため、すべ
ての安全なメソッドは冪等ですが、DELETEは、安全でなくても冪等です。

なぜ重要なのか

ネットワークは、応答を失います。クライアントが要求を送り、応答前に接
続が切れると、サーバーが要求を一度も見ていないのか、見て止まったの
か、実行して返答を失ったのか、区別できません。自然な復旧は再送であ
り、それを無害にするのが冪等性です。RFC
9110は、まさにそこへ再試行規則を置きます。通信障害後、冪等な要求は自
動で繰り返せます。クライアントは、冪等でない要求を自動で再試行するべ
きではありません。ただし、実際には冪等と分かっているか、元の要求が一
度も適用されていないと判断できる場合は除きます。プロキシーは、自らそ
のような再試行をしてはなりません。

キューでは、同じ問いが大規模に起きます。多くのメッセージシステムが約
束するのは、少なくとも一回の配信です。処理を済ませ、受領確認を返す前
に処理側がクラッシュすると、同じメッセージを再び渡されます。ネット
ワーク越しに厳密に一回だけ配信するのは、はるかに難しい約束なので、実
用上の答えは、二回目の配信でも変化しない処理側を作ることです。構成管
理も、この性質に依存します。サーバーを宣言した状態へ整えるツールは、
変更のたびに、しばしば定期的にも、繰り返し動きます。各回は、すでに正
しいサーバーを、見つけたとおりの状態に保つ必要があります。

本当に決めるべきなのは、本来冪等でない操作へ、この性質をどう与えるか
です。一般的な答えは三つあります。第一は設計です。「この行を追記す
る」ではなく、「ファイルにこの行があることを保証する」のように、手順
ではなく目標状態で変更を表します。第二はキーです。クライアントが一意
な識別子を要求へ付け、サーバーは一意制約の下で記録し、繰り返しには、
もう一度実行せず、記録を見つけて元の結果を返します。第三は、動く前に
確認する方法です。Ansibleの大半のモジュールは、現在の状態と望む状態
を比較し、一致すれば何もせず終了します。どれにも費用があります。目標
状態の設計には、最終状態の明確なモデル、キーには保存領域と保管期間の
規則、事前確認には、現在の状態を確実に読む方法が必要です。

実際の活用例

会社自身のサーバーはAnsibleで設定し、そのプロジェクトでは、冪等性を
契約とし、収束したホストは変更ゼロを報告します。引数なしのプロビジョ
ニングで、すべてのホストを宣言した状態へ収束させます。すでに正しいホ
ストで、変更ゼロを報告できないプレイは、未完成と扱います。そのため、
冪等性は、期待するものではなく、毎回測るものになります。

同じ考えをデータへ適用したものが、十九段階のビルドパイプラインを二回
動かすテストです。事例は、対象とする不具合を挙げます。確認せずに挿入
する段階や、先行する段階の出力順へ依存する段階によって、初回は動き、
二回目で壊す生成ツールです。テストは、空のファイルからデータベースを
構築し、スナップショットを取り、その結果に対してパイプライン全体を再
実行します。行数、内容、識別子まで、二回目で何も変わらないことを求め
ます。このテストは、対象とする入力とデータベースの状態について、繰り
返し実行した結果の証拠を示します。

限られた在庫の販売では、最後のチケットを一回だけ売るという記事が、
キーと条件付き書き込みを組み合わせます。各購入手続きに冪等性キーを持
たせ、取り置きテーブルに`UNIQUE
(tenant_id,
idempotency_key)`を置くため、再クリックでは、もう一つ確保せず、すで
にある取り置きを返します。タイムアウトと取り消しボタンなどで、解放処
理が二回動いても、自身の更新でちょうど一行を変えた場合だけ在庫を戻す
ので、一個しか戻りません。さらに後の各メッセージ処理側も、注文をキー
として冪等にします。メッセージは少なくとも一回届き、冪等性によって、
効果を実質一回にします。

問題が起きるところ

再試行した要求が、二回課金します。
支払い、注文、メールを作るPOSTは、既定では冪等でなく、クライアントや
プロキシーが時間切れ後に再試行すると、二つ目を作ります。サーバーが一
意制約の下で保存する冪等性キーを付け、同じキーが戻れば、保存した結果
を返します。

空の結果を、エラーと読みます。 PostgreSQLでは、
`INSERT ... ON CONFLICT DO
NOTHING`が、一意制約へ違反する行を省き、`RETURNING`は、実際に挿入、
更新した行だけを返します。同じ行の挿入を繰り返せば、何も返らず、それ
が二回目の正しい結果です。空を失敗と扱うコードは、無害な再試行をエ
ラーページへ変えてしまいます。すでにある行を検索するべきです。

コマンドタスクが、毎回ホストを変えます。
Ansibleの文書は、大半のモジュールが、すでに望む状態かどうかを確かめ
る一方、「すべてのプレイブックがこのように動くわけではなく、すべての
モジュールがそう動くわけでもない」と説明します。コマンドは任意で、何
をするかAnsibleには分からないため、コマンドを動かすタスクが、よくあ
る例外です。commandモジュールの`creates`は、指定ファイルがすでにあれ
ば省き、`removes`は、ファイルがまだある間だけ動かし、`changed_when`
は、どの結果を変更と数えるかを定めます。どれもないタスクは、ホストが
どんな状態でも、収束処理のたびに再び動きます。

カウンターが、再試行も数えます。
少なくとも一回の配信で、メッセージごとにカウンターを増やす、または通
知を送る処理側は、二回届いた一件に対して、その処理を二回行います。効
果とともに、同じトランザクションで、メッセージの業務上のキーを保存
し、すでに保存したキーは省きます。

二回目が、初回の結果を壊します。
空のデータベースなら正しくても、データがあると、重複挿入、識別子の振
り直し、初回が残した順序への依存で、段階が誤動作する場合があります。
何もないところから一度だけ動くテストは、それでも通ります。前述のパイ
プラインテストのように、ジョブ全体を二回動かし、二回目で何も変わらな
いことを必須条件にします。

参考資料

  * RFC 9110、第9.2.2節：冪等なメソッド — HTTPの定義、冪等なメソッ
ド、自動再試行の規則です。

  * RFC 5789：HTTPのPATCHメソッド —
PATCHが安全でも冪等でもない理由と、条件付き要求で安全に繰り返せるも
のにする方法です。

  * Ansible：プレイブックの紹介 — Ansible自身の言葉による、望む状
態、冪等性、チェックモードです。

  * Ansible：commandモジュール — コマンドを安全に再実行できるものに
する`creates`と`removes`です。

  * PostgreSQL：INSERT — `ON CONFLICT`と、行がすでにある場合に
`RETURNING`が返すものです。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/idempotent/	engineer.company	70
