RFC-0155:可選的功能路徑

RFC-0155:選用能力路徑
狀態已接受
領域
  • 元件架構
說明

在優惠中新增欄位,並使用元件資訊清單中的區段,指出特定能力可能不存在的情況。

問題
毛皮變化
作者
審查人員
提交日期 (年-月-日)2022-02-07
審查日期 (年-月-日)2022-04-14

摘要

優惠中會新增一個欄位,並使用元件資訊清單的各個區段 表示指定能力可能不存在的情況。

提振精神

核心領域資料分割

使用核心領域資料分割時,這會衍生出能力特徵 路徑的來源或目標不存在。例如:

  • /core/wlancfg 元件使用通訊協定 fuchsia.location.sensor.WlanBaseStationWatcher,但這個通訊協定並不是 某些產品的廣告
  • /core/bt-a2dp 元件必須使用 fuchsia.power.battery.BatteryManager 能力 (如果有的話),但 不適用於所有產品。
  • /core/omaha-client-service 元件必須使用 fuchsia.update.config.OptOut 通訊協定 (如有),但不支援 適用於所有產品。
  • 如果有影片可用,CommsAgent 套件必須使用影片 影片。
  • 追蹤服務供應商是一種元件 fuchsia.tracing.provider.Registry 功能。這對開發 用途,但使用者版本不應包含此元件。

上述情境是我們我們希望支援的元件設定 不過,元件架構中目前有幾個地方 引進與以下相關的粗略的邊線:

  • 向不在資訊清單中的元件提供或從中取用元件, 導致資訊清單驗證失敗。
  • 如果提供的能力來自未公開的元件 也會失敗
  • 失敗能力路徑 (例如,嘗試使用的能力並非 時,元件管理員會 (正確) 發出警示層級記錄, 因此在調查 故意省略這項能力的產品。

透過集合驗證路徑

Scrutiny 是一款元件路徑驗證工具 特定元件樹狀結構中的功能具備有效的能力路徑。獨立元素 並提供正確的系統正確斷言,這項工具對於 因為移動路徑可縮短開發週期 從執行階段到建構時間的驗證。

目前禁止審查的許可清單 檢查特定能力路徑這樣一來,當建構成功 元件使用的能力無法使用,但很抱歉 當能力路徑設定錯誤時,如果無法在 能力提供。

此外,一旦解決 https://fxbug.dev/42174612 錯誤,scrutiny 也會啟動 scrutiny 驗證源自工作階段運作範圍的能力路徑。經常 工作階段元件取決於源自於外部 IP 位址的功能 因此如果希望新增其中一個元件 方便審查,因為這類元件可能在 fuchsia.git.

相關人員

誰會負責確認 RFC 是否已獲接受?(這個部分為選填,但 encouraged.)

講師:Hunter Freyer (hjfreyer@google.com)

FEC 任命的人員,透過 RFC 處理此 RFC 上傳資料集之後,您可以運用 AutoML 自動完成部分資料準備工作

審查者:

  • Mark Dittmer (markdittmer@google.com) - 安全性
  • Gary Bressler (geb@google.com) - 元件架構
  • Marc Khouri (mnck@google.com) - WLAN
  • Ani Ramakrishnan (aniramakri@google.com) - 藍牙
  • Yaar Schnitman (yaar@google.com) - 產品

社交功能:

收到 https://fxbug.dev/42168255 和 此 RFC 是一種早期形式 所有相關人員共用

設計

將會新增名為 availability 的欄位,以使用宣告。預設 這個欄位的值會是 required,表示該元件是 並未預期能提供的能力;若沒有,則可能出現故障 廣告。這個 RFC 並未提議對 required 的行為進行任何變更 而是以現今所有功能的運作方式

{
    use: [
        {
            protocol: "fuchsia.logger.LogSink",
            availability: "required",
        },
        {
            directory: "config-data",
            path: "/config",
            rights: [ "r*" ],
            // The `availability` field defaults to `required` when omitted.
        },
    ],
}

使用宣告的 availability 欄位也可以設為 optional, 在能力無法運作時,反映元件正常運作的時機 (可能受到修改行為的保護)。

{
    use: [
        {
            // Emergency location is not present in all products.
            protocol: "fuchsia.location.sensor.WlanBaseStationWatcher",
            availability: "optional",
        },
    ],
}

系統會將名為 void 的來源加到以下來源的可能來源清單中: 優惠聲明。

{
    offer: [
        {
            protocol: "fuchsia.update.config.OptOut",
            from: "void",
        },
    ],
}

如果能力使用宣告為選用,可以從 現有元件或從「void」移除內容如果能力的用途是宣告式 必要時可能無法提供,否則可能會導致 故障

中介優惠 (從父項到子項) 也可以設定 availability 欄位改為下列其中一個值:

  • required (預設):子項「必須」獲得這項能力的存取權, 無論子項能否處理其缺口 ( )。
  • optional:子項「必須」能夠處理沒有這項能力 (您必須選擇選用,在優惠鏈結尾使用宣告)。
  • same_as_target:優惠具有與目標相同的選用性。如果 如果目標需要能力,則這項優惠會明確規定 必須接收能力。如果目標有選擇性使用 則這項優惠明定目標不一定 這項功能
{
    offer: [
        {
            protocol: "fuchsia.power.battery.BatterManager",
            from: "parent",
            to: "bt-a2dp",
            // Emit a build-time error if this protocol is not correctly routed
            // to this child (including offers from void).
            availability: "required",
        },
        {
            protocol: "fuchsia.location.sensor.WlanBaseStationWatcher",
            from: "parent",
            to: "wlancfg",
            // Emit a build-time error if this child is unable to handle the
            // absence of this protocol.
            availability: "required",
        },
    ],
}

如果元件有使用 optional,且其父項提供了 required,如果 能力無效,或是結尾是「void所提供的優惠」。如果元件的 required 的使用方式及其父項提供能力做為 optional,然後 會發出建構時間錯誤。如果未設定這個欄位,你可以設定這個欄位 已忽略。

核心領域組件

RFC-0089 所述,核心領域是從「核心」部分組合而成 資料分割」,也就是在建構時與核心領域合併的 CML 程式碼片段 讓應用程式從可以最快做出回應的位置 回應使用者要求確切的核心資料分割是由產品定義所設定。

我們通常建議直接加入指定同一核心兒童的優惠 做為子項宣告的資料分割。這可確保影片中包含兒童 建構過程中所需的功能 可以使用的所有服務

需要將孩子的優惠加入與子項相同的資料分割, 優惠希望在建構中也能選擇一併包含來源。 如果優惠目標設為子 a 的子發布商,但來源是 b,但 b 是 若是資料分割,則 a 的資料分割只能納入 b 的建構中 包含資料分割,或 系統會在以下位置發出資訊清單驗證錯誤: 建構時間。

要允許和孩子優惠相同的核心資料分割, 無論來源為何,系統都會導入新的欄位 source_availability 宣告。這個欄位會預設為 present,但可以設為 unknown

如果將 source_availability 設為 unknown,優惠宣告就會通過 資訊清單驗證是否參照不在資訊清單中的來源。 在資訊清單編譯期間,系統將不會 替換為 void 來源,允許所有路徑結尾的宣告 這項優惠聲明,才能通過路徑驗證,將 可用性為 optional,以表示這項能力完全不存在 很少直接解答該如何打造產品

{
    offer: [ {
        protocol: "fuchsia.examples.Echo",
        from: "#child-that-might-not-be-declared",
        to: "#echo-user",
        source_availability: "unknown",
    } ],
}

如此一來,平台設定維護工具就能依賴 資料分割做為單一可靠資料來源,內含哪些功能和元件 存在於核心領域省略核心資料分割,不僅會移除子系統 一併更新任何提供來源項目的服務 提供給 void 的子系統,因此這類子系統可針對任何 即使在該子系統上的用量安全,也無法正常獲得子系統的存取權 系統刻意排除這類物件 (但任何必要用途) 仍會造成錯誤)。

