RFC-0100 - 產品中繼資料

RFC-0100：產品中繼資料
狀態已接受
區域
  • 開發人員
說明

產品中繼資料的標準表示法
變更
作者
審查人員
提交日期 (年/月)2021-04-30
審查日期 (年/月)2021-06-02

編輯此 RFC

編輯 RFC 中繼資料

摘要

Fuchsia 軟體開發套件 (SDK) 目前隨附為裝置設定檔中繼資料 (或本文件中為中繼資料)，其結構定義在 //build/sdk/meta/device_profile.json 中定義。中繼資料旨在說明可安裝在裝置上的系統映像檔和套件。我們發現結構定義不完整，需要翻新。此外，SDK 以外的工具現在需要中繼資料，並提高其重要性。

這個 RFC 將針對這項資訊導入新的結構定義，做為平台與工具之間的合約，以及日後更新該結構定義的程序。

提振精神

目前中繼資料會與 SDK 一併傳送。其中包含裝置名稱、該裝置的文字說明，以及可供使用者下載圖片和套件資訊的 URI。我們發現這個中繼資料難以保持在最新狀態和不完整，因此無法使用。

工具最終採用的映像檔和套件非官方慣例，或是可能會變動的硬式編碼假設 (例如用於下載的 URI 結構)。這會導致工具在這些慣例改變時容易毀損。

我們希望解決這些問題。我們會為中繼資料指定正式結構定義，以便工具使用。

當我們發布完整且易於使用的中繼資料時，SDK 使用者可以選擇要將哪個映像檔刷新到裝置上，或是透過模擬器啟動模擬器，而不需要 Fuchsia 基礎架構或 SDK 團隊提供的重大協助。SDK 開發人員擁有單一可靠資料來源，可向使用者呈現產品相關資訊。工具開發人員針對這類資訊的運用方式，有明確定義的合約。

更新難易度

中繼資料目前是以硬式編碼的方式寫入 SDK 產生作業中，且在每次發布新圖片時都須手動更新。因此，新增、重新命名或移除中繼資料很容易出錯。資訊會定期過時，甚至連不上資訊。

實際上，由於 SDK 使用者無法仰賴 SDK 隨附中繼資料的準確度，因此會在自己的工具中以硬式編碼的方式，編寫套件和圖片的位置，以及其他不雅的實作相關資訊。例如，除了網址硬式編碼外，樹狀結構外模擬器啟動作業也依賴未記錄的 images.json 檔案出現在系統映像檔中。

本提案為我們的中繼資料提供新的結構定義，我們預期外部使用者會加以使用。如此就能激勵我們更新。

完整度

現有的裝置中繼資料缺少重要詳細資料。例如，刷新裝置的工具需要分區名稱清單，以及需要寫入這些分區的檔案名稱。目前尚未正式進行，因此我們的發布內容和執行刷新的工具之間沒有合約。因此很難提供穩定性 / 相容性保證。

結合結構定義缺乏完整性和更新中繼資料的難度時，問題就會加劇。舉例來說，假設模擬器工具的假設範例希望確保模擬器啟動的架構與使用者要執行的映像檔相同。在不嘗試啟動映像檔的情況下，工具會如何知道特定位置的任何映像檔是否與特定架構相容？透過更新的結構定義，我們可以有一組描述映像檔架構及其位置的中繼資料。這樣一來，這項工具就能輕鬆為特定映像檔選擇正確的架構。

本提案將概述中繼資料的初始結構定義，並提供更新路徑，以確保更新具有關聯性。

設計

  • 為中繼資料定義新的結構定義。
  • 定義更新該結構定義的程序。
  • 在建構作業中產生遵循該結構定義的中繼資料，並樹狀結構內使用。
  • 在我們的 SDK 版本中，發布符合該結構定義的中繼資料，並將其放在樹狀結構外使用。
  • 提供標準工具和程式庫，這些程式庫會使用中繼資料來刷新的和模擬工作流程。

請注意，我們在這裡定義初始結構定義時，即使沒有額外的 RFC，也會允許演進過程，透過 API 與委員會審查進行。

定義

