plansolve 0.27.0

Official Rust client library for the PlanSolve optimization API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

use serde::{Deserialize, Serialize};

/// The state of the solver for a given job.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum SolverStatus {
    /// The solver is idle and not working on the job.
    #[serde(rename = "NOT_SOLVING")]
    NotSolving,
    /// The solver is actively working on the job.
    #[serde(rename = "SOLVING_ACTIVE")]
    SolvingActive,
    /// The solver is winding down and terminating early.
    #[serde(rename = "TERMINATING_EARLY")]
    TerminatingEarly,
    /// The job is queued and scheduled to start solving.
    #[serde(rename = "SOLVING_SCHEDULED")]
    SolvingScheduled,
    /// Any status value not otherwise recognized.
    #[serde(other)]
    Unknown,
}

/// The status of a solver job, returned by the `/status` endpoints.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SolverStatusResponse {
    /// Public job identifier the status refers to.
    #[serde(default)]
    pub job_id: String,
    /// Raw solver engine status (e.g. `SOLVING_ACTIVE`, `NOT_SOLVING`).
    pub solver_status: SolverStatus,
    /// Current best score as a solver score string, when available.
    #[serde(default)]
    pub score: String,
    /// Whether the current best solution satisfies all hard constraints.
    #[serde(default)]
    pub feasible: bool,
    /// Whether the solver is still actively working on the job.
    #[serde(default)]
    pub solving: bool,
}

impl SolverStatusResponse {
    /// Returns true while the solver is still working on this job.
    ///
    /// Mirrors the polling logic used by the other PlanSolve SDKs: a job is
    /// considered "still solving" until it reports `NOT_SOLVING` with a score.
    pub fn is_solving(&self) -> bool {
        self.solving
            || self.solver_status == SolverStatus::SolvingScheduled
            || self.solver_status != SolverStatus::NotSolving
            || self.score.is_empty()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn status(solving: bool, s: SolverStatus, score: &str) -> SolverStatusResponse {
        SolverStatusResponse {
            job_id: "j".into(),
            solver_status: s,
            score: score.into(),
            feasible: true,
            solving,
        }
    }

    #[test]
    fn done_only_when_idle_with_a_score() {
        // The one and only "finished" combination.
        assert!(!status(false, SolverStatus::NotSolving, "0hard/0medium/0soft").is_solving());
    }

    #[test]
    fn still_solving_in_every_other_case() {
        assert!(status(true, SolverStatus::NotSolving, "0hard/0medium/0soft").is_solving());
        assert!(status(false, SolverStatus::SolvingActive, "0hard/0medium/0soft").is_solving());
        assert!(status(false, SolverStatus::SolvingScheduled, "0hard/0medium/0soft").is_solving());
        // Idle + NotSolving but no score yet => not done.
        assert!(status(false, SolverStatus::NotSolving, "").is_solving());
    }

    #[test]
    fn deserializes_known_and_unknown_statuses() {
        let known: SolverStatusResponse =
            serde_json::from_str(r#"{"solverStatus":"SOLVING_ACTIVE"}"#).unwrap();
        assert_eq!(known.solver_status, SolverStatus::SolvingActive);

        // Unrecognized status values fall back to Unknown instead of erroring.
        let unknown: SolverStatusResponse =
            serde_json::from_str(r#"{"solverStatus":"SOMETHING_NEW"}"#).unwrap();
        assert_eq!(unknown.solver_status, SolverStatus::Unknown);
    }

    #[test]
    fn tolerates_missing_optional_fields() {
        // Only solverStatus is required; the rest default.
        let s: SolverStatusResponse =
            serde_json::from_str(r#"{"solverStatus":"NOT_SOLVING"}"#).unwrap();
        assert_eq!(s.job_id, "");
        assert!(!s.feasible);
        assert!(s.score.is_empty());
    }
}