範例

核心領域中的元件,具有選用能力

在此例中,我們可以說明 的資訊清單與核心領域資料分割如何 wlancfg 會根據提議的設計而改變。

fuchsia.location.sensor.WlanBaseStationWatcher 通訊協定的優惠 會從 emergency.core_shard.cml 移至 wlancfg.core_shard.cml,而 「source_availability」欄位已設為 unknown (因為緊急核心肌群) 資料分割及緊急元件,不一定包含在 與 wlancfg 相同的平台設定)。

// src/connectivity/location/emergency/meta/emergency.core_shard.cml
{
    offer: [
        // This is removed
        {
            protocol: "fuchsia.location.sensor.WlanBaseStationWatcher",
            from: "#emergency",
            to: "#wlancfg",
        },
    ],
}
// src/connectivity/wlan/wlancfg/meta/wlancfg.core_shard.cml
{
    offer: [
        // This is added
        {
            protocol: "fuchsia.location.sensor.WlanBaseStationWatcher",
            from: "#emergency",
            to: "#wlancfg",
            source_availability: "unknown",
        },
    ],
}

必須從優惠宣告移至 wlancfg 的核心資料分割 可以讓 source_availability 欄位正常運作,且和 核心資料分割最佳做法。

除了核心資料分割變更外,在 wlancfg 即將更新為 optional

// src/connectivity/wlan/wlancfg/meta/wlancfg.cml
{
    use: [
        {
            protocol: "fuchsia.location.sensor.WlanBaseStationWatcher",
            // This line is added
            availability: "optional",
        },
    ],
}

現在,當該版本不包含 emergency.core_shard.cml 檔案時 都不會發生建構時間錯誤,因為 wlancfg 無法存取 fuchsia.location.sensor.WlanBaseStationWatcher 通訊協定。也就是說, 通訊協定和設定錯誤可能會從審查的許可清單中移除 ,導致平台上 wlancfg 無法使用通訊協定 設定在「有」可用的情況下,會導致建構時間錯誤。

工作階段中包含選用能力的元件

