RFC-0054：參數屬性

「A Chance to write self documenting APIs」

摘要

我們已經可以將屬性套用至 FIDL 的各種元素，但無法套用至參數。這項提案旨在擴充語法，以便接受參數屬性。

與其他 RFC 的關係

此 RFC 已由下列 RFC 取代：

• RFC-0050：語法重整

提振精神

在更多語言元素上加入屬性，可提高語言一致性，並為日後推出更多功能奠定基礎。任何無法在型別系統中編碼的 API 事實，都可以改為在屬性中編碼。任何無法在類型系統中編碼的事實，都可以透過屬性中的更多結構體擷取，簡化各種後端的延遲驗證。這些屬性可用於 linting，產生器也可以利用這些資訊產生更好的程式碼，或將這些資訊傳播至目標語言的屬性。這有助於對目標語言進行靜態和/或動態分析。此外，屬性也是製作型別系統可能擴充或精進的功能原型時，非常實用的做法。

這項功能的主要用途是檢查句柄遺漏、雙重釋放和釋放後使用錯誤。

核心 ABI (即系統呼叫) 也以 FIDL 格式表示，而且通常無法清楚瞭解句柄的擁有權。使用者是否應在 task_kill 系統呼叫後呼叫 handle_close？說明文件並未清楚說明這點。其他系統呼叫則有非常清楚的說明文件，但只能手動檢查：

[Transport = "Syscall"]
protocol handle {
    /// Close a handle.
    /// Rights: None.
    handle_close(handle handle) -> (status status);

    /// Close a number of handles.
    /// Rights: None.
    handle_close_many(vector<handle> handles) -> (status status);

    /// Duplicate a handle.
    /// Rights: handle must have ZX_RIGHT_DUPLICATE.
    handle_duplicate(handle handle, rights rights) -> (status status, handle out);

    /// Replace a handle.
    /// Rights: None.
    handle_replace(handle handle, rights rights) -> (status status, handle out);
};

在參數上啟用屬性後，我們可以用屬性取代註解。這些屬性與註解一樣易讀，可協助產生器產生可使用靜態和動態分析工具 (例如 這個) 檢查的程式碼。kazoo 工具可為 C 和 C++ 繫結產生對應的註解，讓 Clang 靜態分析器能夠擷取句柄濫用錯誤。

原型在 Fuchsia 中已發現許多錯誤。

設計

這項提案建議在 FIDL 原始語言中新增參數屬性。這些屬性應以與其他屬性類似的方式，在 JSON IR 中公開。我們可能需要更新格式化程式。這不會影響電報格式。語言繫結只會受到引入可變更產生程式碼的特定註解影響，但不會直接受到這項提案的影響。

我們的提案只會變更 FIDL 文法的一個產生規則：

- parameter = type-constructor , IDENTIFIER ;
+ parameter = ( attribute-list ) , type-constructor , IDENTIFIER ;

我們也需要診斷參數的三斜線說明或說明屬性。

導入策略

這項變更具有回溯相容性，不需要遷移。有許多文件需要隨著功能更新。這項提案會變更剖析器，並在 IR 中新增資訊。在引入新的參數屬性時，可以單獨變更產生器。

人體工學

這項功能可讓 FIDL API 更容易理解，並讓繫結更適合靜態和動態分析。額外的複雜度成本應保持在低水準。如需潛在參數屬性的範例，請參閱下一節。編輯器支援功能也可能需要進行小幅更新。

說明文件和範例

語法文件和語言參考資料需要進行小幅更新。我們可能需要新增一些樣式規範，說明如何在特定情況下為參數屬性換行。由於目前的樣式指南並未提及屬性，因此這項問題可能不太重要。

如需範例，請參閱動機一節。

回溯相容性

此提案同時保留 FIDL 原始碼和線路 ABI 的相容性。後續介紹的特定屬性可能會導致線路 ABI 不相容。這些屬性應分別通過 RFC 程序。

成效

未來的屬性可能會對成效產生正面影響。進一步瞭解 API 可能有助於目標語言的最佳化工具。

安全性

特定屬性可協助目標語言中的靜態和動態分析工具，因此可能會提升安全性。

測試

我們會為 fidlc 編寫測試，確保正確剖析，並提供編譯失敗的合理診斷資訊。系統也會測試產生的 JSON IR。為了進行測試，我們需要至少引入一個適用於參數的屬性。由於產生器一開始不會受到影響，因此不需要額外測試。

缺點、替代方案和未知事項

導入成本相對較低。

RFC-0044 可能是替代方案。接受該提案會導致語言出現一些不一致之處，因為一種描述參數的方式可讓使用者編寫參數屬性，而另一種則不行。此外，RFC-0044 有效能成本，因此某些通訊協定 (例如 syscall) 應盡量少用或完全不使用。

既有技術與參考資料

Protobuf 有訊息的選項，其行為與參數屬性有些類似。FIDL 已為成員和通訊協定等部分語言元素提供屬性。