本文所述的定義如下：

  • 「結構定義」是中繼資料結構的正式說明。
  • 中繼資料是特定結構定義的具體例項化。
  • 構件是任何具體檔案或資料，通常由 URI 在中繼資料中參照。
  • 「資訊清單」是包含構件清單的中繼資料。
  • 「映像檔」是刷新實體裝置或啟動模擬器所需的一系列構件，
  • 「套件」是 Fuchsia 中的軟體發布單位，通常會以 Fuchsia ARchive (FAR) 檔案的形式封裝。
  • 「產品」是一種用來建立映像檔和套件的建構設定。
  • 「產品組合」是一組圖片和套件，是產品建構的輸出內容。
  • Target (裝置) 是用於執行產品的實體或虛擬 Fuchsia 裝置。

我們會使用 JSON 代表中繼資料。schemata 以 json-schema.org 定義的草稿 7 格式表示。

結構定義

本節詳細說明我們對結構定義的初始要求和初始變更。

初始結構定義的要求

  1. 中繼資料必須有不重複的名稱或 ID。
  2. 中繼資料必須包含使用者可理解的說明。
  3. 中繼資料結構定義必須建立版本。
  4. 中繼資料必須指定目標裝置硬體特性。其中至少應包含：
    1. 目標 CPU 架構，目前為 arm64 或 x64。
  5. 中繼資料必須指定一或多個產品套裝組合，每個產品組合都必須包含：
    1. 專屬名稱。
    2. 使用者容易理解的說明。
    3. 圖片組合。
    4. 套件。
  6. 中繼資料可能包含其他產品中繼資料，做為鍵/值組合，以協助使用者選取所需產品。這類中繼資料的範例包括建構類型 (使用者和 eng)、啟動類型 (一般與遭到逮捕)。
  7. 圖片或套件組合必須符合下列規定：
    1. 指定一或多個基準 URI。
      1. URI 中繼資料必須允許使用者指定特定格式。舉例來說，URI 存取權可能會封存 (tarball 或 zip) 或純文字。
      2. 使用此中繼資料的 SDK 工具必須支援 gs、http(s) 和 file URI 配置。您必須有 file URI，才能執行本機存取權。
      3. 如果構件可公開存取，使用該中繼資料的 SDK 工具不必通過驗證。
    2. 指定 flash 中繼資料，包括透過 Fastboot 通訊協定佈建裝置所需的充分詳細資料。
    3. 指定模擬器中繼資料，包含足夠的詳細資料，可在虛擬裝置上啟動映像檔。

漸進式結構定義更新

結構定義的演進方式將有幾項可能的調整方向。 例如：

  1. 實體硬體中繼資料可能包含裝置硬體功能，例如螢幕、鍵盤或指標裝置。
  2. 虛擬硬體中繼資料可能會指定足以佈建模擬器的虛擬裝置特性。

為了因應這種情況，結構定義已建立版本。版本是一個字串，每當新增或移除結構定義的元素時，版本都會隨之更新。工具可能會指定多個不同版本的結構定義，或者使用者可能需要改用舊版工具才能使用舊版結構定義。

為簡化版本之間的轉換，我們提議靈活的剖析和版本管理機制。我們引進了版本化信封，可簡化 JSON 剖析作業。剖析工具可以讀取版本欄位，同時忽略 JSON 文件的其餘部分。這項工具可讓工具為每個支援的結構定義版本選擇正確的剖析器。

建議您使用隨機產生的 8 位數十六進位數字，分別建立每個結構定義檔案的版本。所有現有結構定義檔案中的數字皆不得重複。為了防範衝突，建議您實作建構時間衝突偵測，以避免意外重複提交。

