proef_engine_hurl/
lib.rs

1//! The proef API engine: [`EngineFactory`]/[`EngineSession`] over **embedded hurl**
2//! (ADR-0001).
3//!
4//! hurl's crates are pinned exactly (`=8.0.1`) and built `--locked` — the crates
5//! break API in minor releases; upgrades go only through the canary + runbook
6//! (ADR-0003, IMPLEMENTATION-PLAN §7).
7//!
8//! The engine claims the `hurl` step kind, contributes doctor checks, and
9//! executes scenario artifacts via the embedded `run_entries` (see the
10//! `session` module source for the adapter mechanics).
11
12mod session;
13
14use proef_core::engine::{
15    DoctorCheck, DoctorResult, EngineFactory, EngineSession, PayloadProbeError, ScenarioCtx,
16    StepKindSpec,
17};
18use proef_core::error::EngineError;
19
20/// The exact embedded hurl release (kept in lockstep with the Cargo pin —
21/// asserted by `embedded_version_matches_the_cargo_pin`).
22pub const EMBEDDED_HURL_VERSION: &str = "8.0.1";
23
24/// A parseable single-entry probe file used by doctor checks and smoke tests.
25const PROBE_HURL: &str = "GET http://localhost/health\nHTTP 200\n";
26
27/// Step kinds claimed by this engine: the `hurl:` raw block (ADR-0004,
28/// TECH-SPEC §6 — the pack key doubles as the routing kind). The validate hook
29/// is pack validation pass 7's probe parser.
30const STEP_KINDS: &[StepKindSpec] = &[StepKindSpec {
31    prefix: "hurl",
32    schema: r#"{ "type": "string", "description": "Raw hurl entries; ${…} lowered at author time, {{…}} resolved by hurl at run time" }"#,
33    validate: Some(validate_payload),
34}];
35
36/// The compiled-in hurl engine, registered by `proef-cli` (ADR-0002).
37pub struct HurlEngineFactory;
38
39impl EngineFactory for HurlEngineFactory {
40    fn id(&self) -> &'static str {
41        "hurl"
42    }
43
44    fn step_kinds(&self) -> &'static [StepKindSpec] {
45        STEP_KINDS
46    }
47
48    fn doctor(&self) -> Vec<DoctorCheck> {
49        vec![
50            DoctorCheck {
51                name: "embedded hurl",
52                run: check_embedded_version,
53            },
54            DoctorCheck {
55                name: "hurl parser",
56                run: check_parser,
57            },
58            DoctorCheck {
59                name: "libcurl",
60                run: check_libcurl,
61            },
62        ]
63    }
64
65    fn open(&self, ctx: &ScenarioCtx) -> Result<Box<dyn EngineSession>, EngineError> {
66        Ok(Box::new(session::HurlSession::open(ctx)?))
67    }
68}
69
70/// Report the pinned hurl release compiled into this binary.
71fn check_embedded_version() -> DoctorResult {
72    DoctorResult::pass(format!(
73        "hurl {EMBEDDED_HURL_VERSION} (exact pin, ADR-0003)"
74    ))
75}
76
77/// Exercise `hurl_core`'s parser on a probe file — proves the parser linkage that
78/// pack loading (M1) and artifact validation (M2) rely on. Because `hurl_core`
79/// links libxml2, a running probe also proves the libxml2 dynamic linkage loads.
80fn check_parser() -> DoctorResult {
81    match hurl_core::parser::parse_hurl_file(PROBE_HURL) {
82        Ok(file) if file.entries.len() == 1 => DoctorResult::pass(
83            "parsed 1-entry probe file (hurl_core + libxml2 linkage loads)".to_owned(),
84        ),
85        Ok(file) => DoctorResult::warn(format!(
86            "probe parsed with unexpected entry count {}",
87            file.entries.len()
88        )),
89        Err(err) => DoctorResult::fail(format!("cannot parse probe file: {err:?}")),
90    }
91}
92
93/// Probe-parse a lowered payload with hurl's real parser (pack validation
94/// pass 7 — the seam hook on [`StepKindSpec`]).
95fn validate_payload(text: &str) -> Result<(), PayloadProbeError> {
96    let mut normalized = text.to_owned();
97    if !normalized.ends_with('\n') {
98        normalized.push('\n');
99    }
100    match hurl_core::parser::parse_hurl_file(&normalized) {
101        // A parseable payload with zero entries (only comments or blank
102        // lines) would execute nothing while the step reports green — reject
103        // it at load so dry-run and execution agree.
104        Ok(file) if file.entries.is_empty() => Err(PayloadProbeError {
105            line: 1,
106            column: 1,
107            message: "contains no hurl entries (only comments or blank lines)".to_owned(),
108        }),
109        Ok(_) => Ok(()),
110        Err(err) => Err(PayloadProbeError {
111            line: err.pos.line,
112            column: err.pos.column,
113            message: format!("{:?}", err.kind),
114        }),
115    }
116}
117
118/// Report the libcurl this binary is linked against (mirrors `curl --version`) —
119/// the library `run_entries` drives during execution.
120fn check_libcurl() -> DoctorResult {
121    let info = hurl::http::libcurl_version_info();
122    if info.libraries.is_empty() {
123        return DoctorResult::warn("libcurl loaded but reported no libraries".to_owned());
124    }
125    DoctorResult::pass(format!("{} (host {})", info.libraries.join(" "), info.host))
126}
127
128#[cfg(test)]
129mod tests {
130    #![allow(clippy::unwrap_used)]
131
132    use super::*;
133
134    /// The seam facts this engine relies on are pinned (ADR-0001): parseable
135    /// probe, one entry, exact crate version.
136    #[test]
137    fn parser_seam_smoke() {
138        let result = check_parser();
139        assert_eq!(
140            result.status,
141            proef_core::engine::DoctorStatus::Pass,
142            "{}",
143            result.detail
144        );
145    }
146
147    #[test]
148    fn factory_claims_the_hurl_step_kind() {
149        let factory = HurlEngineFactory;
150        assert_eq!(factory.id(), "hurl");
151        assert_eq!(factory.step_kinds().len(), 1);
152        assert_eq!(factory.step_kinds()[0].prefix, "hurl");
153    }
154
155    /// The doc on [`EMBEDDED_HURL_VERSION`] promises lockstep with the Cargo
156    /// pin — this is that assertion: a runbook pin bump that forgets the
157    /// const (or vice versa) fails here, not at doctor time mid-upgrade.
158    #[test]
159    fn embedded_version_matches_the_cargo_pin() {
160        let manifest = std::fs::read_to_string(
161            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../Cargo.toml"),
162        )
163        .unwrap();
164        for dep in ["hurl", "hurl_core"] {
165            let needle = format!("{dep} = \"={EMBEDDED_HURL_VERSION}\"");
166            assert!(
167                manifest.contains(&needle),
168                "workspace Cargo.toml must contain `{needle}` (ADR-0003 lockstep)"
169            );
170        }
171    }
172
173    #[test]
174    fn payload_probe_accepts_valid_and_rejects_broken_hurl() {
175        assert!(validate_payload("GET http://x/one\nHTTP 200").is_ok());
176        // An unknown response section name is unambiguously invalid hurl.
177        let err = validate_payload("GET http://x/one\nHTTP 200\n[Wrong]\n").unwrap_err();
178        assert!(
179            err.line >= 2,
180            "position should be near the broken section: {err:?}"
181        );
182    }
183}
proef_engine_hurl/lib.rs

proef_engine_hurl/
lib.rs
