fix(engine): 回應太大就說「回應太大」——不再冒充「請求失敗」（Arcrun#92）

真因：零件（main.go）給 host function 的接收緩衝區是固定大小（http_request 64KB、 claude_api 1MB）。回應超過這個大小時，wasi-shim 的 writeOut 照寫不誤： new Uint8Array(buf, outPtr, data.length).set(data) data 比零件的 outBuf 大 → 覆寫零件堆積體，零件接著 outBuf[:outLen] 切片 panic；或 writeOut 撞 memory 邊界丟例外 → 回 1 → 零件印一句 "HTTP request failed"。使用者照那句去查連線／URL／防火牆，方向全錯。修法（容量握手，不改 host function 簽名、向後相容）： - 零件呼叫前把 outBuf 長度預先寫進 *outLenPtr（宣告容量） - host 在寫回前讀這個值當上限；塞不下就**不寫**（不再覆寫零件記憶體），回新的 HOST_TOO_LARGE=3 - http_request host fn 收到 3 → 改寫一段講真話的 error envelope（實際大小＋上限＋「不是連線失敗」＋分頁/篩選的具體做法＋機器可讀 code/actual_bytes/limit_bytes），沿用既有 parsed["error"] 判定鏈原樣送到使用者面前 - 舊零件沒宣告容量（讀到 0）→ 維持舊行為。不可硬套 64KB 預設：各零件緩衝區大小不同，硬套會把原本正常的大回應誤判成「太大」，那只是換一種說謊同一條路徑上另一個「訊息與真因脫節」一併修：component-loader 的 makeHttpRunner `try res.json() catch res.text()`，在零件回非 JSON 時 body 已被消費 → 丟 "Body has already been used"，與真因無關（同檔 readBodyOnce 的註解早就寫明這個坑）。改成只讀一次。驗證狀態（誠實標示，mindset §7）： - 通：5 顆零件 tinygo build 全過，wasm 已重編進 .component-builds/ （claude_api 依 .gitignore 慣例不入庫，由部署端重編） - 未跑：runtime 驗證。本 session 的權限層擋掉 node/vitest/wasmtime， before/after 實測輸出待人跑 scripts/repro-oversize-response.mjs - 未做：.worker-builds/ 重編（需 node scripts/build-worker-artifacts.mjs），否則修法不會進 self-hosted 安裝路徑（Arcrun#93 同款陷阱） Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-12 16:49:22 +08:00
parent a24f2912eb
commit 8e9bd09072
14 changed files with 389 additions and 40 deletions
@@ -273,8 +273,13 @@ function makeHttpRunner(url: string): ComponentRunner {
      const text = await res.text();
      return { success: false, status: res.status, error: text.slice(0, 200) };
    }
-    try { return await res.json(); }
-    catch { return { success: true, data: await res.text() }; }
+    // 只讀一次 body（同檔 readBodyOnce 的註解已寫明這個坑，這裡以前卻正好踩到）：
+    // 舊寫法 `try { res.json() } catch { res.text() }` 在零件回非 JSON 時，
+    // res.json() 失敗當下 body 已被消費 → 第二次讀丟 "Body has already been used"，
+    // 使用者看到的是這句跟真因（零件回了非 JSON）完全無關的訊息（Arcrun#92 同類）。
+    const text = await res.text();
+    try { return JSON.parse(text); }
+    catch { return { success: true, data: text }; }
  };
 }

