Restructure spk-solve for multiple solvers

Move `Solver` into a nested module and rename it publicly as
`StepSolver` in order to make way for other solver implementations and
for the name `Solver` to become available for repurposing it later.

The name `StepSolver` was inspired by how the solver makes progress by
calling the `step_state` function.

The `solver_test` module has been separated from the `solver` module
since this is destined to become a module of tests that are generic over
the solver implementation.

Signed-off-by: J Robert Ray <jrray@jrray.org>

Author: jrray

crates/spk-build/src/build/binary.rs

@@ -37,7 +37,7 @@ use spk_schema::{
 };
 use spk_solve::graph::Graph;
 use spk_solve::solution::Solution;
-use spk_solve::{BoxedResolverCallback, Named, ResolverCallback, Solver};
+use spk_solve::{BoxedResolverCallback, Named, ResolverCallback, StepSolver};
 use spk_storage as storage;
 
 use crate::report::{BuildOutputReport, BuildReport, BuildSetupReport};
@@ -131,7 +131,7 @@ pub struct BinaryPackageBuilder<'a, Recipe> {
     prefix: PathBuf,
     recipe: Recipe,
     source: BuildSource,
-    solver: Solver,
+    solver: StepSolver,
     environment: HashMap<String, String>,
     source_resolver: BoxedResolverCallback<'a>,
     build_resolver: BoxedResolverCallback<'a>,
@@ -155,7 +155,7 @@ where
             recipe,
             source,
             prefix: PathBuf::from("/spfs"),
-            solver: Solver::default(),
+            solver: StepSolver::default(),
             environment: Default::default(),
             #[cfg(test)]
             source_resolver: Box::new(spk_solve::DecisionFormatter::new_testing()),

crates/spk-cli/cmd-test/src/test/build.rs

@@ -15,7 +15,7 @@ use spk_schema::foundation::option_map::OptionMap;
 use spk_schema::ident::{PkgRequest, PreReleasePolicy, RangeIdent, Request, RequestedBy};
 use spk_schema::{AnyIdent, Recipe, SpecRecipe};
 use spk_solve::solution::Solution;
-use spk_solve::{BoxedResolverCallback, DefaultResolver, ResolverCallback, Solver};
+use spk_solve::{BoxedResolverCallback, DefaultResolver, ResolverCallback, StepSolver};
 use spk_storage as storage;
 
 use super::Tester;
@@ -117,7 +117,7 @@ impl<'a> PackageBuildTester<'a> {
             }
         }
 
