Safety Module ZH

English version

安全模組 — beam_pipeline_toolkit/safety/

貫穿整個工具箱使用的兩個小型、彼此獨立的防護機制。

leak_guard.py

針對核准輸出(metric 列、遙測事件、run manifest——任何即將被持久化或傳輸的內容)的遞迴式禁用鍵值掃描器，而非用於管線內部流動的原始紀錄(這些紀錄本來就合法地帶有 customer id 之類的欄位)。

• LeakGuard(forbidden_substrings=..., allowed_key_exceptions=...) — 依自己的應用程式/領域建立專屬實例。
• assert_safe(obj) — 遞迴檢查整個物件圖(dict/list/tuple)中任何一個鍵是否包含禁用子字串(不區分大小寫)，若有則拋出 SafetyViolation。採取直接拒絕而非默默移除該鍵——默默移除可能掩蓋真正的整合錯誤。
• is_safe(obj) — 不拋出例外的布林版本。
• default_guard / 模組層級的 assert_safe/is_safe — 一個現成可用的實例，內建 DEFAULT_FORBIDDEN_KEY_SUBSTRINGS(email、phone、customer_id、token、secret、credential、traceback、raw 等),且沒有任何應用程式專屬的例外。pipeline/aggregation.py、pipeline/telemetry.py、pipeline/sinks.py 等模組呼叫的都是這個實例。有自己合法欄位名稱的應用程式,應該建立自己的 LeakGuard,而非修改這個預設實例。

cloud_gate.py

assert_gates_open(*, flags, confirmation=None, expected_confirmation=None, confirmation_flag_name="--confirm-execution") — 每一條會建立雲端資源的程式路徑(Pub/Sub client、BigQuery client、Dataflow 提交)都必須在建立 client 前一刻呼叫的唯一關卡,不能提早呼叫。除非 flags 內每個旗標都是 True,且(若有提供)confirmation 與 expected_confirmation 完全相符,否則會拋出 CloudGateError,並列出所有缺少或無效的關卡。支援任意數量的旗標——兩旗標或三關卡的慣例都適用同一個函式。