@@ -27,6 +27,21 @@ export interface ArcrunHostEnv {
 const WASI_ESUCCESS = 0;
 const WASI_ENOSYS = 76;

+// ── host function 回傳碼（u6u.*）─────────────────────────────────────────────
+// 零件（main.go）用同一組數字判斷，改這裡要同步改 registry/components/*/main.go。
+export const HOST_OK = 0;
+/** host 端出錯（memory 不可用 / 例外）— 零件無從得知細節 */
+export const HOST_ERROR = 1;
+/** 查無此 key / ref（kv_get、secret_get 用） */
+export const HOST_NOT_FOUND = 2;
+/**
+ * Arcrun#92：資料塞不進零件宣告的接收緩衝區（**不是**連線失敗、**不是**對方報錯）。
+ * 舊行為是「照寫下去」——data 比零件的 outBuf 大時會覆寫零件堆積體，零件接著用
+ * `outBuf[:outLen]` 切片會 panic，或 writeOut 撞到 memory 邊界丟例外 → 回 1 →
+ * 零件印一句與真因無關的 "HTTP request failed"。使用者照那句去查連線，方向全錯。
+ */
+export const HOST_TOO_LARGE = 3;
+
 // fd 常數
 const FD_STDIN = 0;
 const FD_STDOUT = 1;
@@ -75,6 +90,51 @@ export interface WasiHostFunctions {
  crypto_sign_rs256?: (data: Uint8Array, pkcs8: Uint8Array) => Promise<Uint8Array>;
 }

+/**
+ * 容量握手的判定規則（Arcrun#92）：資料塞不塞得進零件宣告的緩衝區？
+ * declaredCapacity === 0 ⇒ 舊零件沒宣告容量，host 無從得知上限 → 維持舊行為照寫，
+ * 不可自作聰明套一個預設值（各零件緩衝區大小不同：http_request 64KB、claude_api 1MB，
+ * 硬套會把原本正常的大回應誤判成「太大」——那是換一種說謊）。
+ */
+export function outFitsCapacity(declaredCapacity: number, dataLength: number): boolean {
+  return declaredCapacity === 0 || dataLength <= declaredCapacity;
+}
+
+/** 位元組數轉人看得懂的單位（訊息裡要出現真實數字，不能只說「太大」） */
+export function formatBytes(n: number): string {
+  if (n >= 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  if (n >= 1024) return `${Math.round(n / 1024)} KB`;
+  return `${n} bytes`;
+}
+
+/**
+ * Arcrun#92：「回應太大」的 error envelope。
+ *
+ * 寫法上的三個要求（票上的紅線：不准換一句含糊的萬用句）：
+ *   1. 講**發生什麼**：多大、上限多少（真實數字，不是「太大」兩個字）
+ *   2. 講**不是什麼**：不是連線失敗、資料也沒被偷偷截半——避免使用者往錯方向查
+ *   3. 講**怎麼辦**：縮小回應的具體手段
+ * 另附機器可讀欄位（code / actual_bytes / limit_bytes），讓上層能判斷而不必比對字串。
+ *
+ * status 用 0 而不是 413：對方伺服器並沒有回 413，寫 413 等於偽造一個上游狀態碼
+ * （與 fetch 失敗的 envelope 同慣例，0 = 根本沒拿到 HTTP 狀態）。
+ */
+export function oversizeResponseEnvelope(actualBytes: number, limitBytes: number) {
+  return {
+    error:
+      `回應太大，裝不下：對方回了 ${formatBytes(actualBytes)}，` +
+      `超過這個零件單次能接收的 ${formatBytes(limitBytes)} 上限。` +
+      `這不是連線失敗，資料也沒有被截掉一半——是整包放不進零件。` +
+      `做法：用來源 API 的分頁或篩選參數（例如 limit / page / per_page / fields）把回應縮小再重試；` +
+      `真的需要整包資料時，改成分頁多抓幾次、每次處理一批。`,
+    code: 'response_too_large',
+    actual_bytes: actualBytes,
+    limit_bytes: limitBytes,
+    status: 0,
+    body: '',
+  };
+}
+
 /**
 * 建立 WASI shim 實例
 * @param stdinData - 要寫入 stdin 的 UTF-8 字串（通常是 JSON.stringify(input)）
@@ -95,14 +155,34 @@ export function createWasiShim(stdinData: string, hostFunctions?: WasiHostFuncti
  }

  // 寫入結果到 WASM 的 outPtr buffer（host function 共用）
-  // 回傳 0 = 成功，1 = memory 不可用
+  // 回傳 HOST_OK / HOST_ERROR / HOST_TOO_LARGE
+  //
+  // 容量握手（Arcrun#92）：零件在呼叫 host function 前，把自己 outBuf 的長度預先寫進
+  // *outLenPtr；host 在寫回前讀這個值當容量上限。塞不下就**不寫**（避免覆寫零件記憶體）
+  // 並回 HOST_TOO_LARGE，讓上層改寫一段講真話的訊息。
+  //
+  // 舊零件（沒做握手）讀到 0 = 「未宣告容量」→ 維持舊行為。這裡不能自作聰明假設 64KB：
+  // 各零件緩衝區大小不同（http_request 64KB、claude_api 1MB），統一硬套會把原本
+  // 跑得好好的大回應誤判成太大。
  function writeOut(buf: ArrayBuffer, outPtr: number, outLenPtr: number, data: Uint8Array): number {
    try {
+      const view = new DataView(buf);
+      const declaredCapacity = view.getUint32(outLenPtr, true);
+      if (!outFitsCapacity(declaredCapacity, data.length)) return HOST_TOO_LARGE;
      new Uint8Array(buf, outPtr, data.length).set(data);
-      new DataView(buf).setUint32(outLenPtr, data.length, true);
-      return 0;
+      view.setUint32(outLenPtr, data.length, true);
+      return HOST_OK;
    } catch {
-      return 1;
+      return HOST_ERROR;
+    }
+  }
+
+  /** 讀零件宣告的緩衝區容量（0 = 舊零件沒宣告） */
+  function declaredCapacityOf(buf: ArrayBuffer, outLenPtr: number): number {
+    try {
+      return new DataView(buf).getUint32(outLenPtr, true);
+    } catch {
+      return 0;
    }
  }

@@ -352,12 +432,28 @@ export function createWasiShim(stdinData: string, hostFunctions?: WasiHostFuncti
              try {
                const result = await hostFunctions!.http_request!(url, method, headers, body);
                // await 後重新拿 memory.buffer（grow 會產生新的 ArrayBuffer）
-                return writeOut(memory.buffer, outPtr, outLenPtr, new TextEncoder().encode(result));
+                const encoded = new TextEncoder().encode(result);
+                const status = writeOut(memory.buffer, outPtr, outLenPtr, encoded);
+                if (status !== HOST_TOO_LARGE) return status;
+
+                // Arcrun#92：回應塞不進零件緩衝區。以前這裡會硬寫（覆寫零件記憶體）或回 1，
+                // 零件對外只講得出 "HTTP request failed"——訊息與真因脫節。
+                // 現在改寫一個講真話的 error envelope（零件既有的 parsed["error"] 判定鏈
+                // 會原樣帶到使用者面前，不必改零件也能講對原因）。
+                const capacity = declaredCapacityOf(memory.buffer, outLenPtr);
+                const envelope = new TextEncoder().encode(
+                  JSON.stringify(oversizeResponseEnvelope(encoded.length, capacity)),
+                );
+                const envStatus = writeOut(memory.buffer, outPtr, outLenPtr, envelope);
+                // 連這段說明都塞不下（緩衝區極小）→ 回 3，由零件自己講「回應太大」
+                return envStatus === HOST_OK ? HOST_OK : HOST_TOO_LARGE;
              } catch (e) {
                // t117: 寫錯誤 envelope 到 WASM 輸出（main.go 讀 error key → success:false + 詳情）；
                // 取代只 return 1（WASM 寫無資訊的 "HTTP request failed"）。
                // writeOut 失敗（memory 壞）才 fallback return 1。
-                const errDetail = e instanceof Error ? e.message : String(e);
+                // 訊息截到 200 字：這段本身若超過零件緩衝區會被判成 HOST_TOO_LARGE，
+                // 零件就會把「連不上」說成「回應太大」——又一次訊息與真因脫節（Arcrun#92）。
+                const errDetail = (e instanceof Error ? e.message : String(e)).slice(0, 200);
                const errEnv = new TextEncoder().encode(
                  JSON.stringify({ error: `fetch failed: ${errDetail}`, status: 0, body: '' })
                );
@@ -366,7 +462,8 @@ export function createWasiShim(stdinData: string, hostFunctions?: WasiHostFuncti
            })
          : () => 1,

-        // kv_get(keyPtr, keyLen, outPtr, outLenPtr) → 0 成功；1 錯誤；2 找不到 key
+        // kv_get(keyPtr, keyLen, outPtr, outLenPtr)
+        // → 0 成功；1 錯誤；2 找不到 key；3 值太大塞不進零件緩衝區（Arcrun#92）
        kv_get: hostFunctions?.kv_get
          ? hostWrap(async (keyPtr: number, keyLen: number, outPtr: number, outLenPtr: number): Promise<number> => {
              if (!memory) { console.error('[kv_get] memory null'); return 1; }
@@ -387,7 +484,8 @@ export function createWasiShim(stdinData: string, hostFunctions?: WasiHostFuncti
            })
          : () => 1,

-        // secret_get(refPtr, refLen, outPtr, outLenPtr) → 0 成功；1 錯誤；2 找不到 ref
+        // secret_get(refPtr, refLen, outPtr, outLenPtr)
+        // → 0 成功；1 錯誤；2 找不到 ref；3 值太大塞不進零件緩衝區（Arcrun#92）
        // 與 kv_get 同款 pointer/memory-write 機制；差別只在 host 端實作來源（env[ref] 而非 KV.get）。
        secret_get: hostFunctions?.secret_get
          ? hostWrap(async (refPtr: number, refLen: number, outPtr: number, outLenPtr: number): Promise<number> => {
@@ -0,0 +1,79 @@
+/**
+ * Arcrun#92 — 「回應太大」不准再被說成「請求失敗」
+ *
+ * 背景：零件（main.go）給 host function 的接收緩衝區是固定大小（http_request 64KB、
+ * claude_api 1MB）。回應超過這個大小時，舊 host 會照寫不誤 → 覆寫零件記憶體 → 零件
+ * 切片 panic，或 writeOut 撞 memory 邊界丟例外 → 回 1 → 零件印一句
+ * "HTTP request failed"。使用者拿到那句會去查連線／URL／防火牆，全部查錯方向。
+ *
+ * 這一支測的是**訊息有沒有講真話**，不是「有沒有回錯誤」：
+ *   1. 判定規則本身（沒宣告容量的舊零件不可被誤判成太大）
+ *   2. 訊息內容：真實數字 + 撇清錯誤方向 + 具體該怎麼辦 + 機器可讀欄位
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  outFitsCapacity,
+  formatBytes,
+  oversizeResponseEnvelope,
+  HOST_TOO_LARGE,
+} from '../src/lib/wasi-shim';
+
+describe('容量握手的判定規則', () => {
+  it('宣告 64KB、資料 200KB → 塞不下', () => {
+    expect(outFitsCapacity(65536, 200_000)).toBe(false);
+  });
+
+  it('剛好等於容量 → 塞得下（不可 off-by-one 誤殺）', () => {
+    expect(outFitsCapacity(65536, 65536)).toBe(true);
+  });
+
+  it('舊零件沒宣告容量（0）→ 一律視為塞得下，維持舊行為', () => {
+    // 這條是防「換一種說謊」：不能因為新規則就把 claude_api 那種 1MB 緩衝區的
+    // 大回應統統誤判成「太大」。沒宣告 = host 不知道上限 = 不准亂猜。
+    expect(outFitsCapacity(0, 900_000)).toBe(true);
+  });
+
+  it('HOST_TOO_LARGE 與零件端的 hostTooLarge 常數同值（registry/components/*/main.go）', () => {
+    expect(HOST_TOO_LARGE).toBe(3);
+  });
+});
+
+describe('formatBytes', () => {
+  it('分別用 bytes / KB / MB', () => {
+    expect(formatBytes(512)).toBe('512 bytes');
+    expect(formatBytes(65536)).toBe('64 KB');
+    expect(formatBytes(3_355_443)).toBe('3.2 MB');
+  });
+});
+
+describe('「回應太大」的訊息本身', () => {
+  const env = oversizeResponseEnvelope(3_355_443, 65536);
+
+  it('講出實際大小與上限（不是只說「太大」）', () => {
+    expect(env.error).toContain('3.2 MB');
+    expect(env.error).toContain('64 KB');
+    expect(env.actual_bytes).toBe(3_355_443);
+    expect(env.limit_bytes).toBe(65536);
+  });
+
+  it('明講「不是連線失敗」，把使用者從錯誤方向拉回來', () => {
+    expect(env.error).toContain('不是連線失敗');
+  });
+
+  it('給得出下一步（分頁／篩選），不是叫人「稍後再試」', () => {
+    expect(env.error).toMatch(/分頁|篩選/);
+    expect(env.error).not.toMatch(/稍後再試|請重新操作/);
+  });
+
+  it('不准退回萬用句', () => {
+    expect(env.error).not.toMatch(/請求失敗|HTTP request failed|未知錯誤/);
+  });
+
+  it('帶機器可讀欄位，上層不必比對字串', () => {
+    expect(env.code).toBe('response_too_large');
+  });
+
+  it('status 不偽造上游狀態碼（對方沒回 413）', () => {
+    expect(env.status).toBe(0);
+  });
+});