由於結構定義可能會透過 $ref 設施納入其他結構定義，因此我們建議將結構定義版本附加到結構定義檔案名稱。這不僅能夠區別常見檔案 (例如 //build/sdk/meta/common.json) 的多個版本，還會觸發參照網址結構定義的版本重新計算。

每個不相容的結構定義變更 (例如新增或移除必填欄位) 都會觸發版本重新計算。

我們允許透過 API 審查程序變更結構定義。結構定義變更屬於開發人員功能區。

實作

實作結構定義的主要重點在於將結構定義新增至 fuchsia.git，並確保其會經過 API 審查。還有兩個問題：「中繼資料產生在哪裡？」和「中繼資料使用在哪裡？」

一開始會產生裝置中繼資料：

  • fuchsia.git 中的 Fuchsia 版本；
  • 做為發布圖片的一部分，並由樹狀結構外使用
  • 。

在其他位置也可以產生此物件，特別是在 SDK 版本以外發布的圖片和套件。

ffx 工具大量會使用裝置中繼資料，這項工具會使用這些中繼資料刷新裝置並啟動模擬器。我們會透過 SDK 發布這個結構定義，因此 Fuchsia 樹狀結構以外的工具也可能會使用相關中繼資料。

透過這個方法，所有刷新和模擬工作流程 (無論是在樹狀結構內或樹狀結構外使用) 都會使用裝置中繼資料來指定規格。

這兩種措施都必須超出這個 RFC 範圍的設計。

常見結構定義

我們將擴充 Common.json 結構定義，如下所示。您沒有考慮到回溯不相容的問題，因為這不是不相容的變更。為求簡潔，下方省略 Common.json 中現有的定義。

為求簡潔，我們會省略檔案的原始內容，使用 ... 表示省略。

/** build/sdk/meta/common.json */
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "http://fuchsia.com/schemas/sdk/common.json",
  "definitions": {
    ...,
    "envelope": {
      "description": "A versioned envelope.",
      "type": "object",
      "properties": {
        "version": {"$ref": "#/definitions/version"},
        "data": {
          "description": "The payload."
         }
      },
      "required": [
        "version",
        "data"
      ],
      "additionalProperties": false
    },
    "versioned_sdk_element": {
      "type": "object",
      "allOf": [
        {"$ref": "#/definitions/envelope"},
        {
          "type": "object",
          "properties": {
            "data": {
              "oneOf": [
                {"$ref": "#/definitions/sdk_element"}
              ]
            }
          }
        }
      ]
    },
    "version": {
      "description": "An opaque version string. The string may include any characters. Tools must not attempt to draw any conclusions about inter version compatibility other than the version 'X' manifest complies with the version 'X' of the schema and is therefore parsable by the version 'X' parser. There are no guarantees, for example, a parser for version 'B' may be able to parse a JSON document versioned 'A'.",
      "type": "string",
      "minLength": 1
    },
  }
}

請注意，由於這個結構定義會定義我們使用的結構定義版本，因此不容易變更。工具必須讀取符合這個結構定義的檔案，才能瞭解封裝的 JSON。

裝置

由於裝置上可能會安裝多張圖片，因此我們在裝置硬體規格中納入了裝置硬體規格。裝置硬體規格有兩項用途：

  1. 說明執行映像檔的最低硬體需求。
  2. 它會指定專為執行映像檔而建立的虛擬 (模擬) 裝置。

我們為實體和虛擬裝置推出了兩個新版 SDK 元素。

舞出新方向

目前我們只關心實體裝置的 CPU 架構。日後的結構定義版本中會加入其他硬體屬性。為提供完整範例，下方的結構定義定義了信封結構定義和 sdk_element 結構定義1。

/** build/sdk/meta/physical_device-c906d79c.json */
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "http://fuchsia.com/schemas/sdk/physical_device-c906d79c.json",
  "description": "A physical device specification.",
  "type": "object",
  "allOf": [
    {"$ref": "common.json#/definitions/envelope"},
    {
      "type": "object",
      "properties": {
        "data": {
          "allOf": [
            {"$ref": "common.json#/definitions/sdk_element"},
            {
              "properties": {
                 "type": {
                   "allOf": [
                     {"$ref": "common.json#/definitions/type"},
                     {"enum": ["physical_device"]}
                   ]
                 }
              }
            },
            {"$ref": "hardware-f9928aa4391e2ae3644ce712074a1ef7.json#/definitions/requirements"}
          ]
        }
      }
    }
  ]
}

實體裝置規定結構定義

