commentary + a few API tweaks

Author: hawkw

dev-tools/omdb/src/bin/omdb/db/sitrep.rs

@@ -290,7 +290,7 @@ async fn cmd_db_sitrep_show(
         ),
         Some(fm::SitrepVersion { version, time_made_current, .. }) => {
             let current_version =
-                datastore.fm_get_current_sitrep_version(&opctx).await;
+                datastore.fm_current_sitrep_version(&opctx).await;
             if matches!(current_version, Ok(Some(ref v)) if v.id == id) {
                 println!("    {STATUS:>WIDTH$}: this is the current sitrep!",);
             } else {

nexus/db-model/src/fm_sitrep.rs

@@ -2,7 +2,16 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
-//! Types for representing fault management sitreps in the database.
+//! Types for representing fault management situation reports (sitreps) in the
+//! database.
+//!
+//! The fault management sitrep, and the ways in which it is represented in
+//! CRDB, is described in detail in [RFD
+//! 603](https://rfd.shared.oxide.computer/rfd/0603).
+//!
+//! These types are used when inserting and reading sitreps in CRDB; when in
+//! use, the sitrep is represented as a [`nexus_types::fm::Sitrep`]. See the
+//! documentation in [`nexus_types::fm`] for more information.
 
 use crate::SqlU32;
 use crate::typed_uuid::DbTypedUuid;

nexus/db-queries/src/db/datastore/fm.rs

@@ -34,20 +34,23 @@ use omicron_uuid_kinds::SitrepUuid;
 use uuid::Uuid;
 
 impl DataStore {
-    pub async fn fm_get_current_sitrep_version(
+    /// Reads the current [sitrep version](fm::SitrepVersion) from CRDB.
+    ///
+    /// If no sitreps have been generated, this returns `None`.
+    pub async fn fm_current_sitrep_version(
         &self,
         opctx: &OpContext,
     ) -> Result<Option<fm::SitrepVersion>, Error> {
         opctx.authorize(authz::Action::ListChildren, &authz::FLEET).await?;
         let conn = self.pool_connection_authorized(opctx).await?;
         let version = self
-            .fm_get_current_sitrep_version_on_conn(&conn)
+            .fm_current_sitrep_version_on_conn(&conn)
             .await?
             .map(Into::into);
         Ok(version)
     }
 
-    async fn fm_get_current_sitrep_version_on_conn(
+    async fn fm_current_sitrep_version_on_conn(
         &self,
         conn: &async_bb8_diesel::Connection<DbConnection>,
     ) -> Result<Option<model::SitrepVersion>, Error> {
@@ -60,48 +63,60 @@ impl DataStore {
             .map_err(|e| public_error_from_diesel(e, ErrorHandler::Server))
     }
 
+    /// Reads the [`fm::SitrepMetadata`] describing the sitrep with the given
+    /// ID, if one exists.
     pub async fn fm_sitrep_metadata_read(
         &self,
         opctx: &OpContext,
         id: SitrepUuid,
-    ) -> Result<Option<fm::SitrepMetadata>, Error> {
+    ) -> Result<fm::SitrepMetadata, Error> {
         opctx.authorize(authz::Action::ListChildren, &authz::FLEET).await?;
         let conn = self.pool_connection_authorized(opctx).await?;
-        let meta = self
-            .fm_sitrep_metadata_read_on_conn(id, &conn)
-            .await?
-            .map(Into::into);
+        let meta =
+            self.fm_sitrep_metadata_read_on_conn(id, &conn).await?.into();
         Ok(meta)
     }
 
     async fn fm_sitrep_metadata_read_on_conn(
         &self,
         id: SitrepUuid,
         conn: &async_bb8_diesel::Connection<DbConnection>,
-    ) -> Result<Option<model::SitrepMetadata>, Error> {
+    ) -> Result<model::SitrepMetadata, Error> {
         sitrep_dsl::fm_sitrep
             .filter(sitrep_dsl::id.eq(id.into_untyped_uuid()))
             .select(model::SitrepMetadata::as_select())
             .first_async(conn)
             .await
             .optional()
-            .map_err(|e| public_error_from_diesel(e, ErrorHandler::Server))
+            .map_err(|e| public_error_from_diesel(e, ErrorHandler::Server))?
+            .ok_or_else(|| {
+                Error::non_resourcetype_not_found(format!("sitrep {id:?}"))
+            })
     }
 
+    /// Reads the *entire* current sitrep, along with its version.
+    ///
+    /// This is equivalent to reading the current sitrep version using
+    /// [`DataStore::fm_current_sitrep_version`], and then reading the sitrep
+    /// itself using [`DataStore::fm_sitrep_read_on_conn`].
+    ///
+    /// If this method returns `None`, there is no current sitrep, meaning that
+    /// no sitreps have been created.
     pub async fn fm_sitrep_read_current(
         &self,
         opctx: &OpContext,
-    ) -> Result<Option<(fm::SitrepVersion, fm::Sitrep)>, Error> {
+    ) -> Result<Option<(fm::SitrepVersion, Sitrep)>, Error> {
         let conn = self.pool_connection_authorized(opctx).await?;
         let version: fm::SitrepVersion =
-            match self.fm_get_current_sitrep_version_on_conn(&conn).await? {
+            match self.fm_current_sitrep_version_on_conn(&conn).await? {
                 Some(version) => version.into(),
                 None => return Ok(None),
             };
         let sitrep = self.fm_sitrep_read_on_conn(version.id, &conn).await?;
         Ok(Some((version, sitrep)))
     }
 
+    /// Reads the entire content of the sitrep with the provided ID, if one exists.
     pub async fn fm_sitrep_read(
         &self,
         opctx: &OpContext,
@@ -117,13 +132,8 @@ impl DataStore {
         id: SitrepUuid,
         conn: &async_bb8_diesel::Connection<DbConnection>,
     ) -> Result<Sitrep, Error> {
-        let metadata = self
-            .fm_sitrep_metadata_read_on_conn(id, &conn)
-            .await?
-            .ok_or_else(|| {
-                Error::non_resourcetype_not_found(format!("sitrep {id:?}"))
-            })?
-            .into();
+        let metadata =
+            self.fm_sitrep_metadata_read_on_conn(id, &conn).await?.into();
 
         // TODO(eliza): this is where we would read all the other sitrep data,
         // if there was any.

nexus/src/app/background/tasks/fm_sitrep_load.rs

@@ -81,7 +81,7 @@ impl SitrepLoader {
         let time_loaded = Utc::now();
         let current_version: SitrepVersion = match self
             .datastore
-            .fm_get_current_sitrep_version(opctx)
+            .fm_current_sitrep_version(opctx)
             .await
         {
             Ok(Some(version)) => version.into(),

nexus/types/src/fm.rs

@@ -3,14 +3,34 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 //! Fault management types.
+//!
+//! Of particular importance is the [`Sitrep`], which is the top-level data
+//! structure containing fault management state.
 
 use chrono::{DateTime, Utc};
 use omicron_uuid_kinds::{CollectionUuid, OmicronZoneUuid, SitrepUuid};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+/// A fault management situation report, or _sitrep_.
+///
+/// The sitrep is a data structure that represents a snapshot of the state of
+/// the system as understood by the control plane's fault management subsystem.
+/// At any point in time, a single sitrep is considered the "current" sitrep.
+/// Each sitrep records a _parent sitrep ID_, which indicates the sitrep that
+/// was current at the time that the sitrep was created.
+/// A sitrep may only be made current if its parent is the current sitrep.
+/// This ensures that there is a sequentially consistent history of sitreps.
+/// The fault management subsystem only considers data from the current sitrep
+/// when making decisions and diagnoses.
+///
+/// The sitrep, how it is represented in the database, and how the fault
+/// management subsystem creates and interacts with sitreps, is described in
+/// detail in [RFD 603](https://rfd.shared.oxide.computer/rfd/0603).
 #[derive(Clone, Debug, Eq, PartialEq, JsonSchema, Deserialize, Serialize)]
 pub struct Sitrep {
+    /// Metadata describing this sitrep, when it was created, its parent sitrep
+    /// ID, and which Nexus produced it.
     pub metadata: SitrepMetadata,
     // TODO(eliza): draw the rest of the sitrep
 }
@@ -25,19 +45,52 @@ impl Sitrep {
     }
 }
 
-#[derive(Clone, Debug, Eq, PartialEq, JsonSchema, Deserialize, Serialize)]
-pub struct SitrepVersion {
-    pub id: SitrepUuid,
-    pub version: u32,
-    pub time_made_current: DateTime<Utc>,
-}
-
+/// Metadata describing a sitrep.
+///
+/// This corresponds to the records stored in the `fm_sitrep` database table.
 #[derive(Clone, Debug, Eq, PartialEq, JsonSchema, Deserialize, Serialize)]
 pub struct SitrepMetadata {
+    /// The ID of this sitrep.
     pub id: SitrepUuid,
+
+    /// The ID of the parent sitrep.
+    ///
+    /// A sitrep's _parent_ is the sitrep that was current when the planning
+    /// phase that produced that sitrep ran. The parent sitrep is a planning
+    /// input that produced this sitrep.
+    ///
+    /// The parent sitrep ID is optional, because this sitrep _may_ be the first
+    /// sitrep ever generated by the system. However, once a current sitrep has
+    /// been set, no subsequent sitrep should be created without a parent.
     pub parent_sitrep_id: Option<SitrepUuid>,
+
+    /// The ID of the inventory collection that was used as planning input to
+    /// this sitrep.
+    ///
+    /// When generating a new sitrep, the fault manager should ensure that the
+    /// inventory collection it uses as input is at least as new as the parent
+    /// sitrep's inventory collection.
     pub inv_collection_id: CollectionUuid,
+
+    /// The Omicron zone UUID of the Nexus that generated this sitrep.
+    ///
+    /// This is intended for debugging purposes.
     pub creator_id: OmicronZoneUuid,
+
+    /// A human-readable (but mechanically generated) string describing the
+    /// reason(s) this sitrep was created.
+    ///
+    /// This is intended for debugging purposes.
     pub comment: String,
+
+    /// The time at which this sitrep was created.
     pub time_created: DateTime<Utc>,
 }
+
+/// An entry in the sitrep version history.
+#[derive(Clone, Debug, Eq, PartialEq, JsonSchema, Deserialize, Serialize)]
+pub struct SitrepVersion {
+    pub id: SitrepUuid,
+    pub version: u32,
+    pub time_made_current: DateTime<Utc>,
+}