# ビルド成功後もHTTP 500で応答するOpenNextのWorkerをCIで検出する

## サマリ

- Next.js 16.4を@opennextjs/cloudflare 1.20.11までの1.20系でビルドすると、ビルドは成功するのに、Workerはリクエストにステータス500で応答する。
  - ログには`Unexpected loadManifest(/.next/server/preview-props.json) call!`が出力される。
  - 同じアプリを`next start`で起動するとステータス200で応答するので、Node.jsで実行する確認では検出できない。
- 原因はNext.js 16.4がサーバーの初期化で必ず読み込むようになった`preview-props.json`を、アダプタがWorkerにインライン化していなかったことにある。
  - 初期化で失敗するため、プリレンダリング済みのページも500になる。
  - ファイル自体は成果物に存在し、インライン化の対象を選択するパターンに一致しなかった。
- アダプタを1.20.12以降に、Wranglerを4.148.0以降の4.xに更新すると500は解消する。
  - 1.20.12がWranglerに4.148.0以降を要求するので、両方を1つの変更で更新する。
  - Next.jsを16.3系に固定する回避は、セキュリティ更新を適用できないので採用しない。
- CIでビルドの成果物を本番と同じ種類のランタイム（workerd）で起動し、動的なルートの応答が200かを確認すると、この種類の500をデプロイ前に検出できる。

## 前提となるOpenNextの仕組み

### マニフェストのビルド時のインライン化

