| // Copyright 2022 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| use anyhow::{bail, Context}; |
| use chrono::NaiveDate; |
| use itertools::Itertools; |
| use log::error; |
| use serde::de::{Error, Unexpected}; |
| use serde::{Deserialize, Deserializer, Serialize}; |
| use std::array::TryFromSliceError; |
| use std::collections::BTreeMap; |
| use std::fmt; |
| |
| const VERSION_HISTORY_SCHEMA_ID: &str = "https://fuchsia.dev/schema/version_history.json"; |
| const VERSION_HISTORY_NAME: &str = "Platform version map"; |
| const VERSION_HISTORY_TYPE: &str = "version_history"; |
| |
| /// An `ApiLevel` represents an API level of the Fuchsia platform. |
| #[derive(Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash, Copy, Clone)] |
| pub struct ApiLevel(u32); |
| |
| impl ApiLevel { |
| /// The `NEXT` API level, representing an unstable draft of the next |
| /// numbered stable API level. |
| pub const NEXT: ApiLevel = ApiLevel(4291821568); |
| |
| /// The `HEAD` API level, representing the bleeding edge of development. |
| pub const HEAD: ApiLevel = ApiLevel(4292870144); |
| |
| /// The `PLATFORM` pseudo-API level, which is used in platform builds. |
| pub const PLATFORM: ApiLevel = ApiLevel(4293918720); |
| |
| pub const fn from_u32(value: u32) -> Self { |
| Self(value) |
| } |
| |
| pub fn as_u32(&self) -> u32 { |
| self.0 |
| } |
| |
| #[deprecated = "API levels are 32-bits as of RFC-0246"] |
| pub fn as_u64(&self) -> u64 { |
| self.0 as u64 |
| } |
| } |
| |
| impl fmt::Debug for ApiLevel { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| match *self { |
| ApiLevel::NEXT => write!(f, "ApiLevel::NEXT"), |
| ApiLevel::HEAD => write!(f, "ApiLevel::HEAD"), |
| ApiLevel::PLATFORM => write!(f, "ApiLevel::PLATFORM"), |
| ApiLevel(l) => f.debug_tuple("ApiLevel").field(&l).finish(), |
| } |
| } |
| } |
| |
| impl fmt::Display for ApiLevel { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| match *self { |
| ApiLevel::NEXT => write!(f, "NEXT"), |
| ApiLevel::HEAD => write!(f, "HEAD"), |
| ApiLevel::PLATFORM => write!(f, "PLATFORM"), |
| ApiLevel(l) => write!(f, "{}", l), |
| } |
| } |
| } |
| |
| impl std::str::FromStr for ApiLevel { |
| type Err = std::num::ParseIntError; |
| |
| fn from_str(s: &str) -> Result<Self, Self::Err> { |
| match s { |
| "NEXT" => Ok(ApiLevel::NEXT), |
| "HEAD" => Ok(ApiLevel::HEAD), |
| "PLATFORM" => Ok(ApiLevel::PLATFORM), |
| s => Ok(ApiLevel::from_u32(s.parse()?)), |
| } |
| } |
| } |
| |
| impl From<u32> for ApiLevel { |
| fn from(api_level: u32) -> ApiLevel { |
| ApiLevel(api_level) |
| } |
| } |
| |
| impl From<&u32> for ApiLevel { |
| fn from(api_level: &u32) -> ApiLevel { |
| ApiLevel(*api_level) |
| } |
| } |
| |
| impl From<ApiLevel> for u32 { |
| fn from(api_level: ApiLevel) -> u32 { |
| api_level.0 |
| } |
| } |
| |
| /// An `AbiRevision` is the 64-bit stamp representing an ABI revision of the |
| /// Fuchsia platform. |
| #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Copy, Clone)] |
| pub struct AbiRevision(u64); |
| |
| /// An AbiRevisionExplanation represents the information that can be extracted |
| /// from a raw ABI revision just based on the 64-bit number itself. |
| /// |
| /// See //build/sdk/generate_version_history for the code that generates special |
| /// ABI revisions, and the precise definitions of the fields below. |
| #[derive(Debug, Copy, Clone, Eq, PartialEq)] |
| pub enum AbiRevisionExplanation { |
| /// This is a normal ABI revision, selected randomly. It should correspond |
| /// to a normal API level. |
| Normal, |
| |
| /// This is an unstable ABI revision targeted by platform components. |
| Platform { |
| /// Approximate date of the `integration.git` revision at which the |
| /// package was built. |
| date: chrono::NaiveDate, |
| /// Prefix of an `integration.git` revision from around the same time |
| /// that the package was built. |
| git_revision: u16, |
| }, |
| |
| /// This is an unstable ABI revision targeted by components built with the |
| /// SDK. This corresponds to API levels like `NEXT` and `HEAD`. |
| Unstable { |
| /// Approximate date of the `integration.git` revision from which the |
| /// SDK that built the package was built. |
| date: chrono::NaiveDate, |
| /// Prefix of an `integration.git` revision from around the same time |
| /// that the SDK that built the package was built. |
| git_revision: u16, |
| }, |
| |
| /// This ABI revision is exactly AbiRevision::INVALID, which is 2^64-1. |
| Invalid, |
| |
| /// This is a special ABI revision with an unknown meaning. Presumably it |
| /// was introduced sometime after this code was compiled. |
| Malformed, |
| } |
| |
| impl AbiRevision { |
| /// An ABI revision that is never supported by the platform. To be used when |
| /// an ABI revision is necessary, but none makes sense. |
| pub const INVALID: AbiRevision = AbiRevision(0xFFFF_FFFF_FFFF_FFFF); |
| |
| pub const PATH: &'static str = "meta/fuchsia.abi/abi-revision"; |
| |
| /// Parse the ABI revision from little-endian bytes. |
| pub fn from_bytes(b: [u8; 8]) -> Self { |
| AbiRevision(u64::from_le_bytes(b)) |
| } |
| |
| /// Encode the ABI revision into little-endian bytes. |
| pub fn as_bytes(&self) -> [u8; 8] { |
| self.0.to_le_bytes() |
| } |
| |
| pub const fn from_u64(u: u64) -> AbiRevision { |
| AbiRevision(u) |
| } |
| |
| pub fn as_u64(&self) -> u64 { |
| self.0 |
| } |
| |
| pub fn explanation(self) -> AbiRevisionExplanation { |
| // ABI revisions beginning with 0xFF are "special". |
| const SPECIAL_ABI_REVISION_PREFIX: u64 = 0xFF; |
| const UNSTABLE_ABI_REVISION_PREFIX: u64 = 0xFF00; |
| const PLATFORM_ABI_REVISION_PREFIX: u64 = 0xFF01; |
| |
| // Extract the date from an unstable or platform ABI revision. |
| let get_date = || { |
| // The lower 32 bits of an unstable or platform ABI revision encode |
| // the date. |
| const DATE_MASK: u64 = 0x0000_0000_FFFF_FFFF; |
| let date_ordinal = (self.as_u64() & DATE_MASK) as i32; |
| chrono::NaiveDate::from_num_days_from_ce_opt(date_ordinal).unwrap_or_default() |
| }; |
| |
| // Extract the Git revision prefix from an unstable or platform ABI |
| // revision. |
| let get_git_revision = || { |
| // The second most significant 16 bits are a prefix of the |
| // `integration.git` hash. |
| const GIT_HASH_MASK: u64 = 0x0000_FFFF_0000_0000; |
| ((self.as_u64() & GIT_HASH_MASK) >> 32) as u16 |
| }; |
| |
| if self.as_u64() >> 56 != SPECIAL_ABI_REVISION_PREFIX { |
| AbiRevisionExplanation::Normal |
| } else if self.as_u64() >> 48 == UNSTABLE_ABI_REVISION_PREFIX { |
| AbiRevisionExplanation::Unstable { date: get_date(), git_revision: get_git_revision() } |
| } else if self.as_u64() >> 48 == PLATFORM_ABI_REVISION_PREFIX { |
| AbiRevisionExplanation::Platform { date: get_date(), git_revision: get_git_revision() } |
| } else if self == AbiRevision::INVALID { |
| AbiRevisionExplanation::Invalid |
| } else { |
| AbiRevisionExplanation::Malformed |
| } |
| } |
| } |
| |
| impl fmt::Display for AbiRevision { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| // TODO(https://fxbug.dev/370727480): Pad to 16 digits and add 0x prefix. |
| write!(f, "{:x}", self.0) |
| } |
| } |
| |
| impl std::str::FromStr for AbiRevision { |
| type Err = std::num::ParseIntError; |
| |
| fn from_str(s: &str) -> Result<Self, Self::Err> { |
| let parsed = if let Some(s) = s.strip_prefix("0x") { |
| u64::from_str_radix(&s, 16)? |
| } else { |
| u64::from_str_radix(&s, 10)? |
| }; |
| Ok(AbiRevision::from_u64(parsed)) |
| } |
| } |
| |
| impl<'de> Deserialize<'de> for AbiRevision { |
| fn deserialize<D>(deserializer: D) -> Result<AbiRevision, D::Error> |
| where |
| D: Deserializer<'de>, |
| { |
| let s = String::deserialize(deserializer)?; |
| s.parse().map_err(|_| D::Error::invalid_value(Unexpected::Str(&s), &"an unsigned integer")) |
| } |
| } |
| |
| impl Serialize for AbiRevision { |
| fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> |
| where |
| S: serde::Serializer, |
| { |
| let string = format!("0x{:016x}", self.0); |
| serializer.serialize_str(&string) |
| } |
| } |
| |
| impl From<u64> for AbiRevision { |
| fn from(abi_revision: u64) -> AbiRevision { |
| AbiRevision(abi_revision) |
| } |
| } |
| |
| impl From<&u64> for AbiRevision { |
| fn from(abi_revision: &u64) -> AbiRevision { |
| AbiRevision(*abi_revision) |
| } |
| } |
| |
| impl From<AbiRevision> for u64 { |
| fn from(abi_revision: AbiRevision) -> u64 { |
| abi_revision.0 |
| } |
| } |
| |
| impl From<[u8; 8]> for AbiRevision { |
| fn from(abi_revision: [u8; 8]) -> AbiRevision { |
| AbiRevision::from_bytes(abi_revision) |
| } |
| } |
| |
| impl TryFrom<&[u8]> for AbiRevision { |
| type Error = TryFromSliceError; |
| |
| fn try_from(abi_revision: &[u8]) -> Result<AbiRevision, Self::Error> { |
| let abi_revision: [u8; 8] = abi_revision.try_into()?; |
| Ok(AbiRevision::from_bytes(abi_revision)) |
| } |
| } |
| |
| /// Version represents an API level of the Fuchsia platform API. |
| /// |
| /// See |
| /// https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0239_platform_versioning_in_practice |
| /// for more details. |
| #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone)] |
| pub struct Version { |
| /// The number associated with this API level. |
| pub api_level: ApiLevel, |
| |
| /// The ABI revision associated with this API level. |
| pub abi_revision: AbiRevision, |
| |
| /// The Status denotes the current status of the API level. |
| pub status: Status, |
| } |
| |
| impl Version { |
| /// Returns true if this version is runnable - that is, whether components |
| /// targeting this version will be able to run on this device. |
| fn is_runnable(&self) -> bool { |
| match self.status { |
| Status::InDevelopment | Status::Supported => true, |
| Status::Unsupported => false, |
| } |
| } |
| } |
| |
| #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, PartialOrd, Ord, Hash)] |
| pub enum Status { |
| #[serde(rename = "in-development")] |
| InDevelopment, |
| #[serde(rename = "supported")] |
| Supported, |
| #[serde(rename = "unsupported")] |
| Unsupported, |
| } |
| |
| /// VersionHistory stores the history of Fuchsia API levels, and lets callers |
| /// query the support status of API levels and ABI revisions. |
| #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] |
| pub struct VersionHistory { |
| versions: &'static [Version], |
| } |
| |
| impl VersionHistory { |
| /// Outside of tests, callers should use the static [HISTORY] |
| /// instance. However, for testing purposes, you may want to build your own |
| /// hermetic "alternate history" that doesn't change over time. |
| /// |
| /// If you're not testing versioning in particular, and you just want an API |
| /// level/ABI revision that works, see |
| /// [get_example_supported_version_for_tests]. |
| pub const fn new(versions: &'static [Version]) -> Self { |
| VersionHistory { versions } |
| } |
| |
| /// The ABI revision for components and packages that are "part of the |
| /// platform" and never "move between releases". For example: |
| /// |
| /// - Packages produced by the platform build have this ABI revision. |
| /// - Components which are not packaged but are "part of the platform" |
| /// nonetheless (e.g. components loaded from bootfs) have this ABI |
| /// revision. |
| /// - Most packages produced by assembly tools have this ABI revision. |
| /// - The `update` package is a noteworthy exception, since it "moves |
| /// between releases", in that it is produced by assembly tools from one |
| /// Fuchsia release, and then later read by the OS from a previous |
| /// release (that is, the one performing the update). |
| pub fn get_abi_revision_for_platform_components(&self) -> AbiRevision { |
| self.version_from_api_level(ApiLevel::PLATFORM) |
| .expect("API Level PLATFORM not found!") |
| .abi_revision |
| } |
| |
| /// ffx currently presents information suggesting that the platform supports |
| /// a _single_ API level and ABI revision. This is misleading and should be |
| /// fixed. Until we do, we have to choose a particular Version for ffx to |
| /// present. |
| /// |
| /// TODO: https://fxbug.dev/326096999 - Remove this, or turn it into |
| /// something that makes more sense. |
| pub fn get_misleading_version_for_ffx(&self) -> Version { |
| self.runnable_versions() |
| .filter(|v| { |
| v.api_level != ApiLevel::NEXT |
| && v.api_level != ApiLevel::HEAD |
| && v.api_level != ApiLevel::PLATFORM |
| }) |
| .last() |
| .unwrap() |
| } |
| |
| /// API level to be used in tests that create components on the fly and need |
| /// to specify a supported API level or ABI revision, but don't particularly |
| /// care which. The returned [Version] will be consistent within a given |
| /// build, but may change from build to build. |
| pub fn get_example_supported_version_for_tests(&self) -> Version { |
| self.runnable_versions() |
| .filter(|v| { |
| v.api_level != ApiLevel::NEXT |
| && v.api_level != ApiLevel::HEAD |
| && v.api_level != ApiLevel::PLATFORM |
| }) |
| .last() |
| .unwrap() |
| } |
| |
| /// Check whether the platform supports building components that target the |
| /// given API level, and if so, returns the ABI revision associated with |
| /// that API level. |
| pub fn check_api_level_for_build( |
| &self, |
| api_level: ApiLevel, |
| ) -> Result<AbiRevision, ApiLevelError> { |
| let Some(version) = self.version_from_api_level(api_level) else { |
| return Err(ApiLevelError::Unknown { |
| api_level, |
| supported: self.runnable_versions().map(|v| v.api_level).collect(), |
| }); |
| }; |
| |
| if version.is_runnable() { |
| Ok(version.abi_revision) |
| } else { |
| Err(ApiLevelError::Unsupported { |
| version, |
| supported: self.runnable_versions().map(|v| v.api_level).collect(), |
| }) |
| } |
| } |
| |
| /// Check whether the operating system supports running components that |
| /// target the given ABI revision. |
| pub fn check_abi_revision_for_runtime( |
| &self, |
| abi_revision: AbiRevision, |
| ) -> Result<(), AbiRevisionError> { |
| if let Some(version) = self.version_from_abi_revision(abi_revision) { |
| if version.is_runnable() { |
| Ok(()) |
| } else { |
| Err(AbiRevisionError::Retired { |
| version, |
| supported_versions: self.supported_versions(), |
| }) |
| } |
| } else { |
| // We don't recognize this ABI revision... Look at its structure to |
| // understand what's going on. |
| match abi_revision.explanation() { |
| AbiRevisionExplanation::Platform { date, git_revision } => { |
| let (platform_date, platform_commit_hash) = self.platform_abi_info(); |
| Err(AbiRevisionError::PlatformMismatch { |
| abi_revision, |
| package_date: date, |
| package_commit_hash: git_revision, |
| platform_date, |
| platform_commit_hash, |
| }) |
| } |
| AbiRevisionExplanation::Unstable { date, git_revision } => { |
| let (platform_date, platform_commit_hash) = self.platform_abi_info(); |
| Err(AbiRevisionError::UnstableMismatch { |
| abi_revision, |
| package_sdk_date: date, |
| package_sdk_commit_hash: git_revision, |
| platform_date, |
| platform_commit_hash, |
| supported_versions: self.supported_versions(), |
| }) |
| } |
| AbiRevisionExplanation::Malformed => { |
| Err(AbiRevisionError::Malformed { abi_revision }) |
| } |
| AbiRevisionExplanation::Invalid => Err(AbiRevisionError::Invalid), |
| AbiRevisionExplanation::Normal => Err(AbiRevisionError::TooNew { |
| abi_revision, |
| supported_versions: self.supported_versions(), |
| }), |
| } |
| } |
| } |
| |
| fn runnable_versions(&self) -> impl Iterator<Item = Version> + '_ { |
| self.versions.iter().filter(|v| v.is_runnable()).cloned() |
| } |
| |
| fn supported_versions(&self) -> VersionVec { |
| VersionVec( |
| self.versions |
| .iter() |
| .filter(|v| match v.status { |
| Status::InDevelopment => false, |
| Status::Supported => true, |
| Status::Unsupported => false, |
| }) |
| .cloned() |
| .collect(), |
| ) |
| } |
| |
| fn version_from_abi_revision(&self, abi_revision: AbiRevision) -> Option<Version> { |
| self.versions.iter().find(|v| v.abi_revision == abi_revision).cloned() |
| } |
| |
| pub fn version_from_api_level(&self, api_level: ApiLevel) -> Option<Version> { |
| self.versions.iter().find(|v| v.api_level == api_level).cloned() |
| } |
| |
| fn platform_abi_info(&self) -> (NaiveDate, u16) { |
| if let Some(platform_version) = self.version_from_api_level(ApiLevel::PLATFORM) { |
| if let AbiRevisionExplanation::Platform { date, git_revision } = |
| platform_version.abi_revision.explanation() |
| { |
| return (date, git_revision); |
| } |
| } |
| error!( |
| "No PLATFORM API level found. This should never happen. |
| Returning bogus data instead of panicking." |
| ); |
| (NaiveDate::default(), 0) |
| } |
| } |
| |
| #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] |
| pub enum AbiRevisionError { |
| #[error( |
| "Unknown platform ABI revision: 0x{abi_revision}. |
| Found platform component from {package_date} (Git hash {package_commit_hash:x}). |
| Platform components must be from {platform_date} (Git hash {platform_commit_hash:x})" |
| )] |
| PlatformMismatch { |
| abi_revision: AbiRevision, |
| package_date: NaiveDate, |
| package_commit_hash: u16, |
| platform_date: NaiveDate, |
| platform_commit_hash: u16, |
| }, |
| #[error( |
| "Unknown NEXT or HEAD ABI revision: 0x{abi_revision}. |
| SDK is from {package_sdk_date} (Git hash {package_sdk_commit_hash:x}). |
| Expected {platform_date} (Git hash {platform_commit_hash:x}) |
| The following API levels are stable and supported:{supported_versions}" |
| )] |
| UnstableMismatch { |
| abi_revision: AbiRevision, |
| package_sdk_date: NaiveDate, |
| package_sdk_commit_hash: u16, |
| platform_date: NaiveDate, |
| platform_commit_hash: u16, |
| supported_versions: VersionVec, |
| }, |
| |
| #[error( |
| "Unknown ABI revision 0x{abi_revision}. It was probably created after |
| this platform or tool was built. The following API levels are stable and |
| supported:{supported_versions}" |
| )] |
| TooNew { abi_revision: AbiRevision, supported_versions: VersionVec }, |
| |
| #[error("Retired API level {} (0x{}) cannot run. |
| The following API levels are stable and supported:{supported_versions}", |
| .version.api_level, .version.abi_revision)] |
| Retired { version: Version, supported_versions: VersionVec }, |
| |
| #[error("Invalid ABI revision 0x{}.", AbiRevision::INVALID)] |
| Invalid, |
| |
| #[error("ABI revision 0x{abi_revision} has an unrecognized format.")] |
| Malformed { abi_revision: AbiRevision }, |
| } |
| |
| /// Wrapper for a vector of Versions with a nice implementation of Display. |
| #[derive(Debug, Clone, PartialEq, Eq)] |
| pub struct VersionVec(pub Vec<Version>); |
| |
| impl std::fmt::Display for VersionVec { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| for version in self.0.iter() { |
| write!(f, "\n└── {} (0x{})", version.api_level, version.abi_revision)?; |
| } |
| Ok(()) |
| } |
| } |
| |
| #[derive(Debug, Clone, PartialEq, Eq)] |
| pub enum ApiLevelError { |
| /// The user attempted to build a component targeting an API level that was |
| /// not recognized. |
| Unknown { api_level: ApiLevel, supported: Vec<ApiLevel> }, |
| |
| /// The user attempted to build a component targeting an API level that was |
| /// recognized, but is not supported for building. |
| Unsupported { version: Version, supported: Vec<ApiLevel> }, |
| } |
| |
| impl std::error::Error for ApiLevelError {} |
| |
| impl std::fmt::Display for ApiLevelError { |
| fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { |
| match self { |
| ApiLevelError::Unknown { api_level, supported } => { |
| write!( |
| f, |
| "Unknown target API level: {}. Is the SDK too old to support it? |
| The following API levels are supported: {}", |
| api_level, |
| supported.iter().join(", ") |
| ) |
| } |
| ApiLevelError::Unsupported { version, supported } => { |
| write!( |
| f, |
| "The SDK no longer supports API level {}. |
| The following API levels are supported: {}", |
| version.api_level, |
| supported.iter().join(", ") |
| ) |
| } |
| } |
| } |
| } |
| |
| #[derive(Deserialize)] |
| struct VersionHistoryDataJson { |
| name: String, |
| #[serde(rename = "type")] |
| element_type: String, |
| api_levels: BTreeMap<String, ApiLevelJson>, |
| special_api_levels: BTreeMap<String, SpecialApiLevelJson>, |
| } |
| |
| #[derive(Deserialize)] |
| struct VersionHistoryJson { |
| schema_id: String, |
| data: VersionHistoryDataJson, |
| } |
| |
| #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Deserialize)] |
| struct ApiLevelJson { |
| pub abi_revision: AbiRevision, |
| pub status: Status, |
| } |
| |
| #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Deserialize)] |
| struct SpecialApiLevelJson { |
| pub as_u32: u32, |
| pub abi_revision: AbiRevision, |
| pub status: Status, |
| } |
| |
| pub fn parse_version_history(bytes: &[u8]) -> anyhow::Result<Vec<Version>> { |
| let v: VersionHistoryJson = serde_json::from_slice(bytes)?; |
| |
| if v.schema_id != VERSION_HISTORY_SCHEMA_ID { |
| bail!("expected schema_id = {:?}; got {:?}", VERSION_HISTORY_SCHEMA_ID, v.schema_id) |
| } |
| if v.data.name != VERSION_HISTORY_NAME { |
| bail!("expected data.name = {:?}; got {:?}", VERSION_HISTORY_NAME, v.data.name) |
| } |
| if v.data.element_type != VERSION_HISTORY_TYPE { |
| bail!("expected data.type = {:?}; got {:?}", VERSION_HISTORY_TYPE, v.data.element_type,) |
| } |
| |
| let mut versions = Vec::new(); |
| |
| for (key, value) in v.data.api_levels { |
| versions.push(Version { |
| api_level: key.parse()?, |
| abi_revision: value.abi_revision, |
| status: value.status, |
| }); |
| } |
| |
| for (key, value) in v.data.special_api_levels { |
| let api_level: ApiLevel = |
| key.parse().with_context(|| format!("Unknown special API level: {}", key))?; |
| if api_level.as_u32() != value.as_u32 { |
| bail!( |
| "Special API level {} had unexpected numerical value {} (Expected {})", |
| api_level, |
| value.as_u32, |
| api_level.as_u32() |
| ) |
| } |
| versions.push(Version { |
| api_level, |
| abi_revision: value.abi_revision, |
| status: value.status, |
| }); |
| } |
| |
| versions.sort_by_key(|s| s.api_level); |
| |
| let Some(latest_api_version) = versions.last() else { |
| bail!("there must be at least one API level") |
| }; |
| |
| if latest_api_version.status == Status::Unsupported { |
| bail!("most recent API level must not be 'unsupported'") |
| } |
| |
| Ok(versions) |
| } |
| |
| #[cfg(test)] |
| mod tests { |
| use super::*; |
| |
| #[test] |
| fn test_parse_history_works() { |
| let expected_bytes = br#"{ |
| "data": { |
| "name": "Platform version map", |
| "type": "version_history", |
| "api_levels": { |
| "1":{ |
| "abi_revision":"0xBEBE3F5CAAA046D2", |
| "status":"supported" |
| }, |
| "2":{ |
| "abi_revision":"0x50cbc6e8a39e1e2c", |
| "status":"in-development" |
| } |
| }, |
| "special_api_levels": { |
| "NEXT": { |
| "as_u32": 4291821568, |
| "abi_revision": "0xFF0038FA031D0347", |
| "status": "in-development" |
| }, |
| "HEAD": { |
| "as_u32": 4292870144, |
| "abi_revision": "0xFF0038FA031D0348", |
| "status": "in-development" |
| }, |
| "PLATFORM": { |
| "as_u32": 4293918720, |
| "abi_revision": "0xFF01A9328DA0C138", |
| "status": "in-development" |
| } |
| } |
| }, |
| "schema_id": "https://fuchsia.dev/schema/version_history.json" |
| }"#; |
| |
| assert_eq!( |
| parse_version_history(&expected_bytes[..]).unwrap(), |
| vec![ |
| Version { |
| api_level: 1.into(), |
| abi_revision: 0xBEBE3F5CAAA046D2.into(), |
| status: Status::Supported |
| }, |
| Version { |
| api_level: 2.into(), |
| abi_revision: 0x50CBC6E8A39E1E2C.into(), |
| status: Status::InDevelopment |
| }, |
| Version { |
| api_level: ApiLevel::NEXT, |
| abi_revision: 0xFF0038FA031D0347.into(), |
| status: Status::InDevelopment |
| }, |
| Version { |
| api_level: ApiLevel::HEAD, |
| abi_revision: 0xFF0038FA031D0348.into(), |
| status: Status::InDevelopment |
| }, |
| Version { |
| api_level: ApiLevel::PLATFORM, |
| abi_revision: 0xFF01A9328DA0C138.into(), |
| status: Status::InDevelopment |
| }, |
| ], |
| ); |
| } |
| |
| #[test] |
| fn test_parse_history_rejects_invalid_schema() { |
| let expected_bytes = br#"{ |
| "data": { |
| "name": "Platform version map", |
| "type": "version_history", |
| "api_levels": {}, |
| "special_api_levels": {} |
| }, |
| "schema_id": "some-schema" |
| }"#; |
| |
| assert_eq!( |
| &parse_version_history(&expected_bytes[..]).unwrap_err().to_string(), |
| r#"expected schema_id = "https://fuchsia.dev/schema/version_history.json"; got "some-schema""# |
| ); |
| } |
| |
| #[test] |
| fn test_parse_history_rejects_invalid_name() { |
| let expected_bytes = br#"{ |
| "data": { |
| "name": "some-name", |
| "type": "version_history", |
| "api_levels": {}, |
| "special_api_levels": {} |
| }, |
| "schema_id": "https://fuchsia.dev/schema/version_history.json" |
| }"#; |
| |
| assert_eq!( |
| &parse_version_history(&expected_bytes[..]).unwrap_err().to_string(), |
| r#"expected data.name = "Platform version map"; got "some-name""# |
| ); |
| } |
| |
| #[test] |
| fn test_parse_history_rejects_invalid_type() { |
| let expected_bytes = br#"{ |
| "data": { |
| "name": "Platform version map", |
| "type": "some-type", |
| "api_levels": {}, |
| "special_api_levels": {} |
| }, |
| "schema_id": "https://fuchsia.dev/schema/version_history.json" |
| }"#; |
| |
| assert_eq!( |
| &parse_version_history(&expected_bytes[..]).unwrap_err().to_string(), |
| r#"expected data.type = "version_history"; got "some-type""# |
| ); |
| } |
| |
| #[test] |
| fn test_parse_history_rejects_invalid_versions() { |
| for (api_level, abi_revision, err) in [ |
| ( |
| "some-version", |
| "1", |
| "invalid digit found in string" , |
| ), |
| ( |
| "-1", |
| "1", |
| "invalid digit found in string" , |
| ), |
| ( |
| "1", |
| "some-revision", |
| "invalid value: string \"some-revision\", expected an unsigned integer at line 1 column 58", |
| ), |
| ( |
| "1", |
| "-1", |
| "invalid value: string \"-1\", expected an unsigned integer at line 1 column 47", |
| ), |
| ] { |
| let expected_bytes = serde_json::to_vec(&serde_json::json!({ |
| "data": { |
| "name": VERSION_HISTORY_NAME, |
| "type": VERSION_HISTORY_TYPE, |
| "api_levels": { |
| api_level:{ |
| "abi_revision": abi_revision, |
| "status": Status::InDevelopment, |
| } |
| }, |
| "special_api_levels": {}, |
| }, |
| "schema_id": VERSION_HISTORY_SCHEMA_ID, |
| })) |
| .unwrap(); |
| |
| assert_eq!(parse_version_history(&expected_bytes[..]).unwrap_err().to_string(), err); |
| } |
| } |
| |
| #[test] |
| fn test_parse_history_rejects_bogus_special_levels() { |
| let input = br#"{ |
| "data": { |
| "name": "Platform version map", |
| "type": "version_history", |
| "api_levels": {}, |
| "special_api_levels": { |
| "WACKY_WAVING_INFLATABLE_ARM_FLAILING_TUBE_MAN": { |
| "as_u32": 1234, |
| "abi_revision": "0x50cbc6e8a39e1e2c", |
| "status": "in-development" |
| } |
| } |
| }, |
| "schema_id": "https://fuchsia.dev/schema/version_history.json" |
| }"#; |
| |
| assert_eq!( |
| parse_version_history(&input[..]).unwrap_err().to_string(), |
| "Unknown special API level: WACKY_WAVING_INFLATABLE_ARM_FLAILING_TUBE_MAN" |
| ); |
| } |
| |
| #[test] |
| fn test_parse_history_rejects_misnumbered_special_levels() { |
| let input = br#"{ |
| "data": { |
| "name": "Platform version map", |
| "type": "version_history", |
| "api_levels": {}, |
| "special_api_levels": { |
| "HEAD": { |
| "as_u32": 1234, |
| "abi_revision": "0x50cbc6e8a39e1e2c", |
| "status": "in-development" |
| } |
| } |
| }, |
| "schema_id": "https://fuchsia.dev/schema/version_history.json" |
| }"#; |
| |
| assert_eq!( |
| parse_version_history(&input[..]).unwrap_err().to_string(), |
| "Special API level HEAD had unexpected numerical value 1234 (Expected 4292870144)" |
| ); |
| } |
| |
| #[test] |
| fn test_serialize_abi_revision() { |
| { |
| let abi = AbiRevision::from_u64(16); |
| let str = "\"0x0000000000000010\""; |
| assert_eq!(serde_json::to_string(&abi).unwrap(), str); |
| assert_eq!(serde_json::from_str::<AbiRevision>(str).unwrap(), abi); |
| } |
| { |
| let abi = AbiRevision::from_u64(0x58ea445e942a0004); |
| let str = "\"0x58ea445e942a0004\""; |
| assert_eq!(serde_json::to_string(&abi).unwrap(), str); |
| assert_eq!(serde_json::from_str::<AbiRevision>(str).unwrap(), abi); |
| } |
| } |
| |
| pub const FAKE_VERSION_HISTORY: VersionHistory = VersionHistory { |
| versions: &[ |
| Version { |
| api_level: ApiLevel::from_u32(4), |
| abi_revision: AbiRevision::from_u64(0x58ea445e942a0004), |
| status: Status::Unsupported, |
| }, |
| Version { |
| api_level: ApiLevel::from_u32(5), |
| abi_revision: AbiRevision::from_u64(0x58ea445e942a0005), |
| status: Status::Supported, |
| }, |
| Version { |
| api_level: ApiLevel::from_u32(6), |
| abi_revision: AbiRevision::from_u64(0x58ea445e942a0006), |
| status: Status::Supported, |
| }, |
| Version { |
| api_level: ApiLevel::from_u32(7), |
| abi_revision: AbiRevision::from_u64(0x58ea445e942a0007), |
| status: Status::Supported, |
| }, |
| Version { |
| api_level: ApiLevel::NEXT, |
| abi_revision: AbiRevision::from_u64(0xFF00_8C4D_000B_4751), |
| status: Status::InDevelopment, |
| }, |
| Version { |
| api_level: ApiLevel::HEAD, |
| abi_revision: AbiRevision::from_u64(0xFF00_8C4D_000B_4751), |
| status: Status::InDevelopment, |
| }, |
| Version { |
| api_level: ApiLevel::PLATFORM, |
| abi_revision: AbiRevision::from_u64(0xFF01_8C4D_000B_4751), |
| status: Status::InDevelopment, |
| }, |
| ], |
| }; |
| |
| #[test] |
| fn test_check_abi_revision() { |
| let supported_versions = |
| VersionVec(FAKE_VERSION_HISTORY.versions[1..4].iter().cloned().collect()); |
| |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_abi_revision_for_runtime(0xFF01_ABCD_000B_2224.into()), |
| Err(AbiRevisionError::PlatformMismatch { |
| abi_revision: 0xFF01_ABCD_000B_2224.into(), |
| package_date: NaiveDate::from_ymd_opt(1998, 9, 4).unwrap(), |
| package_commit_hash: 0xABCD, |
| platform_date: NaiveDate::from_ymd_opt(2024, 9, 24).unwrap(), |
| platform_commit_hash: 0x8C4D, |
| }) |
| ); |
| |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_abi_revision_for_runtime(0xFF00_ABCD_000B_2224.into()), |
| Err(AbiRevisionError::UnstableMismatch { |
| abi_revision: 0xFF00_ABCD_000B_2224.into(), |
| package_sdk_date: NaiveDate::from_ymd_opt(1998, 9, 4).unwrap(), |
| package_sdk_commit_hash: 0xABCD, |
| platform_date: NaiveDate::from_ymd_opt(2024, 9, 24).unwrap(), |
| platform_commit_hash: 0x8C4D, |
| supported_versions: supported_versions.clone() |
| }) |
| ); |
| |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_abi_revision_for_runtime(0x1234.into()), |
| Err(AbiRevisionError::TooNew { |
| abi_revision: 0x1234.into(), |
| supported_versions: supported_versions.clone() |
| }) |
| ); |
| |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_abi_revision_for_runtime(0x58ea445e942a0004.into()), |
| Err(AbiRevisionError::Retired { |
| version: FAKE_VERSION_HISTORY.versions[0].clone(), |
| |
| supported_versions: supported_versions.clone() |
| }) |
| ); |
| |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_abi_revision_for_runtime(AbiRevision::INVALID), |
| Err(AbiRevisionError::Invalid) |
| ); |
| |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_abi_revision_for_runtime(0xFF02_0000_0000_0000.into()), |
| Err(AbiRevisionError::Malformed { abi_revision: 0xFF02_0000_0000_0000.into() }) |
| ); |
| |
| FAKE_VERSION_HISTORY |
| .check_abi_revision_for_runtime(0x58ea445e942a0005.into()) |
| .expect("level 5 should be supported"); |
| FAKE_VERSION_HISTORY |
| .check_abi_revision_for_runtime(0x58ea445e942a0007.into()) |
| .expect("level 7 should be supported"); |
| } |
| |
| #[test] |
| fn test_pretty_print_abi_error() { |
| let supported_versions = |
| VersionVec(FAKE_VERSION_HISTORY.versions[1..4].iter().cloned().collect()); |
| |
| assert_eq!( |
| AbiRevisionError::PlatformMismatch { |
| abi_revision: 0xFF01_ABCD_000B_2224.into(), |
| package_date: NaiveDate::from_ymd_opt(1998, 9, 4).unwrap(), |
| package_commit_hash: 0xABCD, |
| platform_date: NaiveDate::from_ymd_opt(2024, 9, 24).unwrap(), |
| platform_commit_hash: 0x8C4D, |
| } |
| .to_string(), |
| "Unknown platform ABI revision: 0xff01abcd000b2224. |
| Found platform component from 1998-09-04 (Git hash abcd). |
| Platform components must be from 2024-09-24 (Git hash 8c4d)" |
| ); |
| |
| assert_eq!( |
| AbiRevisionError::UnstableMismatch { |
| abi_revision: 0xFF00_ABCD_000B_2224.into(), |
| package_sdk_date: NaiveDate::from_ymd_opt(1998, 9, 4).unwrap(), |
| package_sdk_commit_hash: 0xABCD, |
| platform_date: NaiveDate::from_ymd_opt(2024, 9, 24).unwrap(), |
| platform_commit_hash: 0x8C4D, |
| supported_versions: supported_versions.clone() |
| } |
| .to_string(), |
| "Unknown NEXT or HEAD ABI revision: 0xff00abcd000b2224. |
| SDK is from 1998-09-04 (Git hash abcd). |
| Expected 2024-09-24 (Git hash 8c4d) |
| The following API levels are stable and supported: |
| └── 5 (0x58ea445e942a0005) |
| └── 6 (0x58ea445e942a0006) |
| └── 7 (0x58ea445e942a0007)" |
| ); |
| |
| assert_eq!( |
| AbiRevisionError::TooNew { |
| abi_revision: 0x1234.into(), |
| supported_versions: supported_versions.clone() |
| } |
| .to_string(), |
| "Unknown ABI revision 0x1234. It was probably created after |
| this platform or tool was built. The following API levels are stable and |
| supported: |
| └── 5 (0x58ea445e942a0005) |
| └── 6 (0x58ea445e942a0006) |
| └── 7 (0x58ea445e942a0007)" |
| ); |
| assert_eq!( |
| AbiRevisionError::Retired { |
| version: FAKE_VERSION_HISTORY.versions[0].clone(), |
| supported_versions: supported_versions.clone() |
| } |
| .to_string(), |
| "Retired API level 4 (0x58ea445e942a0004) cannot run. |
| The following API levels are stable and supported: |
| └── 5 (0x58ea445e942a0005) |
| └── 6 (0x58ea445e942a0006) |
| └── 7 (0x58ea445e942a0007)" |
| ); |
| |
| assert_eq!( |
| AbiRevisionError::Invalid.to_string(), |
| "Invalid ABI revision 0xffffffffffffffff." |
| ); |
| |
| assert_eq!( |
| AbiRevisionError::Malformed { abi_revision: 0xFF02_0000_0000_0000.into() }.to_string(), |
| "ABI revision 0xff02000000000000 has an unrecognized format." |
| ); |
| } |
| |
| #[test] |
| fn test_pretty_print_api_error() { |
| let supported: Vec<ApiLevel> = |
| vec![5.into(), 6.into(), 7.into(), ApiLevel::NEXT, ApiLevel::HEAD, ApiLevel::PLATFORM]; |
| |
| assert_eq!( |
| ApiLevelError::Unknown { api_level: 42.into(), supported: supported.clone() } |
| .to_string(), |
| "Unknown target API level: 42. Is the SDK too old to support it? |
| The following API levels are supported: 5, 6, 7, NEXT, HEAD, PLATFORM", |
| ); |
| assert_eq!( |
| ApiLevelError::Unsupported { |
| version: FAKE_VERSION_HISTORY.versions[0].clone(), |
| supported: supported.clone() |
| } |
| .to_string(), |
| "The SDK no longer supports API level 4. |
| The following API levels are supported: 5, 6, 7, NEXT, HEAD, PLATFORM" |
| ); |
| } |
| |
| #[test] |
| fn test_check_api_level() { |
| let supported: Vec<ApiLevel> = |
| vec![5.into(), 6.into(), 7.into(), ApiLevel::NEXT, ApiLevel::HEAD, ApiLevel::PLATFORM]; |
| |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_api_level_for_build(42.into()), |
| Err(ApiLevelError::Unknown { api_level: 42.into(), supported: supported.clone() }) |
| ); |
| |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_api_level_for_build(4.into()), |
| Err(ApiLevelError::Unsupported { |
| version: FAKE_VERSION_HISTORY.versions[0].clone(), |
| supported: supported.clone() |
| }) |
| ); |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_api_level_for_build(6.into()), |
| Ok(0x58ea445e942a0006.into()) |
| ); |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_api_level_for_build(7.into()), |
| Ok(0x58ea445e942a0007.into()) |
| ); |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_api_level_for_build(ApiLevel::NEXT), |
| Ok(0xFF00_8C4D_000B_4751.into()) |
| ); |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_api_level_for_build(ApiLevel::HEAD), |
| Ok(0xFF00_8C4D_000B_4751.into()) |
| ); |
| assert_eq!( |
| FAKE_VERSION_HISTORY.check_api_level_for_build(ApiLevel::PLATFORM), |
| Ok(0xFF01_8C4D_000B_4751.into()) |
| ); |
| } |
| |
| #[test] |
| fn test_various_getters() { |
| assert_eq!( |
| FAKE_VERSION_HISTORY.get_abi_revision_for_platform_components(), |
| 0xFF01_8C4D_000B_4751.into() |
| ); |
| assert_eq!( |
| FAKE_VERSION_HISTORY.get_misleading_version_for_ffx(), |
| FAKE_VERSION_HISTORY.versions[3].clone() |
| ); |
| assert_eq!(FAKE_VERSION_HISTORY.get_misleading_version_for_ffx().api_level, 7.into()); |
| assert_eq!( |
| FAKE_VERSION_HISTORY.get_example_supported_version_for_tests(), |
| FAKE_VERSION_HISTORY.versions[FAKE_VERSION_HISTORY.versions.len() - 4].clone() |
| ); |
| assert_eq!( |
| FAKE_VERSION_HISTORY.get_example_supported_version_for_tests().api_level, |
| 7.into() |
| ); |
| } |
| |
| #[test] |
| fn test_explanations() { |
| let exp = |abi_revision| AbiRevision::from_u64(abi_revision).explanation(); |
| |
| assert_eq!(exp(0x1234_5678_9abc_deff), AbiRevisionExplanation::Normal); |
| assert_eq!( |
| exp(0xFF01_abcd_00ab_eeee), |
| AbiRevisionExplanation::Platform { |
| date: chrono::NaiveDate::from_num_days_from_ce_opt(0xab_eeee).unwrap(), |
| git_revision: 0xabcd |
| } |
| ); |
| assert_eq!( |
| exp(0xFF00_1234_0012_3456), |
| AbiRevisionExplanation::Unstable { |
| date: chrono::NaiveDate::from_num_days_from_ce_opt(0x12_3456).unwrap(), |
| git_revision: 0x1234 |
| } |
| ); |
| // 0xabcd_9876 is too large a date for chrono. Make sure we return a |
| // null date, rather than crashing. |
| assert_eq!( |
| exp(0xFF00_1234_abcd_9876), |
| AbiRevisionExplanation::Unstable { |
| date: chrono::NaiveDate::default(), |
| git_revision: 0x1234 |
| } |
| ); |
| assert_eq!( |
| exp(0xFF01_1234_abcd_9876), |
| AbiRevisionExplanation::Platform { |
| date: chrono::NaiveDate::default(), |
| git_revision: 0x1234 |
| } |
| ); |
| assert_eq!(exp(0xFFFF_FFFF_FFFF_FFFF), AbiRevisionExplanation::Invalid); |
| assert_eq!(exp(0xFFFF_FFFF_FFFF_FFFE), AbiRevisionExplanation::Malformed); |
| } |
| } |
