画像変換API:受付から結果を確かめるまで

架空仕様の学習用。img_42 / req_A / job_17を共通の例に使用。HTTP一般はRFC 9110を確認。

全体像

これは画像変換を受け付けて後から結果を確かめる、提供された架空APIの説明です。サーバーの202は受付であり、クライアントが結果を表示できる完了状態とは別です。

架空画像変換APIの構成。クライアントがサーバーへPOSTとGETを送り、サーバーとワーカーがジョブ保存先を使う。
矢印はアクセスする先を示します。受付と変換完了は別であり、上下の位置は通信の時間順を表しません。

受付と処理の完了を分ける理由

サーバーは画像変換の終了を待たずに202とjobIdを返します。クライアントは返されたjobIdで保存済みの状態を読み、変換の結果を判断します。202だけを受け取って結果表示へ進むと、クライアントは未完了のジョブを完了と誤認します。

実際の値を使う通信例へ。API固有の規則は提供された架空仕様です。HTTPの202も処理の受付と未完了を表します(RFC 9110 §15.3.3)。

この例が決めていない運用条件

架空仕様は認証、画像アップロード、保存先の実装、キューの方式、排他制御、削除、保持期間を定めていません。図の保存先は状態を保持する役割であり、特定のデータベース製品を要求しません。

通信を追う

同じ依頼を再送するとき、クライアントは同じrequestKeyを使います。サーバーは同じjobIdを返すため、再送によって重複ジョブを作りません。

番号付き解説を順に確認できます。再生の時間は処理時間を示しません。

①初回のreq_Aはjob_17を作成し、②再送のreq_Aは同じjob_17を再利用する対応図。
①初回と②再送は、同じ依頼・同じキー。202は完了を意味しません。ワーカーの全状態と503の再試行は別図で扱います。
③クライアントがGET /jobs/job_17でサーバーから同じジョブの状態を取得する。
③は①②と同じjob_17の状態照会。新しい変換依頼ではありません。

同じ依頼では同じrequestKeyを保つ

クライアントが再送でrequestKeyを作り直すと、同一キーの保証の前提を満たしません。次の通信例は、図の①に対応するimg_42とreq_Aの初回受付です。

通信例の抜粋 / 画像IDのフィールド名imageIdは説明用
POST /jobs
Content-Type: application/json

{"imageId":"img_42","requestKey":"req_A"}

202 Accepted
{"jobId":"job_17"}

上の応答は受付の結果です。クライアントは202を受け取っても画像を表示せず、次にjob_17の状態と結果を読みます。GET応答のJSONに使うstatusフィールドとURLの具体値は説明用で、提供仕様にJSONの完全な形式はありません。

2回目のPOSTと、未定義のキー条件

クライアントが同じ画像とreq_Aを再送すると、サーバーは重複ジョブを作らずjob_17を返します。架空仕様は同じキーで異なる画像を送る場合、キーの有効期限、並行したPOSTの実装方法、再送時のHTTP応答ステータスを定めていません。利用者は同じキーなら異なる依頼も安全にまとめられるとは解釈できません。

状態と結果

状態はjob_17という同じジョブの進行を表します。ワーカーが状態と結果を保存し、クライアントはGETの値を読んで結果または失敗理由を表示します。

同じjob_17はqueuedからrunningへ進み、成功ならcompletedとresultUrl、失敗ならfailedとreasonを保存する。completedとfailedはrunningから分かれる代替終端。
同じ job_17 を追います。③と④は代替の終端で、矢印だけが状態遷移を示します。

GETの値が表示を決める

次の通信例では、クライアントが最初にqueuedを読み、後の照会でcompletedとresultUrlを読みます。実際に何回照会するかを決めるGETの間隔と打ち切り条件は、架空仕様にありません。

状態取得の説明用通信例 / statusと応答整形は説明用
GET /jobs/job_17

{"status":"queued"}

GET /jobs/job_17

{"status":"completed",
 "resultUrl":"https://example.invalid/results/job_17.png"}
失敗側の通信例と、模擬実行の全状態
失敗時の説明用GET応答
GET /jobs/job_17

{"status":"failed", "reason":"画像を変換できませんでした"}

ワーカーの成功と失敗は同じジョブの代替結果です。この説明ではcompletedの後にfailedへ遷移しません。failedからqueuedへの自動再実行も仕様にありません。

インメモリ模擬実行の全出力には、同じjob_17のqueued、running、成功終端と、別試行の失敗終端を保存しました。

再送と停止

クライアントがPOSTの503を受けたときだけ、提供仕様の再試行規則を使います。初回+最大2回の追加送信でも503なら、クライアントは受付結果不明と表示します。

