執行期設定
每個部門 Worker 在不可變 bundle 之外保有一個非機密的執行期 JSON 物件,存在與儲存相同的 Durable Object 裡。管理者整體替換或刪除;永不合併,且更新它永遠不會重建或重新部署 Worker。憑證不屬於這裡:Worker 機密是另一個僅可寫入的儲存區,任何管理 API 都不會回傳它的值。
管理者 API(CAS)
GET/PUT/DELETE /worker/runtime-config — 部門管理者,且 Worker 必須已部署且 active。
PUTbody:{base_revision, value},其中value是 JSON 物件:≤256 個頂層鍵、鍵 1–256 UTF-8 位元組(無 NUL)、整體 ≤64 KiB 正規 JSON、深度 ≤32、≤10 000 節點、整數在 JavaScript 安全範圍內(更大的識別碼必須用字串 — handler 必須讀到管理者提交的原值)。DELETEbody:{base_revision};刪除仍會推進 revision,所以回來的是found: false, revision: n+1。- 過期的
base_revision→ 409Runtime config revision is stale。 - 請求 body 超過 73 728 B(64 KiB 加上 8 KiB 的外層空間)→ 413
Worker runtime config request exceeds limit。
後端把值正規化一次(排序鍵、緊湊分隔符),將精確的 JSON 字串送過簽章的 purpose=control 通道,再逐位元組驗證回讀:provider 的 valueJson 必須等於後端的正規位元組、雜湊等於回傳的 sha256、revision 恰為 base_revision + 1。任何漂移是 503(不信任 provider),不是 409;部署若在後端讀取之後、呼叫控制通道之前換掉 Worker 的 release,則是有代碼的 503 worker_release_unavailable(管理執行期設定)。回應視圖是 {found, revision, value, sha256} — updated_at 刻意被剝除。
變更走耐久的控制面稽核 outbox:每次實際套用的替換/刪除最終都成為回執背書的稽核事實(runtime_config.replaced/runtime_config.deleted,digest = 正規值的 sha256/"null" 的 sha256),即使請求路徑的結算失敗也一樣(稽核)。
handler 程式碼看到什麼
每次呼叫讀取一份一致的快照,並暴露一個深度凍結的介面。handler 收到單一個凍結的 context 物件,共八個鍵 — request、params、query、operationId、storage、config、secrets、teamsync — 其中 config 就是這個介面:
context.config.configured // boolean — was a config object set?
context.config.revision // number
await context.config.get() // the whole frozen snapshot (undefined when not configured)
await context.config.get("key") // one own-property, or undefinedsecrets(Worker 機密)與 teamsync(服務帳號)是獨立的鍵:Worker 機密永遠不會是這份快照的一部分。以早於 builder 政策 v2.6 建置的修訂版兩個鍵都沒有;secrets 需要以 v2.6 或更新版本建置的修訂版,teamsync 則需要以 v2.9 或更新版本建置的修訂版(截至後端 5.22.0,每個新提交的修訂版都以 v2.10 建置)。
沒有 set、沒有 delete、沒有合併 — 客戶程式碼無法變更設定,也到不了保留的 /_teamsync/control 路徑(invoke 路由對它回 404;runtime 只在已驗證的控制斷言下服務它)。解構的 handler 一樣用 config.get(...)。範本的 listUsers 示範了預期模式:讀值、做邊界檢查、退回靜態預設值。
儲存細節
Durable Object 保有一個單例列(revision、value_json、sha256);初始狀態是 found: false, revision: 0。CAS 發生在 SQLite(WHERE revision = ?);衝突會回傳目前狀態,讓 runtime 的控制層帶著 current 回 409。後端會將它丟棄,只回純字串的 409 Runtime config revision is stale,所以請重新 GET 取得目前的 revision。