[spr] initial version

Created using spr 1.3.6-beta.1

Author: sunshowers

crates/dropshot-api-manager/README.md

@@ -163,7 +163,7 @@ For extra validation on some documents, it's recommended that you put them on th
 
 1. In the API crate, add dependencies on `openapiv3` and `dropshot-api-manager-types`.
 2. Define a function with signature `fn validate_api(spec: &openapiv3::OpenAPI, mut cx: dropshot_api_manager_types::ValidationContext<'_>) which performs the extra validation steps.
-3. In the list of managed APIs, set the `extra_validation` field to this function.
+3. Convert the `ManagedApiConfig` to a `ManagedApi` and call the `with_extra_validation` builder method with this function.
 
 Currently, the validator can do two things:
 

crates/dropshot-api-manager/src/apis.rs

@@ -7,7 +7,12 @@ use dropshot_api_manager_types::{
     ValidationContext, Versions,
 };
 use openapiv3::OpenAPI;
-use std::collections::{BTreeMap, BTreeSet};
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fmt,
+};
+
+use crate::validation::DynValidationFn;
 
 /// Describes an API managed by the Dropshot API manager.
 ///
@@ -36,22 +41,13 @@ pub struct ManagedApiConfig {
     /// server implementation.
     pub api_description:
         fn() -> Result<ApiDescription<StubContext>, ApiDescriptionBuildErrors>,
-
-    /// Extra validation to perform on the OpenAPI document, if any.
-    ///
-    /// For versioned APIs, extra validation is performed on *all* versions,
-    /// including blessed ones. You may want to skip performing validation on
-    /// blessed versions, though, because they're immutable. To do so, use
-    /// [`ValidationContext::is_blessed`].
-    pub extra_validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
 }
 
 /// Describes an API managed by the Dropshot API manager.
 ///
 /// This type is typically created from a [`ManagedApiConfig`] and can be
 /// further configured using builder methods before being passed to
 /// [`ManagedApis::new`].
-#[derive(Debug)]
 pub struct ManagedApi {
     /// The API-specific part of the filename that's used for API descriptions
     ///
@@ -76,7 +72,12 @@ pub struct ManagedApi {
         fn() -> Result<ApiDescription<StubContext>, ApiDescriptionBuildErrors>,
 
     /// Extra validation to perform on the OpenAPI document, if any.
-    extra_validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    ///
+    /// For versioned APIs, extra validation is performed on *all* versions,
+    /// including blessed ones. You may want to skip performing validation on
+    /// blessed versions, though, because they're immutable. To do so, use
+    /// [`ValidationContext::is_blessed`].
+    extra_validation: Option<Box<DynValidationFn>>,
 
     /// If true, allow trivial changes (doc updates, type renames) for the
     /// latest blessed version without requiring version bumps.
@@ -85,15 +86,52 @@ pub struct ManagedApi {
     allow_trivial_changes_for_latest: bool,
 }
 
+impl fmt::Debug for ManagedApi {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let Self {
+            ident,
+            versions,
+            title,
+            metadata,
+            api_description: _,
+            extra_validation,
+            allow_trivial_changes_for_latest,
+        } = self;
+
+        f.debug_struct("ManagedApi")
+            .field("ident", ident)
+            .field("versions", versions)
+            .field("title", title)
+            .field("metadata", metadata)
+            .field("api_description", &"...")
+            .field(
+                "extra_validation",
+                &extra_validation.as_ref().map(|_| "..."),
+            )
+            .field(
+                "allow_trivial_changes_for_latest",
+                allow_trivial_changes_for_latest,
+            )
+            .finish()
+    }
+}
+
 impl From<ManagedApiConfig> for ManagedApi {
     fn from(value: ManagedApiConfig) -> Self {
+        let ManagedApiConfig {
+            ident,
+            versions,
+            title,
+            metadata,
+            api_description,
+        } = value;
         ManagedApi {
-            ident: ApiIdent::from(value.ident.to_owned()),
-            versions: value.versions,
-            title: value.title,
-            metadata: value.metadata,
-            api_description: value.api_description,
-            extra_validation: value.extra_validation,
+            ident: ApiIdent::from(ident.to_owned()),
+            versions,
+            title,
+            metadata,
+            api_description,
+            extra_validation: None,
             allow_trivial_changes_for_latest: false,
         }
     }
@@ -147,6 +185,20 @@ impl ManagedApi {
         self.allow_trivial_changes_for_latest
     }
 
+    /// Sets extra validation to perform on the OpenAPI document.
+    ///
+    /// For versioned APIs, extra validation is performed on *all* versions,
+    /// including blessed ones. You may want to skip performing validation on
+    /// blessed versions, though, because they're immutable. To do so, use
+    /// [`ValidationContext::is_blessed`].
+    pub fn with_extra_validation<F>(mut self, f: F) -> Self
+    where
+        F: Fn(&OpenAPI, ValidationContext<'_>) + Send + 'static,
+    {
+        self.extra_validation = Some(Box::new(f));
+        self
+    }
+
     pub(crate) fn iter_versioned_versions(
         &self,
     ) -> Option<impl Iterator<Item = &SupportedVersion> + '_> {
@@ -204,7 +256,7 @@ impl ManagedApi {
         openapi: &OpenAPI,
         validation_context: ValidationContext<'_>,
     ) {
-        if let Some(extra_validation) = self.extra_validation {
+        if let Some(extra_validation) = &self.extra_validation {
             extra_validation(openapi, validation_context);
         }
     }
@@ -214,11 +266,22 @@ impl ManagedApi {
 /// tool.
 ///
 /// This is repo-specific state that's passed into the OpenAPI manager.
-#[derive(Debug)]
 pub struct ManagedApis {
     apis: BTreeMap<ApiIdent, ManagedApi>,
     unknown_apis: BTreeSet<ApiIdent>,
-    validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    validation: Option<Box<DynValidationFn>>,
+}
+
+impl fmt::Debug for ManagedApis {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let Self { apis, unknown_apis, validation } = self;
+
+        f.debug_struct("ManagedApis")
+            .field("apis", apis)
+            .field("unknown_apis", unknown_apis)
+            .field("validation", &validation.as_ref().map(|_| "..."))
+            .finish()
+    }
 }
 
 impl ManagedApis {
@@ -268,17 +331,17 @@ impl ManagedApis {
     /// This function will be called for each API document. The
     /// [`ValidationContext`] can be used to report errors, as well as extra
     /// files for which the contents need to be compared with those on disk.
-    pub fn with_validation(
-        mut self,
-        validation: fn(&OpenAPI, ValidationContext<'_>),
-    ) -> Self {
-        self.validation = Some(validation);
+    pub fn with_validation<F>(mut self, validation: F) -> Self
+    where
+        F: Fn(&OpenAPI, ValidationContext<'_>) + Send + 'static,
+    {
+        self.validation = Some(Box::new(validation));
         self
     }
 
     /// Returns the validation function for all APIs.
-    pub fn validation(&self) -> Option<fn(&OpenAPI, ValidationContext<'_>)> {
-        self.validation
+    pub(crate) fn validation(&self) -> Option<&DynValidationFn> {
+        self.validation.as_deref()
     }
 
     /// Returns the number of APIs managed by this instance.

crates/dropshot-api-manager/src/resolved.rs

@@ -12,14 +12,13 @@ use crate::{
     spec_files_generated::{GeneratedApiSpecFile, GeneratedFiles},
     spec_files_generic::ApiFiles,
     spec_files_local::{LocalApiSpecFile, LocalFiles},
-    validation::{CheckStale, CheckStatus, overwrite_file, validate},
+    validation::{
+        CheckStale, CheckStatus, DynValidationFn, overwrite_file, validate,
+    },
 };
 use anyhow::{Context, anyhow};
 use camino::{Utf8Path, Utf8PathBuf};
-use dropshot_api_manager_types::{
-    ApiIdent, ApiSpecFileName, ValidationContext,
-};
-use openapiv3::OpenAPI;
+use dropshot_api_manager_types::{ApiIdent, ApiSpecFileName};
 use std::{
     collections::{BTreeMap, BTreeSet},
     fmt::{Debug, Display},
@@ -651,7 +650,7 @@ fn resolve_orphaned_local_specs<'a>(
 fn resolve_api<'a>(
     env: &'a ResolvedEnv,
     api: &'a ManagedApi,
-    validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    validation: Option<&DynValidationFn>,
     api_blessed: Option<&'a ApiFiles<BlessedApiSpecFile>>,
     api_generated: &'a ApiFiles<GeneratedApiSpecFile>,
     api_local: Option<&'a ApiFiles<Vec<LocalApiSpecFile>>>,
@@ -861,7 +860,7 @@ fn resolve_api<'a>(
 fn resolve_api_lockstep<'a>(
     env: &'a ResolvedEnv,
     api: &'a ManagedApi,
-    validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    validation: Option<&DynValidationFn>,
     api_generated: &'a ApiFiles<GeneratedApiSpecFile>,
     api_local: Option<&'a ApiFiles<Vec<LocalApiSpecFile>>>,
 ) -> BTreeMap<semver::Version, Resolution<'a>> {
@@ -934,7 +933,7 @@ struct ApiVersion<'a> {
 fn resolve_api_version<'a>(
     env: &'_ ResolvedEnv,
     api: &'_ ManagedApi,
-    validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    validation: Option<&DynValidationFn>,
     version: ApiVersion<'_>,
     blessed: Option<&'a BlessedApiSpecFile>,
     generated: &'a GeneratedApiSpecFile,
@@ -953,7 +952,7 @@ fn resolve_api_version<'a>(
 fn resolve_api_version_blessed<'a>(
     env: &'_ ResolvedEnv,
     api: &'_ ManagedApi,
-    validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    validation: Option<&DynValidationFn>,
     version: ApiVersion<'_>,
     blessed: &'a BlessedApiSpecFile,
     generated: &'a GeneratedApiSpecFile,
@@ -1052,7 +1051,7 @@ fn resolve_api_version_blessed<'a>(
 fn resolve_api_version_local<'a>(
     env: &'_ ResolvedEnv,
     api: &'_ ManagedApi,
-    validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    validation: Option<&DynValidationFn>,
     version: ApiVersion<'_>,
     generated: &'a GeneratedApiSpecFile,
     local: &'a [LocalApiSpecFile],
@@ -1093,7 +1092,7 @@ fn resolve_api_version_local<'a>(
 fn validate_generated(
     env: &ResolvedEnv,
     api: &ManagedApi,
-    validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    validation: Option<&DynValidationFn>,
     version: ApiVersion<'_>,
     generated: &GeneratedApiSpecFile,
     problems: &mut Vec<Problem<'_>>,

crates/dropshot-api-manager/src/spec_files_generic.rs

@@ -835,7 +835,6 @@ mod test {
                     ..ManagedApiMetadata::default()
                 },
                 api_description: unimplemented_fn,
-                extra_validation: None,
             },
             ManagedApiConfig {
                 ident: "versioned",
@@ -850,7 +849,6 @@ mod test {
                     ..ManagedApiMetadata::default()
                 },
                 api_description: unimplemented_fn,
-                extra_validation: None,
             },
         ];
 

crates/dropshot-api-manager/src/validation.rs

@@ -14,12 +14,16 @@ use dropshot_api_manager_types::{
 use openapiv3::OpenAPI;
 use std::io::Write;
 
+/// A validation function that can be called on an OpenAPI document.
+pub(crate) type DynValidationFn =
+    dyn Fn(&OpenAPI, ValidationContext<'_>) + Send;
+
 pub fn validate(
     env: &ResolvedEnv,
     api: &ManagedApi,
     is_latest: bool,
     is_blessed: Option<bool>,
-    validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    validation: Option<&DynValidationFn>,
     generated: &GeneratedApiSpecFile,
 ) -> anyhow::Result<Vec<(Utf8PathBuf, CheckStatus)>> {
     let openapi = generated.openapi();
@@ -49,7 +53,7 @@ fn validate_generated_openapi_document(
     file_name: &ApiSpecFileName,
     is_latest: bool,
     is_blessed: Option<bool>,
-    validation: Option<fn(&OpenAPI, ValidationContext<'_>)>,
+    validation: Option<&DynValidationFn>,
 ) -> anyhow::Result<ValidationResult> {
     let mut validation_context = ValidationContextImpl {
         ident: api.ident().clone(),