Optimize gen openapi

Author: owjs3901

crates/vespera_macro/src/vespera_impl/cache.rs

@@ -14,10 +14,24 @@ use crate::{
 
 use super::path_utils::{current_crate_tag, find_target_dir};
 
+/// Current cache format. Bump when the on-disk layout changes —
+/// old caches deserialize with `cache_format: 0` (serde default) and
+/// are treated as a miss.
+pub(super) const CACHE_FORMAT: u32 = 1;
+
 /// Cache for avoiding redundant route scanning and OpenAPI generation.
 /// Persisted to `target/vespera/routes.cache` across builds.
+///
+/// The spec JSON strings themselves live in **sidecar files** (the
+/// `include_str!` embed file and the pretty sidecar) — the cache only
+/// stores their content hashes.  Embedding them inline as JSON strings
+/// doubled the cache size via escaping and dominated warm-rebuild
+/// `read_cache` time.
 #[derive(Serialize, Deserialize)]
 pub(super) struct VesperaCache {
+    /// On-disk layout version — see [`CACHE_FORMAT`].
+    #[serde(default)]
+    pub(super) cache_format: u32,
     /// Macro crate version — invalidates cache when macro code changes
     #[serde(default)]
     pub(super) macro_version: String,
@@ -35,10 +49,21 @@ pub(super) struct VesperaCache {
     pub(super) config_hash: u64,
     /// Cached route/struct metadata
     pub(super) metadata: CollectedMetadata,
-    /// Compact JSON for docs embedding (None if docs disabled)
-    pub(super) spec_json: Option<String>,
-    /// Pretty JSON for file output (None if no openapi file configured)
-    pub(super) spec_pretty: Option<String>,
+    /// Content hash of the compact spec in the embed sidecar file
+    /// (`vespera_spec-<tag>.json`).  `None` if docs disabled.
+    #[serde(default)]
+    pub(super) spec_json_hash: Option<u64>,
+    /// Content hash of the pretty spec in the pretty sidecar file
+    /// (`openapi_pretty-<tag>.json`).  `None` if no openapi file configured.
+    #[serde(default)]
+    pub(super) spec_pretty_hash: Option<u64>,
+}
+
+/// Deterministic content hash for sidecar spec validation.
+pub(super) fn hash_str(s: &str) -> u64 {
+    let mut hasher = std::collections::hash_map::DefaultHasher::new();
+    s.hash(&mut hasher);
+    hasher.finish()
 }
 
 /// Compute a deterministic hash of SCHEMA_STORAGE contents.
@@ -94,6 +119,15 @@ pub(super) fn get_cache_path() -> std::path::PathBuf {
 /// every `.rs` mtime in it; for downstream users the directory is
 /// absent and this is a single failed `stat` (returns 0).
 pub(super) fn compute_macro_dev_fingerprint() -> u64 {
+    // Memoized per proc-macro process: macro source mtimes cannot change
+    // the dll that is currently executing, so one scan per process is
+    // exactly as precise as one scan per invocation.  (A fresh cargo
+    // build of vespera_macro loads a fresh dll → fresh process state.)
+    static MEMO: std::sync::OnceLock<u64> = std::sync::OnceLock::new();
+    *MEMO.get_or_init(compute_macro_dev_fingerprint_uncached)
+}
+
+fn compute_macro_dev_fingerprint_uncached() -> u64 {
     let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_default();
     let target_dir = find_target_dir(Path::new(&manifest_dir));
     let Some(workspace_root) = target_dir.parent() else {
@@ -118,6 +152,10 @@ pub(super) fn compute_macro_dev_fingerprint() -> u64 {
 }
 
 /// Recursively collect `(path, mtime)` pairs for `.rs` files.
+///
+/// Uses `DirEntry::metadata()` (not `fs::metadata(&path)`): on Windows
+/// the entry already carries the `FindNextFile` data, so this avoids a
+/// second `stat` syscall per file.
 fn collect_rs_mtimes(dir: &Path, out: &mut Vec<(String, u64)>) {
     let Ok(read_dir) = std::fs::read_dir(dir) else {
         return;
@@ -127,13 +165,11 @@ fn collect_rs_mtimes(dir: &Path, out: &mut Vec<(String, u64)>) {
         if path.is_dir() {
             collect_rs_mtimes(&path, out);
         } else if path.extension().is_some_and(|e| e == "rs") {
-            let mtime = std::fs::metadata(&path)
-                .and_then(|m| m.modified())
-                .map_or(0, |t| {
-                    t.duration_since(std::time::UNIX_EPOCH)
-                        .unwrap_or_default()
-                        .as_secs()
-                });
+            let mtime = entry.metadata().and_then(|m| m.modified()).map_or(0, |t| {
+                t.duration_since(std::time::UNIX_EPOCH)
+                    .unwrap_or_default()
+                    .as_secs()
+            });
             out.push((path.display().to_string(), mtime));
         }
     }
@@ -238,4 +274,49 @@ mod tests {
             "Merge paths should affect config hash"
         );
     }
+
+    #[test]
+    fn test_read_cache_corrupt_file_returns_none() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let path = dir.path().join("routes.cache");
+        std::fs::write(&path, "{not valid json").unwrap();
+        assert!(read_cache(&path).is_none(), "corrupt cache must be a miss");
+    }
+
+    #[test]
+    fn test_read_cache_missing_file_returns_none() {
+        let dir = tempfile::TempDir::new().unwrap();
+        assert!(read_cache(&dir.path().join("nope.cache")).is_none());
+    }
+
+    #[test]
+    fn test_old_format_cache_deserializes_with_format_zero() {
+        // A pre-sidecar cache (inline spec strings, no cache_format
+        // field) must still parse — with cache_format defaulting to 0
+        // so the orchestrator's `== CACHE_FORMAT` check misses.
+        let dir = tempfile::TempDir::new().unwrap();
+        let path = dir.path().join("routes.cache");
+        let old_format = serde_json::json!({
+            "macro_version": "0.1.0",
+            "macro_dev_fingerprint": 1u64,
+            "file_fingerprints": {},
+            "schema_hash": 2u64,
+            "config_hash": 3u64,
+            "metadata": { "routes": [], "structs": [] },
+            "spec_json": "{\"openapi\":\"3.1.0\"}",
+            "spec_pretty": "{\n  \"openapi\": \"3.1.0\"\n}"
+        });
+        std::fs::write(&path, old_format.to_string()).unwrap();
+        let cache = read_cache(&path).expect("old format must still deserialize");
+        assert_eq!(cache.cache_format, 0, "missing field defaults to 0");
+        assert_ne!(cache.cache_format, CACHE_FORMAT, "format check must miss");
+        assert!(cache.spec_json_hash.is_none());
+        assert!(cache.spec_pretty_hash.is_none());
+    }
+
+    #[test]
+    fn test_hash_str_deterministic_and_content_sensitive() {
+        assert_eq!(hash_str("abc"), hash_str("abc"));
+        assert_ne!(hash_str("abc"), hash_str("abd"));
+    }
 }

crates/vespera_macro/src/vespera_impl/openapi_io.rs

@@ -131,33 +131,117 @@ pub fn ensure_openapi_files_from_cache(
     Ok(())
 }
 
-/// Write compact spec JSON to target dir for `include_str!` embedding.
+/// Path of the compact-spec embed sidecar (`include_str!` target).
 ///
 /// The file name is **namespaced per crate**: two workspace members
 /// both using `vespera!` compile in parallel under the same shared
 /// `target/vespera/` directory — with a single shared file name, crate
 /// A's `include_str!` could read the spec crate B just wrote.
+pub(super) fn embed_spec_path() -> std::path::PathBuf {
+    let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_default();
+    find_target_dir(Path::new(&manifest_dir))
+        .join("vespera")
+        .join(format!("vespera_spec-{}.json", current_crate_tag()))
+}
+
+/// Path of the pretty-spec sidecar (warm-rebuild source for
+/// `openapi.json` recovery — see `ensure_openapi_files_from_cache`).
+pub(super) fn pretty_sidecar_path() -> std::path::PathBuf {
+    let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_default();
+    find_target_dir(Path::new(&manifest_dir))
+        .join("vespera")
+        .join(format!("openapi_pretty-{}.json", current_crate_tag()))
+}
+
+/// Build the `include_str!` tokens pointing at the embed sidecar.
+fn embed_tokens(spec_file: &Path) -> proc_macro2::TokenStream {
+    let path_str = spec_file.display().to_string().replace('\\', "/");
+    quote::quote! { include_str!(#path_str) }
+}
+
+/// Hash-validated sidecar specs loaded on a warm cache hit.
+pub(super) struct SidecarSpecs {
+    /// Pretty spec content (for `openapi.json` recovery); `None` when
+    /// no openapi file is configured.
+    pub(super) pretty: Option<String>,
+    /// `include_str!` tokens for the embed sidecar; `None` when docs
+    /// are disabled.
+    pub(super) spec_tokens: Option<proc_macro2::TokenStream>,
+}
+
+/// Load and hash-validate the sidecar spec files on a warm cache hit.
+///
+/// Returns `None` when any expected sidecar is missing or fails its
+/// content-hash check — the caller must then treat the cache as a miss
+/// (a full regeneration rewrites both sidecars, so corruption
+/// self-heals on the next build).
+pub(super) fn load_validated_sidecar_specs(
+    spec_json_hash: Option<u64>,
+    spec_pretty_hash: Option<u64>,
+) -> Option<SidecarSpecs> {
+    let spec_tokens = match spec_json_hash {
+        None => None,
+        Some(expected) => {
+            let path = embed_spec_path();
+            let content = std::fs::read_to_string(&path).ok()?;
+            if super::cache::hash_str(&content) != expected {
+                return None;
+            }
+            Some(embed_tokens(&path))
+        }
+    };
+    let pretty = match spec_pretty_hash {
+        None => None,
+        Some(expected) => {
+            let content = std::fs::read_to_string(pretty_sidecar_path()).ok()?;
+            if super::cache::hash_str(&content) != expected {
+                return None;
+            }
+            Some(content)
+        }
+    };
+    Some(SidecarSpecs {
+        pretty,
+        spec_tokens,
+    })
+}
+
+/// Write the pretty-spec sidecar (write-if-differs).  Best-effort like
+/// the cache itself: failures only cost a future cache miss.
+pub(super) fn write_pretty_sidecar(spec_pretty: Option<&str>) {
+    let Some(pretty) = spec_pretty else {
+        return;
+    };
+    let path = pretty_sidecar_path();
+    if let Some(parent) = path.parent() {
+        let _ = std::fs::create_dir_all(parent);
+    }
+    let should_write = std::fs::read_to_string(&path).map_or(true, |existing| existing != pretty);
+    if should_write {
+        let _ = std::fs::write(&path, pretty);
+    }
+}
+
+/// Write compact spec JSON to target dir for `include_str!` embedding.
 pub(super) fn write_spec_for_embedding(
     spec_json: Option<String>,
 ) -> syn::Result<Option<proc_macro2::TokenStream>> {
     let Some(json) = spec_json else {
         return Ok(None);
     };
-    let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_default();
-    let manifest_path = Path::new(&manifest_dir);
-    let target_dir = find_target_dir(manifest_path);
-    let vespera_dir = target_dir.join("vespera");
-    std::fs::create_dir_all(&vespera_dir).map_err(|e| {
-        syn::Error::new(
-            Span::call_site(),
-            format!(
-                "vespera! macro: failed to create directory '{}': {}",
-                vespera_dir.display(),
-                e
-            ),
-        )
-    })?;
-    let spec_file = vespera_dir.join(format!("vespera_spec-{}.json", current_crate_tag()));
+    let spec_file = embed_spec_path();
+    if let Some(parent) = spec_file.parent() {
+        std::fs::create_dir_all(parent).map_err(|e| {
+            syn::Error::new(
+                Span::call_site(),
+                format!(
+                    "vespera! macro: failed to create directory '{}': {}",
+                    parent.display(),
+                    e
+                ),
+            )
+        })?;
+    }
     let should_write =
         std::fs::read_to_string(&spec_file).map_or(true, |existing| existing != json);
     if should_write {
@@ -172,8 +256,7 @@ pub(super) fn write_spec_for_embedding(
             )
         })?;
     }
-    let path_str = spec_file.display().to_string().replace('\\', "/");
-    Ok(Some(quote::quote! { include_str!(#path_str) }))
+    Ok(Some(embed_tokens(&spec_file)))
 }
 
 #[cfg(test)]