[MGS] Add endpoints for host phase 1 flash hashing (#8593)

This builds on #8584. The main point of this PR is adding two new MGS
endpoints ("start" and "get status" for the async host phase1 hashing
operation); the bulk of the diff is adding a test that exercises the
simulator to show the expected behavior of these endpoints.

Author: jgallagher

Cargo.lock

@@ -60,6 +60,7 @@ progenitor::generate_api!(
     }),
     derives = [schemars::JsonSchema],
     patch = {
+        ComponentFirmwareHashStatus = { derives = [PartialEq, Eq, PartialOrd, Ord] },
         HostPhase2RecoveryImageId = { derives = [PartialEq, Eq, PartialOrd, Ord] },
         ImageVersion = { derives = [PartialEq, Eq, PartialOrd, Ord] },
         RotImageDetails = { derives = [PartialEq, Eq, PartialOrd, Ord] },

clients/gateway-client/src/lib.rs

@@ -16,7 +16,7 @@ use gateway_types::{
         SpState,
     },
     component_details::SpComponentDetails,
-    host::HostStartupOptions,
+    host::{ComponentFirmwareHashStatus, HostStartupOptions},
     ignition::{IgnitionCommand, SpIgnitionInfo},
     rot::{RotCfpa, RotCfpaSlot, RotCmpa, RotState},
     sensor::SpSensorReading,
@@ -259,6 +259,41 @@ pub trait GatewayApi {
         path: Path<PathSpComponent>,
     ) -> Result<HttpResponseOk<SpUpdateStatus>, HttpError>;
 
+    /// Start computing the hash of a given slot of a component.
+    ///
+    /// This endpoint is only valid for the `host-boot-flash` component.
+    ///
+    /// Computing the hash takes several seconds; callers should poll for results
+    /// using `sp_component_hash_firmware_get()`. In general they should call
+    /// `sp_component_hash_firmware_get()` first anyway, as the hashes are
+    /// cached in the SP and may already be ready.
+    #[endpoint {
+        method = POST,
+        path = "/sp/{type}/{slot}/component/{component}/hash/{firmware_slot}",
+    }]
+    async fn sp_component_hash_firmware_start(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<PathSpComponentFirmwareSlot>,
+    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;
+
+    /// Get a computed hash of a given slot of a component.
+    ///
+    /// This endpoint is only valid for the `host-boot-flash` component.
+    ///
+    /// Computing the hash takes several seconds; this endpoint returns the
+    /// current status. If the status is `HashNotStarted`, callers should start
+    /// hashing using `sp_component_hash_firmware_start()`. If the status is
+    /// `HashInProgress`, callers should wait a bit then call this endpoint
+    /// again.
+    #[endpoint {
+        method = GET,
+        path = "/sp/{type}/{slot}/component/{component}/hash/{firmware_slot}",
+    }]
+    async fn sp_component_hash_firmware_get(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<PathSpComponentFirmwareSlot>,
+    ) -> Result<HttpResponseOk<ComponentFirmwareHashStatus>, HttpError>;
+
     /// Abort any in-progress update an SP component
     ///
     /// Aborting an update to the SP itself is done via the component name
@@ -542,6 +577,19 @@ pub struct PathSpComponent {
     pub component: String,
 }
 
+#[derive(Deserialize, JsonSchema)]
+pub struct PathSpComponentFirmwareSlot {
+    /// ID for the SP that the gateway service translates into the appropriate
+    /// port for communicating with the given SP.
+    #[serde(flatten)]
+    pub sp: SpIdentifier,
+    /// ID for the component of the SP; this is the internal identifier used by
+    /// the SP itself to identify its components.
+    pub component: String,
+    /// Firmware slot of the component.
+    pub firmware_slot: u16,
+}
+
 #[derive(Deserialize, JsonSchema)]
 pub struct PathSpTaskDumpIndex {
     /// ID for the SP that the gateway service translates into the appropriate

gateway-api/src/lib.rs

@@ -56,3 +56,18 @@ impl From<StartupOptions> for HostStartupOptions {
         }
     }
 }
+
+#[derive(Serialize, Deserialize, JsonSchema)]
+#[serde(tag = "status", rename_all = "snake_case")]
+pub enum ComponentFirmwareHashStatus {
+    /// The hash is not available; the client must issue a separate request to
+    /// begin calculating the hash.
+    HashNotCalculated,
+    /// The hash is currently being calculated; the client should sleep briefly
+    /// then check again.
+    ///
+    /// We expect this operation to take a handful of seconds in practice.
+    HashInProgress,
+    /// The hash of the given firmware slot.
+    Hashed { sha256: [u8; 32] },
+}

gateway-types/src/host.rs

@@ -23,8 +23,10 @@ use dropshot::WebsocketEndpointResult;
 use dropshot::WebsocketUpgrade;
 use futures::TryFutureExt;
 use gateway_api::*;
