# デプロイ更新の「狭間」が本番データを壊す — 新旧の版が同時に動く前提で冪等性を設計する ## 誰向けか サーバレス関数や Google Apps Script の Web App のように、**「コードを push する」と 「公開されている版を切り替える」が別操作**になっている実行環境で、 その API を自動化から叩いている人。 一般に語られるのは「push しただけでは反映されない」という話までだが、 本当に痛いのは**切替の最中に新旧の版が混ざり、その混在が移行ロジック経由でデータを壊す**ことである。 この文書はその型と、設計・切り分け・検証の3点をまとめる。 --- ## 症状（実際に起きた並び） ある Web App に、シート状のデータストアを読み書きする API を実装した。 レイアウトは `1行目=サマリ / 2行目=ヘッダー / 3行目以降=データ` とし、 コードには**旧レイアウトからの移行処理**が入っていた: ``` if (1行目 が ヘッダーと一致) { 1行目の前に1行挿入する // ヘッダーを2行目へ落とす } if (2行目 が ヘッダーでない) { 2行目にヘッダーを書く } ``` この移行処理は「1行目にヘッダーがある旧レイアウト」を想定していて、単体では正しく見える。 1. 公開中のデプロイが**旧い版に固定**されていることに気付き、既存デプロイを上書きして最新版へ更新した 2. **その直後**、同じ一連の呼び出しの中で - action A（新機能）→ 成功 - action B（新機能）→ 成功 - action C（新機能）→ **`unknown_kind` 相当のエラー**（＝旧版の応答） 3. 数分後、同じ payload で action C を再実行 → **成功** 4. データを読み戻すと **ヘッダー行が2行目と3行目に二重化**しており、 3行目（データ1行目のはず）が潰れていた ## 何が起きていたか **デプロイの切替は即時でも原子的でもない。** 切替直後の一定時間、 リクエストごとに新旧どちらの版に当たるかが揺れる。そのため: 1. **旧版**に当たった書き込みが、**旧レイアウト（1行目=ヘッダー）**でデータを書き戻した 2. その直後、**新版**に当たった別の書き込みが「1行目がヘッダーだ」と検知し、 移行処理の**無条件の行挿入**を実行した 3. 挿入先の2行目には**すでに正しいヘッダーがあった**ため、 それが3行目へ押し出され、**ヘッダー行が2本になった** 「action C だけ落ちる」も「ヘッダーが二重」も、**どちらも同じ原因（版の混在）**だった。 コードのバグに見えるが、コードは単独では正しい。壊れたのは**版が2つ同時に動いた**からである。 さらに悪いのは、この移行処理が**定期トリガーからも同じ経路を通る**設計だったこと。 放置すれば同じ条件が揃うたびに再発する。 --- ## 対策1: 冪等性の定義を広げる 多くの人が書く冪等性のテストは「**同じ関数を2回呼んでも同じ結果**」である。これでは足りない。 必要なのは「**新旧の版が同時に動いても収束する**」ことだ。 移行ロジックの鉄則: > **移行先が既に正しい状態かを確認してから動かす。** > 「旧形式を見つけたら無条件に変換する」は、新旧が混ざった瞬間にデータを壊す。 先の例なら、判定を次のように分ける: | 1行目 | 2行目 | 正しい振る舞い | |---|---|---| | 空 | ヘッダー | **何もしない**（既に正しい） | | ヘッダー | データ | 行を挿入して移行する（本来の旧レイアウト） | | ヘッダー | ヘッダー | **挿入せず、1行目を消すだけ**（混在で生じた状態） | | 空 | ヘッダー | 3行目にもヘッダーがあれば**その重複行を削除する** | | サマリ文字列 | ヘッダー | **何もしない**（正常運用中） | | 空 | 空 | ヘッダーを2行目に書く（初期化） | 実装のコツは、**判定を純粋関数に切り出す**こと。 「現在の1行目・2行目・3行目の内容」を入力に取り、「挿入する/消す/何もしない」という **計画（plan）だけを返す**関数にすれば、実際のストレージに接続せずに全状態をテストできる。 上の表がそのままテストケースになる。 ## 対策2: 壊れた本番データを直す関数を用意する 冪等化しても**すでに壊れているデータは直らない**。修復関数を必ず併せて作る: - ヘッダーと**完全一致する行**を、正しい位置以外から削除する - **データ行は絶対に削除しない**（消してよいのは「ヘッダーと完全一致」だけ） - 戻り値に**修復後の実際のレイアウトと削除件数**を返す（後述の read-back verify に使う） - 自動化から叩けるところに登録する（人が管理画面を開かなくても直せるように） ## 対策3: 切替直後は本番データを触らない 運用手順として次を守る: 1. デプロイを更新したら**数分置く** 2. まず**読み取り専用の action**（疎通確認・一覧取得）を叩いて、新版が返ることを確認する 3. その後で書き込み系を試す 4. **切替直後に一部の action だけ失敗しても、すぐコードのバグと断定しない。** 同じ payload を数分後に再実行して切り分ける この手順を踏むだけで、今回の「存在しないバグを追いかける」時間はゼロになる。 実際、`unknown_kind` は**バグではなかった**（数分後に同じ payload で成功した）。 --- ## 併せて踏みやすい2つの罠 ### 罠1: 公開されているのは「デプロイされた版」であってコードの最新ではない `push` 相当の操作でコードを送っても、公開エンドポイントの挙動は**デプロイ時に固定された版のまま**。 症状が独特で、**古い action は動き、新しく足した action だけが失敗する**。 コードを読むと確かに新 action があるので「コードはあるのに動かない」と原因を取り違えやすい。 - **確認**: デプロイ一覧を出すと版番号が見える。`@1` のまま新機能を足していたらこれが原因 - **直し方**: **既存のデプロイを上書き**する。新規デプロイを作ると URL が変わり、 設定ファイルや配布済みの参照を全部貼り替えることになる。 「URL を変えない」を最優先にする（一度配ったものを貼り替えさせない） ### 罠2: `curl` でリダイレクトを追う POST は、書き方次第で本文が落ちる この種の Web App は `POST /exec` → 302 → 別ホストへ、という流れになるためリダイレクト追従が必須。 ところが: | 書き方 | 結果 | |---|---| | `curl -L -X POST -d …` | **411 Length Required**（`-X` がリダイレクト先にも POST を強制し本文が付かない） | | `curl -L --post301 --post302 --post303 …` | **HTML ページが返る**（同じ理由） | | `curl -L -H 'Content-Type: application/json' --data-binary @file …` | **成功** | **`-X POST` を書かない**のが正解。`-d` / `--data-binary` を渡せば curl は自動で POST にし、 302 では正しく GET に切り替える。 GET は通るのに POST だけ落ちる、という**部分的な失敗が切り分けの手がかり**になる。 「認証が悪い」「トークンが違う」と疑って時間を溶かしやすいので、まずここを確認する。 --- ## 検証の型（これが本題かもしれない） 今回の一連は、すべて**「成功したという報告を信じたこと」**が遠回りの原因だった。 - 自動化ツールは `exit 0` を返しながら**1行も変更していない**ことがある - API は `{"ok":true}` を返しながら**壊れたレイアウトに書き込んでいる**ことがある だから完了判定は必ず**実データの読み戻し**で行う: 1. 書き込み API を叩く 2. **別経路**（一覧取得 API、あるいはストレージを直接読む手段）で**実際の中身を読む** 3. 期待した位置に期待した値があるかを見る（行番号・列名まで） 4. 全 action を1つずつ叩く。**疎通確認 action だけ通って満足しない** （今回まさに「疎通確認は通るのに新 action は旧版」だった） 排他制御のような仕組みも、**同じ操作を2回叩いて2回目が正しく失敗するか**まで確認する。 1回成功したことは、排他が効いている証拠にはならない。 --- ## チェックリスト - [ ] 公開エンドポイントの**版番号**を確認したか（コードの最新と一致しているか） - [ ] デプロイ更新は**既存デプロイの上書き**か（URL を変えていないか） - [ ] 移行ロジックは**移行先が既に正しいかを確認**してから動くか - [ ] 冪等性のテストに**「新旧の版が混ざった状態」**が含まれているか - [ ] 判定を**純粋関数**に切り出して全状態をテストできるか - [ ] **壊れた既存データを直す修復関数**があり、自動化から叩けるか - [ ] 修復関数は**データ行を消さない**ことをテストで保証しているか - [ ] デプロイ直後は**読み取りで新版を確認 → 数分置く → 書き込み**の順を守っているか - [ ] 完了判定を**実データの読み戻し**で行っているか（`ok` / `exit 0` を信じていないか） - [ ] **全 action** を1つずつ叩いたか（疎通確認だけで済ませていないか） ---