這個結構定義可讓我們表示裝置硬體需求。這樣一來，工具就能確保裝置硬體與我們會用來佈建的構件相符。目前，它只會說明 CPU 架構。

/** build/sdk/meta/hardware-c0a116ca.json */
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "definitions": {
        "requirements": {
            "properties": {
                "hardware": {
                    "additionalProperties": false,
                    "properties": {
                        "cpu": {
                            "additionalProperties": false,
                            "properties": {
                                "arch": {
                                    "oneOf": [
                                      {"$ref": "common.json#/definitions/target_arch"}
                                    ]
                                }
                            },
                            "required": ["arch"],
                            "type": "object"
                        }
                    },
                    "required": ["cpu"],
                    "type": "object"
                }
            },
            "required": ["hardware"],
            "type": "object"
        },
    },
    "description": "Hardware requirements for running a product image.",
    "id": "http://fuchsia.com/schemas/sdk/hardware-c0a116ca.json"
}

虛擬

虛擬裝置規格可讓我們選取適當的產品套裝組合，以便啟動模擬器。在日後的修訂版本中，我們會進一步開發結構定義，以設定模擬器。為舉例說明，以下的結構定義使用新定義的 versioned_sdk_element 結構定義。

/** build/sdk/meta/virtual_device-8a8e2ba9.json */
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "http://fuchsia.com/schemas/sdk/virtual_device-8a8e2ba9.json",
  "description": "A virtual device specification for launching emulators.",
  "type": "object",
  "allOf": [
    {"$ref": "common.json#/definitions/versioned_sdk_element"},
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "properties": {
             "type": {
               "allOf": [
                 {"$ref": "common.json#/definitions/type"},
                 {"enum": ["virtual_device"]}
               ]
             },
             "description": {"type": "string"},
             "virtual": {"$ref": "virtual_hardware-4c5d1a5d.json#/definitions/spec"}
          },
          "required": ["virtual"]
        }
      }
    }
  ]
}

虛擬裝置需求結構定義

虛擬硬體規格是用來在啟動模擬器時選取適當的產品套裝組合。

/** build/sdk/meta/virtual_hardware-4c5d1a5d.json */
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "http://fuchsia.com/schemas/sdk/virtual_hardware-4c5d1a5d.json",
  "description": "A virtual device specification for launching emulators.",
  "definitions": {
    "spec": {
      "emu": {
        "type": "object",
        "properties": {
          "cpu": {
            "type": "object",
            "properties": {
              "arch": {
                "oneOf": [
                  {"$ref": "common.json#/definitions/target_arch"}
                ]
              }
            },
            "required": ["arch"],
            "additionalProperties": false
          }
        },
        "required": ["cpu"],
        "additionalProperties": false
      }
    },
    "required": ["emu"]
    }
  }
}

產品組合

映像檔與套件組合可讓您存取裝置上安裝的軟體構件。

