非同期処理とジョブキュー — 1つの遅い処理が全部を止める

非同期処理とジョブキュー。順番待ちのジョブカードと作業するワーカーの機械、応答するブラウザ。

前々回・前回で、同じ答えを何度も作り直さない話(キャッシュ・CDN)をやりました。

これは【深掘り】の記事です。本線の順路ではありません。 読まなくても先へ進めます。 本線の ボトルネックは動く — 負荷分散とキャッシュの設計 の続きとして、「待たせなくてよい仕事を、どうやって待たせないようにするか」だけを、実際に動かして確かめます。

前回: CDNとエッジキャッシュ — 距離は速度で解決できない

この記事のコマンドは、すべてVMの中(Ubuntu Server)で打ちます。 Windows の PowerShell では打ちません。

前提: 本線の APIの正体はJSONを返すHTTP — Node.jsで作る と コンテナは軽い仮想マシンではない — Dockerの導入 を終えていること。node -v と docker ps が動けば十分です。 この記事は既存の ~/server を触りません。 新しく ~/asynclab を作って、そこだけで完結させます。壊れても消せば戻ります。

ですが、キャッシュが1ミリも効かない仕事があります。 利用者がいま上げた画像を、いま縮小する。その1枚は世界に1つで、過去の答えは無い。

こういう画面です。

「アップロード」を押す。ぐるぐるが回る。 30秒。その間、他のボタンも押せない。 しびれを切らしてもう一度押す。サムネイルが2枚できる。

このとき、遅いのは変換そのものです。索引を張っても、キャッシュを挟んでも、CDNを前に置いても1ミリも速くなりません。 速くする前に必ず測るの回でやった手を全部使っても、3秒かかる変換は3秒かかります。

そこで変えるのは、速さではなく順番です。

利用者が結果を待つ必要のない仕事は、受け付けだけして、あとでやる。

これを非同期にすると言います。この記事の主題は、「何を待たせないか」という一点です。

そして、この記事の本番は組み替えたあとです。非同期にした瞬間、利用者から「終わったのか」が見えなくなり、リトライが二重実行になり、失敗が誰にも届かなくなります。 そこまでやります。

対象レベル: 中級〜上級 / 区分: 発展

目次

この記事でわかること

  • 1つの遅い処理は、無関係な他のエンドポイントまで巻き込んで遅くすること。遅いのは自分だけ、にはならないこと
  • 「非同期にする」は速くすることではないこと。待たされる人を減らすだけで、仕事の総量は1ミリも減らないこと
  • 202 を返した瞬間、「終わったか」を伝える責任が新しく発生すること。それを設計しないと、利用者は永遠にぐるぐるを見ること
  • リトライがある世界では、冪等でない処理は必ず二重実行されること。二重課金は「起きるかもしれない」ではなく「起きる」こと
  • 非同期にすると仕事は増えること(失敗の追跡・順序・監視・デバッグ)。減るのは待ち時間だけだということ
  • キューは無限ではないこと。受け付けを止める設計(バックプレッシャー)が無いと、詰まったときに全部倒れること

この記事でやること

  1. 3秒かかるエンドポイントを実際に作り、hey で同時に叩いて、無関係な /health まで遅くなるのを実測する
  2. キューに積んで 202 Accepted を返す形に組み替え、ワーカーに処理させて、同じ負荷で応答時間が戻るのを実測する
  3. 結果の返し方を3方式で対比し、ポーリング(GET /jobs/:id)を実装する
  4. 同じ依頼を2回投げて二重実行を起こし、依頼IDで記録して冪等に直す
  5. キューが溢れる状態を作り、429 で受け付けを止める
  6. 後片づけする(コンテナとワーカーを残さない)

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
同期(synchronous)依頼した人が、結果が出るまでその場で待つやり方。ふつうのHTTPリクエストはこれ
非同期(asynchronous)受け付けだけ先に返して、実際の処理はあとでやるやり方。待つのをやめる、ということ
ジョブあとでやる仕事1件。ここでは「この画像を縮小して」という依頼1つ
キュージョブを並べておく置き場。入れる側と取り出す側が別々に動く
ワーカーキューから取り出して実際に処理する裏方のプロセス。画面を持たない
202 Accepted「受け取った。まだ終わっていない」を意味するHTTPのステータス。200 OK は「終わった」
ポーリング利用者側から「終わりましたか」と定期的に聞きに行くこと
Webhook終わったほうから相手のURLを叩いて知らせること。Botの回で出てきたあれです
冪等(べきとう)同じ操作を何回やっても、結果の状態が同じという性質。RESTの回で出てきました
バックプレッシャー処理が追いつかないとき、受け付ける側を意図的に止める仕組み。「押し返す圧力」の意味
イベントループNode.js が1本のスレッドで順番に仕事を回している輪。ここが塞がると、その間はどのリクエストも進まない

準備 — 実験場を作る

すべてVMの中(Ubuntu Server)で打ちます。

