跳至主要內容
hs-sql-agent
2.0.4
文件 2.0.4
文件 開發

架構

hs-sql-agent 的產品組合、SQL Compiler 邊界與 DML 核准架構。

hs-sql-agent 把產品如何組合誰擁有執行權分開。Host 可以決定要使用多少產品能力,但 SQL 驗證、核准證據、重新驗證與 commit 仍是伺服器掌握的邊界。

產品組合

  • Docker / ToolBox:完整的獨立第一方組合。
  • HsSqlAgent.Hosting:在 .NET Host 內嵌入相同的標準組合。
  • HsSqlAgent.Server:讓 Host 自行替換或省略能力的模組化 building blocks。
  • HsSqlAgent.Approvals.AbstractionsIDmlApprovalProviderIDmlApprovalCompletionSink 等與傳輸方式無關的核准契約。
  • HsSqlAgent.Approvals.Webhook:官方通用非同步 Webhook 核准 adapter。

HsSqlAgent.Hosting 負責標準組合與 Provider selector;需要客製驗證、授權、UI、遙測、Middleware 或核准整合時,使用 HsSqlAgent.Server

SQL 執行邊界

Query 與 DML 不會直接交給資料庫 Driver。Typed SQL Pipeline 先解析、繫結、授權、驗證政策與來源語意、證明目標 Capability,最後才產生 Provider-specific Command。

不支援的語意會 fail closed。Provider-specific rendering 是最後階段,不是用來取代驗證的捷徑。

DML Transaction 核准

execute_dml_sql 可接受一個或多個受支援的 DML。多語句輸入會解析成 Batch,只核准一次,並依原始順序在一個由伺服器掌握的 Transaction 中提交。

UPDATE / DELETE 的核准會綁定精確的 Primary Key Row Set,每個 Statement 在真正修改前都會重新驗證。INSERT ... VALUES 綁定不可變的 Literal Payload 與編譯後 Command;INSERT ... SELECT 在來源 Row Set 核准語意定義完成前仍不開放。

若前一個 Statement 改變了後一個 Statement 原先核准的 Row Set,整個 Transaction 會 fail closed 並 rollback。

Durable Approval Lifecycle

核准 Provider 可以回傳 Pending。有 Admin Store 時,hs-sql-agent 會保存受保護的 Resume Intent 與核准 Fingerprint。之後收到完成決策時,不會沿用舊 Session,而是重新載入授權與資料庫設定、重新解析與 Preview DML、比對證據,再建立新的短效執行 Challenge。

核准 adapter 永遠拿不到直接 SQL 執行 primitive,讓外部工作流程保持在 commit 邊界之外。