RFC-0168：透過 InspectSink 公開檢查

摘要

這項 RFC 導入 fuchsia.diagnostics.InspectSink 通訊協定，可讓元件公開檢查資料。因此，現在可以移除目前的機制 (DirectoryReady 事件)。

提振精神

Inspect today 是透過與一般元件架構能力轉送不一致的機制公開。目前，元件會在傳出命名空間中向架構公開 diagnostics 目錄。

RFC-121 已將 DirectoryReady 事件標示為已淘汰，這是為了在 SDK 中發布事件功能。不過，如果這個目錄不存在，我們還沒有好的解決方案，可讓元件公開檢查資料。此外，Fuchsia 上的 Flutter 想要移除對這些檔案系統抽象化的依賴，並簡化實作方式。重新思考元件如何公開檢查功能，可讓他們移除大量的執行階段複雜度，並為開發人員人體工學提供優勢。

利害關係人

講師：leannogasawara@google.com

審查者：

• crjohns@google.com
• geb@google.com
• shayba@google.com

已諮詢：

• dworsham@google.com
• surajmalhotra@google.com
• zarvox@google.com

社交化：這份 RFC 先前以 Google 文件形式，在診斷、元件架構、Flutter 等團隊間傳閱。

設計

背景

過去，封存工具會透過 /hub 擷取檢查資料。其程式碼庫的結構為中樞上的目錄監看程式，會在 out/diagnostics 目錄出現時開始追蹤元件的檢查資料 (當時的名稱不同)。這項功能最終遭到移除，並透過事件 (在 appmgr 和元件管理員中) 完成。此外，當時讀取檢查資料的測試是直接從 /hub 讀取。

目前，封存工具會依據 DirectoryReady 事件執行兩項操作：

• 從元件擷取檢查資料 (元件 expose /diagnostics to framework)。
• 將檢查資料歸因於來源元件。

DirectoryReady 事件可解決這兩項問題。不過，我們已經有 (2) 的CapabilityRequested，作者認為我們可以透過一般通訊協定 (類似 fuchsia.logger.LogSink) 處理 (1)，帶來額外優勢。

解決歸因問題並非本 RFC 的目標。這項工作將在日後進行，目的是移除目前用於 LogSink 和 DebugData 的 CapabilityRequested 事件。

InspectSink

這項 RFC 導入 InspectSink 通訊協定，可讓 Archivist 從元件擷取檢查資料。這個通訊協定的定義如下：

library fuchsia.diagnostics;

using zx;

@discoverable
protocol InspectSink {
    /// Publishes a handle to the `fuchsia.inspect.Tree` protocol that the server can use to read
    /// Inspect data, including lazy nodes.
    Publish(struct {
        tree fuchsia.inspect.Tree;
        root zx.handle:<VMO, zx.rights.BASIC | zx.rights.READ | zx.rights.MAP, optional>;
    });

    /// Publishes a read handle to the inspect VMO  that the component asynchronously updates.
    /// The server can read Inspect using the Inspect reader algorithm [1]. A component using this
    /// method to publish Inspect won't be able to expose lazy nodes.
    ///
    /// [1]: /docs/reference/platform-spec/diagnostics/inspect-vmo-format.md#reader_algorithm
    PublishVmo(struct {
        name string;
        root zx.handle:<VMO, zx.rights.BASIC | zx.rights.READ | zx.rights.MAP>;
    });
}

主要方法是 Publish，大多數元件都會使用這個方法，因為這是公開 Inspect 的標準方式。fuchsia.inspect.Tree不過，我們提供一種機制，可讓元件只發布 Inspect VMO。原因如下：

• 如果元件不需要成為伺服器，就不必是伺服器 (沒有理由執行非同步迴圈，只要取用功能，不必提供任何服務)，但仍應能夠公開檢查。
• 在驅動程式遷移至使用 fuchsia.inspect.Tree (問題) 前，驅動程式會繼續公開 VMO。
• 在 Inspect Dart 程式庫支援 fuchsia.inspect.Tree 前，必須繼續公開 VMO。

與 fuchsia.logger.LogSink 相同，這個通訊協定會由 Archivist 提供服務，並路由至元件。

與提供 out/diagnostics 目錄相比，這項通訊協定有以下幾項優點：

1. 符合標準元件通訊協定路徑：

   • 元件只會使用 fuchsia.inspect.InspectSink 通訊協定，而不是執行 expose /diagnostics to framework，類似於元件目前匯出記錄和追蹤記錄的方式。
   • 封存者可以透過 CapabilityRequested 接收連線，並保留出處資訊。

