create-feltdb 0.11.7 → 0.11.9

package/dist/server-source/crates/feltdb/src/workload_diagnostics.rs

@@ -135,10 +135,18 @@ pub enum Phase {
     /// AuditWrite` is therefore routing plus decode plus encode, measured as a
     /// difference of two spans rather than asserted.
     HandlerBody,
+    /// Resolving a managed request's application contract: the revision, the
+    /// runtime inventory it is validated against, and the resolved runtime.
+    /// Every `/v1` request pays it, so it must not depend on unrelated state.
+    ContractResolution,
+    /// Cloning one state namespace's rows for a state-contract read or
+    /// transaction. Proportional to that application's stored rows, not to
+    /// other applications'.
+    NamespaceSnapshot,
 }
 
 impl Phase {
-    pub const ALL: [Phase; 25] = [
+    pub const ALL: [Phase; 27] = [
         Phase::StateLockWait,
         Phase::StateLockHold,
         Phase::IndexedQuery,
@@ -164,6 +172,8 @@ impl Phase {
         Phase::AuditGroupSync,
         Phase::AuditClose,
         Phase::HandlerBody,
+        Phase::ContractResolution,
+        Phase::NamespaceSnapshot,
     ];
 
     /// The stable name this phase is reported under.
@@ -194,6 +204,8 @@ impl Phase {
             Phase::AuditGroupSync => "audit_group_sync",
             Phase::AuditClose => "audit_close",
             Phase::HandlerBody => "handler_body",
+            Phase::ContractResolution => "contract_resolution",
+            Phase::NamespaceSnapshot => "namespace_snapshot",
         }
     }
 
@@ -210,9 +222,11 @@ impl Phase {
             // The predicate runs on both executions, so its parent is the lock
             // rather than either query phase.
             Phase::PredicateEvaluation => Some(Phase::StateLockHold),
-            Phase::Authorization | Phase::AuditWrite | Phase::HandlerBody => {
-                Some(Phase::HttpHandler)
-            }
+            Phase::Authorization
+            | Phase::AuditWrite
+            | Phase::HandlerBody
+            | Phase::ContractResolution
+            | Phase::NamespaceSnapshot => Some(Phase::HttpHandler),
             Phase::Ordering | Phase::ResultMaterialization => Some(Phase::HandlerBody),
             Phase::RecordMutation | Phase::IndexMaintenance | Phase::Persistence => {
                 Some(Phase::StateLockHold)

package/dist/server-source/crates/feltdb-server/src/backup.rs

@@ -4,11 +4,32 @@ use std::{
     fs::{self, File},
     io::{self, Read, Write},
     path::{Path, PathBuf},
-    time::{SystemTime, UNIX_EPOCH},
+    time::{Instant, SystemTime, UNIX_EPOCH},
 };
 
 pub const BACKUP_FORMAT: u32 = 1;
 
+/// Where the backed-up state came from. Optional in the manifest so that
+/// bundles written before provenance was recorded still verify: the format is
+/// unchanged, and an absent field is reported as unknown rather than invented.
+#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
+pub struct BackupSource {
+    /// Absolute path of the durable state file the bundle was taken from.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub data: Option<String>,
+    /// SHA-256 of the authoritative state artifact (`state.log`, or the
+    /// consistent `database.snapshot.json` of an online backup).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_sha256: Option<String>,
+    /// The `feltdb-server` crate version that wrote the bundle (not the npm
+    /// package version).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub server_version: Option<String>,
+    /// The durable format version of the build that wrote the bundle.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub durable_format: Option<u32>,
+}
+
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct BackupEntry {
     pub path: String,
@@ -21,6 +42,93 @@ pub struct BackupManifest {
     pub format: u32,
     pub created_ms: u64,
     pub entries: Vec<BackupEntry>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<BackupSource>,
+}
+
+/// The explicit outcome of a backup operation.
+///
+/// `status` is `ok` only when the bundle was written *and* independently
+/// verified; the CLI exit code follows it, so a successful backup is never
+/// reported as a failure and an unverifiable one is never reported as valid.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct BackupReport {
+    pub operation: String,
+    pub status: String,
+    /// Absolute path of the bundle.
+    pub path: String,
+    /// SHA-256 of the bundle manifest: the bundle's stable identity.
+    pub backup_id: String,
+    pub source: BackupSource,
+    pub format: u32,
+    pub created_ms: u64,
+    pub files: usize,
+    pub bytes_written: u64,
+    /// `verified` or `failed`.
+    pub verification: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<String>,
+    pub duration_ms: u64,
+}
+
+/// Resolve a user-supplied path against the working directory.
+///
+/// A bare relative path such as `backup` has an *empty* parent, not `.`; every
+/// operation that syncs or stages next to the output therefore works on the
+/// absolute form, which is what makes `backup`, `./backup` and
+/// `/abs/path/backup` behave identically.
+pub fn normalize_path(path: &Path) -> io::Result<PathBuf> {
+    if path.as_os_str().is_empty() {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "backup path must not be empty",
+        ));
+    }
+    std::path::absolute(path)
+}
+
+/// SHA-256 of a bundle's manifest bytes, used as the bundle identity.
+pub fn backup_id(archive: &Path) -> io::Result<String> {
+    Ok(format!(
+        "{:x}",
+        Sha256::digest(fs::read(archive.join("manifest.json"))?)
+    ))
+}
+
+/// Verify a bundle and describe it as a report, without ever turning a
+/// verification failure into success.
+pub fn verification_report(archive: &Path, started: Instant, operation: &str) -> BackupReport {
+    let path = normalize_path(archive).unwrap_or_else(|_| archive.to_path_buf());
+    match verify_bundle(&path).and_then(|manifest| Ok((backup_id(&path)?, manifest))) {
+        Ok((id, manifest)) => BackupReport {
+            operation: operation.into(),
+            status: "ok".into(),
+            path: path.display().to_string(),
+            backup_id: id,
+            source: manifest.source.clone().unwrap_or_default(),
+            format: manifest.format,
+            created_ms: manifest.created_ms,
+            files: manifest.entries.len(),
+            bytes_written: manifest.entries.iter().map(|entry| entry.bytes).sum(),
+            verification: "verified".into(),
+            error: None,
+            duration_ms: started.elapsed().as_millis() as u64,
+        },
+        Err(error) => BackupReport {
+            operation: operation.into(),
+            status: "failed".into(),
+            path: path.display().to_string(),
+            backup_id: backup_id(&path).unwrap_or_default(),
+            source: BackupSource::default(),
+            format: 0,
+            created_ms: 0,
+            files: 0,
+            bytes_written: 0,
+            verification: "failed".into(),
+            error: Some(error.to_string()),
+            duration_ms: started.elapsed().as_millis() as u64,
+        },
+    }
 }
 
 pub fn server_artifacts(data: &Path, keys: &Path, audit: &Path) -> Vec<(String, PathBuf)> {
@@ -72,6 +180,20 @@ pub fn create_bundle_with_virtual(
     artifacts: &[(String, PathBuf)],
     virtual_files: &[(String, Vec<u8>)],
 ) -> io::Result<BackupManifest> {
+    create_bundle_with_source(output, artifacts, virtual_files, BackupSource::default())
+}
+
+/// Write a bundle and record where its state came from.
+///
+/// The bundle is staged beside the output and published with one rename, so a
+/// reader sees either no bundle or a complete one.
+pub fn create_bundle_with_source(
+    output: &Path,
+    artifacts: &[(String, PathBuf)],
+    virtual_files: &[(String, Vec<u8>)],
+    mut source: BackupSource,
+) -> io::Result<BackupManifest> {
+    let output = &normalize_path(output)?;
     if output.exists() {
         return Err(io::Error::new(
             io::ErrorKind::AlreadyExists,
@@ -114,6 +236,14 @@ pub fn create_bundle_with_virtual(
             });
         }
         entries.sort_by(|left, right| left.path.cmp(&right.path));
+        if source.state_sha256.is_none() {
+            source.state_sha256 = entries
+                .iter()
+                .find(|entry| {
+                    entry.path == "files/database.snapshot.json" || entry.path == "files/state.log"
+                })
+                .map(|entry| entry.sha256.clone());
+        }
         let manifest = BackupManifest {
             format: BACKUP_FORMAT,
             created_ms: SystemTime::now()
@@ -121,6 +251,7 @@ pub fn create_bundle_with_virtual(
                 .unwrap_or_default()
                 .as_millis() as u64,
             entries,
+            source: Some(source),
         };
         write_synced(
             &staging.join("manifest.json"),
@@ -128,9 +259,7 @@ pub fn create_bundle_with_virtual(
         )?;
         sync_directory(&staging)?;
         fs::rename(&staging, output)?;
-        if let Some(parent) = output.parent() {
-            sync_directory(parent)?;
-        }
+        sync_parent(output)?;
         Ok(manifest)
     })();
     if result.is_err() {
@@ -140,6 +269,7 @@ pub fn create_bundle_with_virtual(
 }
 
 pub fn verify_bundle(archive: &Path) -> io::Result<BackupManifest> {
+    let archive = &normalize_path(archive)?;
     if archive.with_extension("partial").exists() {
         return Err(io::Error::new(
             io::ErrorKind::InvalidData,
@@ -167,6 +297,25 @@ pub fn verify_bundle(archive: &Path) -> io::Result<BackupManifest> {
             ));
         }
     }
+    // Completeness runs both ways: every manifest entry is present and intact
+    // (above), and nothing unrecorded sits in the bundle. An extra file would be
+    // restored as state that no checksum ever covered.
+    let recorded: std::collections::BTreeSet<&str> = manifest
+        .entries
+        .iter()
+        .map(|entry| entry.path.as_str())
+        .collect();
+    let mut present = Vec::new();
+    collect_files(&archive.join("files"), "files", &mut present)?;
+    if let Some(extra) = present
+        .iter()
+        .find(|path| !recorded.contains(path.as_str()))
+    {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            format!("backup contains a file absent from its manifest: {extra}"),
+        ));
+    }
     Ok(manifest)
 }
 
@@ -174,6 +323,7 @@ pub fn verify_bundle(archive: &Path) -> io::Result<BackupManifest> {
 /// does not exceed `at_ms`. Every manifest-bearing child is verified first so a
 /// corrupt recent backup cannot cause a silent fallback to older data.
 pub fn select_bundle_at(catalog: &Path, at_ms: u64) -> io::Result<PathBuf> {
+    let catalog = &normalize_path(catalog)?;
     let mut candidates = Vec::new();
     for entry in fs::read_dir(catalog)? {
         let path = entry?.path();
@@ -198,6 +348,8 @@ pub fn select_bundle_at(catalog: &Path, at_ms: u64) -> io::Result<PathBuf> {
 }
 
 pub fn restore_bundle(archive: &Path, output: &Path) -> io::Result<BackupManifest> {
+    let archive = &normalize_path(archive)?;
+    let output = &normalize_path(output)?;
     let manifest = verify_bundle(archive)?;
     if output.exists() {
         return Err(io::Error::new(
@@ -221,9 +373,7 @@ pub fn restore_bundle(archive: &Path, output: &Path) -> io::Result<BackupManifes
         )?;
         sync_directory(&staging)?;
         fs::rename(&staging, output)?;
-        if let Some(parent) = output.parent() {
-            sync_directory(parent)?;
-        }
+        sync_parent(output)?;
         Ok(manifest.clone())
     })();
     if result.is_err() {
@@ -271,6 +421,22 @@ fn copy_source(
     }
     Ok(())
 }
+fn collect_files(directory: &Path, relative: &str, found: &mut Vec<String>) -> io::Result<()> {
+    if !directory.exists() {
+        return Ok(());
+    }
+    for child in fs::read_dir(directory)? {
+        let child = child?;
+        let name = format!("{relative}/{}", child.file_name().to_string_lossy());
+        let kind = child.file_type()?;
+        if kind.is_dir() {
+            collect_files(&child.path(), &name, found)?;
+        } else {
+            found.push(name);
+        }
+    }
+    Ok(())
+}
 fn copy_tree(source: &Path, destination: &Path) -> io::Result<()> {
     if !source.exists() {
         return Ok(());
@@ -322,6 +488,14 @@ fn sync_file(path: &Path) -> io::Result<()> {
 fn sync_directory(path: &Path) -> io::Result<()> {
     File::open(path)?.sync_all()
 }
+/// Sync the directory that holds `path`. A relative path with no directory
+/// component lives in the working directory; its parent is `.`, never `""`.
+fn sync_parent(path: &Path) -> io::Result<()> {
+    match path.parent() {
+        Some(parent) if !parent.as_os_str().is_empty() => sync_directory(parent),
+        _ => sync_directory(Path::new(".")),
+    }
+}
 
 #[cfg(test)]
 mod tests {
@@ -409,4 +583,113 @@ mod tests {
         assert!(select_bundle_at(&root.join("catalog"), first.created_ms - 1).is_err());
         fs::remove_dir_all(root).unwrap();
     }
+
+    #[test]
+    fn relative_and_absolute_paths_normalize_identically() {
+        let cwd = std::env::current_dir().unwrap();
+        assert_eq!(
+            normalize_path(Path::new("backup")).unwrap(),
+            cwd.join("backup")
+        );
+        assert_eq!(
+            normalize_path(Path::new("./backup")).unwrap(),
+            cwd.join("./backup")
+        );
+        assert_eq!(
+            normalize_path(&cwd.join("backup")).unwrap(),
+            cwd.join("backup")
+        );
+        assert!(normalize_path(Path::new("")).is_err());
+        // The defect: a bare name has an empty parent, which cannot be opened
+        // for the post-rename directory sync. `sync_parent` must treat it as `.`.
+        assert_eq!(Path::new("backup").parent(), Some(Path::new("")));
+        sync_parent(Path::new("backup")).unwrap();
+    }
+
+    #[test]
+    fn backup_into_missing_parent_records_provenance_and_verifies() {
+        let root = std::env::temp_dir().join(format!(
+            "feltdb-provenance-{}-{}",
+            std::process::id(),
+            rand::random::<u64>()
+        ));
+        fs::create_dir_all(&root).unwrap();
+        fs::write(root.join("state.log"), b"state").unwrap();
+        let archive = root.join("does/not/exist/yet/archive");
+        let manifest = create_bundle_with_source(
+            &archive,
+            &[("state.log".into(), root.join("state.log"))],
+            &[],
+            BackupSource {
+                data: Some("/data/state.log".into()),
+                ..BackupSource::default()
+            },
+        )
+        .unwrap();
+        let source = manifest.source.unwrap();
+        assert_eq!(source.data.as_deref(), Some("/data/state.log"));
+        assert_eq!(
+            source.state_sha256.as_deref(),
+            Some(manifest.entries[0].sha256.as_str())
+        );
+        let report = verification_report(&archive, Instant::now(), "verify");
+        assert_eq!(report.status, "ok");
+        assert_eq!(report.verification, "verified");
+        assert_eq!(report.bytes_written, 5);
+        assert_eq!(report.backup_id, backup_id(&archive).unwrap());
+        fs::remove_dir_all(root).unwrap();
+    }
+
+    #[test]
+    fn unrecorded_files_and_missing_manifests_fail_verification() {
+        let root = std::env::temp_dir().join(format!(
+            "feltdb-completeness-{}-{}",
+            std::process::id(),
+            rand::random::<u64>()
+        ));
+        fs::create_dir_all(&root).unwrap();
+        fs::write(root.join("state.log"), b"state").unwrap();
+        let archive = root.join("archive");
+        create_bundle(&archive, &[("state.log".into(), root.join("state.log"))]).unwrap();
+        fs::write(archive.join("files/injected"), b"unrecorded").unwrap();
+        let report = verification_report(&archive, Instant::now(), "verify");
+        assert_eq!(report.status, "failed");
+        assert!(report.error.unwrap().contains("absent from its manifest"));
+        fs::remove_file(archive.join("files/injected")).unwrap();
+        fs::remove_file(archive.join("files/state.log")).unwrap();
+        assert_eq!(
+            verification_report(&archive, Instant::now(), "verify").status,
+            "failed"
+        );
+        fs::remove_file(archive.join("manifest.json")).unwrap();
+        assert_eq!(
+            verification_report(&archive, Instant::now(), "verify").verification,
+            "failed"
+        );
+        fs::remove_dir_all(root).unwrap();
+    }
+
+    #[test]
+    fn manifests_written_before_provenance_still_verify() {
+        let root = std::env::temp_dir().join(format!(
+            "feltdb-legacy-manifest-{}-{}",
+            std::process::id(),
+            rand::random::<u64>()
+        ));
+        fs::create_dir_all(root.join("archive/files")).unwrap();
+        fs::write(root.join("archive/files/state.log"), b"legacy").unwrap();
+        let digest = format!("{:x}", Sha256::digest(b"legacy"));
+        fs::write(
+            root.join("archive/manifest.json"),
+            format!(r#"{{"format":1,"created_ms":1,"entries":[{{"path":"files/state.log","bytes":6,"sha256":"{digest}"}}]}}"#),
+        )
+        .unwrap();
+        let manifest = verify_bundle(&root.join("archive")).unwrap();
+        assert!(manifest.source.is_none());
+        assert_eq!(
+            verification_report(&root.join("archive"), Instant::now(), "verify").source,
+            BackupSource::default()
+        );
+        fs::remove_dir_all(root).unwrap();
+    }
 }