/** build/sdk/meta/product_bundle-514c2856.json */
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "http://fuchsia.com/schemas/sdk/product_bundle-514c2856.json",
  "description": "Artifacts required to boot and run software on a device.",
  "type": "object",
   "allOf": [
    {"$ref": "common.json#/definitions/versioned_sdk_element"},
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "properties": {
             "type": {
               "allOf": [
                 {"$ref": "common.json#/definitions/type"},
                 {"enum": ["product_bundle"]}
               ]
             },
             "description": {
               "description": "A human readable description of the product bundle.",
               "type": "string"
             },
             "device_refs": {
               "description": "A list of physical or virtual device names this product can run on.",
               "type": "array",
               "minItems": 1,
               "items": {
                   "type": "string",
                   "minLength": 1
               }
             },
             "metadata": {
               "description": "A list of key-value pairs describing product dimensions. Tools must not rely on the presence or absence of certain keys. Tools may display them to the human user in order to assist them in selecting a desired image or log them for the sake of analytics. Typical metadata keys are: build_info_board, build_info_product, is_debug.",
               "$ref": "common.json#/definitions/key_value_list"
             },
             "manifests": {
               "description": "Manifests describing how to boot the product on a device.",
               "flash": {"$ref": "flash_manifest-c85dbd8e.json#/definitions/manifest"},
               "emu": {"$ref": "emu_manifest-b0708439.json#/definitions/manifest"}
             },
             "images": {
               "description": "A list of system image bundles. Each image bundle must be equivalent to all others. I.e., all image bundle URIs are effectively mirrors of each other. Their formats may vary. Pick an entry that best suits your needs.",
               "type": "array",
               "minItems": 1,
               "items": {"$ref": "#/definitions/image_bundle"}
             },
             "packages": {
               "description": "A list of package bundles. Each package bundle must be equivalent to all otherwise. I.e., all package bundle URIs are effectively mirrors of each other. Their formats may vary. Pick an entry that best suits your needs.",
               "type": "array",
               "minItems": 1,
               "items": {"$ref": "#/definitions/package_bundle"}
             }
          },
          "required": ["device_refs", "manifests", "images", "packages"]
        }
      }
    }
  ],
  "definitions": {
    "image_bundle": {
      "description": "A set of artifacts necessary to provision a physical or virtual device",
      "type": "object",
      "properties": {
         "base_uri": {
           "description": "A base URI for accessing artifacts in the bundle.",
           "$ref": "#/definitions/bundle_uri"
         },
         "format": {
           "description": "Bundle format: files - a directory layout; tgz - a gzipped tarball. In case of the 'files' format, the base base path points to a directory. The manifest paths is relative to the directory. To get a full path append a path inside the manifest to base_uri. In case of the 'tgz' format, the base path points to the archive. The manifest path is relative within the archive."
           "enum": [
             "files",
             "tgz"
            ]
         }
      },
      "required": [
        "base_uri",
        "format"
      ],
      "additionalProperties": false
    },
    "package_bundle": {
      "description": "A set of artifacts necessary to run a physical or virtual device",
      "type": "object",
      "properties": {
         "repo_uri": {
           "description": "A package repository URI. This may be an archive or a directory.",
           "$ref": "#/definitions/bundle_uri"
         },
         "format": {
           "description": "Repository format: files - a directory layout; tgz - a gzipped tarball.",
           "enum" : [
             "files",
             "tgz"
           ]
         },
         "blob_uri": {
           "description": "An optional blob repository URI. If omitted, it is assumed to be <repo_uri>/blobs. If repo_uri refers to a gzipped tarball, ./blobs directory is expected to be found inside the tarball.",
           "$ref": "#/definitions/bundle_uri"
         }
      },
      "required": [
        "repo_uri",
        "format"
      ],
      "additionalProperties": false
    },
    "bundle_uri": {
      "description": "Allowed system image and package bundle URIs.",
      "type": "string",
      "format": "uri",
      "pattern": "^(?:http|https|gs|file):\/\/"
    }
  }
}

Flash 結構定義

以 Flash 結構定義為基礎的資訊清單，會描述刷新裝置所需的映像檔構件。資訊清單與建構產生的現有 flash.json 相符。Flash 中繼資料會嵌入產品套件 SDK 元素中。

/** build/sdk/meta/flash_manifest-c85dbd8e.json */
{

  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "http://fuchsia.com/schemas/sdk/flash_manifest-c85dbd8e.json",
  "description": "A manifest that describes how to flash a device.",
  "type": "object",
  "properties": {
    "manifest": {"$ref": "#/definitions/manifest"}
  },
  "required": ["manifest"],
  "additionalProperties": false,
  "definitions": {
    "manifest": {
      "description": "A named list of partitions and OEM files necessary to flash a device.",
      "type": "object",
      "properties": {
        "hw_revision" : {
          "description": "A board name used to verify whether the device can be flashed using this manifest.",
          "type": "string"
        },
        "products": {
          "description": "A list of product specifications that can be flashed onto the device.",
          "type": "array",
          "items": {"$ref": "#/definitions/product"},
          "minItems": 1
        }
      },
      "required": ["hw_revision", "products"],
      "additionalProperties": false
    },
    "product": {
      "description": "A named product specification.",
      "type": "object",
      "properties": {
        "name": {
          "description": "A unique name of this manifest.",
          "type": "string"
        },
        "partitions": {
          "description": "A list of partition names and file names corresponding to the partitions.",
          "$ref": "common.json#/definitions/key_value_list"
        },
        "bootloader_partitions": {
          "description": "A list of partition names and file names corresponding to the partitions.",
          "$ref": "common.json#/definitions/key_value_list"
        },
        "oem_files": {
          "description": "A list of OEM command and file names corresponding to the command.",
          "$ref": "common.json#/definitions/key_value_list"
        }
      },
      "required": ["name", "partitions"],
      "additionalProperties": false
    }
  }
}

