Kaigi on Rails 2021 proposal

code:markdown

# Kaigi on Rails CfP

SmartBank社で家計簿プリカ「B/43」の開発・運用をしています。Ruby on Railsによるmobile application向けAPI開発、Single Page Application開発が主な業務内容です。

POST/PATCHリクエストを冪等にする冴えたやり方〜Idempotency-Key Header〜

（公開プログラムの簡潔で魅力的な説明文です。文字数は600字以内です）

商品を注文する、顧客にお金を請求する、他人の口座に送金する…。このような、不可逆で二重に行われてほしくない処理をネットワーク越しにリクエストすることがしばしばあります。もしこれらの処理のリクエストにて通信が失敗するとどうなるでしょうか？

通信エラーに直面したクライアントはリトライするかもしれません。しかし1回目のリクエストでサーバ側の処理が完了していた場合、リトライにより処理が複数回行われてしまう可能性があります。

この問題を解決する鍵は冪等性です。サービス呼び出しが冪等、つまり「同一リクエストを何度受け取っても結果が変わらない」仕組みをサーバが備えていれば、クライアントは通信が成功するまでリトライできるようになります。

その仕組みの1つがIETF draftとして提出されているIdempotency-Key Headerです。これはRFC7231にて冪等ではないとされるPOST/PATCHリクエストを冪等にするためのソリューションで、PayPalやStripeなど一部ベンダーは既に類似実装を各社のAPIに適用しています。

このセッションではIdempotency-Key Headerが解決する課題とコンセプトを解説し、Rubyアプリケーションにおける実装例を紹介します。例の一つは私が携わる金融サービスで設計・実装したものであり、運用を通じて得られた知見も交えてお話します。

（概要、成果、対象者など、関連する詳細を含めてください）

以下を聞き手として想定します。

- 冪等性という言葉を聞いたことがない初級者

- Web APIやバッチ処理において冪等性を考慮した設計はできるが、Idempotency-Key Headerの提案仕様や実装の具体例は知らない中級者

以下の構成・内容でお話する予定です。

1. 解決したい課題 (3分)

- 課題を定義して聴衆とスピーカーの目線を合わせる

- Webサービスにおいてリクエストの通信エラーは必ず発生する

- 通信エラーが発生した際、単純にリトライすると意図しない結果を引き起こす処理がある（記事投稿や購入、送金など）

- クライアント側でリトライ可否を知ろうとすると余計な複雑さを持ち込むことになる

1. 冪等性の説明 (2分)

- 課題解決の鍵となる用語・概念をおさらいする

1. HTTPにおける冪等性 (3分)

- HTTP仕様では冪等性はどのように扱われているか、RFCやMDN Web Docsを参照しつつ理解を深める

- POST/PATCHリクエストはRFC7231では冪等ではないという事実に着目する

1. Idempotency-Key Headerの提案仕様 (10分)

- PayPalのJayadeba Jena氏らに提出された「The Idempotency-Key HTTP Header Field」を参照し、POST/PATCHリクエストを冪等にするための具体的な解決策を理解する

1. Idempotency-Key Headerの実装パターン (12分)

- RubyアプリケーションにおけるIdempotency-Key Headerの実装例は多くないが、いくつか参考になるプロダクトやドキュメントはあるので紹介する

- Stripe APIの例（クライアント目線）

- Stripeでの実装例

- 元StripeのエンジニアによるSinatraでの実装例

- Rack middlewareとして実装しているOSS

- スピーカーが開発・運用する金融サービスでの実装例

- Rack middlewareとして実装した理由

- 提案仕様とはあえて違う設計にした箇所

聞き手はこのセッションを通じて以下の成果を得られると考えます。

- 冪等性の概念の理解

- 業務でWebアプリケーションを構築する際に、自身が実装するAPIエンドポイントが冪等であるべきかどうか、といった設計の観点

- APIエンドポイントを冪等にする場合の設計・実装イメージ

（この講演を検討すべき理由と、そのテーマで講演する資格があることを説明してください）

本セッションで話すトピックが2021年のKaigi on Railsに相応しいと主張できる根拠が3つあります。

1つは時期性。Idempotency-Key Headerのドラフトの提案は2020年11月に行われ、2021年の7月に更新されています。今すぐにWeb標準となることはなくとも、数年後に標準化される可能性を見据え、予め押さえておくトピックといえます。

2つ目は業界内における現状の知見の少なさ。Idempotency-Key Headerを使うにせよ別の仕組みにせよ、POST/PATCHリクエストを冪等にしてアプリケーションを堅牢化するための知見が多く出回っていないことを、実装のために調査したときに強く感じました。私が自社サービスにおいて同等の仕組みを実装した際に得られた知見を広く公開することや、それにより議論が深まることに価値があると考えます。

3つ目はビジネスとアーキテクチャのトレンド。冪等性はマイクロサービスや決済・金融サービスの文脈においてその重要性が近年さらに増しているといえます。マイクロサービスはソフトウェアの成熟・複雑化に伴い近年増加しつつありますし、BaaSの勃興などを背景として多くのエンジニアが決済・金融サービスに携わる可能性が高まっています。この潮流において語るべき技術トピックの1つと考えます。

私は入金・出金・送金といった銀行に類似する機能を持つ金融サービスを開発・運用するプログラマであり、Idempotency-Key Headerが解決する課題がいかに重要なものであるかを実体験として語ることができます。

また、PayPalによる提案仕様を参照しながらIdempotency-Key Headerの仕組みを自社サービスのために実装しました。この仕組みは現在も運用されており、同サービスの堅牢性向上に寄与しています。そのため、Stripe APIなどのIdempotency-Key Headerを利用可能なサービスの単なるコンシューマとしてではなく、サービス提供側の観点を持ちつつコードレベルで解説することができます。