bash
$ mkdir -p ~/asynclab
$ cd ~/asynclab
$ npm init -y
$ npm install express redis

node_modules ができれば成功です。中身は消してよいものでした(npmの回)。

bash
$ ls ~/asynclab
node_modules  package-lock.json  package.json

負荷をかける道具を入れる

同時に何本も叩く道具として hey を使います。まず入るか確かめます。

bash
$ sudo apt update
$ sudo apt install -y hey
$ hey -h

使い方の一覧がずらっと出れば入っています。 hey: command not found と出た場合は、Ubuntu のリポジトリに無いので、公式の配布物を取ってきます。

bash
$ cd ~
$ curl -L -o hey https://hey-release.s3.us-east-2.amazonaws.com/hey_linux_amd64
$ chmod +x hey
$ sudo mv hey /usr/local/bin/hey
$ hey -h

どちらの方法でも構いません。 hey -h が反応することだけ確かめてから先へ進みます。反応しないまま先へ進むと、この記事の測定が全部できません。

ab(apache2-utils)でも同じことはできます。 本線の負荷分散の回では ab を使いました。ここで hey にするのは、同時実行数を保ったまま流し続ける指定(-z)が書きやすいからです。道具の違いであって、思想の違いではありません。

置き場(Redis)を立てる

キューと、ジョブの状態の保管に Redis を使います。本線のRedisの回で入れたものとは別に、この実験専用のコンテナを立てます。

bash
$ docker run -d --name asynclab-redis -p 127.0.0.1:6379:6379 redis:7-alpine
$ docker ps --filter name=asynclab-redis
CONTAINER ID   IMAGE            COMMAND                  STATUS         PORTS                      NAMES
9f2c1b0a7e31   redis:7-alpine   "docker-entrypoint.s…"   Up 3 seconds   127.0.0.1:6379->6379/tcp   asynclab-redis

-p 127.0.0.1:6379:6379 の 127.0.0.1: を省略しないでください。 省略すると VM の外から誰でも触れる Redis になります。Redis には既定でパスワードがありません。

bash
$ docker exec -it asynclab-redis redis-cli ping
PONG

PONG が返れば準備完了です。

もし既に 6379 を使っている(本線の回のRedisが動いている)なら、docker: Error response from daemon: ... port is already allocated が出ます。その場合はこの実験だけポートをずらします。

bash
$ docker run -d --name asynclab-redis -p 127.0.0.1:6380:6379 redis:7-alpine

ずらしたら、これ以降のコードの 6379 を 6380 に読み替えてください。


同期のまま重い処理を入れて、詰まらせる

まず、悪い形を本当に動かします。 動くところを見ないと、次でやることの意味が分かりません。

~/asynclab/server.js を作ります。

bash
$ nano ~/asynclab/server.js
const express = require('express');

const app = express();
app.use(express.json());

// 3秒間、CPUを使い続ける。画像変換やPDF生成の代わり
function heavyWork(ms) {
  const end = Date.now() + ms;
  let count = 0;
  while (Date.now() < end) {
    count++;
  }
  return count;
}

// 何もしない軽いエンドポイント。これが巻き込まれるかを見る
app.get('/health', (req, res) => {
  res.json({ ok: true, at: Date.now() });
});

// 重いエンドポイント。結果が出るまで返さない=同期
app.post('/thumbnails/sync', (req, res) => {
  const started = Date.now();
  heavyWork(3000);
  res.json({ done: true, ms: Date.now() - started });
});

app.listen(3000, () => console.log('listening on 3000'));

保存して起動します。

bash
$ cd ~/asynclab
$ node server.js
listening on 3000

この端末は起動しっぱなしにします。 以降のコマンドは別の端末(もう1本 SSH で繋ぐ)で打ちます。VS Code から繋いでいるなら、ターミナルをもう1枚開くだけです。

まず1本だけ叩いて、素の速さを測る

bash
$ curl -s -o /dev/null -w "health: %{time_total}s\n" http://localhost:3000/health
$ curl -s -o /dev/null -w "sync:   %{time_total}s\n" -X POST http://localhost:3000/thumbnails/sync
health: 0.004521s
sync:   3.012884s

ここまでは想定どおりです。重い処理は3秒。軽い処理は4ミリ秒。

問題は、この2つが同時に来たときです。

重い処理を同時に流しながら、軽いほうを測る

重いほうを同時5本で10秒間流し続けます。-z 10s が「10秒間ずっと」、-c 5 が「同時5本」です。

bash
$ hey -z 10s -c 5 -m POST -H "Content-Type: application/json" -d '{}' http://localhost:3000/thumbnails/sync

これを流したまま、さらに別の端末で軽いほうを測ります。

bash
$ hey -z 5s -c 2 http://localhost:3000/health
Summary:
  Total:        5.0113 secs
  Requests/sec: 0.5987