模擬器結構定義

模擬器結構定義會指定在模擬器上啟動產品所需的映像檔構件。

/** build/sdk/meta/emu_manifest-b0708439.json */
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "http://fuchsia.com/schemas/sdk/emu_manifest-b0708439.json",
  "definitions": {
    "manifest": {
      "description": "A manifest that describes how to boot an emulator.",
      "type": "object",
      "properties": {
        "kernel": {
          "description": "A path to the kernel image file. The path is relative to the image bundle base.",
          "type": "string",
          "minLength": 1
        },
        "initial_ramdisk": {
          "description": "A path to the initial ramdisk, the kernel ZBI. The path is relative to the image bundle base.",
          "type": "string",
          "minLength": 1
        },
        "disk_images": {
          "description": "A list of one or more disk image paths to FVM images. Each path is relative to the image bundle base.",
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
          },
          "minItems": 1
        }
      },
      "required": ["kernel", "initial_ramdisk", "disk_images"],
      "additionalProperties": false
    }
  }
}

其他常見定義

下方是一般定義的額外補充內容。如要瞭解版本相關新增項目，請參閱 common.json 的相關章節。為求簡潔，以下在 common.json 中現有的定義省略。

/** build/sdk/meta/common.json */
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "http://fuchsia.com/schemas/sdk/common.json",
  "definitions": {
    ...,
   "key_value": {
     "description": "A key-value pair.",
      "type": "array",
      "items": [
        {"type": "string"},
        {"type": ["number", "string"]}
      ],
      "minItems": 2,
      "additionalItems": false
    },
    "key_value_list": {
      "description": "A list of key-value pairs.",
      "type": "array",
      "items": {"$ref": "#/definitions/key_value"}
    }

範例

裝置

實體裝置

以下是裝置硬體規格的範例。

{
  "version": "c906d79c",
  "data": {
    "type": "physical_device",
    "name": "generic-x64",
    "description": "A generic x64 device.",
    "hardware": {
      "cpu": {
        "arch": "x64"
      }
    }
  }
}

產品組合

實體裝置的終端機

這是一般終端機產品範例，可在一般 x64 裝置上啟動，當中包含兩個封存的鏡像，分別用於透過 gs 和 https 型 URI 存取的圖片和套件。

{
  "version": "514c2856",
  "data": {
    "type": "product_bundle",
    "name": "generic-x64",
    "description": "A terminal x64 product.",
    "device_refs": ["generic-x64"],
    "metadata": [
      ["build-type", "release"],
      ["product", "terminal"]
    ],
    "manifests": {
      "flash": {
        "hw_revision": "x64",
        "products" : [
          {
            "bootloader_partitions": [],
            "name": "fuchsia",
            "oem_files": [],
            "partitions": [
              ["", "fuchsia.zbi"],
              ["", "zedboot.zbi"],
              ["", "fuchsia.vbmeta"],
              ["", "zedboot.vbmeta"]
            ]
          }
        ]
      }
    },
    "images": [
      {
        "base_uri": "gs://fuchsia/development/0.20201216.2.1/images/generic-x64.tgz",
        "format": "tgz"
      },
      {
        "base_uri": "https://storage.googleapis.com/fuchsia/development/0.20201216.2.1/images/generic-x64.tgz",
        "format": "tgz"
      }
    ],
    "packages": [
      {
        "repo_uri": "gs://fuchsia/development/0.20201216.2.1/packages/generic-x64.tar.gz",
        "format": "tgz"
      },
      {
        "repo_uri": "https://storage.googleapis.com/fuchsia/development/0.20201216.2.1/packages/generic-x64.tar.gz",
        "format": "tgz"
      }
    ]
  }
}
模擬器上的終端機

這是可在 x64 模擬器中開機的一般終端產品示例。您可以直接透過 GCS 存取圖片和套件。

{
  "version": "514c2856",
  "data": {
    "type": "product_bundle",
    "name": "generic-x64",
    "description": "A terminal x64 product.",
    "device_refs": ["qemu-x64"],
    "metadata": [
      ["build-type" , "debug"],
      ["product", "terminal"]
    ],
    "manifests": {
      "emu": {
        "kernel": "qemu-kernel.kernel",
        "initial_ramdisk": "zircon-a.zbi",
        "disk_images": ["storage-sparse.blk"]
      }
    },
    "images": [
      {
        "base_uri": "https://storage.googleapis.com/fuchsia-artifacts/builds/8852232026486839104/images/",
        "format": "files"
      }
    ],
    "packages": [
      {
        "repo_uri": "https://storage.googleapis.com/fuchsia-artifacts/builds/8852232026486839104/packages/",
        "blob_repo_uri": "https://storage.googleapis.com/fuchsia-artifacts/blobs/",
        "format": "files"
      }
    ]
  }
}

效能

這不太可能對效能造成影響，因為產生及剖析中繼資料的做法不會耗用大量資源。

人體工學

發布標準化中繼資料時，無須使用繁瑣的硬式編碼設定，就能簡化整合作業。

我們選擇 JSON，因為它是知名的格式，也是 Fuchsia 設定檔的實際標準。JSON 結構定義格式經過正式化程序 並經由對等互連審查。

回溯相容性

由於現有的中繼資料沒有使用者，因此中繼資料推出不會影響回溯相容性。

這些結構定義的未來修訂版本將由 API 進行審查，並透過標準 LSC 程序管理，此程序涉及到高優先順序客戶進行測試和直接互動。這個程序會透過版本定義結構定義來協助執行這項程序。

安全性考量

根據這些結構定義的中繼資料，安全性不會低於現有解決方案 (這是針對類似資訊的臨時硬式編碼)。

我們會在這些結構定義的生命週期初期提高構件推送的安全性。視安全性團隊仍在進行中的回饋而定，這可能是在部署之前。重要的是，工具必須驗證已下載構件內容的完整性：構件必須是中繼資料發布時的預期目標。為此，您可以在結構定義中新增雜湊函式的輸出內容，或使用支援完整性檢查的通訊協定 (例如 TUF) 來完成這項操作。

屬於 Fuchsia SDK 的一部分，使用此結構定義並擷取構件時，必須導入額外的安全措施以確保傳輸安全，防止中間人等攻擊。方法是拒絕從不安全 / 不受信任的位置擷取或使用構件。

隱私權注意事項

這項提案沒有任何已知的隱私權考量。審查中繼資料的使用者或團隊可能會考量到隱私權，我們預計他們會自行進行隱私權審查。舉例來說，發布中繼資料的團隊可能需要審慎考量追蹤下載的方式。

測試

雖然結構定義的存在不需要測試，但我們仍會確保建構作業產生的中繼資料符合結構定義。我們也會進行相容性測試，確保工具會視需要持續使用舊版結構定義。

說明文件

目前未在結構定義之外規劃任何說明文件，不過可能會隨需求而改變。建立或更新結構定義的開發人員可能需要提供詞彙解釋、每個結構定義的使用方式，以及各結構定義如何互動。

缺點、替代方案和未知

我們會承諾使用特定的 API 來指定裝置映像檔。這有利於提高各版本的相容性、利用現有的變更管理程序，並讓我們能夠發布一致的工具，但這些工具雖然保持不變，但缺點是由於彈性降低 (因為生化障礙導致變更結構定義的時間較長)。

先前的圖片和參考資料

本文件會收集並處理整個樹狀結構中的常用設定，如上所述。您可以在 //build/images/BUILD.gn 中找到許多現有的中繼資料；例如，您可以在此找到目前的刷新結構定義版本。

  1. 所有中繼資料都會以 SDK 元素的形式發布。 ↩