-        let mut solver = Solver::default();
+        let mut solver = StepSolver::default();
         solver.set_binary_only(true);
         solver.update_options(self.options.clone());
         for repo in self.repos.iter().cloned() {
@@ -154,7 +154,7 @@ impl<'a> PackageBuildTester<'a> {
     }
 
     async fn resolve_source_package(&mut self, package: &AnyIdent) -> Result<Solution> {
-        let mut solver = Solver::default();
+        let mut solver = StepSolver::default();
         solver.update_options(self.options.clone());
         let local_repo: Arc<storage::RepositoryHandle> =
             Arc::new(storage::local_repository().await?.into());

crates/spk-cli/cmd-test/src/test/install.rs

@@ -12,7 +12,7 @@ use spk_schema::foundation::option_map::OptionMap;
 use spk_schema::ident::{PkgRequest, PreReleasePolicy, RangeIdent, Request, RequestedBy};
 use spk_schema::ident_build::Build;
 use spk_schema::{Recipe, SpecRecipe, Variant, VariantExt};
-use spk_solve::{BoxedResolverCallback, DefaultResolver, ResolverCallback, Solver};
+use spk_solve::{BoxedResolverCallback, DefaultResolver, ResolverCallback, StepSolver};
 use spk_storage as storage;
 
 use super::Tester;
@@ -94,7 +94,7 @@ where
 
         let requires_localization = rt.config.mount_backend.requires_localization();
 
-        let mut solver = Solver::default();
+        let mut solver = StepSolver::default();
         solver.set_binary_only(true);
         solver.update_options(self.options.clone());
         for repo in self.repos.iter().cloned() {

crates/spk-cli/cmd-test/src/test/sources.rs

@@ -13,7 +13,7 @@ use spk_schema::foundation::ident_component::Component;
 use spk_schema::foundation::option_map::OptionMap;
 use spk_schema::ident::{PkgRequest, PreReleasePolicy, RangeIdent, Request, RequestedBy};
 use spk_schema::{Recipe, SpecRecipe};
-use spk_solve::{BoxedResolverCallback, DefaultResolver, ResolverCallback, Solver};
+use spk_solve::{BoxedResolverCallback, DefaultResolver, ResolverCallback, StepSolver};
 use spk_storage as storage;
 
 use super::Tester;
@@ -92,7 +92,7 @@ impl<'a> PackageSourceTester<'a> {
 
         let requires_localization = rt.config.mount_backend.requires_localization();
 
-        let mut solver = Solver::default();
+        let mut solver = StepSolver::default();
         solver.set_binary_only(true);
         solver.update_options(self.options.clone());
         for repo in self.repos.iter().cloned() {

crates/spk-cli/common/src/flags.rs

@@ -257,10 +257,10 @@ pub struct Solver {
 }
 
 impl Solver {
-    pub async fn get_solver(&self, options: &Options) -> Result<solve::Solver> {
+    pub async fn get_solver(&self, options: &Options) -> Result<solve::StepSolver> {
         let option_map = options.get_options()?;
 
-        let mut solver = solve::Solver::default();
+        let mut solver = solve::StepSolver::default();
         solver.update_options(option_map);
 
         for (name, repo) in self.repos.get_repos_for_non_destructive_operation().await? {

crates/spk-exec/src/exec_test.rs

@@ -9,15 +9,15 @@ use rstest::{fixture, rstest};
 use spk_cmd_build::build_package;
 use spk_schema::foundation::fixtures::*;
 use spk_schema::ident::build_ident;
-use spk_solve::{DecisionFormatterBuilder, Solver};
+use spk_solve::{DecisionFormatterBuilder, StepSolver};
 use spk_solve_macros::request;
 use spk_storage::fixtures::*;
 
 use crate::solution_to_resolved_runtime_layers;
 
 #[fixture]
-fn solver() -> Solver {
-    Solver::default()
+fn solver() -> StepSolver {
+    StepSolver::default()
 }
 
 /// If two layers contribute files to the same subdirectory, the Manifest is
@@ -26,7 +26,7 @@ fn solver() -> Solver {
 #[tokio::test]
 async fn get_environment_filesystem_merges_directories(
     tmpdir: tempfile::TempDir,
-    mut solver: Solver,
+    mut solver: StepSolver,
 ) {
     let rt = spfs_runtime().await;
 

crates/spk-solve/src/io.rs

@@ -40,17 +40,9 @@ use spk_solve_graph::{
     State,
 };
 
-use crate::solver::ErrorFreq;
-use crate::{
-    Error,
-    ResolverCallback,
-    Result,
-    Solution,
-    Solver,
-    SolverRuntime,
-    StatusLine,
-    show_search_space_stats,
-};
+use crate::solvers::step::ErrorFreq;
+use crate::solvers::{StepSolver, StepSolverRuntime};
+use crate::{Error, ResolverCallback, Result, Solution, StatusLine, show_search_space_stats};
 #[cfg(feature = "statsd")]
 use crate::{
     SPK_SOLUTION_PACKAGE_COUNT_METRIC,
@@ -1101,15 +1093,15 @@ impl Display for MultiSolverKind {
 }
 
 struct SolverTaskSettings {
-    solver: Solver,
+    solver: StepSolver,
     solver_kind: MultiSolverKind,
     ignore_failure: bool,
 }
 
 struct SolverTaskDone {
     pub(crate) start: Instant,
     pub(crate) loop_outcome: LoopOutcome,
-    pub(crate) runtime: SolverRuntime,
+    pub(crate) runtime: StepSolverRuntime,
     pub(crate) verbosity: u8,
     pub(crate) solver_kind: MultiSolverKind,
     pub(crate) can_ignore_failure: bool,
@@ -1119,7 +1111,7 @@ struct SolverTaskDone {
 struct SolverResult {
     pub(crate) solver_kind: MultiSolverKind,
     pub(crate) solve_time: Duration,
-    pub(crate) solver: Solver,
+    pub(crate) solver: StepSolver,
     pub(crate) result: Result<(Solution, Arc<tokio::sync::RwLock<spk_solve_graph::Graph>>)>,
 }
 
@@ -1163,7 +1155,7 @@ impl DecisionFormatter {
     /// result from the first to finish.
     pub async fn run_and_print_resolve(
         &self,
-        solver: &Solver,
+        solver: &StepSolver,
     ) -> Result<(Solution, Arc<tokio::sync::RwLock<Graph>>)> {
         let solvers = self.setup_solvers(solver);
         self.run_multi_solve(solvers, OutputKind::Println).await
@@ -1174,7 +1166,7 @@ impl DecisionFormatter {
     /// won't benefit from running solvers in parallel.
     pub async fn run_and_print_decisions(
         &self,
-        runtime: &mut SolverRuntime,
+        runtime: &mut StepSolverRuntime,
     ) -> Result<(Solution, Arc<tokio::sync::RwLock<Graph>>)> {
         // Note: this is only used directly by cmd_view/info when it
         // runs a solve. Once 'spk info' no longer runs a solve we may
@@ -1196,7 +1188,7 @@ impl DecisionFormatter {
     /// options) and takes the result from the first to finish.
     pub async fn run_and_log_resolve(
         &self,
-        solver: &Solver,
+        solver: &StepSolver,
     ) -> Result<(Solution, Arc<tokio::sync::RwLock<Graph>>)> {
         let solvers = self.setup_solvers(solver);
         self.run_multi_solve(solvers, OutputKind::Tracing).await
@@ -1208,7 +1200,7 @@ impl DecisionFormatter {
     /// parallel.
     pub async fn run_and_log_decisions(
         &self,
-        runtime: &mut SolverRuntime,
+        runtime: &mut StepSolverRuntime,
     ) -> Result<(Solution, Arc<tokio::sync::RwLock<Graph>>)> {
         // Note: this is not currently used directly. We may be able
         // to remove this method.
@@ -1223,7 +1215,7 @@ impl DecisionFormatter {
             .await
     }
 
-    fn setup_solvers(&self, base_solver: &Solver) -> Vec<SolverTaskSettings> {
+    fn setup_solvers(&self, base_solver: &StepSolver) -> Vec<SolverTaskSettings> {
         // Leave the first solver as is.
         let solver_with_no_change = base_solver.clone();
 
@@ -1540,7 +1532,7 @@ impl DecisionFormatter {
 
     async fn run_solver_loop(
         &self,
-        runtime: &mut SolverRuntime,
+        runtime: &mut StepSolverRuntime,
         mut output_location: OutputKind,
     ) -> LoopOutcome {
         // This block exists to shorten the scope of `runtime`'s borrow.
@@ -1576,7 +1568,7 @@ impl DecisionFormatter {
         &self,
         loop_outcome: LoopOutcome,
         solve_time: Duration,
-        runtime: &mut SolverRuntime,
+        runtime: &mut StepSolverRuntime,
         mut output_location: OutputKind,
     ) -> Result<(Solution, Arc<tokio::sync::RwLock<Graph>>)> {
         match loop_outcome {
@@ -1686,7 +1678,7 @@ impl DecisionFormatter {
     async fn show_search_space_info(
         &self,
         solution: &Result<Solution>,
-        runtime: &SolverRuntime,
+        runtime: &StepSolverRuntime,
     ) -> Result<()> {
         if let Ok(ref s) = *solution {
             tracing::info!("Calculating search space stats. This may take some time...");
@@ -1713,7 +1705,7 @@ impl DecisionFormatter {
     }
 
     #[cfg(feature = "statsd")]
-    fn send_solver_start_metrics(&self, runtime: &SolverRuntime) {
+    fn send_solver_start_metrics(&self, runtime: &StepSolverRuntime) {
         let Some(statsd_client) = get_metrics_client() else {
             return;
         };
@@ -1774,7 +1766,7 @@ impl DecisionFormatter {
     #[cfg(feature = "sentry")]
     fn add_details_to_next_sentry_event(
         &self,
-        solver: &Solver,
+        solver: &StepSolver,
         solve_duration: Duration,
     ) -> Vec<String> {
         let seconds = solve_duration.as_secs_f64();
@@ -1831,7 +1823,7 @@ impl DecisionFormatter {
     #[cfg(feature = "sentry")]
     fn send_sentry_warning_message(
         &self,
-        solver: &Solver,
+        solver: &StepSolver,
         solve_duration: Duration,
         sentry_warning: SentryWarning,
     ) {
@@ -1900,7 +1892,11 @@ impl DecisionFormatter {
         FormattedDecisionsIter::new(decisions, self.settings.clone())
     }
 
-    pub(crate) fn format_solve_stats(&self, solver: &Solver, solve_duration: Duration) -> String {
+    pub(crate) fn format_solve_stats(
+        &self,
+        solver: &StepSolver,
+        solve_duration: Duration,
+    ) -> String {
         // Show how long this solve took
         let mut out: String = " Solver took: ".to_string();
         let seconds = solve_duration.as_secs_f64();
@@ -2130,7 +2126,7 @@ impl DecisionFormatter {
 impl ResolverCallback for &DecisionFormatter {
     async fn solve<'s, 'a: 's>(
         &'s self,
-        r: &'a Solver,
+        r: &'a StepSolver,
     ) -> Result<(Solution, Arc<tokio::sync::RwLock<Graph>>)> {
         self.run_and_print_resolve(r).await
     }
@@ -2140,7 +2136,7 @@ impl ResolverCallback for &DecisionFormatter {
 impl ResolverCallback for DecisionFormatter {
     async fn solve<'s, 'a: 's>(
         &'s self,
-        r: &'a Solver,
+        r: &'a StepSolver,
     ) -> Result<(Solution, Arc<tokio::sync::RwLock<Graph>>)> {
         self.run_and_print_resolve(r).await
     }

crates/spk-solve/src/lib.rs

@@ -7,7 +7,7 @@ mod io;
 #[cfg(feature = "statsd")]
 mod metrics;
 mod search_space;
-mod solver;
+mod solvers;
 mod status_line;
 
 use std::sync::Arc;
@@ -34,7 +34,7 @@ pub use metrics::{
     get_metrics_client,
 };
 pub(crate) use search_space::show_search_space_stats;
-pub use solver::{Solver, SolverRuntime};
+pub use solvers::{StepSolver, StepSolverRuntime};
 pub use spk_schema::foundation::ident_build::Build;
 pub use spk_schema::foundation::ident_component::Component;
 pub use spk_schema::foundation::option_map;
@@ -62,11 +62,11 @@ pub use {
 
 #[async_trait::async_trait]
 pub trait ResolverCallback: Send + Sync {
-    /// Run a solve using the given [`crate::Solver`],
+    /// Run a solve using the given [`crate::StepSolver`],
     /// producing a [`crate::Solution`].
     async fn solve<'s, 'a: 's>(
         &'s self,
-        r: &'a Solver,
+        r: &'a StepSolver,
     ) -> Result<(Solution, Arc<tokio::sync::RwLock<Graph>>)>;
 }
 
@@ -77,7 +77,7 @@ pub struct DefaultResolver {}
 impl ResolverCallback for DefaultResolver {
     async fn solve<'s, 'a: 's>(
         &'s self,
-        r: &'a Solver,
+        r: &'a StepSolver,
     ) -> Result<(Solution, Arc<tokio::sync::RwLock<Graph>>)> {
         let mut runtime = r.run();
         let solution = runtime.solution().await;

crates/spk-solve/src/solvers/mod.rs

@@ -0,0 +1,12 @@
+// Copyright (c) Contributors to the SPK project.
+// SPDX-License-Identifier: Apache-2.0
+// https://github.com/spkenv/spk
+
+pub(crate) mod step;
+
+pub use step::{Solver as StepSolver, SolverRuntime as StepSolverRuntime};
+
+// Public to allow other tests to use its macros
+#[cfg(test)]
+#[path = "./solver_test.rs"]
+mod solver_test;