Idempotency-Key:PDF ジョブの安全な再試行
/api/v1/ 配下の POST ジョブに Idempotency-Key を送る。成功応答は 24 時間プロセス内メモリにキャッシュし、再実行せず Idempotency-Replayed: true を返す。

ネットワークのタイムアウトとクライアントの再試行は、multipart の PDF アップロードでは普通のことだ。冪等キーが無ければ、二度目の POST が同じ結合、OCR、圧縮をもう一度走らせ、アップロードと処理時間を無駄にやり直すことになる。Idempotency-Key があれば、PDF123 は最初の成功応答をリプレイできる。
ミドルウェアがしていること
pdfx-server のサーバーミドルウェアは、変更系の呼び出しにだけ適用される。/api/v1/ 配下への POST(/api/v1/pipeline を含む)だ。GET とその他のメソッドはそのまま通る。リクエストに Idempotency-Key ヘッダーが無い(または trim すると空になる)場合、op は通常どおり走り、キャッシュの参照も行われない。
ヘッダーがある場合:
- ストアはエントリをプリンシパル + キーで鍵付けする。プリンシパルは
X-API-KEY(key:…として)、無ければAuthorization(auth:…として)、無ければリテラルのanonから導かれる。この二つの値は SHA-256 でハッシュ化されてマップの鍵になる。リクエストの本体は鍵の一部ではない。 - 24 時間以内のキャッシュヒットでは、保存されたステータス、content type、content disposition、本体を返し、
Idempotency-Replayed: trueを付ける。 - ミスならリクエストは続行する。成功した応答だけがバッファされ保存される(成功以外の応答はリプレイ用にキャッシュされない)。
- 応答の本体は最大 100 MiB までバッファされ、リプレイがファイルのバイトを再送できるようにする。バッファできない本体は、黙ってキャッシュを飛ばすのではなく、そのリクエストが HTTP 500 を返す。上限を超える応答は、キャッシュされないまま通るのではなく失敗する。
失敗したジョブは同じキーで安全に再試行できる。失敗は保存されないので、次の試行が成功すればそれがキャッシュされた結果になる。別のファイルやパラメータにキーを再利用してはいけない。キャッシュがハッシュ化するのはプリンシパルとキーだけで、本体は含まない。API Key も Authorization も共有しない二つの呼び出し元が偶然衝突することはない。匿名の呼び出し元は anon プリンシパルを共有するため、別々のキーを選ぶ必要がある。
送り方
論理的なジョブごとに、安定した不透明な文字列を選ぶ(UUID でよい)。
curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "[email protected]"
匿名でも API Key でも動く。透かしを入れてから圧縮するパイプラインでも、重複排除したい HTTP リクエストごとにキーを一つ送る。別々に POST するなら各ステップに一つ、単一の /api/v1/pipeline 呼び出しなら一つだ。
ツールページでのブラウザの単発作業(圧縮、OCR など)では、キーを発明する必要はない。ヘッダーが重要なのは再試行するクライアントだ。公開 skill /skills/pdf123.md は、同じ理由で pipeline の例に Idempotency-Key を示している。
うまくいくクライアントのパターン
- 最初の POST の前にキーを生成し、同じ論理ジョブのタイムアウト再試行ではそれを再利用する。
- 成功したとき、その応答が op をもう一度走らせたのかキャッシュから来たのかを知りたければ
Idempotency-Replayed: trueを確認する。 - ファイル、op、パラメータが変わったらキーを変える。プリンシパルが同じままであっても。
/api/v1/pipelineでは、キー一つがパイプラインの POST 全体を覆い、内側の各ステップを覆うのではない。
リプレイがそうではないもの
リプレイは永続的なジョブキューではない。ストアはプロセスローカル(mutex の裏の HashMap)で TTL は 24 時間だ。期限が切れたあと、あるいはメモリ上のマップを失う再起動のあとは、同じキーでも op がもう一度走る。複数インスタンスの配備では、前に共有ストアを置かない限りこのマップは共有されない。今日のミドルウェアはプロセス単位だ。
Idempotency-Replayed: true は、その応答がキャッシュから来たことの証明として扱い、永久の台帳とは考えない。PDF が再処理されたという意味でもなく、TTL が延びたという意味でもない。
より詳しい面は 開発者向け と AI エージェントのために作る にある。圧縮 などのツールページは、キーを発明せずにブラウザの単発作業にも使える。