再起動安全なWebhook配信
再起動安全なWebhook配信
Section titled “再起動安全なWebhook配信”plugins.output.webhook.state-pathに永続SQLiteファイルを設定すると、出力のキューに入ったWebhook配信を再起動後も保持できます。
output: webhookplugins: output: webhook: url: "https://example.org/adder-hook" format: "adder" state-path: "/var/lib/adder/webhook.sqlite" max-pending: 1024state-pathを設定すると、Adderは各イベントを1回だけ整形し、リクエスト本文をSQLiteに追加してから送信します。追加処理にはSQLiteトランザクションを使用します。HTTP 2xx応答を受け取ると、出力はそのエントリを明示的に削除します。HTTP 2xx応答は、HTTP Semanticsに従って受信側がリクエストを受け付けたことを示しますが、受信側の後続処理が完了したことは証明しません。再起動時、Startは保留中のエントリを元の順序で再生してから戻ります。再生を完了できない場合、起動は失敗し、保留中のエントリはSQLiteに残ります。
永続モードでは、POSTを本文のないGETに変更するリダイレクトを拒否します。307および308リダイレクトではリクエスト本文を保持できます。
既存の再試行ポリシーは各配信実行に適用されます。最初に1回試行し、一時的な失敗に対して最大3回再試行します。終端応答または再試行上限の消化によって配信できない場合、出力は終端失敗を報告してパイプラインを停止し、エントリをSQLiteに残します。同じURLとformatで再起動すると、そのエントリを再試行します。通常の停止処理では、出力バッファーが受け入れた後続イベントを永続化します。プロセスがクラッシュすると、SQLiteへの追加前に上流にあったイベント、パイプラインまたは出力チャネル内のイベントを失う可能性があります。このオプションは、chainsyncカーソルとWebhook追加処理を1つのアトミックなトランザクションにはしません。
イベント検証と停止処理
Section titled “イベント検証と停止処理”Adderは、payloadがnilのイベント、イベント種類に合わないpayloadまたはcontextを持つイベント、既知のイベントでcontextがnilのイベント、未知のイベント種類を安全に拒否します。このような入力を受けてもプロセスを異常終了させず、エラーをWebhook出力のエラーチャネルへ、送信処理をブロックせずに報告します。エラーチャネルが受信できない場合は、エラーをログに記録します。
イベントの整形やJSONマーシャリングに失敗した場合、出力はそのエラーを返します。Webhook URLの解析、リクエスト作成、HTTP通信の設定、送信で発生したエラーも呼び出し元またはエラーチャネルへ伝播します。
StartとStopは出力の状態とチャネルを安全に協調して管理します。Stopはワーカーの完了を待ってから共有チャネルを閉じます。再試行のバックオフ待機中に停止すると、待機を停止シグナルで中断します。停止によるキャンセルは受信側の成功応答でもSQLiteの確認応答でもないため、保留中のエントリを完了扱いにせず、永続キューに残します。
キューにはmax-pendingエントリ数のハード上限があります。最小値は11、デフォルトは1024です。エンコード済みのエントリごとの上限は16 MiBです。state-pathにはディスク上の永続SQLiteファイルを指定します。:memory:のようなインメモリデータベースは使用できません。通常のファイル名を指定します。AdderはSQLite URIとDSNクエリパラメーターを拒否するため、設定によってキューの保存方法や耐久性を変更できません。
状態ファイルは、他のローカルユーザーが変更できないディレクトリに配置します。Unixでは、Adderが各パス構成要素の所有者と権限を確認し、直近の親ディレクトリがシンボリックリンクの場合は拒否します。/tmpのようなroot所有のスティッキーな祖先ディレクトリは使用できます。Adderは、データベースと既存のSQLiteジャーナルサイドカーファイルを開く前に、所有者だけがアクセスできるファイル権限に制限します。起動時の検査では、Adderが状態ファイルまたは既存のサイドカーファイルのシンボリックリンクを拒否します。Unixのモード検査では拡張ACLを確認しません。別のアカウントへの書き込み権限付与を許可しない設定が必要です。Windowsでは、Adderアカウントだけに書き込み権限を許可するディレクトリACLを設定します。AdderはディレクトリACLを検証しません。
これらの検査では、Adderユーザーとして動作する別のプロセスがAdderの起動中にファイルを変更することは防げません。
キューが満杯になった場合、またはSQLiteがイベントを永続化できない場合、出力はイベントを黙って破棄せずに失敗します。保留中のエントリには自動的な有効期限がありません。2xxの確認応答を受け取るか、オペレーターが明示的に削除するまで残ります。Adderは配信済みのエントリを直ちに削除します。1つのstate-pathにつき1つのAdderプロセスだけを使用し、再起動時もデータベースファイルを保持します。Adderは既存の状態ファイルに対するURLまたはformatの変更を拒否します。これにより、古い配信が別の宛先に送信されることを防ぎます。新しい宛先には別の状態ファイルを使用します。
キューに入れた各配信は、再試行と再起動の間で安定したX-Adder-Delivery-IDヘッダーを保持します。受信側がリクエストを受け付けた後、SQLiteが確認応答を記録する前にプロセスが停止すると、再生によって同じリクエストを再送することがあります。受信側はこのヘッダーで重複排除できます。出力が提供するのは永続化したエントリに対する少なくとも1回の試行であり、厳密に1回の副作用ではありません。ロールバックイベントは先行するブロックイベントの後にキューへ入り、先行イベントを消去しません。コンシューマーは自身の状態にロールバックを適用する必要があります。
復旧を確認する
Section titled “復旧を確認する”- テスト用の受信側が
500を返すように設定し、イベントを送信します。出力が失敗し、エントリがSQLiteファイルに残ることを確認します。 - 受信側が
200を返す状態で再起動し、同じX-Adder-Delivery-IDを受信することを確認します。 - 次のSQLでSQLiteファイルを照会し、結果が
0になることを確認します。
SELECT COUNT(*) FROM queue WHERE name = 'webhook.pending';パッケージテストは、外部サービスを使用せずに、この手順、バッファー済みイベントの正常な永続化、宛先の識別情報、順序を保ったSQLite再生を検証します。
Docs authored by Doc Holiday