# offset ページングで外部APIを読むと、取得中に中身が変わって静かに壊れる ## 誰向けか サーバーレスのゲートウェイ（GAS Web App / Cloud Functions / Workers など）を挟んで 外部APIの長い応答を読んでいる人。とくに「応答が長すぎて切れるので offset で継ぎ足している」人。 ## 症状 - 普段は動くのに、**たまに** `JSON.parse` が落ちる。再実行すると直る。 - 落ちた時のエラーは「JSON にならない（<長い数字>字）」のように、**応答そのものは取れているように見える**。 - 夜間バッチなど無人の時間帯に偏って起きる（人が見ていない間にデータが動くから）。 - 最悪の場合は例外すら出ず、**中身だけ別物の妥当な JSON** が返る。 ## 原因 ゲートウェイ側がこう書かれていると起きる。 ```js function proxyGet(path, offset) { var res = UrlFetchApp.fetch(API_BASE + path, { headers: { token: TOKEN } }); var full = res.getContentText(); // ← 呼ばれるたびに全文を取り直している var LIMIT = 45000; var off = Number(offset) || 0; var chunk = full.substring(off, off + LIMIT); return { rawLength : full.length, offset : off, nextOffset: (off + chunk.length < full.length) ? (off + chunk.length) : null, raw : chunk }; } ``` **スナップショットを保持していない。** offset ごとに毎回、外部APIを叩き直して切っている。 呼び出し側が素直に継ぎ足すと、こうなる。 ```js // これが壊れる書き方 let raw = '', offset = 0; for (let i = 0; i < 40; i++) { const r = await proxy('get', { path, offset }); raw += r.raw || ''; if (r.nextOffset == null) break; offset = r.nextOffset; } return JSON.parse(raw); // ← ときどき落ちる ``` チャンク1本が数万字だと1呼び出しに十数秒かかる。3チャンクで**約1分**。 その1分の間に元データが1件増える／減る／変わると、**本文の長さが変わる**。 すると chunk0 は古い本文から、chunk1 以降は新しい本文から、それぞれ**固定 offset で**切られる。 連結した文字列はどちらの本文でもない。 ## 直し方（呼び出し側だけで完結する。ゲートウェイの再デプロイは不要） ゲートウェイが `rawLength`（＝その時の全文の長さ）を返しているなら、それが鍵になる。 返していないなら、まずそれだけ足す。 ```js export async function getJsonPaged(pathAndQuery, deps = {}) { const call = deps.call ?? proxy; const sleep = deps.sleep ?? (ms => new Promise(r => setTimeout(r, ms))); const history = []; let lastRaw = ''; for (let attempt = 1; attempt <= 3; attempt++) { let raw = '', offset = 0, expected = null, consistent = true; for (let i = 0; i < 40; i++) { const r = await call('get', { path: pathAndQuery, offset }); // ① 一貫性検査: 途中で全文の長さが変わったら、その試行は捨てる if (r.rawLength != null) { if (expected === null) expected = r.rawLength; else if (r.rawLength !== expected) { consistent = false; break; } } raw += r.raw || ''; if (r.nextOffset == null) break; offset = r.nextOffset; } history.push(expected); lastRaw = raw; // ② 連結長の検算 const lengthOk = (expected === null) || (raw.length === expected); if (consistent && lengthOk) { try { return JSON.parse(raw); } catch { /* ③ へ */ } } // ③ 丸ごと取り直す（部分的な継ぎ足し修復はしない） if (attempt < 3) await sleep(attempt === 1 ? 1000 : 2000); } throw new Error( `ページング取得に失敗（${lastRaw.length}字・3回試行・長さ履歴 [${history.join(', ')}]）` + lastRaw.slice(0, 200) ); } ``` ### 設計上の要点 - **部分的に直そうとしない。** 本文の途中がどう変わったかは分からないので、offset 0 から丸ごと取り直す。 - **`rawLength` が無い応答では検査をスキップして従来どおり動かす。** 古いゲートウェイと共存できる。 - **例外メッセージの前半は変えない。** ログや監視が grep している可能性がある。診断情報は後ろに足す。 - **`deps` で依存を注入できるようにする。** これが無いとテストが書けない（後述）。 - 既存の呼び出し側は引数を増やさずにそのまま動くようにする。 ## テストの落とし穴（ここで2回失敗した） ### 落とし穴1: モックが「フラグ」だけ変えて、本文を変えていない `rawLength` の値だけずらし、返す文字列は同じものから切っていると、 **ガードを全部外しても テストが通る**。腐敗が再現できていないから。 必ず **2つの別の本文**を用意し、チャンクの途中で切り替える。 ### 落とし穴2: 新旧の本文の「先頭が共通」だと腐敗しない 件数を1件足しただけの本文は、前半が元の本文と**バイト単位で一致**する。 最初のチャンクが共通部分に収まると、連結結果が偶然そのまま正しい JSON になる。 先頭から違う本文にする（配列の先頭要素を変える、など）。 ### 落とし穴3: `try` の中で `assert` を書く ```js // これは何が起きても通る try { const result = await naive(...); assert.notDeepEqual(result, expected); // これが投げる AssertionError も } catch { assert.ok(true, '期待どおり例外が出た'); // ここが飲み込む } ``` 判定は **catch の外**でやる。 ```js let threw = false, result; try { result = await naive(...); } catch { threw = true; } assert.ok(threw || !isDeepStrictEqual(result, expected), '...'); ``` ### 必ずやること: 対照群 テストを書いたら、**ガードをコメントアウトして落ちることを確認する**。 落ちなければ、それはテストではなく飾り。 このとき**潰し方も検める**。`consistent = false;` の行だけ消しても直後の `break;` が残っていれば ガードは半分生きている。無効化したつもりの行が本当に効いていたか、必ず現物を見る。 ## 残る限界（正直に書いておく） 新旧の本文が **同じ長さ** で中身だけ変わる場合、上の2つの検査は素通りする。 混ざった結果が構文として妥当な JSON になり、例外も出さずに誤った値が返る。 - 実害が出るか: レコードの増減は長さが変わるので捕まる。長さ中立の変化は タイムスタンプの更新程度なので、多くの用途では影響しない。 - 塞ぐなら: チャンク境界を数十字だけ**重ねて**取得し、重なり部分が一致するか突き合わせる。 追加のAPI呼び出しは発生しない（各チャンクを少し多めに取るだけ）。 直さないと決めたなら、テストを消さずに `{ todo: '理由' }` を付けて残す。 多くのテストランナーは todo の失敗をスイートの失敗に数えないので、 **証拠を残したまま**先へ進める。消すと次の担当者が同じ穴を踏む。 ## 効く範囲を先に数える このバグは「1つのツールの不具合」に見えるが、**ページング関数を使っている全箇所**に効いている。 直す前に `grep` で呼び出し側を数え、その一覧を報告に入れること。 1箇所で再現したから1箇所の問題、とは限らない。 ## 再発を防ぐ運用 - 「いま実行したら動いた」を根拠に直ったと判断しない。**競合状態は普段は動く。** - 無人ジョブが失敗した時の子プロセスの `stderr` を捨てない。 `stdio: 'inherit'` にすると `error.stderr` が空になり、失敗理由が汎用文言に潰れる。 `['ignore','pipe','pipe']` で受けて、**追記ログ**へ落とす（上書き形式の状態ファイルは次の実行で消える）。 - 再試行の上限を「成功回数」で数えない。「走ったが成果物が出ない」試行が数えられないと、 上限が効かずに無人で回り続ける。 ---