[nexus] Add TUF repo list endpoint, make other endpoints conventional (#9106)

Built on top of #8897

These are breaking API changes and I won't merge until I have a PR up on
the CLI side that makes this all work.

### Add list endpoint and fix other ones

Made the endpoints match the other ones. Not married to the verb
`upload`, but `system_update_repository_update` felt a little silly.

```diff
-system_update_get_repository        GET      /v1/system/update/repository/{system_version}
-system_update_put_repository        PUT      /v1/system/update/repository
+system_update_repository_list       GET      /v1/system/update/repositories
+system_update_repository_upload     PUT      /v1/system/update/repositories
+system_update_repository_view       GET      /v1/system/update/repositories/{system_version}
```

### Standardize and simplify response types

What's responsible for this PR being so big is that I reworked these
endpoints to return a new `TufRepo` struct that is only the metadata and
no artifacts. The main reason for this was that the list endpoint would
have to pull artifacts for every repo in the list. The list is likely to
be small, so it's probably not a big deal, but it also seems that the
artifacts are not useful to the end user. Once the list endpoint was
simplified, it makes sense to return the same thing from the view and
update endpoints. The upload endpoint returns a `TufRepoUpload` which
has the `TufRepo` together with an indicator saying whether the repo
contents were new repo or already existed.

Author: david-crespo

Cargo.lock

@@ -53,6 +53,7 @@ use dropshot::RequestContext;
 use dropshot::ResultsPage;
 use dropshot::WhichPage;
 use schemars::JsonSchema;
+use semver::Version;
 use serde::Deserialize;
 use serde::Serialize;
 use serde::de::DeserializeOwned;
@@ -163,6 +164,54 @@ pub fn marker_for_name_or_id<T: SimpleIdentityOrName, Selector>(
     }
 }
 
+// Pagination by semantic version in ascending or descending order
+
+/// Scan parameters for resources that support scanning by semantic version
+#[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
+pub struct ScanByVersion<Selector = ()> {
+    #[serde(default = "default_version_sort_mode")]
+    sort_by: VersionSortMode,
+    #[serde(flatten)]
+    pub selector: Selector,
+}
+
+/// Supported sort modes when scanning by semantic version
+#[derive(Copy, Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum VersionSortMode {
+    /// Sort in increasing semantic version order (oldest first)
+    VersionAscending,
+    /// Sort in decreasing semantic version order (newest first)
+    VersionDescending,
+}
+
+fn default_version_sort_mode() -> VersionSortMode {
+    VersionSortMode::VersionDescending
+}
+
+impl<T> ScanParams for ScanByVersion<T>
+where
+    T: Clone + Debug + DeserializeOwned + JsonSchema + PartialEq + Serialize,
+{
+    type MarkerValue = Version;
+
+    fn direction(&self) -> PaginationOrder {
+        match self.sort_by {
+            VersionSortMode::VersionAscending => PaginationOrder::Ascending,
+            VersionSortMode::VersionDescending => PaginationOrder::Descending,
+        }
+    }
+
+    fn from_query(
+        p: &PaginationParams<Self, PageSelector<Self, Self::MarkerValue>>,
+    ) -> Result<&Self, HttpError> {
+        Ok(match p.page {
+            WhichPage::First(ref scan_params) => scan_params,
+            WhichPage::Next(PageSelector { ref scan, .. }) => scan,
+        })
+    }
+}
+
 /// See `dropshot::ResultsPage::new`
 fn page_selector_for<F, T, S, M>(
     item: &T,
@@ -313,6 +362,13 @@ pub type PaginatedByNameOrId<Selector = ()> = PaginationParams<
 pub type PageSelectorByNameOrId<Selector = ()> =
     PageSelector<ScanByNameOrId<Selector>, NameOrId>;
 
+/// Query parameters for pagination by semantic version
+pub type PaginatedByVersion<Selector = ()> =
+    PaginationParams<ScanByVersion<Selector>, PageSelectorByVersion<Selector>>;
+/// Page selector for pagination by semantic version
+pub type PageSelectorByVersion<Selector = ()> =
+    PageSelector<ScanByVersion<Selector>, Version>;
+
 pub fn id_pagination<'a, Selector>(
     pag_params: &'a DataPageParams<Uuid>,
     scan_params: &'a ScanById<Selector>,

common/src/api/external/http_pagination.rs

@@ -3427,6 +3427,10 @@ pub struct ServiceIcmpConfig {
     pub enabled: bool,
 }
 
+// TODO: move these TUF repo structs out of this file. They're not external
+// anymore after refactors that use views::TufRepo in the external API. They are
+// still used extensively in internal services.
+
 /// A description of an uploaded TUF repository.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
 pub struct TufRepoDescription {
@@ -3501,40 +3505,6 @@ pub struct TufArtifactMeta {
     pub sign: Option<Vec<u8>>,
 }
 
-/// Data about a successful TUF repo import into Nexus.
-#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
-#[serde(rename_all = "snake_case")]
-pub struct TufRepoInsertResponse {
-    /// The repository as present in the database.
-    pub recorded: TufRepoDescription,
-
-    /// Whether this repository already existed or is new.
-    pub status: TufRepoInsertStatus,
-}
-
-/// Status of a TUF repo import.
-///
-/// Part of `TufRepoInsertResponse`.
-#[derive(
-    Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema,
-)]
-#[serde(rename_all = "snake_case")]
-pub enum TufRepoInsertStatus {
-    /// The repository already existed in the database.
-    AlreadyExists,
-
-    /// The repository did not exist, and was inserted into the database.
-    Inserted,
-}
-
-/// Data about a successful TUF repo get from Nexus.
-#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
-#[serde(rename_all = "snake_case")]
-pub struct TufRepoGetResponse {
-    /// The description of the repository.
-    pub description: TufRepoDescription,
-}
-
 #[derive(
     Clone, Debug, Deserialize, JsonSchema, Serialize, PartialEq, ObjectIdentity,
 )]