Next.jsはルートの一覧やプリレンダリングの情報を、`.next`の下のJSONファイル（マニフェスト）に保存する。
サーバーはこれを`loadManifest`という関数で読み込む。
Node.jsで実行するときは、この関数がファイルシステムから読み込む。
OpenNextの [Cloudflare向けアダプタ](https://opennext.js.org/cloudflare)（@opennextjs/cloudflare）でビルドするときは、アダプタがこの関数を置換する。
対象は`.next`からファイル名のパターン（glob）で収集したマニフェストである。
置換後の関数には各マニフェストのJSONがコード中の値として記述され、実行時にはファイルを参照せずにその値が返却される。
インライン化されていないパスでは [例外を送出する](https://github.com/opennextjs/opennextjs-cloudflare/blob/%40opennextjs/cloudflare%401.20.2/packages/cloudflare/src/cli/build/patches/plugins/load-manifest.ts)。
Next.jsが欠落を許容する一部のマニフェストは例外の対象外で、空のオブジェクトが返却される。

### workerdとwrangler dev

[workerd](https://github.com/cloudflare/workerd) はCloudflare Workersのランタイムのオープンソース版である。
[`wrangler dev`](https://developers.cloudflare.com/workers/local-development/) は、Workerをworkerdで開発者のマシンやCIのランナー上で起動する。
`opennextjs-cloudflare preview`も [内部で`wrangler dev`を使用する](https://github.com/opennextjs/opennextjs-cloudflare/blob/%40opennextjs/cloudflare%401.20.12/packages/cloudflare/src/cli/commands/preview.ts)。
ビルドの成果物（`.open-next/worker.js`）をこれで起動すると、Node.jsではなく本番と同じランタイムでリクエストを処理できる。

## ビルドが成功してもWorkerだけがステータス500で応答する

自社ではNext.jsを16.4.1に更新したとき、アダプタは1.20.2のままだった。
CIの`next build`と`opennextjs-cloudflare build`は成功し、デプロイ後のWorkerは全リクエストにステータス500で応答した。

### 最小のアプリでのHTTP 500の再現

最小のApp Routerのアプリで、この組み合わせを再現した。
アプリはプリレンダリングするページ`/`と、リクエストごとに処理するRoute Handler `/api/hello`（`force-dynamic`）で構成した。
結果は次のとおり。

| アダプタ | `next start`の`/api/hello` | Workerの`/api/hello` | Workerの`/` |
| ---: | ---: | ---: | ---: |
| 1.20.2 | 200 | 500 | 500 |
| 1.20.12 | — | 200 | 200 |

Wranglerは4.148.0に固定し、アダプタの版だけを1.20.2と1.20.12で変更した。
1.20.2ではWorkerのログに次のスタックトレースが出力される。

```text
Error: Unexpected loadManifest(/.next/server/preview-props.json) call!
    at loadManifest (.open-next/server-functions/default/handler.mjs)
    at NextNodeServer.getPreviewProps (.open-next/server-functions/default/handler.mjs)
    at new Server (.open-next/server-functions/default/handler.mjs)
    at new NextNodeServer (.open-next/server-functions/default/handler.mjs)
```

`new NextNodeServer`の中で例外が発生しているので、ルートの処理の前の、サーバーの初期化で失敗している。
プリレンダリング済みの`/`も500になるのは、OpenNextではこのページもWorkerのサーバー処理を経由して返却されるからである。

### この記事の障害かを判別する

Next.js 16.4とアダプタ1.20.11までの1.20系の組み合わせで上のメッセージが出力されていれば、この記事の障害に該当する。

メッセージのパスが別のファイルでも、同種の障害の可能性がある。
[Next.js 16.2では`prefetch-hints.json`のパスで同じ例外が報告された](https://github.com/opennextjs/opennextjs-cloudflare/issues/1157)。

## preview-props.jsonがインライン化の対象のglobに一致しない

draft mode（CMSの下書きを公開前に表示する機能）の鍵をpreview propsと呼ぶ。
[Next.js 16.4はこれを`prerender-manifest.json`から`.next/server/preview-props.json`に分離した](https://github.com/opennextjs/opennextjs-cloudflare/issues/1355)。
このファイルは [サーバーの初期化時に必ず読み込まれる](https://github.com/vercel/next.js/blob/v16.4.1/packages/next/src/server/next-server.ts#L2069-L2080)。
1.20.2のアダプタがインライン化の対象を選択するglobは次のとおりで、`preview-props.json`は名前の末尾が`-manifest`でないため一致しない。
[1.20.0](https://github.com/opennextjs/opennextjs-cloudflare/blob/%40opennextjs/cloudflare%401.20.0/packages/cloudflare/src/cli/build/patches/plugins/load-manifest.ts) から [1.20.11](https://github.com/opennextjs/opennextjs-cloudflare/blob/%40opennextjs/cloudflare%401.20.11/packages/cloudflare/src/cli/build/patches/plugins/load-manifest.ts) までの各版のglobも同じである。

```ts
const manifests = await glob(
  join(dotNextDir, "**/{*-manifest,required-server-files,prefetch-hints}.json"),
  { windowsPathsNoEscape: true }
);
```

ビルドの時点では一致しないファイルは単に対象外になるだけなので、ビルドは成功する。

```mermaid
sequenceDiagram
  participant B as opennextjs-cloudflare build
  participant W as Worker（workerd）
  participant N as NextNodeServerの初期化
  B->>B: .nextからマニフェストをglobで収集し、loadManifestにインライン化する
  alt アダプタ1.20.11まで
    Note over B: preview-props.jsonはglobに一致せず、インライン化されない
    W->>N: 最初のリクエストでサーバーを生成する
    N->>N: loadManifest(server/preview-props.json)
    N-->>W: Unexpected loadManifestの例外
    W-->>W: 500（プリレンダリング済みのページも）
  else アダプタ1.20.12以降
    Note over B: preview-props.jsonもインライン化する
    W->>N: 最初のリクエストでサーバーを生成する
    N->>N: インライン化したpreview-props.jsonの中身を返却する
    N-->>W: ルートの処理を開始する
  end
```

## アダプタを1.20.12以降に更新する

修正は [1.20.12](https://github.com/opennextjs/opennextjs-cloudflare/releases/tag/%40opennextjs/cloudflare%401.20.12) で導入された。
[修正](https://github.com/opennextjs/opennextjs-cloudflare/pull/1356) はglobに`server/preview-props.json`を追加するものである。

更新の前に、peerDependencies（同時に導入する必要のあるパッケージと、バージョンの範囲）を確認する。

```bash
npm view @opennextjs/cloudflare@1.20.12 peerDependencies
# { next: '>=15.5.28 <16 || >=16.4.1', wrangler: '^4.148.0', 'rclone.js': '^0.6.6' }
```

1.20.12は [`wrangler: '^4.148.0'`を要求する](https://www.npmjs.com/package/@opennextjs/cloudflare/v/1.20.12?activeTab=code)。
1.20.2の要求は`^4.86.0`だったので、Wranglerも4.148.0以降の4.xに更新する。
peerDependenciesの不一致は、インストールやビルドの失敗として顕在化するとは限らない。
Next.jsのminorを更新するときは、アダプタとWranglerも1つの変更で更新し、peerDependenciesの範囲と整合させる。

### HTTP 500の対処として採用しなかった案

- Next.jsを16.3系に固定する案は採用しなかった。
  - アダプタの修正が公開されるまでの回避にはなる。
  - 1.20.12は [Next.js 16.4.1のセキュリティ更新にも追従している](https://github.com/opennextjs/opennextjs-cloudflare/releases/tag/%40opennextjs/cloudflare%401.20.12)。
  - 16.3系に固定している間は、この更新を適用できない。
- `preview-props.json`に空のオブジェクトを返却するパッチも採用しなかった。
  - このファイルはdraft modeの鍵を格納している。
  - [修正のPR](https://github.com/opennextjs/opennextjs-cloudflare/pull/1356) も読み込まれなくてもよいマニフェスト向けの空のオブジェクトを返却する方法を採用せず、`preview-props.json`の鍵をインライン化している。

## CIでビルドの成果物をworkerdで起動する

Next.jsのminorの更新では、アダプタが対応するまでの間、この記事と同種の例外でWorkerがステータス500で応答する可能性がある。
そこで、CIで`opennextjs-cloudflare build`の後に、成果物を`wrangler dev`で起動して数本のURLにリクエストするスモークテストを追加した。

### リクエストするURLとスクリプト

リクエストするURLにはデータベースや認証に依存せず常にステータス200で応答する動的なルートを選択する。
既存のルートに該当するものが無い場合、次のRoute Handlerが最小の例である。

```ts
// app/api/hello/route.ts
export const dynamic = "force-dynamic";
export function GET() {
  return Response.json({ ok: true });
}
```

次のスクリプトはWorkerが起動するまで最大60秒待機する。
その後、動的なルートとプリレンダリング済みのページの応答が200かを確認する。
`wrangler.jsonc`の`main`が`.open-next/worker.js`を指していることを前提にしている。
wranglerと子プロセスのworkerdを1つのプロセスグループとして停止するため、`setsid`を利用する。
このため、`setsid`を利用できるLinuxのランナー（GitHub Actionsの`ubuntu-latest`など）で実行する。

```bash
#!/usr/bin/env bash
# usage: smoke.sh <port>  opennextjs-cloudflare build の後に実行する
set -euo pipefail
port="$1"
log="$(mktemp)"
# wrangler と子プロセスの workerd をまとめて止めるため、別のプロセスグループで起動する
setsid npx wrangler dev --ip 127.0.0.1 --port "$port" >"$log" 2>&1 &
pid=$!
trap 'kill -- -"$pid" 2>/dev/null || true; wait "$pid" 2>/dev/null || true' EXIT

for _ in $(seq 60); do
  grep -q "Ready on" "$log" && break
  kill -0 "$pid" 2>/dev/null || { cat "$log"; exit 1; }
  sleep 1
done
grep -q "Ready on" "$log" || { echo "not ready within 60s"; cat "$log"; exit 1; }

for path in /api/hello /; do
  status="$(curl -sS --max-time 10 -o /dev/null -w '%{http_code}' "http://127.0.0.1:${port}${path}" || true)"
  if [[ "$status" != 200 ]]; then
    echo "FAIL ${path} (${status})"
    tail -n 40 "$log"
    exit 1
  fi
  echo "OK ${path}"
done
```

アダプタが1.20.2の成果物では、`/api/hello`で500を受信して終了コード1で終了し、ログに`Unexpected loadManifest`が出力される。
1.20.12と1.20.13の成果物では両方が200で、終了コードは0になる。

### スモークテストのCIへの配置とデータベースなどへの接続先

GitHub Actionsでは、ビルドの後のステップに配置する。

```yaml
- name: Build Cloudflare Worker
  run: npx opennextjs-cloudflare build
- name: Smoke test Cloudflare Worker
  run: ./scripts/smoke.sh 8787
```

静的なアセットはWorkerのサーバー処理を経由せずに配信される場合がある。
このため、スモークテストのリクエスト先には動的なルートを含める。

[`wrangler dev`は、WorkerからデータベースのD1やオブジェクトストレージのR2を利用するための設定（binding）をデフォルトでローカルのシミュレーターに接続する](https://developers.cloudflare.com/workers/local-development/)。
`wrangler.jsonc`でbindingに`remote: true`を指定した設定では、接続先はデプロイ済みのリソースとなる。
CIではその指定を削除した一時的な設定ファイルを作成し、スクリプトの`wrangler dev`の行に`-c <設定ファイル>`を追加する。

データベースを参照するAPIにもリクエストするなら、起動の前にローカルのD1へマイグレーションを適用する。
コマンドは`wrangler d1 migrations apply <database> --local -c <設定ファイル>`である。

このスモークテストで分かるのはビルドの成果物がCIのランナー上のworkerdで起動し、リクエストを処理できることまでである。
本番のsecretの設定、本番のD1やR2に保存されたデータ、Cloudflare Accessの設定に起因する失敗は検出できない。