2. 檢查資料可在啟動元件非同步迴圈前提供。

   • 目錄是由 fuchsia.io.Directory 支援，且大多數元件不會提供 out 目錄，直到啟動非同步迴圈為止。使用這個通訊協定後，快照就能包含尚未啟動非同步迴圈，但已寫入檢查資料的元件檢查資料。

   • fuchsia.inspect.Tree 通訊協定也適用相同原則。在元件開始放送這個通訊協定之前，快照中不會提供元件的檢查資料。在大多數情況下，元件開始非同步迴圈後，才會放送這個通訊協定。使用上述通訊協定，我們就能立即向 Archivist 提供根 VMO (因此至少會納入快照) 和 fuchsia.inspect.Tree 的控制代碼，以供日後要求使用。

3. 不再有執行器和檔案系統實作相關問題。

   • 我們目前在 appmgr 和元件管理員中都有程式碼，可處理元件未及時放送 out/diagnostics 的特殊情況，Flutter 執行元件就是如此。該執行元件會先提供 out/ 目錄，然後填入內容。理想情況下，我們只會使用目錄監看程式，但並非所有 VFS 實作項目都實作了監看程式 (特別是 Flutter 使用的 C++ SDK 中的 VFS 實作項目)，而且我們無法依賴使用完整 fuchsia.io.Directory 實作項目的未來執行器。

這項變更可在幕後完成，方法是變更 inspect/client.shard.cml 以使用新通訊協定，而非將診斷目錄公開給架構。這個檔案是透過 SDK 提供，所有公開「隨處檢查」功能的元件都會使用這個檔案。inspect/client.shard.cml

本提案適用於 v2 元件。為確保相容性，我們仍會處理 v1 元件的 out/diagnostics。由於持續遷移至 v2，作者認為不值得花時間變更 v1 的運作方式。目標是在幕後進行這項變更，因此遷移至 v2 的元件不需要變更程式碼，即可公開檢查。

實作

我們會遵循標準的 LSC 程序。

具體步驟如下：

1. 在 Archivist 中實作新通訊協定 InspectSink。
2. 使用 inspect/client.shard.cml 識別元件，並從 Archivist 將路徑 fuchsia.inspect.InspectSink 傳送至元件。不過，這項做法會導致必須在 CML 定義中完整列舉所有這類元件的問題，但我們已提出解決方案，並已向社群公開，後續的 RFC 將涵蓋這項解決方案。
3. 變更 inspect/client.shard.cml 以使用這個通訊協定，並將 /diagnostics 目錄公開給架構，以便進行軟轉換。
4. 支援連線至 InspectSink，而非在檢查程式庫中公開 diagnostics 目錄。
5. 在元件管理工具中移除 DirectoryReady 的實作項目，並在所有元件完成轉換且所有預先建構項目都已重新整理後，從 fuchsia.sys2.Event 定義中移除。我們會根據 CTF 測試和支援時間，判斷何時可以完成這項作業。

效能

由於我們不再需要遍歷目錄或建立 DirectoryReady 事件，而是只依賴單一通訊協定，因此效能應會有所提升。

安全性考量

這項變更符合元件架構安全屬性，尤其是最低權限原則和階層式隔離原則。

隱私權注意事項

隱私權方面沒有任何異動。檢查資料會繼續透過一般的隱私權管道傳輸。

測試

我們會透過下列方式測試這項 RFC 的實作情形：

• 在連結至 InspectSink 的程式庫中進行單元測試。
• 在 Archivist 中經過單元測試和整合測試，可做為 InspectSink 的用途。
• CTF 測試，偵測相容性異動。

說明文件

檢查探索和代管會更新。

目標是在幕後進行這項變更，也就是在撰寫檢查的程式庫中進行。不過，如果元件遷移至第 2 版時需要變更程式碼，我們會在遷移指南的診斷部分反映這些變更。

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

記錄和檢查都使用單一通訊協定

我們可以建立 DiagnosticsSink，讓元件在單一位置連結檢查和記錄。

• 優點：只需一個通訊協定即可轉送，不必使用兩個。
• 缺點：如果日後需要以不同方式處理記錄或檢查，維持個別通訊協定可能會比兩者使用相同通訊協定更容易。

我們認為這項缺點會讓替代方案非常不吸引人，因為記錄和檢查是不同的事物，因此分開傳送這些項目是合理的做法。

既有技術和參考資料

不適用