在此例中,我們可以說明資訊清單和核心領域資料分割的運用方式 取得 fuchsia.power.battery.BatteryManager 通訊協定 /core/battery_manager/core/session_manager/session:session/workstation_session/login_shell/ermine_shell 會根據提議的設計而改變

workstation.core_shard.cml 檔案中通訊協定的優惠如下: 已更新為 source_availability 設為 unknown

// src/session/bin/session_manager/meta/workstation.core_shard.cml
{
    offer: [
            protocol: "fuchsia.power.battery.BatteryManager",
            from: "#battery_manager",
            to: "#session-manager",
            // This line is added
            source_availability: "unknown",
    ],
}

coreermine_shell 之間的優惠不必修改。 系統會更新 ermine_shell 資訊清單,將「availability」欄位設為 通訊協定的 optional

// src/experiences/session_shells/ermine/shell/meta/ermine.cml
{
    use: [
        {
            protocol: "fuchsia.power.battery.BatteryManager",
            availability: "optional",
        },
    ],
}

經過這些變更後,workstation.core.shard.cml 檔案可能會納入 沒有 battery_manager.core_shard.cml 的平台設定 會導致建構時間檢查錯誤,或將這項能力新增至許可清單。 這表示電池管理員元件可以安全從平台中排除 需要在沒有主機端的硬體上執行工作站工作階段 電池。

工作階段擁有者想確保一律啟用某項選用能力

可供使用

延續上例,假設要參加名為 workstation-on-laptopsworkstation 工作階段相同,但 而且具備額外的筆記型電腦專屬功能如果這個工作階段的擁有者希望 使用 workstation 工作階段中顯示的相同 ermine 元件, 但希望確保服務「一律」能存取 fuchsia.power.battery.BatteryManager 通訊協定 (由建構時間強制執行) 錯誤),則工作階段擁有者可能會提供此通訊協定為 requiredermine

// src/experiences/session_shells/ermine/session/meta/workstation_on_laptops_session.cml
{
    offer: [
            protocol: "fuchsia.power.battery.BatteryManager",
            from: "parent",
            // login_shell offers the capability to ermine
            to: "#login_shell",
            availability: "required",
    ],
}

在本例中,如果將 workstation-on-laptops 工作階段與 提供 fuchsia.power.battery.BatteryManager 的平台設定 void 的通訊協定 (即 battery_manager.core_shard.cml 不是 納入),則即使 ermine.cml 沒有建構時間錯誤,也會發出建構時間錯誤 可選擇是否用於通訊協定

工作階段擁有者想確保元件可在缺少

一項選用能力

再次在「選手可選用 BatteryManager」上建構舉例來說,如果 工作站工作階段的擁有者希望確保 ermine 能夠處理缺少 fuchsia.power.battery.BatteryManager 的 不受通訊協定目前的可用性影響 設為 optionalermine

// src/experiences/session_shells/ermine/session/meta/workstation_session.cml
{
    offer: [
            protocol: "fuchsia.power.battery.BatteryManager",
            from: "parent",
            // login_shell offers the capability to ermine
            to: "#login_shell",
            availability: "optional",
    ],
}

這項選用優惠不會影響 因此 ermine 也有選用能力。如果 ermine 經過修改,要求取得這項能力後,建構時間 錯誤就會由審查發出, 有效或結尾是「void提供的優惠」。

實作

如要導入這些變更,請fuchsia.component.decl.Component FIDL 資料表 和 CML JSON 結構定義必須更新為包含新的欄位 更新 CMC、cm_fidl_validator 和 Scrutiny,以正確處理 設計一節所述的 optional 語意。

成效

提議的變更不會對建構時間造成任何顯著影響, 因為在這些資訊清單中加入額外列舉,成本非常高 小型此外,元件管理員中提議的執行階段行為變更 請放心,這樣做並不會對成效造成任何重大影響 建構新命名空間組合邏輯時,全都存在於記憶體中 工作開始。

人體工學

這項變更應該大幅改善元件作者的人體工學 目前需要與許可清單互動才能抑制審查的對象 驗證錯誤時,系統會針對預期的驗證錯誤 經過改善後,審查作業完全不會導致這些預期錯誤。

回溯相容性

這項變更僅會添加至 FIDL 資料表和 JSON 格式,因此 沒有回溯相容性疑慮

安全性考量

這項變更可讓元件作者停用「審查」功能 未獲得安全性許可的未轉送功能錯誤 團隊,不再使用許可清單控管清除錯誤 抑制未轉送功能的情況。

這種行為違反規定,因為 變更元件路徑本身不會受到這個提案的影響。

隱私權注意事項

提議的變更不會影響使用者資料的收集、處理或做法 進而產生任何隱私權疑慮。

測試

目前已針對元件資訊清單管道進行了廣泛的測試。 這些測試會遭到修改,納入這項新功能的涵蓋範圍。

說明文件

系統會更新元件資訊清單說明文件,說明新的欄位內容 及其對驗證的影響

缺點、替代方案和未知

既有藝術品和參考資料

待辦事項