Latency distribution:
  50% in 3.0102 secs
  90% in 6.0195 secs
  99% in 9.0281 secs

[スクリーンショット: 01_hey_sync_blocked.png] /thumbnails/sync を流しながら /health を測ったときの hey の出力を撮ってください。Latency distribution の行が入るようにお願いします。

4ミリ秒だったはずの /health が、3秒から9秒になっています。

/health のコードは1行も変えていません。重い処理の巻き添えです。

なぜ「無関係なはずの」エンドポイントが遅くなるのか

Node.js は、JavaScriptを1本のスレッドで順番に回します(イベントループ)。

heavyWork() の中の while は、その1本を掴んだまま3秒間離しません。 その間、届いた /health のリクエストは受信こそされていますが、実行される順番が回ってこないのです。

状態何が起きているか
リクエストは届いているOSのソケットには入っている。捨てられてはいない
でも処理されないイベントループが heavyWork で塞がっている
利用者から見ると「サーバーが落ちた」と区別がつかない。ただ返ってこない

そして、これは Node.js 固有の話ではありません。 PHPでもPython(同期のWSGI)でもJavaでも、「同時に処理できる数」には上限があります。 ワーカープロセス数、スレッド数、コネクションプールの本数。重い処理がその枠を全部占領すれば、軽い処理は枠が空くまで待たされます。

枠が4つあるサーバー

[重い3秒][重い3秒][重い3秒][重い3秒]  ← 全部埋まった
                                       ↑ /health はここで待つ

これは、本線で見たあの構図と同じ

1つの遅いものが、全体を巻き込んで止める。

これは本線の落ちても全部は止めない — サーキットブレーカと縮退で見たものと、まったく同じ形です。あちらは「外部APIが応答しない」でした。こちらは「自分の処理が重い」です。原因は違いますが、起きることは同じです。

サーキットブレーカの回この回
遅いもの外部のAPI自分のCPU処理
起きること枠が埋まって、無関係な画面まで死ぬ同じ
打つ手諦める(タイムアウトして切り離す)待たない(受け付けだけして後でやる)

打つ手が2つある、と理解してください。 結果が要らないものは切り離す。結果は要るがいま要らないものは、後でやる。この記事は後者です。


受け付けだけして、後でやる

組み替えます。 変えるのは1点だけです。

heavyWork() を呼ぶのをやめて、「やってほしい」という紙をキューに置く。

全体像

[利用者] --POST /thumbnails--> [API] --積む--> [キュー(Redis)]
             <--202 Accepted--                       |
                                                   取り出す
                                                     |
                                              [ワーカー(別プロセス)]
                                                     |
                                              結果を書く(Redis)

APIとワーカーは、別のプロセスです。 ここが肝で、APIのイベントループはもう塞がりません。

server.js を書き換える

bash
$ nano ~/asynclab/server.js

全文です。 さきほどの /thumbnails/sync も比較のために残します。

const express = require('express');
const { randomUUID } = require('crypto');
const { createClient } = require('redis');

const app = express();
app.use(express.json());

const redis = createClient({ url: 'redis://127.0.0.1:6379' });
redis.on('error', (err) => console.error('redis error', err));

function heavyWork(ms) {
  const end = Date.now() + ms;
  let count = 0;
  while (Date.now() < end) {
    count++;
  }
  return count;
}

app.get('/health', (req, res) => {
  res.json({ ok: true, at: Date.now() });
});

// 【旧】同期版。比較のために残す
app.post('/thumbnails/sync', (req, res) => {
  const started = Date.now();
  heavyWork(3000);
  res.json({ done: true, ms: Date.now() - started });
});

// 【新】非同期版。受け付けて 202 を返すだけ
app.post('/thumbnails', async (req, res) => {
  const id = randomUUID();

  await redis.hSet(`job:${id}`, {
    status: 'queued',
    source: req.body.source || 'sample.png',
    createdAt: String(Date.now())
  });
  await redis.expire(`job:${id}`, 3600);

  await redis.lPush('jobs', JSON.stringify({ id }));

  res.set('Location', `/jobs/${id}`);
  res.status(202).json({ id, status: 'queued' });
});

// 状態を問い合わせる(ポーリング用)
app.get('/jobs/:id', async (req, res) => {
  const job = await redis.hGetAll(`job:${req.params.id}`);
  if (Object.keys(job).length === 0) {
    return res.status(404).json({ error: 'not found' });
  }
  res.json({ id: req.params.id, ...job });
});

redis.connect().then(() => {
  app.listen(3000, () => console.log('listening on 3000'));
});

読むところは3つです。

行何をしているか
redis.hSet('job:<id>', ...)依頼の受領記録。まだ何もしていないが「受け取った」ことは残す
redis.lPush('jobs', ...)キューに積む。中身はジョブIDだけ。画像そのものは入れない
res.status(202)「受け取った、まだ終わっていない」。200 ではないことに意味がある

