| RFC-0146：CML 中的結構化設定結構定義 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 針對 CML 中的結構化設定結構定義所做的設計、實作策略和其他決策 |
| 問題 | |
| 變更 | |
| 作者 | |
| 審查人員 | |
| 提交日期 (年/月) | 2021-10-18 |
| 審查日期 (年/月) | 2021-12-22 |
摘要
本文件擷取了有關 CML 中結構化設定結構定義的設計、實作策略和其他決策，以 RFC-0127 為基礎。本提案會提供設定結構定義的 JSON 語法、用於在元件資訊清單中編碼設定結構定義的一組 FIDL 類型，以及將設定結構定義從 JSON 轉換為 FIDL 的程序。
請注意，「config schema」(設定結構定義) 是 RFC-0127 中定義的「設定定義檔」具體實作。
提振精神
開發人員需要為元件宣告設定結構定義。也必須建構剖析設定結構定義、編譯設定結構定義並傳送至元件管理服務的程序。本提案旨在解決這些疑慮。
設定結構定義是向使用者顯示的結構化設定主要介面，根據 RFC-0098 設定的條件，這項功能需要 RFC 提案才能使用。
Fuchsia SDK 中包含建議的資訊清單語法和 FIDL 結構。如要控管這項功能的使用情形，資訊清單檔案中的設定結構定義會受到 cmc 中的功能旗標管制。
相關人員
講師：pascallouis@google.com
審查人員：adamperry@google.com、jsankey@google.com、geb@google.com、pascallouis@google.com、cpu@google.com
顧問：aaronwood@google.con、yifeit@google.com、surajmalhotra@google.com、shayba@google.com
社交：本設計已與元件架構團隊分享，也是元件架構設計討論的話題。
設計
範圍
本提案將考量下列事項：
本提案考量以下因素：未來可行，亦不在本 RFC 的涵蓋範圍內：
- 支援資訊清單資料分割中的設定結構定義
- 支援複雜的資料類型
- 支援設定結構定義中的預設值
- 支援覆寫政策
- 根據 RFC-0127，設定檔的覆寫政策會宣告為
CML 語法
我們會在元件資訊清單中引入新的頂層索引鍵，用於定義元件的結構化設定。對應的值會包含每個設定欄位的鍵。
結構化設定欄位需要類型系統。Fuchsia 團隊在開發 FIDL 類型系統方面擁有豐富經驗，並定義了與 FIDL 相容且具有相同理念的類型系統 (例如版面配置和限制的區隔)，藉此利用這項體驗。可透過結構化設定金鑰表示的類型組合目前是可在 FIDL 中表示的類型子集。結構化設定和 FIDL 都會隨時間改變。我們認為，與 FIDL 類型相比，結構化設定類型可能會逐漸變得更加生動，例如透過限制使用限制來將數字限制在特定範圍。
CML 樣式和語法用於一致性。當相同的概念存在時，我們會盡力讓命名和分解方式保持一致。例如，執行個體 FIDL 類型會以版面配置、選擇性參數化和選擇性限制等方式表示。此分解存在於建議的 CML 語法擴充功能中 (類型含有選用屬性)；原始版面配置 (例如 int32) 或較複雜的版面配置 (例如 vector) 具有相同名稱；限制可套用至類型，例如設定向量或字串大小上限。
元件資訊清單的變更摘要如下：
{
use: {
...,
},
...
config: {
<key>: {
type: "<type string>",
<additional properties based on type>
},
...
}
}
config 是資訊清單中的頂層鍵，其值是 JSON 字典。字典的每個成員都是設定欄位，由鍵和類型組成。
設定金鑰具有下列屬性：
- 這些是元件設定結構定義內的專屬 ID
- 它們會用於系統組合，以及處理覆寫覆寫值
- 系統組合會使用已編譯資訊清單中的設定金鑰來建立設定檔值檔案
- 設定金鑰是穩定的 ID，可用於定義父項覆寫
- 必須與規則運算式
[a-z]([a-z0-9_]*[a-z0-9])?相符- 這個規則運算式與 FIDL、JSON 和潛在用戶端程式庫中的 ID 相容。
- 必要時，這會在鍵中保留編碼分隔符的空間。
- 未來也可以進一步拓展。
- 長度不得超過 64 個半形字元
- 這項功能未來可能會擴大支援範圍。
設定欄位中的類型字串只能使用下列其中一個值：
booluint8、uint16、uint32、uint64int8、int16、int32、int64stringvector
此設計支援 enum、float、struct 和 array 等類型，但不在這個 RFC 的範圍內。關於這些複雜類型的語法，請參閱「未來工作」一節。
bool 和整數沒有任何類型限制：
config: {
enable_advanced_features: { type: "bool" },
num_threads: { type: "uint64" },
}
string 必須具有 max_size 類型限制。max_size 剖析為 uint32：
config: {
network_id: {
type: "string",
max_size: 100,
}
}
vector 必須具備 max_count 類型限制和 element 類型引數。max_count 會剖析為 uint32。element 僅限於 bool、整數或 string：
config: {
tags: {
type: "vector",
max_count: 10,
element: {
type: "string",
max_size: 20,
}
}
}
範例
以下元件資訊清單已進行調整，以使用結構化設定。這些範例會明確著重於資訊清單的 config 區段。
群島
目前的設定會分成指令列引數和隨附元件的 JSON 設定檔。以下範例說明這些設定來源現在如何連結至結構化設定。
config: {
// proxy the kernel logger
enable_klog: { type: "bool" },
// initializes syslog library with a log socket to itself
consume_own_logs: { type: "bool" },
// connects to the component event provider. This can be set to false when the
// archivist won't consume events from the Component Framework v1 to remove log spam.
enable_component_event_provider: { type: "bool" },
...
// initializes logging to debuglog via fuchsia.boot.WriteOnlyLog
log_to_debuglog: { type: "bool" },
// number of threads the archivist has available to use.
num_threads: { type: "uint32" }
}
偵測
sampler、persistence 和 detect 等程式會編譯為「啟動器」二進位檔，以便節省空間。由於啟動器中的每個程式都有自己的資訊清單，因此可以有不同的結構設定。
請考慮使用指令列引數完成目前設定的 detect 程式：
program: {
...
args: [
// The mode is passed over argv because it does not vary for this component manifest.
// Launcher will use the mode to determine the program to run.
"detect"
]
},
config: {
// how often to scan Diagnostic data
// unit: minutes
//
// NOTE: in detect's CLI parsing, this is optional with a default specified in code.
// when using structured config, the default would be provided by a build template or
// by product assembly.
check_every: { type: "uint64" },
// if true, minimum times will be ignored for testing purposes.
// never check in code with this flag enabled.
test_only: { type: "bool" },
}
遊戲主機
目前設定是使用指令列引數完成。本例顯示對結構化設定中字串向量等進階類型的需求。
config: {
// Add a tag to the allow list. Log entries with matching tags will be output to
// the console. If no tags are specified, all log entries will be printed.
allowed_log_tags: {
type: "vector",
max_count: 40,
element: {
type: "string",
max_size: 40,
}
},
// Add a tag to the deny list. Log entries with matching tags will be prevented
// from being output to the console. This takes precedence over the allow list.
denied_log_tags: {
type: "vector",
max_count: 40,
element: {
type: "string",
max_size: 40,
}
},
}
FIDL 規格
上述定義的 CML 語法必須透過 cmc 編譯為對等的 FIDL 物件，並由元件管理服務處理，並在後續實作階段用於覆寫解析度。
針對設定結構定義使用 FIDL 是內部選擇，可簡化 cmc 和元件管理服務中的實作。FIDL 並非開發人員在設定結構定義中使用的介面。
ConfigSchema 物件包含：
- 已排序的欄位清單 (
ConfigField物件) - 結構定義檢查碼：所有設定欄位的雜湊值
ConfigField FIDL 物件由 key 和 type 組成。這兩個欄位的意義與 CML 語法中的意義相同：key 專門用於識別設定欄位，而 type 則是設定值必須符合的類型。
FIDL 編碼允許最多 2^32 - 1 個設定欄位。
cmc 會以確定性順序排序設定欄位，但這個 RFC 不會指定該順序。使用確定順序可為結構定義檢查碼、下游工具和執行階段設定解析保持一致。如果不指定順序，未來就有空間進行最佳化。
結構定義檢查碼是由 cmc 使用每個欄位的鍵和值類型計算。這個總和檢查碼也會顯示在設定檔中。元件管理服務會檢查結構定義和值檔案中的檢查碼是否相同，以免發生版本偏移。
library fuchsia.component.decl;
// Config keys can only consist of these many bytes
const CONFIG_KEY_MAX_SIZE uint32 = 64;
// The string identifier for a config field.
alias ConfigKey = string:CONFIG_KEY_MAX_SIZE;
// The checksum produced for a configuration interface.
// Two configuration interfaces are the same if their checksums are the same.
type ConfigChecksum = flexible union {
// A SHA-256 hash produced over a component's config interface.
1: sha256 array<uint8>:32
};
/// The schema of a component's configuration interface.
type ConfigSchema = table {
// Ordered fields of the component's configuration interface.
1: fields vector<ConfigField>:MAX;
// Checksum produced over a component's configuration interface.
2: checksum ConfigChecksum;
};
// Declares a single config field (key + type)
type ConfigField = table {
// The identifier for this config field.
// This key will be used to match overrides.
1: key ConfigKey;
// The type of config values. Config values are verified
// against this layout at build time and run time.
2: type ConfigType;
};
// The type of a config value
type ConfigType = struct {
layout ConfigTypeLayout;
parameters vector<LayoutParameter>;
constraints vector<LayoutConstraint>;
};
// Defines valid type ids for config fields.
type ConfigTypeLayout = flexible enum {
BOOL = 1;
UINT8 = 2;
UINT16 = 3;
UINT32 = 4;
UINT64 = 5;
INT8 = 6;
INT16 = 7;
INT32 = 8;
INT64 = 9;
STRING = 10;
VECTOR = 11;
};
// Parameters of a given type layout
type LayoutParameter = table {
// For vectors, this is the type of the nested element.
1: nested_type ConfigType;
};
// Constraints on a given type layout
type LayoutConstraint = table {
// For strings, this is the maximum number of bytes allowed.
// For vectors, this is the maximum number of elements allowed.
1: max_size uint32;
};
Component 相當於 CML 資訊清單的 FIDL，且現在必須包含 ConfigSchema FIDL 物件。
// *** component.fidl ***
library fuchsia.component.decl;
// NOTE: as long as the two libraries are supported, this change will also be made to
// library fuchsia.sys2;
/// A component declaration.
///
/// This information is typically encoded in the component manifest (.cm file)
/// if it has one or may be generated at runtime by a component resolver for
/// those that don't.
type Component = table {
/// ... previous fields ...
/// The schema of a component's configuration interface.
10: config ConfigSchema;
};
對「cmc」所做的變更
我們會擴充 cmc，以使用 config 區段反序列化 CML、驗證其內容，並在已編譯的資訊清單中納入產生的結構定義。
我們會在功能旗標後方為 cmc 實作此功能。在我們實作其他結構化設定時，只有明確許可清單中的樹狀結構內結構元件才能使用 config 節區。
元件管理服務工具異動
我們會變更元件管理服務，將結構化設定結構定義提供給每個元件執行個體 resolved/config 目錄下的中樞。中樞命名空間的確切編碼可能不穩定，不在這個 RFC 的涵蓋範圍內。
藉由這項變更對中樞，我們得以建立整合測試，驗證設定結構定義是否能成功通過元件解析管道。
對「ffx component」所做的變更
ffx component show 會使用中樞輸出元件執行個體的相關資訊。對元件管理服務進行變更後，這個外掛程式現在可以輸出每個元件執行個體的設定結構定義。
$ ffx component show netstack
Moniker: /core/network/netstack
URL: fuchsia-pkg://fuchsia.com/network#meta/netstack.cm
Type: CML static component
Component State: Resolved
...
Configuration:
log_packets [bool]
verbosity [string:10]
socket_stats_sampling_interval [uint32]
opaque_iids [bool]
tags [vector<string:10>:20]
Execution State: Running
...
請注意，上述 ffx component show 的指令輸出內容隨時可能變動。在實作實際值的解析度之前，這個指令只會列印設定結構定義。
實作
這個設計的實作程序將分為三個漸進式階段。
效能
- 我們會根據結構化設定，針對在元件開始時間新增的效能命中資料進行基準測試。我們已發出錯誤。
- 這項設計會使用 FIDL 資料表來編碼結構定義，因此相較於宣告結構體，剖析
ComponentDeclFIDL 物件時可能會增加一些負擔。與整體元件啟動時間相比，我們預期這種開銷可以微不足道。 - 這種設計會將設定金鑰儲存為
ConfigFieldFIDL 物件中的字串，這麼做會耗用額外的磁碟空間，且需要在啟動元件時複製更多資料。- 這是非 ELF 執行器的必要條件，其中某些執行者需要使用字串鍵來原生編碼設定值。
- 這也有助於簡化透過中心偵錯的流程。
- 如果是 N 設定金鑰，我們預期需要 O(N) 費用才能比對設定值。如果未設定覆寫，則系統不會檢查設定金鑰是否相等。
- 我們並不擔心
cmc等主機工具的效能。 - 對設定結構定義或設定值進行雜湊處理時，元件管理服務概不負責。
cmc會事先進行雜湊處理。元件管理服務只需要檢查結構定義和值檔案中的雜湊的相等性。 - 元件管理服務會將設定結構定義儲存在中樞檔案系統中。這可能會對元件管理服務的記憶體用量造成額外影響 (不容忽視)。
- 我們建議以中樞式提取式 (而非推送式) 為核心來解決這個問題。已對這項功能要求提出錯誤。
安全性考量
作者沒有任何潛在疑慮。請注意，這項功能是在 cmc 中使用許可清單，可進一步降低安全性風險。
隱私權注意事項
設定金鑰會顯示在元件資訊清單中。如果元件會公開發布，則這些金鑰不應包含專屬資訊。
作者不會看到任何其他潛在疑慮。
測試
我們預計會：
cmc的單元測試，這會測試config架構的驗證和編譯 (包括失敗案例)- 元件管理服務的單元測試，使用結構化設定測試中樞的目錄結構
- 元件管理服務的整合測試，可解析元件資訊清單，並確認中樞會顯示其設定結構定義
ffx component show的單元測試，可正確從中心處剖析結構化設定。
說明文件
我們預計在結構化設定達到成熟度時，加入以下說明文件：
- 元件結構化設定結構定義的 CML 語法
- 元件結構化設定結構定義的 FIDL 規格
- 宣告設定結構定義的最佳做法：註解、命名慣例等等
- 範例/程式碼研究室：將
config區段新增至元件的資訊清單、建構元件、使用ffx component show驗證設定欄位
缺點、替代方案和未知
替代項目：config 區段指向 FIDL 檔案
資訊清單中的 config 區段可以指向說明設定結構定義的 FIDL 來源檔案。RFC-0127 會詳細說明這個替代方案及其缺點。從 RFC-0127 得到的結論也適用於此處。
替代選項：program 下的「config」部分
program: {
config: {
<key>: {
type: "<type string>",
<additional JSON fields based on type>
},
}
}
- 優點：在
program和config之間建立關聯 - 缺點：過多巢狀
- Con：沒有
program區段的元件無法擁有結構化設定。日後，設定轉送可能會涉及沒有程式的元件。
替代選項：fields 部分
config: {
fields: {
<key>: {
type: "<type string>",
}
...
}
}
- Pro：保留空間給日後設定結構定義的擴充功能。目前還沒有確定是否需要日後的擴充性。
- Con：較精簡
替代選項：場域詳細
方法 B：
config: [
{
key: "<key>",
type: "<type string>",
}
...
]
- Pro：使用 JSON 陣列，而非 JSON 物件。與資訊清單的其他部分更一致：
use、expose等。 - Con：這個選項的外觀與已定義設定欄位的結構體/資料表/對應語意不同。在 JSON 中，字串鍵指向值的值通常由地圖/物件表示。
- 缺點：更詳細
方法 C：
config: {
<key>: "<type string>"
...
}
- 專業：更簡潔
- Con： 保留空場，方便日後延長欄位使用。這可能需要處理複雜的類型和預設值。
方法 D：
config: [
{
<type string>: "<key>",
...
},
],
- 專家：更簡潔，沒有任何樣板「type」或「key」關鍵字
- 優點：與能力轉送語法一致
- 缺點：重複的金鑰需要明確檢查
- 缺點：不清楚這如何與向量的
element類型引數搭配運作
未來的工作
資訊清單資料分割中的結構化設定
我們會延後這項工作，直到證明作業確實必要為止。我們也沒有處理合併衝突的適當策略。如果合併衝突停止編譯，則每個資料分割都必須為設定欄位命名。如果可以解決合併衝突，不同的資料分割可能會無意間共用相同的設定欄位。
設定結構定義中的預設值
您可以在設定欄位中使用預設值。這些預設值將以 JSON 類型說明。RFC-0127 會假設預設值應為設定結構定義的一部分，但目前產生設定檔值檔案讓建構規則或子組合更適合提供預設值。
config: {
enable_advanced_features: {
type: "bool",
default: false,
}
tags: {
type: "vector",
max_count: 10,
element: {
type: "string",
max_size: 20,
}
default: [
"foo",
"bar",
"baz",
]
}
}
我們會延後這項工作，直到可以證明子組件系統無法用於預設值為止。
複雜資料類型
我們預計日後會支援 array、enum、float 和 struct 等複雜類型。vector 應支援這些類型，並可能盡可能執行其他驗證步驟。
config: {
fsck: {
type: "struct",
fields: {
check_on_mount: { type: "bool" },
verify_hard_links: { type: "bool" },
repair_errors: { type: "bool" },
}
},
compression_type: {
type: "enum",
variants: {
uncompressed: 0,
zstd_chunked: 1,
}
},
// Vectors can store complex structures
coordinates: {
type: "vector",
max_count: 10,
element: {
type: "struct",
fields: {
x: { type: "int32" },
y: { type: "int32" },
}
}
},
}
設定欄位註解工具
上述範例的設定欄位包含 JSON 註解，詳細說明設定欄位。系統可以處理這些註解，並新增至結構化設定的其他區域。一種可以想像，在 Rust 和 C++ 中產生的用戶端程式庫會有相同的說明。
這樣一來，如果開發人員編寫用戶端程式碼，就會在編輯器中收到這些說明做為提示。系統組合等工具也能提供更詳細的說明和錯誤文字。
這麼做需要變更 JSON 剖析程式庫 (目前不會剖析 JSON 註解)。
config: {
/// Add a tag to the allow list. Log entries with matching tags will be output to
/// the console. If no tags are specified, all log entries will be printed.
allowed_log_tags: {
type: "vector",
max_count: 40,
element: {
type: "string",
max_size: 40,
}
},
/// Add a tag to the deny list. Log entries with matching tags will be prevented
/// from being output to the console. This takes precedence over the allow list.
denied_log_tags: {
type: "vector",
max_count: 40,
element: {
type: "string",
max_size: 40,
}
},
}
max_size 和 max_count 支援的最大值
資訊清單可能會需要使用向量和字串中 max_size 和 max_count 屬性的支援最大值。只要使用 MAX 字串，或直接省略屬性即可。
config: {
network_id: {
type: "string",
max_size: "MAX",
}
}
config: {
tags: {
type: "vector",
element: {
type: "string"
}
}
}