https://rindrics.com/tags/equality/ Equality Hugo -- gohugo.io en Mon, 14 Sep 2026 00:00:00 +0900 https://rindrics.com/posts/designing-idempotency-by-usecase/ Mon, 14 Sep 2026 00:00:00 +0900 https://rindrics.com/posts/designing-idempotency-by-usecase/ <p>data-rigistry開発の<a href="../immutable-data-registry-alloy-design/">前回</a>記事からだいぶ間が空いてしまったが、久しぶりに時間をとれたので冪等性について考えてみる。</p> <h2 id="はじめに">はじめに</h2> <p>資源計算に利用するデータを登録するためのサービスdata-registryを作っている。</p> <p>下記は前回の記事。</p> <div class="card"> <a href="https://rindrics.com/posts/immutable-data-registry-alloy-design/" target="_blank" rel="noopener noreferrer" class="card-link"> <div class="card-content"> <h4 class="card-title">イミュータブルなデータレジストリの設計とAlloyによる形式検証 | rindrics.com</h4> <span class="card-url">https://rindrics.com/posts/immutable-data-registry-alloy-design/</span> </div> </a> </div> <p>上の記事では初期設計をやってみたのだが、反省点がいくつかあった:</p> <ul> <li>要件定義が雑だった</li> <li>スコープを決めていなかった</li> <li>進め方の戦略がなかった</li> </ul> <p>そこで本記事では、前回の反省を活かし、「取り組むスコープを決めた上で」「ユースケース駆動で要件・仕様を吟味」する「という方法で進める」ことにする。</p> <p>本記事で扱う問題のスコープは下記の通り:</p> <ul> <li>等値性の定義</li> <li>ユースケースの整理</li> <li>冪等性キーの生成場所と等値性の判定場所の決定</li> </ul> <h2 id="冪等性が必要な理由">冪等性が必要な理由</h2> <p>冪等性が必要な本質的な理由は2つ：</p> <ol> <li> <p><strong>クライアント実装の簡潔性</strong></p> <ul> <li>再試行時に「同じリクエストを送ってもいい」という保証があれば、クライアント側で「送信完了か確認不可か」を区別する必要がない</li> <li>再試行戦略が単純になる</li> </ul> </li> <li> <p><strong>並行処理時の安全性</strong></p> <ul> <li>複数プロセスが同じデータを登録する場合、競合を避けて結果の予測可能性を確保</li> <li>「どのRevisionが実際に採用されるのか」が明確になる</li> </ul> </li> </ol> <p>特に、意図的な再試行ではなく、並行リクエストやネットワークエラーによる自動再試行への対策のために導入する。</p> <h2 id="等値性の定義">等値性の定義</h2> <p>サービスの冪等なふるまいを設計していくにあたり、まずはどんなときに冪等性が保証されるべきか: つまりdata-registryが扱うペイロードの等値性について考えてみる。</p> <p>このサービスの性質を考えれば、登録対象のデータそのものの等値性が考慮される必要があることは自明。 また、等値性を考えるうえでのヒントとして、既存のシステム要件 <code>SR004</code> を考慮するとよい:</p> <blockquote> <p>SR004 新しい版は、既存の版を0個または1個参照しなければならない</p> </blockquote> <p>データ登録要求の仕様は決まっていないものの、新しい版を紐づける先の <code>parentRevision</code> の値については、少なくとも等値性に関わる情報と考えてよさそう。</p> <p>上記から、data-registryにおける等値性の定義は下記の通りとする:</p> <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>等値とみなすリクエスト = hash(parentRevisionId, hash(data))が同じリクエスト </span></span></code></pre></div><h2 id="ユースケースの明確化">ユースケースの明確化</h2> <p>ペイロードの等値性をひとまず定義できたところで、続いて冪等性に関するユースケースをまとめていく。</p> <h3 id="リクエスト処理時のユースケース">リクエスト処理時のユースケース</h3> <p>まず、data-registryのクライアント側で発生する機能的なユースケースを考えてみる。</p> <h4 id="並行リクエストを冪等に処理する">並行リクエストを冪等に処理する</h4> <ul> <li>概要: 複数のプロセスから並行で同一の内容のリクエストが届いた場合に呼び出される</li> <li>期待: リクエストが一つだけ届いた場合と同様の状態になる</li> <li>アクター: プロセスA、プロセスB</li> <li>メインフロー: <ul> <li>1: プロセスAが、システムにデータの登録を要求する</li> <li>2: プロセスBが、システムにデータの登録を要求する</li> <li>3: システムは、プロセスAに要求されたデータを永続化する</li> <li>4: システムは、永続化が成功した旨のメッセージをプロセスAに返却する</li> <li>5: システムは、プロセスBの要求がプロセスAと同一であることを検知する</li> <li>6: システムは、永続化はせずに、プロセスBに対してプロセスAと同一の内容を返却する</li> </ul> </li> </ul> <h4 id="ネットワークエラーによる再試行で冪等性を保証する">ネットワークエラーによる再試行で冪等性を保証する</h4> <ul> <li>概要: クライアントがリクエストを送信したが、ネットワークエラーによってレスポンスが返らず、クライアント側でタイムアウト後に同じリクエストを再送する</li> <li>期待: リクエストが一度だけ送信された場合と同じ状態になる</li> <li>アクター: クライアント、システム</li> <li>メインフロー: <ul> <li>1: クライアントが、識別可能な形式でシステムにデータの登録を要求する</li> <li>2: システムは、リクエストを受け取り処理を開始する</li> <li>3: システムは、新しいRevisionを作成する</li> <li>4: ネットワークエラーが発生し、レスポンスがクライアントに到達しない</li> <li>5: クライアントがタイムアウトし、同じ内容で再度リクエストを送信する</li> <li>6: システムは、該当するリクエストが既に処理されていることを認識する</li> <li>7: システムは、既に登録済みのRevisionをクライアントに返却する（新たな登録は行わない）</li> </ul> </li> </ul> <h4 id="データの内容は同じだが異なる親revisionに対して登録する">データの内容は同じだが異なる親Revisionに対して登録する</h4> <ul> <li>概要: データの内容は同じだが、異なる親Revisionに対して登録要求が届く</li> <li>期待: 各要求は異なるものとして扱われ、別のRevisionが作成される</li> <li>アクター: プロセスA、プロセスB</li> <li>メインフロー: <ul> <li>1: プロセスAが、親Revision-1を指定してデータを登録する</li> <li>2: システムは、(親Revision-1, データ) に対応するRevisionを作成する</li> <li>3: プロセスBが、親Revision-2を指定して同じデータを登録する</li> <li>4: システムは、これら2つのリクエストが異なることを認識する（親が異なるため）</li> <li>5: システムは、(親Revision-2, データ) に対応する別のRevisionを作成する（二重登録ではなく、論理的に異なる履歴）</li> </ul> </li> </ul> <h4 id="複数の言語で実装されたクライアントからのリクエストを処理する">複数の言語で実装されたクライアントからのリクエストを処理する</h4> <ul> <li>概要：Go、Python、JavaScript など複数の言語でクライアントが実装される。システム全体で、同じ(親Revision, データ)に対しては同じ識別キーが割り当たる必要がある</li> <li>期待: 実装言語に関わらず、同じ仕様に従えば同じキーが生成される</li> <li>アクター：言語Aで実装されたクライアント、言語Bで実装されたクライアント、サーバー</li> <li>メインフロー: <ul> <li>1: 言語Aのクライアントが、ある仕様に基づいて識別キーを生成する</li> <li>2: 言語Bのクライアントが、同じ仕様に基づいて、同じ(親Revision, データ)に対して識別キーを生成する</li> </ul> </li> </ul> <h3 id="運用時のユースケース">運用時のユースケース</h3> <h4 id="識別キー計算仕様を変更する">識別キー計算仕様を変更する</h4> <ul> <li>概要: 運用中にセキュリティ向上などの理由で、識別キーの計算方法（例：ハッシュアルゴリズム）を変更する</li> <li>期待: 全ての識別キー計算方法を更新できる</li> <li>前提: デプロイによるコンテナ入れ替え時の新旧クライアント混在の影響は考えない</li> <li>識別キーをクライアント側で生成する場合: <ul> <li>アクター: システム管理者、クライアントAの開発者、クライアントBの開発者</li> <li>メインフロー: <ul> <li>1: システム管理者は、クライアントAの開発者とクライアントBの開発者に対して識別キーの計算方法の更新を要求する</li> <li>2: クライアントAの開発者は、クライアントAの識別キー計算方法を更新する</li> <li>3: クライアントAの開発者は、システムに対して新しいクライアントAのデプロイを要求する</li> <li>4: システムは、新しいクライアントAをデプロイする</li> <li>5: クライアントBの開発者は、クライアントBの識別キー計算方法を更新する</li> <li>6: クライアントBの開発者は、システムに対して新しいクライアントAのデプロイを要求する</li> <li>7: システムは、新しいクライアントBをデプロイする</li> </ul> </li> </ul> </li> <li>識別キーをサーバー側で生成する場合: <ul> <li>アクター: システム管理者、サーバー開発者</li> <li>メインフロー: <ul> <li>1: システム管理者は、サーバー開発者に対して識別キーの計算方法の更新を要求する</li> <li>2: サーバー開発者は、サーバー内における識別キー計算方法を更新する</li> <li>3: サーバー開発者は、システムに対して新しいサーバーのデプロイを要求する</li> <li>4: システムは、新しいサーバーをデプロイする</li> </ul> </li> </ul> </li> </ul> <h4 id="複数の識別キー計算仕様に対応する">複数の識別キー計算仕様に対応する</h4> <ul> <li>概要: 運用中にセキュリティ向上などの理由で、識別キーの計算方法（例：ハッシュアルゴリズム）を変更する必要が出た場合、システムが円滑に移行できる</li> <li>前提: クライアントの実装言語は一つ（組み合わせ爆発回避のため）</li> <li>期待: 計画的な移行により、冪等性を失わずに仕様を変更できる</li> <li>識別キーをクライアント側で生成する場合: <ul> <li>サーバーメンテナンス（停止）期間を設けない場合: <ul> <li>前提: クライアントの識別キーの計算方法は実装済みで、デプロイ待ちの状態</li> <li>アクター: サーバー開発者、サーバー、クライアント開発者、エンドユーザーA、エンドユーザーB、ハッシュアルゴリズムAを使う古いクライアント、ハッシュアルゴリズムBを使う新しいクライアント、</li> <li>メインフロー: <ul> <li>1: サーバー開発者は、新旧2種類のハッシュアルゴリズムに対応するようにサーバを変更する</li> <li>2: サーバー開発者は、システムに対して新しいサーバーのデプロイを要求する</li> <li>3: システムは、新しいサーバーをデプロイする</li> <li>4: サーバー開発者は、クライアント開発者に識別キーの計算方法を更新したクライアントをデプロイしても良い旨を連絡する</li> <li>5: クライアント開発者は、システムに対して識別キーの計算方法を更新したクライアントのデプロイを要求する</li> <li>6: システムは、クライアントを入れ替え始める</li> <li>7: エンドユーザーAが、システムに対してデータの登録を要求する</li> <li>8: システムは、エンドユーザーAの要求を新しいクライアントに振り分ける</li> <li>9: 新しいクライアントは、サーバーに対してデータの登録を要求する</li> <li>10: サーバーは新しいクライアントからのデータを永続化し、永続化が成功した旨のメッセージを新しいクライアントに返却する</li> <li>11: エンドユーザーAは、データが登録されたことを確認する</li> <li>12: エンドユーザーBが、システムに対してエンドユーザーAと同一の内容で登録要求する</li> <li>13: システムは、エンドユーザーBの要求を古いクライアントに振り分ける</li> <li>14: 古いクライアントは、サーバーに対してデータの登録を要求する</li> <li>15: サーバーは、古いクライアントからの要求内容が処理済みの要求と同一と判定し、新しいクライアントに返却したものと同じメッセージを古いクライアントに返却する</li> <li>16: エンドユーザーBは、データが登録されたことを確認する</li> <li>17: システムは、クライアントの入れ替えを完了する</li> </ul> </li> </ul> </li> <li>サーバーメンテナンス（停止）期間を設ける場合: <ul> <li>アクター: サーバー開発者、クライアント開発者</li> <li>メインフロー: <ul> <li>1: サーバー開発者は、システムに対してサーバーの停止を要求する</li> <li>2: システムは、サーバーを停止する</li> <li>4: サーバー開発者は、クライアント開発者に識別キーの計算方法を更新したクライアントをデプロイしても良い旨を連絡する</li> <li>5: クライアント開発者は、システムに対して識別キーの計算方法を更新したクライアントのデプロイを要求する</li> <li>6: システムは、クライアントを入れ替え始める</li> <li>7: システムは、クライアントの入れ替えを完了する</li> <li>8: クライアント開発者は、サーバー開発者に対してクライアントのデプロイが完了した旨を連絡する</li> <li>9: サーバー開発者はシステムに対してサーバーの再稼働を要求する</li> <li>10: システムは、サーバーを再稼働させる</li> </ul> </li> </ul> </li> </ul> </li> <li>識別キーをサーバー側で生成する場合: <ul> <li>メインフロー: <ul> <li>1: サーバー開発者は、サーバー内の識別キー計算方法を更新する</li> <li>2: サーバー開発者は、識別キーの計算方法が更新されたサーバーのデプロイをシステムに要求する</li> <li>3: システムは新しいサーバーをデプロイする</li> </ul> </li> </ul> </li> </ul> <h2 id="冪等性キーの生成場所と等値性の判定場所の決定">冪等性キーの生成場所と等値性の判定場所の決定</h2> <p>上で洗い出したユースケースをもとに、冪等性キーの生成場所と等値性の判定場所について考えていく。</p> <p>冪等性キーの生成場所について、サーバー側・クライアント側それぞれを選択した場合のメリット・デメリットは下記の通り:</p> <ul> <li><strong>サーバー側で生成した場合</strong> <ul> <li>pros: <ul> <li>冪等性キーの生成ロジックの更新などの運用タスクがサーバー側だけで完結する✓</li> </ul> </li> <li>cons: <ul> <li>実際には等値と判定されるペイロードも、クライアント側で冪等処理されずサーバーにリクエストされる✗ <ul> <li>同値のペイロードが大量にリクエストされた場合にDoSとなりうる <ul> <li>緩和条件: <ul> <li>エンドポイントをprivateに保った場合</li> <li>リクエスト数が少ない場合</li> </ul> </li> </ul> </li> </ul> </li> </ul> </li> </ul> </li> <li><strong>クライアント側で生成した場合</strong> <ul> <li>pros: <ul> <li>同値のペイロードに対する処理を、サーバーにリクエストすることなくクライアント側で完結させられる（キャッシュを保持する場合）✓</li> </ul> </li> <li>cons: <ul> <li>冪等性キーの生成ロジックやライブラリを更新する場合、クライアントの種数ぶんの更新タスクが発生する✗ <ul> <li>クライアントの実装言語が複数ある場合、運用工数はさらに大きくなる</li> <li>緩和条件: <ul> <li>冪等性キーの生成ロジックを共通サービスから取得した場合 <ul> <li>費用対効果が見合わない✗</li> </ul> </li> </ul> </li> </ul> </li> </ul> </li> </ul> </li> </ul> <p>上記から、両方法にはパフォーマンス上および運用上のメリット・デメリットがあることがわかった。</p> <p>資源評価プラットフォームの性質を考慮すれば、そもそもリクエスト数はそれほど多くならないと考えられるため、サーバー側で生成する方法のデメリットである、リクエスト集中時のスループットの悪さはほとんど無視できると思われる。 加えて、将来的には資源計算の入力データだけでなく、出力を保存するユースケースも考えうる: つまりクライアント種が増える可能性も考えれば、サーバーで生成する方法の運用上のメリットが重要となる。 もちろん、出力を保存するサービスを専用の新サービスとして開発する構成も考えうるが、data-registryはその名前が示すように既に充分抽象化されているように思う。</p> <p>上記を考え併せて、現時点では、冪等性キーはサーバー側で生成する方法を選ぶことにする。</p> <p>冪等性キーがサーバー側で生成されるとなれば、等値性判定もサーバー側に集約するのが自然だろう。</p> <h2 id="まとめ">まとめ</h2> <p>本記事では、前回の反省を活かして必要十分にまとめられたように思う。</p> <p>今回の主役であった冪等性については、過去記事の時点でシステム要件 <code>SR005</code> として定義してあった:</p> <blockquote> <p>SR005: 同一の登録要求識別子を持つ登録要求に対しては同一の結果を返し、新たな版を重複して作成してはならない</p> </blockquote> <p>本記事で下した冪等性キーの生成や等値性判定を行う場所についての意思決定は既存の <code>SR005</code> には反映されないものの、アーキテクチャに関する意思決定としてdata-registryのADRとした。</p> <p>現時点におけるdata-registry開発の進捗はこんな感じ:</p> <ul> <li><input checked="" disabled="" type="checkbox"> API契約を書く</li> <li><input checked="" disabled="" type="checkbox"> ルーティングの動作確認</li> <li><input checked="" disabled="" type="checkbox"> db セットアップ</li> <li><input checked="" disabled="" type="checkbox"> リポジトリ・ハンドラの実装</li> <li><input checked="" disabled="" type="checkbox"> API基本設計</li> <li><input disabled="" type="checkbox"> Revision生成ロジックの設計 <ul> <li><input checked="" disabled="" type="checkbox"> 等値性の定義</li> <li><input checked="" disabled="" type="checkbox"> 冪等性キー生成場所と等値性判定の場所の決定</li> <li><input disabled="" type="checkbox"> 冪等処理の設計</li> </ul> </li> <li><input disabled="" type="checkbox"> データベース設計</li> <li><input disabled="" type="checkbox"> リファクタリング</li> <li><input disabled="" type="checkbox"> エラーハンドリングの追加</li> </ul> <p>つづく</p>