+use gateway_messages::HfError;
 use gateway_messages::RotBootInfo;
 use gateway_messages::SpComponent;
+use gateway_messages::SpError;
 use gateway_sp_comms::HostPhase2Provider;
 use gateway_sp_comms::VersionedSpState;
 use gateway_sp_comms::error::CommunicationError;
@@ -36,6 +38,7 @@ use gateway_types::component::SpComponentList;
 use gateway_types::component::SpIdentifier;
 use gateway_types::component::SpState;
 use gateway_types::component_details::SpComponentDetails;
+use gateway_types::host::ComponentFirmwareHashStatus;
 use gateway_types::host::HostStartupOptions;
 use gateway_types::ignition::SpIgnitionInfo;
 use gateway_types::rot::RotCfpa;
@@ -536,6 +539,93 @@ impl GatewayApi for GatewayImpl {
         apictx.latencies.instrument_dropshot_handler(&rqctx, handler).await
     }
 
+    async fn sp_component_hash_firmware_start(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<PathSpComponentFirmwareSlot>,
+    ) -> Result<HttpResponseUpdatedNoContent, HttpError> {
+        let apictx = rqctx.context();
+
+        let PathSpComponentFirmwareSlot { sp, component, firmware_slot } =
+            path.into_inner();
+        let sp_id = sp.into();
+        let handler = async {
+            let sp = apictx.mgmt_switch.sp(sp_id)?;
+            let component = component_from_str(&component)?;
+
+            if component != SpComponent::HOST_CPU_BOOT_FLASH {
+                return Err(HttpError::for_bad_request(
+                    Some("RequestUnsupportedForComponent".to_string()),
+                    "Only the host boot flash can be hashed".into(),
+                ));
+            }
+
+            // The SP (reasonably!) returns a `HashInProgress` error if we try
+            // to start hashing while hashing is being calculated, but we're
+            // presenting an idempotent "start hashing if it isn't started"
+            // endpoint instead. Swallow that error.
+            match sp.start_host_flash_hash(firmware_slot).await {
+                Ok(())
+                | Err(CommunicationError::SpError(SpError::Hf(
+                    HfError::HashInProgress,
+                ))) => Ok(HttpResponseUpdatedNoContent()),
+                Err(err) => {
+                    Err(SpCommsError::SpCommunicationFailed { sp: sp_id, err }
+                        .into())
+                }
+            }
+        };
+        apictx.latencies.instrument_dropshot_handler(&rqctx, handler).await
+    }
+
+    async fn sp_component_hash_firmware_get(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<PathSpComponentFirmwareSlot>,
+    ) -> Result<HttpResponseOk<ComponentFirmwareHashStatus>, HttpError> {
+        let apictx = rqctx.context();
+
+        let PathSpComponentFirmwareSlot { sp, component, firmware_slot } =
+            path.into_inner();
+        let sp_id = sp.into();
+        let handler = async {
+            let sp = apictx.mgmt_switch.sp(sp_id)?;
+            let component = component_from_str(&component)?;
+
+            if component != SpComponent::HOST_CPU_BOOT_FLASH {
+                return Err(HttpError::for_bad_request(
+                    Some("RequestUnsupportedForComponent".to_string()),
+                    "Only the host boot flash can be hashed".into(),
+                ));
+            }
+
+            let status = match sp.get_host_flash_hash(firmware_slot).await {
+                // success
+                Ok(sha256) => ComponentFirmwareHashStatus::Hashed { sha256 },
+
+                // expected failure: hash needs to be calculated (or
+                // recalculated; either way the client operation is the same)
+                Err(CommunicationError::SpError(SpError::Hf(
+                    HfError::HashUncalculated | HfError::RecalculateHash,
+                ))) => ComponentFirmwareHashStatus::HashNotCalculated,
+
+                // expected failure: hashing is currently in progress; client
+                // needs to wait and try again later
+                Err(CommunicationError::SpError(SpError::Hf(
+                    HfError::HashInProgress,
+                ))) => ComponentFirmwareHashStatus::HashInProgress,
+
+                // other errors are failures
+                Err(err) => {
+                    return Err(HttpError::from(
+                        SpCommsError::SpCommunicationFailed { sp: sp_id, err },
+                    ));
+                }
+            };
+
+            Ok(HttpResponseOk(status))
+        };
+        apictx.latencies.instrument_dropshot_handler(&rqctx, handler).await
+    }
+
     async fn sp_component_update_abort(
         rqctx: RequestContext<Self::Context>,
         path: Path<PathSpComponent>,

gateway/src/http_entrypoints.rs

@@ -41,6 +41,7 @@ dropshot.workspace = true
 gateway-messages.workspace = true
 gateway-test-utils.workspace = true
 hubtools.workspace = true
+omicron-test-utils.workspace = true
 rand.workspace = true
 repo-depot-api.workspace = true
 sp-sim.workspace = true