キューに大きなデータを入れないでください。 入れるのは「どれを処理するか」の目印だけです。実データはファイルなりDBなりに置いて、キューにはその場所を書きます。キューはメモリの上に載っていることが多く、そこに画像本体を積むと、詰まったとき真っ先にメモリが尽きます。

worker.js を書く

bash
$ nano ~/asynclab/worker.js
const { createClient } = require('redis');

const redis = createClient({ url: 'redis://127.0.0.1:6379' });
redis.on('error', (err) => console.error('redis error', err));

function heavyWork(ms) {
  const end = Date.now() + ms;
  let count = 0;
  while (Date.now() < end) {
    count++;
  }
  return count;
}

async function main() {
  await redis.connect();
  console.log('worker started');

  while (true) {
    // キューが空なら、来るまでここで止まる(0 = 無期限)
    const item = await redis.brPop('jobs', 0);
    const job = JSON.parse(item.element);

    console.log('start', job.id);
    await redis.hSet(`job:${job.id}`, { status: 'running', startedAt: String(Date.now()) });

    heavyWork(3000);

    await redis.hSet(`job:${job.id}`, {
      status: 'done',
      result: `thumb-${job.id}.png`,
      finishedAt: String(Date.now())
    });
    console.log('done ', job.id);
  }
}

main();

brPop の br は「ブロックして右から取り出す」という意味です。キューが空のとき、CPUを使って何度も見に行くのではなく、そこで眠って待ちます。 lPush で左から入れて brPop で右から出すので、入れた順に出ます(先入れ先出し)。

3つ目の端末でワーカーを起動します。

bash
$ cd ~/asynclab
$ node worker.js
worker started

APIのほうも再起動します(server.js を書き換えたので、Ctrl + C で止めて node server.js)。

1本投げてみる

bash
$ curl -i -X POST -H "Content-Type: application/json" \
    -d '{"source":"cat.png"}' http://localhost:3000/thumbnails
HTTP/1.1 202 Accepted
Location: /jobs/6f2b1d4c-9a35-4f77-9a4e-6a5c1c2b3d10
Content-Type: application/json; charset=utf-8

{"id":"6f2b1d4c-9a35-4f77-9a4e-6a5c1c2b3d10","status":"queued"}

即座に返ってきました。 ワーカー側の端末を見ると start と、3秒後に done が出ているはずです。

同じ負荷をかけて、応答時間が戻るのを見る

山場①とまったく同じ負荷を、今度は非同期版にかけます。

bash
$ hey -z 10s -c 5 -m POST -H "Content-Type: application/json" -d '{}' http://localhost:3000/thumbnails

流したまま、別端末で /health を測ります。

bash
$ hey -z 5s -c 2 http://localhost:3000/health
Summary:
  Total:        5.0021 secs
  Requests/sec: 3412.8

Latency distribution:
  50% in 0.0004 secs
  90% in 0.0011 secs
  99% in 0.0038 secs

[スクリーンショット: 02_hey_async_recovered.png] 非同期版に組み替えたあと、同じ手順で /health を測った hey の出力を撮ってください。山場①と並べて比べられるように、Latency distribution を必ず入れてください。

同期版非同期版
/health の 50%3.01秒0.0004秒
/health の 99%9.03秒0.0038秒
/thumbnails の応答3秒数ミリ秒

戻りました。 ですが、ここで喜んで終わらないでください。

仕事は1ミリも減っていない

キューの長さを見てください。

bash
$ docker exec -it asynclab-redis redis-cli llen jobs
(integer) 3180

3180件が、まだ手つかずで積まれています。 ワーカーは1件3秒なので、この行列を捌くのに2時間半かかります。

非同期にして消えたのは「待たされる人」だけです。仕事の量は1ミリも減っていません。

これがこの記事でいちばん大事な一文です。非同期は魔法ではなく、置き場所を変えただけです。積まれた仕事は、誰かが必ずやることになります。

そして、いま新しい問題が生まれました。

  • 利用者は「終わったか」を知る手段がない(202は「受け取った」としか言っていない)
  • 失敗しても、利用者に伝わらない(もうHTTPの接続は切れている)
  • 積まれ続けたら、いつまでも終わらない

順に潰します。


結果をどう返すか — 3つの方式

202 を返した瞬間、「終わったことを伝える責任」が新しく発生します。 方式は3つです。

方式どう動くか実装の手間遅延相手(受け取る側)に要る条件
ポーリング利用者側から「終わりましたか」と定期的に聞くいちばん軽い。状態を返すAPIを1本足すだけ問い合わせ間隔ぶん遅れる(3秒間隔なら最大3秒)何も要らない。HTTPが叩ければよい
Webhook / コールバック終わった側が、相手のURLを叩いて知らせる中くらい。再送・署名・失敗時の扱いが要るほぼ即時相手が公開URLを持ち、受け口を実装できること。ブラウザには無理
WebSocket / SSE繋ぎっぱなしにして、終わったら流し込む重い。接続の維持・切断・再接続・複数台のときの配り分け即時接続を張り続けられること。プロキシやモバイル回線で切れる前提が要る