①から応答待ちを読み始める。1・2回目の503では同じキーで再送し、3回目の503では⑤受付結果不明へ止まる。いずれかで202なら④受付確認へ進む。
①から開始。503の1・2回目は再送、3回目は⑤で停止。202は④へ。

追加2回は、合計3送信まで

図の①〜③を同じキーで試し、応答がすべて503になる例です。クライアントは追加送信を2回に抑え、4回目を送信しません。

503が継続する説明用トレース
1回目 POST /jobs  requestKey=req_A → 503
2回目 POST /jobs  requestKey=req_A → 503
3回目 POST /jobs  requestKey=req_A → 503

クライアント表示: 受付結果不明

「受付結果不明」はジョブのfailed状態とは異なります。failedはワーカーが保存した変換の失敗であり、受付結果不明はクライアントが受付を確定できない表示です。クライアントは不明を画像変換失敗へ置き換えません。

HTTP一般の意味と、この架空APIだけの再試行規則

HTTPの503はサーバーが一時的に要求を扱えない応答です。サーバーはRetry-Afterで待ち時間を示せますが、この架空APIは待ち時間やバックオフを定めていません。同じrequestKeyを使う規則と追加2回の上限は提供仕様だけの規則です(RFC 9110 §15.6.4、架空仕様)。

503以外のPOST応答、通信断、タイムアウト、GETの失敗時は未定義です。この説明は未定義の条件へ再試行規則を拡張しません。

資料と確認範囲

API固有の規則は提供された架空仕様です。HTTP一般の資料と説明用の仮定を分けて確認できます。

このページは資料名と確認範囲を示します。原文・HTTP資料・模擬実行の説明へ。

説明の根拠を分ける

job_17、requestKey、状態、最大2回という規則は提供された架空仕様に基づきます。RFCはHTTPの意味を確認する補助資料であり、この架空APIの存在や動作を保証しません。

制作者はインメモリ模擬実装を node simulation.cjs で実行しました。模擬結果は入力の説明との整合を確かめるためのものです。模擬実装が再送にも202を返す点は説明用の仮定です。原文は再送のHTTP状態を定めていません。実APIへの通信、永続化、並行アクセスの保証や利用者による承認は実施していません。

原文と模擬コードの全文

原文はinput.mdへ保存しました。模擬コードは架空仕様の説明用です。

JavaScript / simulation.cjs / 説明用インメモリ模擬実装
// 説明用のインメモリ模擬実装。実APIへの通信ではない。
// 再送応答の202は模擬実装の仮定。原文は再送時のHTTP状態を指定しない。
const jobs = new Map();
let nextId = 17;
function post({imageId,requestKey}) {
  if (!jobs.has(requestKey)) jobs.set(requestKey,{jobId:`job_${nextId++}`,imageId,status:'queued'});
  return {status:202,body:{jobId:jobs.get(requestKey).jobId}};
}
function get(jobId) { return {...[...jobs.values()].find(j=>j.jobId===jobId)}; }
function run(jobId,success) {
 const job=[...jobs.values()].find(j=>j.jobId===jobId);
 job.status='running';
 const running=get(jobId);
 if(success){job.status='completed';job.resultUrl='https://example.invalid/results/job_17.png';}
 else {job.status='failed';job.reason='画像を変換できませんでした';}
 return {running,terminal:get(jobId)};
}
function retry(statuses,requestKey='req_A') {
 const sent=[];
 for(let i=0;i<3;i++){
  const status=statuses[i];sent.push({attempt:i+1,requestKey,status});
  if(status===202)return {sent,display:'受付済み。job_17の状態を取得する'};
  if(status!==503)throw new Error('この模擬例が扱わない応答');
 }
 return {sent,display:'受付結果不明'};
}
const input={imageId:'img_42',requestKey:'req_A'};
const first=post(input),duplicate=post(input),queued=get('job_17');
const success=run('job_17',true);
jobs.clear();nextId=17;post(input);const failure=run('job_17',false);
const result={notice:'提供された架空仕様の理解を助ける模擬実装であり、実サーバー、永続化、排他制御の実装保証ではない。',input,first,duplicate,queued,success,failure,retries:[[202],[503,202],[503,503,202],[503,503,503]].map(s=>retry(s)),unspecified:['再送時のHTTP応答状態','キーの有効期間','同じキーで異なる画像IDの場合','並行POSTの排他','GETの間隔','503の待ち時間・バックオフ','POST以外のエラー応答']};
require('node:fs').writeFileSync(require('node:path').join(__dirname,'simulation-results.json'),JSON.stringify(result,null,2)+'\n');
console.log(JSON.stringify({first:first.body.jobId,duplicate:duplicate.body.jobId,queued:queued.status,completed:success.terminal.status,failed:failure.terminal.status,retryCounts:result.retries.map(r=>r.sent.length)}));