Skip to main content

fpm_rs/
benchmark_bundle.rs

1//! Normalized benchmark comparison bundles.
2
3use std::{
4    collections::{BTreeMap, BTreeSet},
5    fs::{self, File},
6    io::{BufReader, BufWriter, Write},
7    path::{Component, Path, PathBuf},
8};
9
10use polars::prelude::{DataFrame, DataType, ParquetReader, SerReader};
11use serde::{Deserialize, Serialize};
12
13use crate::{
14    Error, Result,
15    benchmark::BenchmarkRecord,
16    reconstruction::{BundleArtifact, BundleExportOptions, ReconstructionResult, ResultBundle},
17    tabular::{
18        benchmark_artifacts_dataframe, benchmark_frames_dataframe, benchmark_metadata_dataframe,
19        benchmark_runs_dataframe,
20        parquet::{ParquetWriteOptions, sha256, write_parquet_file},
21    },
22};
23
24/// Current benchmark-bundle manifest format version.
25pub const BENCHMARK_BUNDLE_FORMAT_VERSION: u32 = 2;
26
27const RUNS: &str = "tables.runs";
28const FRAMES: &str = "tables.frames";
29const ARTIFACTS: &str = "tables.artifacts";
30const METADATA: &str = "tables.metadata";
31
32/// Manifest-described Parquet tables in a benchmark bundle.
33#[derive(Clone, Debug)]
34pub struct BenchmarkBundleTables {
35    /// One-row-per-run summary table artifact.
36    pub runs: BundleArtifact,
37    /// Per-acquisition-frame metrics table artifact.
38    pub frames: BundleArtifact,
39    /// Generated artifact-path table artifact.
40    pub artifacts: BundleArtifact,
41    /// Extensible benchmark metadata table artifact.
42    pub metadata: BundleArtifact,
43}
44
45/// Reopened benchmark suite with table metadata and lazily loaded result bundles.
46#[derive(Clone)]
47pub struct BenchmarkBundle {
48    /// Root directory containing the benchmark bundle.
49    pub path: PathBuf,
50    /// Path to the benchmark manifest JSON file.
51    pub manifest_path: PathBuf,
52    /// Stable benchmark-suite name.
53    pub name: String,
54    /// Optional human-readable benchmark label.
55    pub label: Option<String>,
56    /// Parquet table artifact descriptors.
57    pub tables: BenchmarkBundleTables,
58    /// Result bundles keyed by benchmark run ID.
59    pub results: BTreeMap<String, ResultBundle>,
60}
61
62/// Options controlling benchmark-bundle metadata.
63#[derive(Clone, Debug, Default)]
64pub struct BenchmarkBundleExportOptions {
65    /// Optional human-readable bundle label.
66    pub label: Option<String>,
67}
68
69#[derive(Serialize, Deserialize)]
70#[serde(deny_unknown_fields)]
71struct BenchmarkManifest {
72    benchmark_bundle_format_version: u32,
73    name: String,
74    label: Option<String>,
75    crate_version: String,
76    artifacts: Vec<BenchmarkManifestArtifact>,
77    results: BTreeMap<String, PathBuf>,
78}
79
80#[derive(Serialize, Deserialize)]
81#[serde(deny_unknown_fields)]
82struct BenchmarkManifestArtifact {
83    role: String,
84    relative_path: PathBuf,
85    media_type: String,
86    byte_size: u64,
87    sha256: String,
88}
89
90/// Atomically writes benchmark tables plus referenced reconstruction result bundles.
91///
92/// Every record must have a unique run ID and every supplied result must correspond to a
93/// successful record. Existing complete destinations are rejected.
94pub fn write_benchmark_bundle(
95    path: impl AsRef<Path>,
96    name: impl Into<String>,
97    records: &[BenchmarkRecord],
98    results: &BTreeMap<String, ReconstructionResult>,
99    options: BenchmarkBundleExportOptions,
100) -> Result<BenchmarkBundle> {
101    validate_records(records, results)?;
102    let name = name.into();
103    if name.is_empty() {
104        return Err(Error::InvalidParameter {
105            name: "benchmark name",
106            reason: "must be non-empty".into(),
107        });
108    }
109    let (final_path, workspace) = unique_paths(path.as_ref())?;
110    if let Some(parent) = final_path.parent() {
111        fs::create_dir_all(parent)?;
112    }
113    fs::create_dir(&workspace)?;
114    fs::create_dir(workspace.join("results"))?;
115    write_json(
116        &workspace.join("run-state.json"),
117        &serde_json::json!({
118            "benchmark_bundle_format_version": BENCHMARK_BUNDLE_FORMAT_VERSION,
119            "phase": "exporting",
120        }),
121    )?;
122
123    let export = (|| -> Result<(Vec<BenchmarkManifestArtifact>, BTreeMap<String, PathBuf>)> {
124        let mut result_paths = BTreeMap::new();
125        for record in records {
126            let Some(result) = results.get(&record.run_id) else {
127                continue;
128            };
129            let relative = PathBuf::from("results").join(&record.run_id);
130            result.write_bundle(
131                workspace.join(&relative),
132                BundleExportOptions {
133                    run_id: Some(record.run_id.clone()),
134                    label: Some(format!("{}: {}", record.case_id, record.algorithm)),
135                    include_previews: false,
136                },
137            )?;
138            result_paths.insert(record.run_id.clone(), relative);
139        }
140        let relative_strings = result_paths
141            .iter()
142            .map(|(run_id, path)| (run_id.clone(), path.to_string_lossy().into_owned()))
143            .collect();
144        let mut artifacts = Vec::with_capacity(4);
145        let writer_options = ParquetWriteOptions::default();
146        write_benchmark_table(
147            &workspace,
148            "tables/runs.parquet",
149            RUNS,
150            &name,
151            benchmark_runs_dataframe(records)?,
152            &writer_options,
153            &mut artifacts,
154        )?;
155        write_benchmark_table(
156            &workspace,
157            "tables/frames.parquet",
158            FRAMES,
159            &name,
160            benchmark_frames_dataframe(records)?,
161            &writer_options,
162            &mut artifacts,
163        )?;
164        write_benchmark_table(
165            &workspace,
166            "tables/artifacts.parquet",
167            ARTIFACTS,
168            &name,
169            benchmark_artifacts_dataframe(records, &relative_strings)?,
170            &writer_options,
171            &mut artifacts,
172        )?;
173        write_benchmark_table(
174            &workspace,
175            "tables/metadata.parquet",
176            METADATA,
177            &name,
178            benchmark_metadata_dataframe(records)?,
179            &writer_options,
180            &mut artifacts,
181        )?;
182        Ok((artifacts, result_paths))
183    })();
184    let (artifacts, result_paths) = match export {
185        Ok(value) => value,
186        Err(error) => {
187            let _ = write_json(
188                &workspace.join("run-state.json"),
189                &serde_json::json!({
190                    "benchmark_bundle_format_version": BENCHMARK_BUNDLE_FORMAT_VERSION,
191                    "phase": "failed",
192                }),
193            );
194            return Err(error);
195        }
196    };
197    fs::remove_file(workspace.join("run-state.json"))?;
198    let manifest = BenchmarkManifest {
199        benchmark_bundle_format_version: BENCHMARK_BUNDLE_FORMAT_VERSION,
200        name,
201        label: options.label,
202        crate_version: env!("CARGO_PKG_VERSION").into(),
203        artifacts,
204        results: result_paths,
205    };
206    write_json(&workspace.join("manifest.json"), &manifest)?;
207    fs::rename(workspace, &final_path)?;
208    read_benchmark_bundle(final_path)
209}
210
211/// Verifies and reopens a complete benchmark bundle and its nested result manifests.
212pub fn read_benchmark_bundle(path: impl AsRef<Path>) -> Result<BenchmarkBundle> {
213    let path = path.as_ref();
214    if path
215        .file_name()
216        .and_then(|value| value.to_str())
217        .is_some_and(|value| value.ends_with(".inprogress"))
218    {
219        return Err(Error::IncompleteBundle(format!(
220            "{} is an in-progress benchmark workspace",
221            path.display()
222        )));
223    }
224    let manifest_path = path.join("manifest.json");
225    let manifest: BenchmarkManifest =
226        serde_json::from_reader(BufReader::new(File::open(&manifest_path)?))
227            .map_err(|error| Error::InvalidManifest(error.to_string()))?;
228    if manifest.benchmark_bundle_format_version != BENCHMARK_BUNDLE_FORMAT_VERSION {
229        return Err(Error::UnsupportedBundleVersion {
230            actual: manifest.benchmark_bundle_format_version,
231            supported: BENCHMARK_BUNDLE_FORMAT_VERSION,
232        });
233    }
234    if manifest.name.is_empty() || manifest.crate_version.is_empty() {
235        return Err(Error::InvalidManifest(
236            "benchmark name and crate_version must be non-empty".into(),
237        ));
238    }
239    let root = path.canonicalize()?;
240    let mut handles = BTreeMap::new();
241    for artifact in &manifest.artifacts {
242        if ![RUNS, FRAMES, ARTIFACTS, METADATA].contains(&artifact.role.as_str()) {
243            return Err(Error::UnsupportedArtifactRole(artifact.role.clone()));
244        }
245        validate_relative(&artifact.relative_path)?;
246        let artifact_path = path.join(&artifact.relative_path);
247        let canonical_artifact = artifact_path.canonicalize().map_err(|error| {
248            if error.kind() == std::io::ErrorKind::NotFound {
249                Error::MissingArtifact {
250                    role: artifact.role.clone(),
251                }
252            } else {
253                Error::Io(error)
254            }
255        })?;
256        if !canonical_artifact.starts_with(&root) {
257            return Err(Error::InvalidRelativePath(
258                artifact.relative_path.display().to_string(),
259            ));
260        }
261        if fs::metadata(&artifact_path)?.len() != artifact.byte_size {
262            return Err(Error::InvalidManifest(format!(
263                "benchmark artifact {} has the wrong size",
264                artifact.role
265            )));
266        }
267        if artifact.media_type != "application/vnd.apache.parquet"
268            || artifact.sha256.len() != 64
269            || !artifact.sha256.bytes().all(|byte| byte.is_ascii_hexdigit())
270        {
271            return Err(Error::InvalidManifest(format!(
272                "benchmark artifact {} has invalid media type or digest metadata",
273                artifact.role
274            )));
275        }
276        if sha256(&artifact_path)? != artifact.sha256 {
277            return Err(Error::ArtifactHashMismatch {
278                role: artifact.role.clone(),
279            });
280        }
281        if handles
282            .insert(
283                artifact.role.clone(),
284                BundleArtifact {
285                    role: artifact.role.clone(),
286                    path: artifact_path,
287                    media_type: artifact.media_type.clone(),
288                    byte_size: artifact.byte_size,
289                    sha256: artifact.sha256.clone(),
290                    dtype: None,
291                    shape: None,
292                },
293            )
294            .is_some()
295        {
296            return Err(Error::InvalidManifest(format!(
297                "duplicate benchmark artifact role {}",
298                artifact.role
299            )));
300        }
301    }
302    let required = |role: &str| {
303        handles
304            .get(role)
305            .cloned()
306            .ok_or_else(|| Error::MissingArtifact { role: role.into() })
307    };
308    let tables = BenchmarkBundleTables {
309        runs: required(RUNS)?,
310        frames: required(FRAMES)?,
311        artifacts: required(ARTIFACTS)?,
312        metadata: required(METADATA)?,
313    };
314    let successful_run_ids = validate_benchmark_tables(&tables, &manifest.results)?;
315    let manifest_run_ids = manifest.results.keys().cloned().collect::<BTreeSet<_>>();
316    if successful_run_ids != manifest_run_ids {
317        return Err(Error::InvalidManifest(
318            "successful benchmark runs and nested result bundles differ".into(),
319        ));
320    }
321    let mut results = BTreeMap::new();
322    for (run_id, relative) in &manifest.results {
323        validate_relative(relative)?;
324        let result_path = path.join(relative);
325        let canonical_result = result_path.canonicalize().map_err(|error| {
326            if error.kind() == std::io::ErrorKind::NotFound {
327                Error::MissingArtifact {
328                    role: format!("results.{run_id}"),
329                }
330            } else {
331                Error::Io(error)
332            }
333        })?;
334        if !canonical_result.starts_with(&root) {
335            return Err(Error::InvalidRelativePath(relative.display().to_string()));
336        }
337        let result = ResultBundle::read(result_path)?;
338        if result.run_id != *run_id {
339            return Err(Error::InconsistentRunId {
340                expected: run_id.clone(),
341                actual: result.run_id,
342            });
343        }
344        results.insert(run_id.clone(), result);
345    }
346    Ok(BenchmarkBundle {
347        path: path.into(),
348        manifest_path,
349        name: manifest.name,
350        label: manifest.label,
351        tables,
352        results,
353    })
354}
355
356fn validate_benchmark_tables(
357    tables: &BenchmarkBundleTables,
358    result_paths: &BTreeMap<String, PathBuf>,
359) -> Result<BTreeSet<String>> {
360    let runs = read_table(&tables.runs.path)?;
361    validate_schema(
362        RUNS,
363        &runs,
364        &[
365            ("run_id", DataType::String, false),
366            ("case_id", DataType::String, true),
367            ("algorithm", DataType::String, false),
368            ("algorithm_configuration", DataType::String, true),
369            ("dataset_name", DataType::String, true),
370            ("dataset_version", DataType::String, true),
371            ("random_seed", DataType::UInt64, true),
372            ("frame_count", DataType::UInt64, true),
373            ("crop_row", DataType::UInt64, true),
374            ("crop_column", DataType::UInt64, true),
375            ("crop_height", DataType::UInt64, true),
376            ("crop_width", DataType::UInt64, true),
377            ("completed_iterations", DataType::UInt64, true),
378            ("elapsed_seconds", DataType::Float64, false),
379            ("final_objective", DataType::Float64, true),
380            ("success", DataType::Boolean, false),
381            ("error", DataType::String, true),
382            ("repetition", DataType::UInt64, true),
383            ("warmup", DataType::Boolean, true),
384            ("benchmark_group", DataType::String, true),
385            ("reference_run_id", DataType::String, true),
386        ],
387    )?;
388    let run_ids = runs.column("run_id")?.str()?;
389    let case_ids = runs.column("case_id")?.str()?;
390    let successes = runs.column("success")?.bool()?;
391    let errors = runs.column("error")?.str()?;
392    let completed_iterations = runs.column("completed_iterations")?.u64()?;
393    let final_objectives = runs.column("final_objective")?.f64()?;
394    let frame_counts = runs.column("frame_count")?.u64()?;
395    let crop_rows = runs.column("crop_row")?.u64()?;
396    let crop_columns = runs.column("crop_column")?.u64()?;
397    let crop_heights = runs.column("crop_height")?.u64()?;
398    let crop_widths = runs.column("crop_width")?.u64()?;
399    let mut all_run_ids = BTreeSet::new();
400    let mut successful_run_ids = BTreeSet::new();
401    let mut expected_frame_counts = BTreeMap::new();
402    for row in 0..runs.height() {
403        let missing = |column: &str| Error::InvalidParquetSchema {
404            role: RUNS.into(),
405            reason: format!("required benchmark column {column} contains null"),
406        };
407        let run_id = run_ids.get(row).ok_or_else(|| missing("run_id"))?;
408        let case_id = case_ids.get(row).ok_or_else(|| missing("case_id"))?;
409        let success = successes.get(row).ok_or_else(|| missing("success"))?;
410        let crop = [
411            crop_rows.get(row),
412            crop_columns.get(row),
413            crop_heights.get(row),
414            crop_widths.get(row),
415        ];
416        if !crop.iter().all(Option::is_none)
417            && (!crop.iter().all(Option::is_some)
418                || crop[2] == Some(0)
419                || crop[3] == Some(0)
420                || crop[0]
421                    .zip(crop[2])
422                    .is_none_or(|(origin, size)| origin.checked_add(size).is_none())
423                || crop[1]
424                    .zip(crop[3])
425                    .is_none_or(|(origin, size)| origin.checked_add(size).is_none()))
426        {
427            return Err(Error::InvalidParquetSchema {
428                role: RUNS.into(),
429                reason: "crop columns must be all null or one non-empty detector rectangle".into(),
430            });
431        }
432        if run_id.is_empty() || case_id.is_empty() || !all_run_ids.insert(run_id.to_owned()) {
433            return Err(Error::InvalidParquetSchema {
434                role: RUNS.into(),
435                reason: "run_id and case_id must be non-empty and run_id unique".into(),
436            });
437        }
438        let valid_status = if success {
439            errors.get(row).is_none() && completed_iterations.get(row).is_some()
440        } else {
441            errors.get(row).is_some_and(|value| !value.is_empty())
442                && completed_iterations.get(row).is_none()
443                && final_objectives.get(row).is_none()
444        };
445        if !valid_status {
446            return Err(Error::InvalidParquetSchema {
447                role: RUNS.into(),
448                reason: "success, error, and result fields are inconsistent".into(),
449            });
450        }
451        if success {
452            successful_run_ids.insert(run_id.to_owned());
453        }
454        expected_frame_counts.insert(
455            run_id.to_owned(),
456            frame_counts
457                .get(row)
458                .ok_or_else(|| missing("frame_count"))?,
459        );
460    }
461
462    for (artifact, role, schema) in [
463        (
464            &tables.frames,
465            FRAMES,
466            &[
467                ("run_id", DataType::String, false),
468                ("frame_index", DataType::UInt64, false),
469                ("original_frame_index", DataType::UInt64, false),
470                ("original_illumination_index", DataType::UInt64, true),
471                ("normalized_l2", DataType::Float64, true),
472            ][..],
473        ),
474        (
475            &tables.artifacts,
476            ARTIFACTS,
477            &[
478                ("run_id", DataType::String, false),
479                ("role", DataType::String, false),
480                ("relative_path", DataType::String, false),
481            ][..],
482        ),
483        (
484            &tables.metadata,
485            METADATA,
486            &[
487                ("run_id", DataType::String, false),
488                ("key", DataType::String, false),
489                ("value", DataType::String, false),
490            ][..],
491        ),
492    ] {
493        let dataframe = read_table(&artifact.path)?;
494        validate_schema(role, &dataframe, schema)?;
495        for run_id in dataframe.column("run_id")?.str()?.iter().flatten() {
496            if !all_run_ids.contains(run_id) {
497                return Err(Error::InconsistentRunId {
498                    expected: "one of the IDs in tables.runs".into(),
499                    actual: run_id.into(),
500                });
501            }
502        }
503    }
504
505    let frames = read_table(&tables.frames.path)?;
506    let mut next_frame = BTreeMap::<String, u64>::new();
507    for (run_id, frame_index) in frames
508        .column("run_id")?
509        .str()?
510        .iter()
511        .flatten()
512        .zip(frames.column("frame_index")?.u64()?.into_no_null_iter())
513    {
514        let expected = next_frame.entry(run_id.into()).or_default();
515        if frame_index != *expected {
516            return Err(Error::InvalidParquetSchema {
517                role: FRAMES.into(),
518                reason: "frame indexes must be ordered, unique, and zero-based per run".into(),
519            });
520        }
521        *expected += 1;
522    }
523    if expected_frame_counts
524        .iter()
525        .any(|(run_id, &count)| next_frame.get(run_id).copied().unwrap_or(0) != count)
526    {
527        return Err(Error::InvalidParquetSchema {
528            role: FRAMES.into(),
529            reason: "frame rows must match each run's declared frame_count".into(),
530        });
531    }
532
533    let artifacts = read_table(&tables.artifacts.path)?;
534    let artifact_run_ids = artifacts.column("run_id")?.str()?;
535    let artifact_roles = artifacts.column("role")?.str()?;
536    let artifact_paths = artifacts.column("relative_path")?.str()?;
537    let mut artifact_ids = BTreeSet::new();
538    for ((run_id, role), relative_path) in artifact_run_ids
539        .iter()
540        .flatten()
541        .zip(artifact_roles.iter().flatten())
542        .zip(artifact_paths.iter().flatten())
543    {
544        if role != "result_bundle"
545            || !artifact_ids.insert(run_id.to_owned())
546            || validate_relative(Path::new(relative_path)).is_err()
547            || result_paths
548                .get(run_id)
549                .is_none_or(|expected| expected != Path::new(relative_path))
550        {
551            return Err(Error::InvalidParquetSchema {
552                role: ARTIFACTS.into(),
553                reason: "result artifacts must have one safe result_bundle path per run".into(),
554            });
555        }
556    }
557    if artifact_ids != successful_run_ids {
558        return Err(Error::InvalidParquetSchema {
559            role: ARTIFACTS.into(),
560            reason: "artifact rows and successful runs differ".into(),
561        });
562    }
563
564    let metadata = read_table(&tables.metadata.path)?;
565    let mut metadata_keys = BTreeSet::new();
566    for (run_id, key) in metadata
567        .column("run_id")?
568        .str()?
569        .iter()
570        .flatten()
571        .zip(metadata.column("key")?.str()?.iter().flatten())
572    {
573        if !metadata_keys.insert((run_id.to_owned(), key.to_owned())) {
574            return Err(Error::InvalidParquetSchema {
575                role: METADATA.into(),
576                reason: "metadata keys must be unique per run".into(),
577            });
578        }
579    }
580    Ok(successful_run_ids)
581}
582
583fn read_table(path: &Path) -> Result<DataFrame> {
584    Ok(ParquetReader::new(File::open(path)?).finish()?)
585}
586
587fn validate_schema(
588    role: &str,
589    dataframe: &DataFrame,
590    expected: &[(&str, DataType, bool)],
591) -> Result<()> {
592    if dataframe.width() != expected.len() {
593        return Err(Error::InvalidParquetSchema {
594            role: role.into(),
595            reason: format!(
596                "found {} columns, expected {}",
597                dataframe.width(),
598                expected.len()
599            ),
600        });
601    }
602    for &(name, ref dtype, nullable) in expected {
603        let column = dataframe
604            .column(name)
605            .map_err(|error| Error::InvalidParquetSchema {
606                role: role.into(),
607                reason: error.to_string(),
608            })?;
609        if column.dtype() != dtype || (!nullable && column.null_count() != 0) {
610            return Err(Error::InvalidParquetSchema {
611                role: role.into(),
612                reason: format!(
613                    "column {name} has dtype {:?} and {} nulls; expected {dtype:?}",
614                    column.dtype(),
615                    column.null_count()
616                ),
617            });
618        }
619    }
620    Ok(())
621}
622
623fn validate_records(
624    records: &[BenchmarkRecord],
625    results: &BTreeMap<String, ReconstructionResult>,
626) -> Result<()> {
627    if records.is_empty() {
628        return Err(Error::InvalidParameter {
629            name: "benchmark records",
630            reason: "must contain at least one run".into(),
631        });
632    }
633    let mut run_ids = BTreeSet::new();
634    for record in records {
635        if record.format_version != crate::benchmark::BENCHMARK_RECORD_FORMAT_VERSION
636            || record.run_id.is_empty()
637            || record.case_id.is_empty()
638            || record.dataset_name.is_empty()
639            || record.algorithm.is_empty()
640            || record.crate_version.is_empty()
641            || !run_ids.insert(record.run_id.as_str())
642        {
643            return Err(Error::InvalidParameter {
644                name: "benchmark records",
645                reason:
646                    "records must use the supported version, required identities must be non-empty, and run_id must be unique"
647                        .into(),
648            });
649        }
650        if !record.elapsed_seconds.is_finite()
651            || record.elapsed_seconds < 0.0
652            || record.frame_count != record.frames.len()
653            || record.success != record.error.is_none()
654            || record
655                .error
656                .as_ref()
657                .is_some_and(|message| message.is_empty())
658        {
659            return Err(Error::InvalidParameter {
660                name: "benchmark records",
661                reason: "run status, timing, frame count, or error message is inconsistent".into(),
662            });
663        }
664        let run_path = Path::new(&record.run_id);
665        if record
666            .spatial_crop
667            .is_some_and(|[row, column, height, width]| {
668                height == 0
669                    || width == 0
670                    || [height, width] != record.image_shape
671                    || row.checked_add(height).is_none()
672                    || column.checked_add(width).is_none()
673            })
674        {
675            return Err(Error::InvalidParameter {
676                name: "benchmark spatial crop",
677                reason: "must be a non-empty detector rectangle matching image_shape".into(),
678            });
679        }
680        if run_path.components().count() != 1
681            || !matches!(run_path.components().next(), Some(Component::Normal(_)))
682        {
683            return Err(Error::InvalidParameter {
684                name: "benchmark run_id",
685                reason: "must be safe as one result-directory name".into(),
686            });
687        }
688        if record.success != results.contains_key(&record.run_id) {
689            return Err(Error::InvalidParameter {
690                name: "benchmark results",
691                reason: format!(
692                    "successful run {} must have exactly one ReconstructionResult",
693                    record.run_id
694                ),
695            });
696        }
697        for (index, frame) in record.frames.iter().enumerate() {
698            if frame.frame_index != index {
699                return Err(Error::InvalidParameter {
700                    name: "benchmark frame records",
701                    reason: "frame indexes must be unique, ordered, and zero-based".into(),
702                });
703            }
704        }
705    }
706    if results
707        .keys()
708        .any(|run_id| !run_ids.contains(run_id.as_str()))
709    {
710        return Err(Error::InvalidParameter {
711            name: "benchmark results",
712            reason: "result map contains an unknown run_id".into(),
713        });
714    }
715    Ok(())
716}
717
718fn validate_relative(path: &Path) -> Result<()> {
719    if path.as_os_str().is_empty()
720        || path.is_absolute()
721        || path
722            .components()
723            .any(|component| !matches!(component, Component::Normal(_)))
724    {
725        return Err(Error::InvalidRelativePath(path.display().to_string()));
726    }
727    Ok(())
728}
729
730fn write_json(path: &Path, value: &impl Serialize) -> Result<()> {
731    if let Some(parent) = path.parent() {
732        fs::create_dir_all(parent)?;
733    }
734    let file = File::create(path)?;
735    let mut writer = BufWriter::new(file);
736    serde_json::to_writer_pretty(&mut writer, value)?;
737    writer.flush()?;
738    writer.get_ref().sync_all()?;
739    Ok(())
740}
741
742fn write_benchmark_table(
743    workspace: &Path,
744    relative_path: &str,
745    role: &str,
746    name: &str,
747    mut dataframe: DataFrame,
748    options: &ParquetWriteOptions,
749    artifacts: &mut Vec<BenchmarkManifestArtifact>,
750) -> Result<()> {
751    let table_path = workspace.join(relative_path);
752    write_parquet_file(&table_path, role, name, &mut dataframe, options)?;
753    artifacts.push(BenchmarkManifestArtifact {
754        role: role.into(),
755        relative_path: relative_path.into(),
756        media_type: "application/vnd.apache.parquet".into(),
757        byte_size: fs::metadata(&table_path)?.len(),
758        sha256: sha256(&table_path)?,
759    });
760    Ok(())
761}
762
763fn unique_paths(requested: &Path) -> Result<(PathBuf, PathBuf)> {
764    let name = requested
765        .file_name()
766        .and_then(|value| value.to_str())
767        .ok_or_else(|| Error::InvalidParameter {
768            name: "benchmark bundle path",
769            reason: "must name a UTF-8 directory".into(),
770        })?;
771    for suffix in 0_u64.. {
772        let final_path = if suffix == 0 {
773            requested.to_owned()
774        } else {
775            requested.with_file_name(format!("{name}-{suffix}"))
776        };
777        let final_name = final_path
778            .file_name()
779            .and_then(|value| value.to_str())
780            .ok_or_else(|| Error::InvalidParameter {
781                name: "benchmark bundle path",
782                reason: "must name a UTF-8 directory".into(),
783            })?;
784        let workspace = final_path.with_file_name(format!("{final_name}.inprogress"));
785        if !final_path.exists() && !workspace.exists() {
786            return Ok((final_path, workspace));
787        }
788    }
789    Err(Error::InvalidParameter {
790        name: "benchmark bundle path",
791        reason: "could not choose a unique directory".into(),
792    })
793}