common/src/api/external/mod.rs

@@ -12,7 +12,7 @@ use nexus_db_schema::schema::{
     tuf_artifact, tuf_repo, tuf_repo_artifact, tuf_trust_root,
 };
 use nexus_types::external_api::shared::TufSignedRootRole;
-use nexus_types::external_api::views;
+use nexus_types::external_api::views::{self, TufRepoUploadStatus};
 use omicron_common::{api::external, update::ArtifactId};
 use omicron_uuid_kinds::GenericUuid;
 use omicron_uuid_kinds::TufArtifactKind;
@@ -30,8 +30,6 @@ use uuid::Uuid;
 
 /// A description of a TUF update: a repo, along with the artifacts it
 /// contains.
-///
-/// This is the internal variant of [`external::TufRepoDescription`].
 #[derive(Debug, Clone)]
 pub struct TufRepoDescription {
     /// The repository.
@@ -64,7 +62,6 @@ impl TufRepoDescription {
         }
     }
 
-    /// Converts self into [`external::TufRepoDescription`].
     pub fn into_external(self) -> external::TufRepoDescription {
         external::TufRepoDescription {
             repo: self.repo.into_external(),
@@ -78,8 +75,6 @@ impl TufRepoDescription {
 }
 
 /// A record representing an uploaded TUF repository.
-///
-/// This is the internal variant of [`external::TufRepoMeta`].
 #[derive(
     Queryable, Identifiable, Insertable, Clone, Debug, Selectable, AsChangeset,
 )]
@@ -134,7 +129,6 @@ impl TufRepo {
         )
     }
 
-    /// Converts self into [`external::TufRepoMeta`].
     pub fn into_external(self) -> external::TufRepoMeta {
         external::TufRepoMeta {
             hash: self.sha256.into(),
@@ -156,6 +150,17 @@ impl TufRepo {
     }
 }
 
+impl From<TufRepo> for views::TufRepo {
+    fn from(repo: TufRepo) -> views::TufRepo {
+        views::TufRepo {
+            hash: repo.sha256.into(),
+            system_version: repo.system_version.into(),
+            file_name: repo.file_name,
+            time_created: repo.time_created,
+        }
+    }
+}
+
 #[derive(Queryable, Insertable, Clone, Debug, Selectable, AsChangeset)]
 #[diesel(table_name = tuf_artifact)]
 pub struct TufArtifact {
@@ -413,3 +418,24 @@ impl FromSql<Jsonb, diesel::pg::Pg> for DbTufSignedRootRole {
             .map_err(|e| e.into())
     }
 }
+
+// The following isn't a real model in the sense that it represents DB data,
+// but it is the return type of a datastore function. The main reason we can't
+// just use the view for this like we do with TufRepoUploadStatus is that
+// TufRepoDescription has a bit more info in it that we rely on in code outside
+// of the external API, like tests and internal APIs
+
+/// The return value of the tuf repo insert function
+pub struct TufRepoUpload {
+    pub recorded: TufRepoDescription,
+    pub status: TufRepoUploadStatus,
+}
+
+impl From<TufRepoUpload> for views::TufRepoUpload {
+    fn from(upload: TufRepoUpload) -> Self {
+        views::TufRepoUpload {
+            repo: upload.recorded.repo.into(),
+            status: upload.status,
+        }
+    }
+}

nexus/db-model/src/tuf_repo.rs

@@ -111,7 +111,7 @@ mod switch_port;
 mod target_release;
 #[cfg(test)]
 pub(crate) mod test_utils;
-mod update;
+pub mod update;
 mod user_data_export;
 mod utilization;
 mod v2p_mapping;