選び方はこの順で考えます。

  1. 相手がブラウザで、待つのが数分以内 → ポーリング
  2. 相手が他のサーバー(機械)→ Webhook(Botの回でやったのは、まさにこの受け側です)
  3. 1秒以内に何度も更新が飛ぶ(チャット・進捗バー)→ WebSocket / SSE(WebSocketとSSEの回)

迷ったらポーリングです。 「原始的で格好悪い」と思うかもしれませんが、壊れ方がいちばん単純です。通知が1回落ちても、次の問い合わせで復旧します。Webhook は相手が落ちていたときの再送を自分で書くことになり、SSE は接続が切れたときの取りこぼしを自分で埋めることになります。

この記事ではポーリングを実装します。 さきほど GET /jobs/:id を書いたので、もう半分できています。

ポーリングを動かす

投げて、そのIDを問い合わせます。

bash
$ JOB=$(curl -s -X POST -H "Content-Type: application/json" \
    -d '{"source":"cat.png"}' http://localhost:3000/thumbnails | grep -o '"id":"[^"]*"' | cut -d'"' -f4)
$ echo $JOB
$ curl -s http://localhost:3000/jobs/$JOB
6f2b1d4c-9a35-4f77-9a4e-6a5c1c2b3d10
{"id":"6f2b1d4c-...","status":"queued","source":"cat.png","createdAt":"1758950412345"}

3秒ほど待ってもう一度叩くと、status が変わります。

bash
$ curl -s http://localhost:3000/jobs/$JOB
{"id":"6f2b1d4c-...","status":"done","result":"thumb-6f2b1d4c-....png","source":"cat.png","createdAt":"1758950412345","startedAt":"1758950412401","finishedAt":"1758950415404"}

画面側は、これを2〜3秒おきに叩いて status を見るだけです。

ポーリングで必ず入れる3つがあります。入れないと、ワーカーが死んだときにブラウザが永遠に叩き続けます。

入れるものなぜ
打ち切り(例: 60回で諦める)終わらないジョブは必ずある。無限ループを画面に置かない
間隔を伸ばす(1秒→2秒→4秒)長引くジョブほど、頻繁に聞く意味が薄い。サーバーへの問い合わせを減らす
failed という状態「終わった」と「失敗した」を区別する。次で足します

冪等にする

ここが、非同期にしたときにいちばん事故る場所です。

まず、事故を起こす

利用者は待たされるともう一度押します。それをそのまま再現します。

bash
$ curl -s -X POST -H "Content-Type: application/json" -d '{"source":"cat.png"}' http://localhost:3000/thumbnails
$ echo
$ curl -s -X POST -H "Content-Type: application/json" -d '{"source":"cat.png"}' http://localhost:3000/thumbnails
{"id":"a1b2c3d4-1111-4aaa-8bbb-000000000001","status":"queued"}
{"id":"e5f6a7b8-2222-4ccc-8ddd-000000000002","status":"queued"}

別のIDが2つできました。 ワーカー側の端末を見てください。

start a1b2c3d4-1111-4aaa-8bbb-000000000001
done  a1b2c3d4-1111-4aaa-8bbb-000000000001
start e5f6a7b8-2222-4ccc-8ddd-000000000002
done  e5f6a7b8-2222-4ccc-8ddd-000000000002

同じ画像を、2回変換しました。

これがサムネイル生成なら、CPUが無駄になっただけです。 ですが、この処理が「決済する」「メールを送る」「在庫を減らす」だったら。

二重課金です。 そして、これは「起きるかもしれない」ではありません。ボタンの二度押し・ブラウザの再読み込み・スマホの回線が切れた直後の再送・自動リトライ。 経路はいくらでもあり、利用者数が増えれば必ず起きます。

非同期にすると、この危険は上がります。 同期なら「3秒待てば結果が返る」ので、押した人は結果を見て止まります。非同期は即座に202が返るので、押した人は「効いたのか分からない」まま、もう一度押せてしまいます。

依頼IDで記録する

打つ手は1つです。

依頼する側に「この依頼の名前」を付けさせて、サーバー側でそれを記録する。同じ名前が来たら、実行せずに前の結果を返す。

この名前を冪等キー(idempotency key)と呼びます。決済サービスのAPIには、たいてい Idempotency-Key というヘッダがあります。

server.js の POST /thumbnails を差し替えます。この関数だけ全文で置き換えてください。

// 【新】冪等版。Idempotency-Key を見る
app.post('/thumbnails', async (req, res) => {
  const key = req.get('Idempotency-Key');
  const id = randomUUID();

  if (key) {
    // NX = すでにあれば書かない。書けた人だけが「初めての依頼」
    const won = await redis.set(`idem:${key}`, id, { NX: true, EX: 86400 });
    if (!won) {
      const existing = await redis.get(`idem:${key}`);
      res.set('Location', `/jobs/${existing}`);
      return res.status(200).json({ id: existing, reused: true });
    }
  }

  await redis.hSet(`job:${id}`, {
    status: 'queued',
    source: req.body.source || 'sample.png',
    createdAt: String(Date.now())
  });
  await redis.expire(`job:${id}`, 3600);
  await redis.lPush('jobs', JSON.stringify({ id }));

  res.set('Location', `/jobs/${id}`);
  res.status(202).json({ id, status: 'queued' });
});

APIを再起動して、同じキーで2回投げます。

bash
$ curl -s -X POST -H "Content-Type: application/json" \
    -H "Idempotency-Key: order-2026-0927-001" \
    -d '{"source":"cat.png"}' http://localhost:3000/thumbnails
$ echo
$ curl -s -X POST -H "Content-Type: application/json" \
    -H "Idempotency-Key: order-2026-0927-001" \
    -d '{"source":"cat.png"}' http://localhost:3000/thumbnails
{"id":"7c9d0e1f-3333-4eee-8fff-000000000003","status":"queued"}
{"id":"7c9d0e1f-3333-4eee-8fff-000000000003","reused":true}

同じIDが返り、ワーカーは1回しか動きません。

start 7c9d0e1f-3333-4eee-8fff-000000000003
done  7c9d0e1f-3333-4eee-8fff-000000000003

[スクリーンショット: 03_idempotency_reused.png] 同じ Idempotency-Key で2回投げたときの curl の結果と、ワーカー側が1回しか動いていない端末を撮ってください。2つの端末が同じ画面に入っていると分かりやすいです。

なぜ「読んでから書く」ではいけないのか

素直に書くと、こうしたくなります。

// これは間違い
const existing = await redis.get(`idem:${key}`);
if (existing) return res.status(200).json({ id: existing });
await redis.set(`idem:${key}`, id);

2回目が「1回目のsetが終わる前」に来ると、両方とも existing が空になり、両方とも通ります。 二度押しはまさにこの数ミリ秒の間に起きます。

だから SET ... NX(無ければ書く)を使います。「調べる」と「書く」が1回の操作で、途中に他人が割り込めません。 トランザクションの回で見た話と同じ性質です。DBでやるなら、依頼IDの列に一意制約(UNIQUE)を張って、2件目を弾かせます。

キーは誰が作るのか

依頼する側(クライアント)です。 サーバーが作ってしまうと、リクエストごとに違うキーになって意味がありません。

場面キーに使うもの
画面のフォームフォームを開いたときに1つ発行して、hidden に入れておく。再送されても同じ値になる
他システムからの連携相手の伝票番号・注文番号
自動リトライ1回目に使ったキーを、リトライでもそのまま使う(これが要点)

「リトライで同じキーを使う」が抜けると、冪等キーは何も守りません。 リトライのたびに新しいキーを振っていたら、それはただの別の依頼です。

有効期限を必ず付けてください。 上のコードの EX: 86400(24時間)です。付けないと、キーの記録が永久に増え続けます。

ワーカー側の二重実行は、これでは防げない

正直に書きます。いま防いだのは「同じ依頼が2回受け付けられる」ことだけです。

ワーカーが処理の途中で落ちた場合は別問題です。この記事の brPop は、取り出した瞬間にキューから消えます。 つまり、

  • 落ちたら、そのジョブは消えて誰にも実行されません(やり直しが無い)
  • 逆に、取り出したあとキューに戻す仕組みを入れると、今度は2回実行されうる

「1回だけ確実に」は、そう簡単には作れません。 本線のメッセージキューとRabbitMQで ack と再配送をやり、Kafkaとオフセットでも同じ問題を見ました。だからこそ、処理そのものを冪等に書く(同じジョブを2回やっても結果が変わらないように書く)のが、いちばん確実な守りになります。


どこまで非同期にするか

全部を非同期にしてはいけません。 判断はこの3つで決まります。

問いはいいいえ
利用者はその場で結果を待つか(次の操作にその結果が要るか)同期のまま。ログイン・検索・カートに入れる非同期の候補
失敗を後から伝えられるか(メール・通知・画面の履歴で足りるか)非同期にできる同期のまま。その場で「失敗しました」と言うしかないもの
順序が要るか(前の処理が終わってから次でないと壊れるか)非同期にするなら、順序を保つ仕組みが要る。安易にやらない非同期にしやすい

具体例に落とすとこうなります。

処理どちら理由
ログイン同期結果が出ないと次の画面に行けない
検索・一覧表示同期待っているのは結果そのもの
決済の実行同期(ただし外部への通知は非同期)「払えたか」をその場で伝えないと、利用者は買えたか分からない
確認メールの送信非同期3秒遅れても誰も困らない。むしろメールサーバーの遅さに画面を巻き込まない
画像・動画の変換非同期重い。完了は後で伝えれば足りる
帳票・CSVの生成非同期重い。ダウンロードリンクを後で出せばよい
検索インデックスの更新非同期数秒遅れて反映されても実用上困らない
在庫を減らす同期遅らせると、売り切れたものを売ってしまう

判断の軸は「重いかどうか」ではありません。 「利用者がその結果を待っているか」です。1秒で終わるメール送信でも非同期にする価値はあり、5秒かかる在庫確認でも同期のままにすべきことがあります。


非同期にすると増える仕事

正直に書きます。 非同期は、待ち時間を減らすかわりに、運用の仕事を確実に増やします。

増える仕事具体的に何をすることになるか
失敗の追跡HTTPの接続はもう切れている。失敗を誰にも伝えられない。 failed の状態を持ち、失敗理由を残し、失敗ジョブを溜める場所(デッドレター)を作り、誰かが定期的に見ることになる
順序ワーカーを2本に増やした瞬間、「AのあとにB」は保証されなくなる。同じ利用者のジョブは同じワーカーへ、といった振り分けが要る
監視見る数値が増える。キューの長さ・待ち時間・失敗率・ワーカーの生死。監視の回で入れた仕組みに、キュー長を必ず足す
デバッグログがAPIとワーカーの2箇所に割れる。「この依頼が何をしたか」を1本に繋ぐには、依頼IDを両方のログに必ず出す(分散トレーシングの回でやった考え方)
プロセスが増えるワーカーは止まっていても誰も気づきません。起動し直す仕組み(systemd や Kubernetes)が要る。「動いている」と「有効になっている」は別物でした

いちばん怖いのは4つ目です。 同期なら「押したら3秒後にエラーが出た」で終わりだったものが、「押したけど、何も起きない」になります。エラーが目に見えなくなるのが、非同期の最大の代償です。

最低限これだけはやってください。

  • 依頼IDを、APIのログにもワーカーのログにも必ず出す
  • failed の状態と、失敗理由を残す(ポーリングで返せるように)
  • キューの長さを1つ、監視に出す

バックプレッシャー — 無限に積まない

さきほど、10秒の負荷で3180件積まれました。あれを放置するとどうなるか。

Redis のメモリが尽きます。 そして Redis が死ぬと、キューに入っていた依頼が全部消えます。

「受け付けだけ返す」は、無限に受け付けてよいという意味ではありません。 積める量には上限があり、上限に達したら受け付けを止めるのが正しい設計です。これをバックプレッシャーと言います。

POST /thumbnails の先頭に、この4行を足します。

  const depth = await redis.lLen('jobs');
  if (depth >= 100) {
    res.set('Retry-After', '30');
    return res.status(429).json({ error: 'queue is full', depth });
  }

置く場所は関数のいちばん上(const key = req.get(...) の前)です。APIを再起動して、わざと溢れさせます。

bash
$ hey -z 5s -c 5 -m POST -H "Content-Type: application/json" -d '{}' http://localhost:3000/thumbnails
Status code distribution:
  [202] 104 responses
  [429] 18432 responses

100件まで受け付けて、あとは 429 で断りました。

bash
$ docker exec -it asynclab-redis redis-cli llen jobs
(integer) 100

キューは100で止まっています。

ステータス意味相手がすべきこと
429 Too Many Requestsいまは受けられないRetry-After 秒だけ待って、同じ Idempotency-Key で投げ直す
503 Service Unavailable一時的に働けない同上

断るのは、失敗ではありません。 断らずに受け続けて、あとで全部まとめて失うほうがずっと悪いのです。

  • キューが溢れると、それまでに積んだ分まで巻き添えで消えます
  • 429 は、少なくとも「受けられなかった」と相手に伝わります。黙って消えるより百倍ましです
  • 上限の数字は「捌ける速さ × 許せる待ち時間」で決めます。 1件3秒・ワーカー1本・「10分以上待たせない」なら、上限は200件です

そして、429 が出るということは、ワーカーが足りていないということです。 バックプレッシャーは症状を教えてくれる仕組みであって、治療ではありません。 治療はワーカーを増やすこと(あるいは処理を速くすること)です。


つまずいたところ

遠回りした過程を、消さずに書きます。

1. 最初、setTimeout で「重い処理」を書いたら、まったく詰まらなかった

最初に書いた重い処理は、こうでした。

app.post('/thumbnails/sync', async (req, res) => {
  await new Promise((r) => setTimeout(r, 3000));  // 3秒かかるつもり
  res.json({ done: true });
});

これで hey を流しても、/health は4ミリ秒のままでした。 「非同期にする意味が無いじゃないか」と30分ほど悩みました。

理由は、setTimeout は待っている間、CPUを1ミリも使っていないからです。Node.js は「3秒後に起こして」とOSに頼んで、その間ほかのリクエストを普通に処理します。 詰まりません。

待ち方イベントループ詰まるか
setTimeout / DBの応答待ち / 外部APIの応答待ち手放している詰まらない(同時に何百本でも待てる)
画像変換 / 圧縮 / 暗号化 / 巨大なJSONのパース握ったまま詰まる

画像変換は後者です。 だから記事の heavyWork() は while ループにしました。「重い=遅い」ではなく、「重い=CPUを使う」かどうかが分かれ目だと、ここで初めて分かりました。

ただし、setTimeout 型(=待つだけ)でも安心はできません。 外部APIが応答しないと、接続とメモリは掴んだまま溜まり続け、最終的には別の限界に当たります。それが本線のサーキットブレーカの回で見た形でした。

2. 202 を返しているのに、画面が「成功しました」と出てしまった

ポーリングを実装する前、フロント側は res.ok(200番台かどうか)だけを見ていました。202 は200番台なので、res.ok は true です。

結果、キューに積んだだけで「変換が完了しました」と表示されました。 利用者が一覧を見に行くと何もありません。

200 と 202 を区別してください。 意味がまるで違います。

ステータス意味
200 OK終わった。結果はここにある
202 Accepted受け取った。終わっていない。結果はまだ無い

3. ワーカーを止めたまま気づかず、1時間放置した

Ctrl + C でワーカーを止めたあと、APIだけ動かして実験を続けていました。APIは何事もなく 202 を返し続けます。

キューの長さを見るまで、誰も止まっていることに気づきませんでした。

bash
$ docker exec -it asynclab-redis redis-cli llen jobs

この1行が監視に無いと、非同期は静かに壊れます。 「エラーが出ない壊れ方」は、エラーが出る壊れ方よりずっと厄介です。

4. hey が command not found だった

Ubuntu のリポジトリに hey が無い環境がありました。ab に読み替えるか、公式の配布物を落とすかの二択です。この記事では準備の節に両方書きました。 道具が入らないまま先に進むと、測れないので何も確かめられません。


後片づけ

プロセスとコンテナを残さないでください。 ワーカーは黙って動き続け、Redis はメモリを掴み続けます。

1. ワーカーとAPIを止める

それぞれの端末で Ctrl + C を押します。閉じてしまった端末があるなら、確認して止めます。

bash
$ ps aux | grep -e server.js -e worker.js | grep -v grep

残っていたら、表示された2列目の数字(PID)を指定して止めます。

bash
$ kill <さっき出たPID>

kill -9 を最初に打たないでください。 ふつうの kill で止まります。

2. Redis のコンテナを消す

bash
$ docker stop asynclab-redis
$ docker rm asynclab-redis
$ docker ps -a --filter name=asynclab-redis

一覧に何も出なければ消えています。中に積んだジョブも一緒に消えますが、実験用なので構いません。

3. 実験場ごと消す(残しておいても構いません)

bash
$ rm -rf ~/asynclab

rm -rf は戻せません。 打つ前にパスをもう一度読んでください。

4. 元の環境が無事か確かめる

bash
$ docker ps
$ node -v

本線で立てたコンテナが動いていること、Node.js が消えていないことを確認して終わりです。


まとめ — 理解できたこと

  • 1つの遅い処理は、無関係なエンドポイントまで道連れにする。 /health が3秒から9秒になった。コードは1行も変えていない
  • 原因は「処理の枠が埋まる」こと。 Node.js ならイベントループ、他の言語ならスレッドやプロセスの数。言語を変えても消えない
  • これはサーキットブレーカの回と同じ構図。 打つ手は2つ。結果が要らないなら切り離す。いま要らないなら後でやる
  • 非同期にしても、仕事の総量は1ミリも減らない。 減るのは待たされる人だけ。3180件はキューに積まれたままだった
  • 202 を返した瞬間、「終わったと伝える責任」が生まれる。 返し方はポーリング / Webhook / WebSocket・SSE の3つ。迷ったらポーリング。壊れ方がいちばん単純
  • リトライがある世界では、冪等でない処理は必ず二重実行される。 依頼IDをクライアントが発行し、SET NX で1回だけ通す。「読んでから書く」では守れない
  • 有効期限を付ける。 冪等キーもジョブの記録も、放っておくと永久に増える
  • 非同期は仕事を増やす。 失敗の追跡・順序・監視・デバッグ。最大の代償は「エラーが目に見えなくなる」こと
  • 無限に積まない。 上限に達したら 429 と Retry-After で断る。断るのは失敗ではない。黙って全部失うほうが悪い
  • 何を非同期にするかは、重さでは決まらない。 利用者がその結果を待っているかで決まる

参考リンク


次に読む

この記事は 【深掘り】システム設計 の 7 / 17 本目です。

記事
← 前の記事CDNとエッジキャッシュ — 距離は速度で解決できない
→ 次の記事メッセージキューの型 — 急ぎの仕事が後ろで待つ

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

System Design›System Design — Asynchronism
  • 202 Accepted とワーカー
  • 冪等性・バックプレッシャー・結果の返し方

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次